hydrogen

hydrogen.radiative_processes_exact(spectrum_at_planet, r_grid, density, f_h_r, h_fraction, f_he_r=None)

Calculate the photoionization rate of hydrogen as a function of radius based on the EUV spectrum arriving at the planet and the neutral H density profile.

Parameters:

spectrum_at_planetdict

Spectrum of the host star arriving at the planet covering fluxes at least up to the wavelength corresponding to the energy to ionize hydrogen (13.6 eV, or 911.65 Angstrom).

r_gridnumpy.ndarray

Radius grid for the calculation, in units of cm.

densitynumpy.ndarray

Total density profile for the atmosphere, in units of g / cm ** 3.

f_h_rnumpy.ndarray or float

H ion fraction profile for the atmosphere.

h_fractionfloat

Hydrogen number fraction of the outflow.

f_he_rnumpy.ndarray or float or None

He ion fraction profile for the atmosphere. If None, then assume that the profile is the same as f_h_r.

Returns:

phi_primefloat

Ionization rate of hydrogen for each point on r_grid in unit of 1 / s.

hydrogen.radiative_processes(spectrum_at_planet)

Calculate the photoionization rate of hydrogen at null optical depth based on the EUV spectrum arriving at the planet.

Parameters:

spectrum_at_planetdict

Spectrum of the host star arriving at the planet covering fluxes at least up to the wavelength corresponding to the energy to ionize hydrogen (13.6 eV, or 911.65 Angstrom).

Returns:

phifloat

Ionization rate of hydrogen at null optical depth in unit of 1 / s.

a_0float

Flux-averaged photoionization cross-section of hydrogen in unit of cm ** 2.

hydrogen.radiative_processes_mono(flux_euv, average_photon_energy=20.0)

Calculate the photoionization rate of hydrogen at null optical depth based on the monochromatic EUV flux arriving at the planet.

Parameters:

flux_euvfloat

Monochromatic extreme-ultraviolet (0 - 912 Angstrom) flux arriving at the planet in unit of erg / s / cm ** 2.

average_photon_energyfloat, optional

Average energy of the photons ionizing H in unit of eV. Default is 20 eV (as in Murray-Clay et al 2009, Allan & Vidotto 2019).

Returns:

phifloat

Ionization rate of hydrogen at null optical depth in unit of 1 / s.

a_0float

Flux-averaged photoionization cross-section of hydrogen in unit of cm ** 2.

hydrogen.recombination(temperature)

Calculates the case-B hydrogen recombination rate for a gas at a certain temperature.

Parameters:

temperaturefloat

Isothermal temperature of the upper atmosphere in unit of Kelvin.

Returns:

alpha_recfloat

Recombination rate of hydrogen in units of cm ** 3 / s.

hydrogen.ion_fraction(radius_profile, planet_radius, temperature, h_fraction, mass_loss_rate, planet_mass, mean_molecular_weight_0=1.0, star_mass=1.0, semimajor_axis=1.0, spectrum_at_planet=None, flux_euv=None, initial_f_ion=0.0, relax_solution=False, convergence=0.01, max_n_relax=10, exact_phi=False, return_mu=False, return_rates=False, **options_solve_ivp)

Calculate the fraction of ionized hydrogen in the upper atmosphere in function of the radius in unit of planetary radius.

Parameters:

radius_profilenumpy.ndarray

Radius in unit of planetary radii.

planet_radiusfloat

Planetary radius in unit of Jupiter radius.

temperaturefloat

Isothermal temperature of the upper atmosphere in unit of Kelvin.

h_fractionfloat

Total (ion + neutral) H number fraction of the atmosphere.

mass_loss_ratefloat

Mass loss rate of the planet in units of g / s.

planet_massfloat

Planetary mass in unit of Jupiter mass.

mean_molecular_weight_0float

Initial mean molecular weight of the atmosphere in unit of proton mass. Default value is 1.0 (100% neutral H). Since its final value depend on the H ion fraction itself, the mean molecular weight can be self-consistently calculated by setting relax_solution to True.

star_massfloat, optional

Stellar mass in units of M_sun, needed for the tidal gravity calculation. Default is 1.

semimajor_axisfloat, optional

Planetary semimajor axis in units of au, needed for the tidal gravity calculation. Default is 1 (so the tidal gravity correction is minimal by default).

spectrum_at_planetdict, optional

Spectrum of the host star arriving at the planet covering fluxes at least up to the wavelength corresponding to the energy to ionize hydrogen (13.6 eV, or 911.65 Angstrom). Can be generated using tools.make_spectrum_dict. If None, then flux_euv must be provided instead. Default is None.

flux_euvfloat, optional

