radis.lbl.base module

Summary

A class to aggregate methods to calculate spectroscopic parameter and populations (and unload factory.py)

BaseFactory is inherited by BroadenFactory eventually

Routine Listing

PUBLIC METHODS

PRIVATE METHODS - CALCULATE SPECTROSCOPIC PARAMETERS (everything that doesnt depend on populations / temperatures) (computation: work & update with ‘df0’ and called before eq_spectrum() )

PRIVATE METHODS - APPLY ENVIRONMENT PARAMETERS (all functions that depends upon T or P) (calculates populations, linestrength & radiance, lineshift) (computation: work on df1, called by or after eq_spectrum() )

Most methods are written in inherited class with the following inheritance scheme:

DatabankLoader > BaseFactory > BroadenFactory > BandFactory > SpectrumFactory

digraph inheritanceb7d785f131 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "BandFactory" [URL="radis.lbl.bands.html#radis.lbl.bands.BandFactory",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="See Also"]; "BroadenFactory" -> "BandFactory" [arrowsize=0.5,style="setlinewidth(0.5)"]; "BaseFactory" [URL="#radis.lbl.base.BaseFactory",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top"]; "DatabankLoader" -> "BaseFactory" [arrowsize=0.5,style="setlinewidth(0.5)"]; "BroadenFactory" [URL="radis.lbl.broadening.html#radis.lbl.broadening.BroadenFactory",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A class that holds all broadening methods."]; "BaseFactory" -> "BroadenFactory" [arrowsize=0.5,style="setlinewidth(0.5)"]; "DatabankLoader" [URL="radis.lbl.loader.html#radis.lbl.loader.DatabankLoader",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip=".. inheritance-diagram:: radis.lbl.factory.SpectrumFactory"]; "SpectrumFactory" [URL="radis.lbl.factory.html#radis.lbl.factory.SpectrumFactory",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A class to put together all functions related to loading CDSD / HITRAN"]; "BandFactory" -> "SpectrumFactory" [arrowsize=0.5,style="setlinewidth(0.5)"]; }
class BaseFactory[source]

Bases: DatabankLoader

NwG[source]
NwL[source]
Qgas(df1, Tgas)[source]

Calculate partition function Qgas at temperature Tgas, for all lines of df1. Returns a single value if all lines have the same Qgas value, or a column if they are different

Parameters:

Tgas (float (K)) – gas temperature

Returns:

float or dict

Return type:

Returns Qgas as a dictionary with isotope values as its keys

See also

Qgas_Qref_ratio()

Qneq(df, Tvib, Trot, vib_distribution, rot_distribution, overpopulation)[source]

Nonequilibrium partition function

Returns:

column or float

Return type:

depending if there are many isotopes or one

Qneq_Qvib_Qrotu_Qrotl(df, Tvib, Trot, vib_distribution, rot_distribution, overpopulation)[source]

Nonequilibrium partition function; with the detail of vibrational partition function and rotational partition functions

Qref_Qgas_ratio(df1, Tgas, Tref)[source]

Calculate Qref/Qgas at temperature Tgas, Tref, for all lines of df1. Returns a single value if all lines have the same Qref/Qgas ratio, or a column if they are different

See also

Qgas()

SpecDatabase[source]
assert_no_nan(df, column)[source]

Assert there are no nan in the column.

Crash with a nice explanation if one is found

autoretrievedatabase[source]
autoupdatedatabase[source]
calc_S0(df)[source]

Calculate S0 from A [s-1], the tabulated Einstein coefficient. S0 is the part of the linestrength that does not depend on the temperature.

Parameters:

df (DataFrame) – The DataFrame to which the S0 column is to be added

Returns:

None

Return type:

df is updated directly with new column S0

References

\[S_0 = \frac{I_a A_{21} g'}{8 \pi c \nu^2}\]

Do not confuse with S(T = 296 K), the definition of Eq. (1) in https://hitran.org/docs/definitions-and-units/ or Eq.(A11) in [Rothman-1998]

\[S(T_{ref} = 296 K) = \frac{I_a A_{21}}{8 \pi c \nu^2} \frac{g' e^{-c_2E''/T_{ref}}(1-e^{-c_2\nu_{ij}/T_{ref}})}{Q(T_{ref})}\]

Notes

Currently this value is used in GPU calculations. It is one of the columns that is transferred to the GPU memory. The idea behind S0 is that it is scaled with all variables that do not change during iterations as to minimize calculations.

Units: cm-1/(molecules/cm-2)

calc_einstein_coefficients()[source]

Calculate \(A (= A_{ul})\), \(B_{lu}\), \(B_{ul}\) Einstein coefficients from weighted transition moments squared \(R_s^2\).

Returns:

None

Return type:

self.df0 is updated directly with new columns A, Blu, Bul

Note

Einstein A coefficient already in the HITRAN database. In the HITRAN database, the maximum difference betweeen the tabulated and the recalculated values of A was 0.053% for CO2 and 0.099%, see https://github.com/radis/radis/issues/665

References

Einstein induced absorption coefficient (in \(cm^3/J/s^2\))

\[B_{lu}=10^{-36}\cdot\frac{8{\pi}^3}{3h^2} R_s^2 \cdot 10^{-7}\]

Einstein induced emission coefficient (in \(cm^3/J/s^2\))

\[B_{ul}=10^{-36}\cdot\frac{8{\pi}^3}{3h^2} \frac{gl}{gu} R_s^2 \cdot 10^{-7}\]

Einstein spontaneous emission coefficient (in \(s^{-1}\))

\[A = A_{ul}=10^{-36}\cdot\frac{\frac{64{\pi}^4}{3h} {\nu}^3 gl}{gu} R_s^2\]

See (Eqs.(A7), (A8), (A9) in [Rothman-1998])

calc_emission_integral()[source]

Calculate the emission integral (in \(mW/sr\)) of all lines in DataFrame df1.

\[E_i=\frac{n_u A_{ul}}{4 \pi} \Delta E_{ul}\]

Where \(A_{ul}\) (\(s^{-1}\)) is the Einstein coefficient of the corresponding line, \(n_u\) (in \(cm^{-3}/cm^{-3}\) is the fraction of the molecule population in the upper rovibrational state, and \(\Delta E_{ul}\) the transition energy.

Emission Integral is a non usual quantity introduced in RADIS as an equivalent for emission calculations of the Linestrength quantity used in absorption calculations.

The emission integral is later multiplied by the total density \(n_tot\) and the lineshape \(\Phi_i\) to obtain the spectral emission coefficient \(\epsilon_i\) associated to each line.

\[\epsilon_i(\lambda) = E_i \cdot n_{tot} \cdot \Phi_i(\lambda)\]

Which are afterwards summed over all N lines to obtain the total emission coefficient :

\[\epsilon(\lambda) = \sum_i^N {\epsilon_i}(\lambda)\]
Returns:

Emission integral Ei added in df1

Return type:

None

See also

calc_linestrength_noneq()

calc_lineshift()[source]

Calculate lineshift due to pressure.

Returns:

None

Return type:

self.df1 is updated directly with new column shiftwav

References

Shifted line center based on pressure shift coefficient \(lambda_{shift}\) and pressure \(P\).

\[\omega_{shift}=\omega_0+\lambda_{shift} P\]

See Eq.(A13) in [Rothman-1998]

calc_linestrength_eq(Tgas)[source]

Calculate linestrength at temperature Tgas correcting the database linestrength tabulated at temperature \(T_{ref}\).

Parameters:

Tgas (float (K)) – gas temperature

Returns:

None

Return type:

self.df1 is updated directly with new column S

References

\[S(T) = S_0 \frac{Q_{ref}}{Q_{gas}} \operatorname{exp}\left(-E_l \left(\frac{1}{T_{gas}}-\frac{1}{T_{ref}}\right)\right) \frac{1-\operatorname{exp}\left(\frac{-\omega_0}{Tgas}\right)}{1-\operatorname{exp}\left(\frac{-\omega_0}{T_{ref}}\right)}\]

See Eq.(A11) in [Rothman-1998]

Notes

Internals:

(some more informations about what this function does)

Starts with df1 which is still a copy of df0 loaded by load_databank() Updates linestrength in df1. Cutoff criteria is applied afterwards.

Examples using radis.lbl.base.BaseFactory.calc_linestrength_eq

Scale Linestrengths of carbon-monoxide

Scale Linestrengths of carbon-monoxide

See also

linestrength_from_Einstein()

calc_linestrength_noneq()[source]

Calculate linestrengths at non-LTE. This value must be divided by the partition function to get the actual spectrum.

Parameters:

Pre-requisite – lower state population nl has already been calculated by calc_populations_noneq()

Returns:

Linestrength S added in self.df

Return type:

None

References

This function returns S(T)

\[S(T) = \frac{I_a A_{21} g'}{8 \pi c \nu^2} g' e^{-c_2E''/T}(1-e^{-c_2\nu_{ij}/T})\]

Do not confuse with S(T), the definition of Eq. (1) in https://hitran.org/docs/definitions-and-units/ or Eq.(A11) in [Rothman-1998]

\[S_{HITRAN}(T) = \frac{I_a A_{21}}{8 \pi c \nu^2} \frac{g' e^{-c_2E''/T}(1-e^{-c_2\nu_{ij}/T})}{Q(T)}\]

Notes

Internals:

(some more informations about what this function does)

Starts with df1 which is was a copy of df0 loaded by load_databank(), with non-equilibrium quantities added and populations already calculated. Updates linestrength in df1. Cutoff criteria is applied afterwards.

See also

calc_populations_noneq(), calc_emission_integral(), linestrength_from_Einstein()

calc_populations_eq(Tgas)[source]

Calculate upper state population for all active transitions in equilibrium case (only used in total power calculation)

Parameters:

Tgas (float (K)) – temperature

Returns:

nu is stored in self.df1

Return type:

None

Notes

Isotopes: these populations are not corrected for the isotopic abundance, i.e, abundance has to be accounted for if used for emission density calculations (based on Einstein A coefficient), but not for linestrengths (that include the abundance dependency already)

References

Population of upper state follows a Boltzmann distribution:

\[n_u = g_u \frac{\operatorname{exp}\left(\frac{-E_u}{T_{gas}}\right)}{Q_{gas}}\]

See also

calc_populations_noneq(), _calc_populations_noneq_multiTvib(), at()

calc_populations_noneq(Tvib=None, Trot=None, Telec=None, vib_distribution='boltzmann', rot_distribution='boltzmann', overpopulation=None)[source]

Calculate upper and lower state population for all active transitions, as well as all levels (through at_noneq() for molecules)

Parameters:

  • Tvib, Trot, Telec (float (K)) – temperatures

  • vib_distribution ('boltzmann', 'treanor') – vibrational level (only applicable for molecules)

  • rot_distribution ('boltzmann') – rotational level distribution (only applicable for molecules)

  • overpopulation (dict, or None) – dictionary of overpopulation factors for vibrational levels (only applicable for molecules)

Returns:

None

Return type:

nu, nl, (and nu_vib, nl_vib too for molecules) are stored in self.df1

Notes

Isotopic abundance:

Note that these populations are not corrected for the isotopic abundance, i.e, abundance has to be accounted for if used for emission density calculations (based on Einstein A coefficient), but not for linestrengths (that include the abundance dependency already)

All populations:

This method calculates populations of emitting and absorbing levels. Populations of all levels (even the one not active on the spectral range considered) are calculated during the Partition function calculation. See: at_noneq()

References

Boltzmann vibrational distributions

\[n_{vib}=\frac{g_{vib}}{Q_{vib}} \operatorname{exp}\left(\frac{-E_{vib}}{T_{vib}}\right)\]

or Treanor vibrational distributions

\[n_{vib}=\frac{g_{vib}}{Qvib} \operatorname{exp}\left(-\left(\frac{E_{vib,harm}}{T_{vib}}+\frac{E_{vib,anharm}}{T_{rot}}\right)\right)\]

Overpopulation of vibrational levels

\[n_{vib}=\alpha n_{vib}\]

Boltzmann rotational distributions

\[n_{rot}=\frac{g_{rot}}{Q_{rot}} \operatorname{exp}\left(\frac{-E_{rot}}{T_{rot}}\right)\]

Final rovibrational population of one level

\[n=n_{vib} n_{rot} \frac{Q_{rot} Q_{vib}}{Q}\]

See also

calc_populations_eq(), _calc_populations_noneq_multiTvib(), at_noneq()

calc_weighted_trans_moment()[source]

Calculate weighted transition-moment squared \(R_s^2\) (in Debye^2)

Returns:

self.df0 is updated directly with new column Rs2 . R is in Debye^2 (1e-36 ergs.cm3)

Return type:

None

References

Weighted transition-moment squared \(R_s^2\) from linestrength \(S_0\) at temperature \(T_{ref}\), derived from Eq.(A5) in [Rothman-1998]

cond_units[source]
cond_units0 = {'Tgas': 'K', 'Tref': 'K', 'Trot': 'K', 'Tvib': 'K', 'calculation_time': 's', 'cutoff': 'cm-1/(#.cm-2)', 'neighbour_lines': 'cm-1', 'path_length': 'cm', 'pressure': 'bar', 'truncation': 'cm-1', 'wavelength_max': 'nm', 'wavelength_min': 'nm', 'wavenum_max': 'cm-1', 'wavenum_max_calc': 'cm-1', 'wavenum_min': 'cm-1', 'wavenum_min_calc': 'cm-1', 'wstep': 'cm-1'}[source]

Calculation Conditions units

database[source]
dataframe_engine[source]
dataframe_type[source]
df0[source]

initial line database after loading. If for any reason, you want to manipulate the line database manually (for instance, keeping only lines emitting by a particular level), you need to access the df0 attribute of SpectrumFactory.

Warning

never overwrite the df0 attribute, else some metadata may be lost in the process. Only use inplace operations. If reducing the number of lines, add a df0.reset_index()

For instance:

from radis import SpectrumFactory
sf = SpectrumFactory(
    wavenum_min= 2150.4,
    wavenum_max=2151.4,
    pressure=1,
    isotope=1)
sf.load_databank('HITRAN-CO-TEST')
sf.df0.drop(sf.df0[sf.df0.vu!=1].index, inplace=True)   # keep lines emitted by v'=1 only
sf.eq_spectrum(Tgas=3000, name='vu=1').plot()

df0 contains the lines as they are loaded from the database. df1 is generated during the spectrum calculation, after the line database reduction steps, population calculation, and scaling of intensity and broadening parameters with the calculated conditions.

See also

df1

Type:

pd.DataFrame

df1[source]

line database, scaled with populations + linestrength cutoff Never edit manually. See all comments about df0

See also

df0

Type:

pd.DataFrame

get_energy_levels(molecule, isotope, state='X', conditions=None)[source]

Return energy levels database for given molecule > isotope > state (look up Factory.parsum_calc[molecule][iso][state])

Parameters:

  • molecule (str) – molecule name

  • isotope (int) – isotope identifier

  • state (str:) – electronic state. Default 'X' (ground-state)

  • conditions (str, or None) – if not None, add conditions on which energies to retrieve, e.g:

    >>> 'j==0' or 'v1==0'

    Conditions are applied using Dataframe.query() method. In that case, get_energy_levels() returns a copy. Default None

Returns:

energies – a view of the energies stored in the Partition Function calculator for isotope iso. If conditions are applied, we get a copy

Return type:

pandas Dataframe

See also

get_populations()

get_lines()[source]

Return lines if self.misc.export_lines is True, else get None.

get_lines_abundance(df)[source]

Returns the isotopic abundance of each line in df

Parameters:

df (dataframe)

Returns:

float or dict

Return type:

The abundance of all the isotopes in the dataframe

get_molar_mass(df)[source]

Returns molar mass for all lines of DataFrame df.

Parameters:

df (pd.DataFrame)

Return type:

The molar mass of all the isotopes in the dataframe

get_populations(levels='vib')[source]

For all molecules / isotopes / electronic states, lookup energy levels as calculated in partition function calculators, and (if calculated) populations, and returns as a dictionary.

Parameters:

levels ('vib', 'rovib', list of these, or None) – what levels to get. Note that 'rovib' can yield large Spectrum objects.

Returns:

pops –

Structure:

{molecule: {isotope: {electronic_state: {'vib': pandas Dataframe,    # (copy of) vib levels
                                         'rovib': pandas Dataframe,  # (copy of) rovib levels
                                         'Ia': float    # isotopic abundance
                                         }}}}

Return type:

dict

See also

get_energy_levels()

input[source]
input_wunit[source]
interactive_params[source]
levels[source]
levelspath[source]
min_width[source]
misc[source]

Miscellaneous parameters (MiscParams) params that cannot change the output of calculations (ex: number of CPU, etc.)

molparam[source]

contains information about molar mass; isotopic abundance.

See MolParams

Type:

MolParam

params[source]

Parameters they may change the output of calculations (ex: threshold, cutoff, broadening methods, etc.)

Type:

Computational parameters

parsum_calc[source]

store all partition function calculators, per isotope

Type:

dict

parsum_tab[source]

store all partition function tabulators, per isotope

Type:

dict

plot_hist(dataframe='df0', what='int', axvline=None)[source]

Plot distribution of column what in dataframe

For instance, help determine a cutoff criteria

plot_hist("df1", "int")
Parameters:

  • dataframe (‘df0’, ‘df1’) – which dataframe to plot (df0 is the loaded one, df1 the scaled one)

  • what (str) – which feature to plot. Default 'S' (scaled linestrength). Could also be 'int' (reference linestrength intensity), 'A' (Einstein coefficient)

  • axvline (float) – if not None, plot a vertical line at this position.

plot_linestrength_hist(cutoff=None)[source]

Plot linestrength distribution (to help determine a cutoff criteria)

Examples

s, sf = calc_spectrum(..., return_factory=True)
sf.plot_linestrength_hist()
plot_populations(what='vib', isotope=None, nfig=None)[source]

Plot populations currently calculated in factory.

Plot populations of all levels that participate in the partition function. Output is different from the Spectrum plot_populations() method, where only the levels that directly contribute to the spectrum are shown

Note: only valid after calculating non_eq spectrum as it uses the partition function calculator object

Parameters:

  • what (‘vib’, ‘rovib’) – what levels to plot

  • isotope (int, or None) – which isotope to plot. If None and if there are more than one isotope, raises an error.

Other Parameters:

nfig (int, or str) – on which Figure to plot. Default None

print_conditions(prepend=None)[source]

Prints all physical / computational parameters. These are also stored in each result Spectrum.

Parameters:

prepend (str) – just to text to display before printing conditions

profiler[source]
reftracker[source]
save_memory[source]

if True, tries to save RAM memory (but may take a little for time, saving stuff to files instead of RAM for instance)

Type:

bool

truncation[source]
units[source]
units0 = {'abscoeff': 'cm-1', 'abscoeff_continuum': 'cm-1', 'absorbance': '', 'emisscoeff': 'mW/cm3/sr/cm-1', 'emisscoeff_continuum': 'mW/cm3/sr/cm-1', 'emissivity_noslit': '', 'radiance_noslit': 'mW/cm2/sr/cm-1', 'transmittance_noslit': '', 'waverange': 'cm-1'}[source]

Default output units … may be changed at the initialisation of the SpectrumFactory, for instance … if user gives wavelength units we want to return radiance in … “mW/cm2/sr/nm” units for consistency

verbose[source]

increase verbose level. 0, 1, 2 supported at the moment

Type:

bool, or int

warnings[source]

Default warnings for SpectrumFactory. See default_warning_status

Type:

dict

wavenumber[source]
wavenumber_calc[source]
wbroad_centered[source]
woutrange[source]
get_wavenumber_range(wmin=None, wmax=None, wunit=cm - 1, wavenum_min=None, wavenum_max=None, wavelength_min=None, wavelength_max=None, medium='air', return_input_wunit=False)[source]

Returns wavenumber based on whatever input was given: either ν_min, ν_max directly, or λ_min, λ_max in the given propagation medium.

Parameters:

  • medium ('air', 'vacuum') – propagation medium

  • wmin, wmax (float, or Quantity or None) – hybrid parameters that can serve as both wavenumbers or wavelength depending on the unit accompanying them. If unitless, wunit is assumed as the accompanying unit.

  • wunit (string) – The unit accompanying wmin and wmax. Cannot be passed without passing values for wmin and wmax. Default: cm-1

  • wavenum_min, wavenum_max (float, or Quantity or None) – wavenumbers

  • wavelength_min, wavelength_max (float, or Quantity or None) – wavelengths in given medium

Returns:

  • wavenum_min, wavenum_max (float) – wavenumbers

  • input_wunit (‘nm’, ‘nm_vac’, ‘cm-1’) – in which wavespace was the input given before conversion (used to keep default plot/get consistent with input units)

linestrength_from_Einstein(A, gu, El, Ia, nu, Q, T)[source]

Calculate linestrength at temperature T from Einstein coefficients.

Parameters:

  • A (float, s-1) – Einstein emission coefficients

  • gu (int) – upper state degeneracy

  • El (float, cm-1) – lower state energy

  • Ia (float) – isotope abundance

  • nu (cm-1) – transition wavenumber

  • Q (float) – partition function at temperature T

  • T (float) – temperature

Returns:

S – linestrength at temperature T.

Return type:

float

References

\[S(T) =\frac{1}{8\pi c_{CGS} {\nu}^2} A \frac{I_a g_u \operatorname{exp}\left(\frac{-c_2 E_l}{T}\right)}{Q(T)} \left(1-\operatorname{exp}\left(\frac{-c_2 \nu}{T}\right)\right)\]

Combine Eq.(A.5), (A.9) in [Rothman-1998]

See also

calc_linestrength_eq()