Extreme-ultraviolet (0-911.65 Angstrom) flux arriving at the planet in units of erg / s / cm ** 2. If None, then spectrum_at_planet must be provided instead. Default is None.

initial_f_ionfloat, optional

The initial ionization fraction at the layer near the surface of the planet. Default is 0.0, i.e., 100% neutral.

relax_solutionbool, optional

The first solution is calculating by initially assuming the entire atmosphere is in neutral state. If True, the solution will be re-calculated in a loop until it converges to a delta_f of 1%, or for a maximum of 10 loops (default parameters). Default is False.

convergencefloat, optional

Value of delta_f at which to stop the relaxation of the solution for f_r. Default is 0.01.

max_n_relaxint, optional

Maximum number of loops to perform the relaxation of the solution for f_r. Default is 10.

exact_phibool, optional

If set to True, the H photoionization is calculated exactly (using the radiative_processes_exact() function). If set to False, then calculate it using an approximation with radiative_processes(). Default value is False.

return_mubool, optional

If True, then this function returns a second variable mu_bar, which is the self-consistent, density-averaged mean molecular weight of the atmosphere. Equivalent to the mu_bar of Eq. A.3 in Lampón et al. 2020.

return_ratesbool, optional

If True, then this function also returns a dict object containing the rates of photoionization and recombination in function of radius and in units of 1 / s. Default is False.

**options_solve_ivp:

Options to be passed to the scipy.integrate.solve_ivp() solver. You may want to change the options method (integration method; default is 'RK45'), atol (absolute tolerance; default is 1E-6) or rtol (relative tolerance; default is 1E-3). If you are having numerical issues, you may want to decrease the tolerance by a factor of 10 or 100, or 1000 in extreme cases.

Returns:

f_rnumpy.ndarray

Values of the fraction of ionized hydrogen in function of the radius.

mu_barfloat

Mean molecular weight of the atmosphere, in unit of proton mass, averaged across the radial distance using according to the function average_molecular_weight in the parker module. Only returned when return_mu is set to True.

ratesdict

Dictionary containing the rates of photoionization and recombination in function of radius and in units of 1 / s. Only returned when return_rates is set to True.

hydrogen.boltzmann_distribution(temperature, n, nlte_scaling=1.0)

Calculates the distribution of electronic states of the different atomic shells of the hydrogen atom via the Boltzmann equation in LTE and NLTE. In short, it calculates which fraction of the total number of H atoms are in the shell needed to produce H-alpha, H-beta etc lines.

Parameters:

temperature: ``float``

Temperature in K.

nint

For which shell number do we calculate the Boltzmann distribution.

nlte_scalingfloat

If NLTE is assumed, the scaling factor can be a free fitting parameter in the retrieval on the data. Default: 1. (LTE, no scaling).

Returns:

boltzmann_nfloat

Unitless fraction of Hydrogen population in the needed atomic shell for the specific Balmer-line.

hydrogen.saha_distribution(temperature, electron_density)

Calculate the distribution of ionization states for the Balmer series of hydrogen using the Saha equation.

Parameters:

temperature: ``float``

Temperature in K

electron_density: ``float``

the electron density (most likely coming from the background, but tbd). If only one level of ionisation is important then n1 = ne The electron density has to have units of (cm**-3)

Returns:

saha_nfloat

Unitless fraction of ionised Hydrogen from total Hydrogen for the specific Balmer-line.

hydrogen.relation_boltzmann_saha(temperature, n, electron_density, nlte_scaling=1.0)

Calculates the fraction with relation to the total number of atoms taking into account Boltzmann and Saha

Parameters:

temperature: ``float``

Temperature in K

ninteger

Number of the atomic shell

electron_density: ``float``

the electron density (most likely coming from the background, but tbd). If only one level of ionisation is important then n1 = ne The electron density has to have units of (cm**-3)

nlte_scalingfloat

If NLTE is assumed, the scaling factor can be a free fitting parameter in the retrieval on the data. Default: 1. (LTE, no scaling).

Returns:

total_fractionfloat

Unitless fraction of available Hydrogen from total Hydrogen for the specific Balmer-line

hydrogen.balmer_fraction(temperature, n_e, g_factor, n_shell)

Calculates the scaling factor of the hydrogen density for the Balmer lines after Wyttenbach et al. 2020 eq. 9.

Parameters:

temperature: ``float``

Temperature in K.

n_e: ``float``

the electron density (most likely coming from the background, but tbd). If only one level of ionisation is important then n1 = ne The electron density has to have units of (cm**-3)

g_factor: ‘’float’’

the g scaling factor of the line in question from lines.py

n_shellinteger

Number of the atomic shell

Returns:

n_H_2n_scalefloat

Unitless fraction to adjust the hydrogen density for the specific Balmer

line.