API

The Source class

The core of pyhonradex is the Source class which is used to solve the radiative transfer.

class pythonradex.radiative_transfer.Source(datafilepath, geometry, line_profile_type, width_v, use_Ng_acceleration=True, treat_line_overlap=False, warn_negative_tau=True, verbose=False, test_mode=False)

Solving the non-LTE radiative transfer using escape probabilities.

emitting_molecule

object containing all the information about the emitting atom or molecule

Type:

pythonradex.molecule.EmittingMolecule

tau_nu0_individual_transitions

optical depth of each individual transition at the central frequency (contributions of dust or overlapping lines to the optical depth are not included). For spherical geometries, the optical depth is along the diameter of the sphere.

Type:

numpy.ndarray

level_pop

fractional population of each level

Type:

numpy.ndarray

Tex

excitation temperature of each transition

Type:

numpy.ndarray

lower_level_population

for each transition, the fractional population of the lower level of that transition

Type:

numpy.ndarray

upper_level_population

for each transition, the fractional population of the upper level of that transition

Type:

numpy.ndarray

Note

The attributes tau_nu0_individual_transitions, level_pop, Tex, lower_level_population and upper_level_population are available only after solving the radiative transfer by calling solve_radiative_transfer

__init__(datafilepath, geometry, line_profile_type, width_v, use_Ng_acceleration=True, treat_line_overlap=False, warn_negative_tau=True, verbose=False, test_mode=False)

Initialises a new instance of the Source class.

Parameters:

  • datafilepath (str) – filepath to the file in LAMDA format that contains the atomic / molecular data

  • geometry (str) – determines how the escape probability and flux are calculated. Available options: “static sphere”, “static sphere RADEX”, “static slab”, “LVG slab”, “LVG sphere” and “LVG sphere RADEX”. The options containing “RADEX” are meant to mimic the behaviour of the original RADEX code by using the same equations for the escape probability and the (non-background-subtracted) intensity as RADEX.

  • line_profile_type (str) – The type of the line profile. Available options: “rectangular” or “Gaussian”. Note that for LVG geometries, only “rectangular” is allowed.

  • width_v (float) – The width of the line profile in [m/s]. For a Gaussian profile, this is interpreted as the FWHM. Note that the interpretation of this parameter depends on the adopted geometry. For the static geometries, width_v is the width of the intrinsic emission profile. On the other hand, for LVG geometries (for which the line profile is rectangular), width_v corresponds to the total velocity width of the source. So, for “LVG sphere”, width_v=2*V, where V is the velocity at the surface of the sphere. In terms of the constant velocity gradient dv/dr=V/R (with R the radius of the sphere), we can also say that width_v=dv/dr*2*R. For “LVG slab”, width_v=dv/dz*Z where Z is the depth of the slab and dv/dz the constant velocity gradient of the slab.

  • use_Ng_acceleration (bool) – Whether to use Ng acceleration. Defaults to True.

  • treat_line_overlap (bool) – Whether to treat the overlap of emission lines by averaging over the line profile. If False, all calculations are done at the rest frequency (same as RADEX), and overlap effects are neglected. If True, overlapping lines are treated correctly by performing averages over frequency. This slows down the calculation considerably. Defaults to False. Can only be used in combination with static geometries (i.e. not with LVG geometries).

  • warn_negative_tau (bool) – Whether the raise a warning when negative optical depth is encountered. Defaults to True. Setting this to False may be useful when calculating a grid of models.

  • verbose (bool) – Whether to print additional information. Defaults to False.

  • test_mode (bool) – Enter test mode. Only for developer, should not be used by general user. Defaults to False.

update_parameters(N=None, Tkin=None, collider_densities=None, ext_background=None, T_dust=None, tau_dust=None)
Set or update the parameters for a radiative transfer calculation.

Any of the parameters can be set to None if no update of that parameter is wished.

Parameters:

  • ext_background (func, number or None) – A function taking the frequency in Hz as input and returning the background radiation field in [W/m2/Hz/sr]. A single number is interpreted as a constant value for all frequencies. Defaults to None (i.e. do not update).

  • N (float or None) – The column density in [m-2]. Defaults to None (i.e. do not update). For spherical geometries, this corresponds to the column density along the diameter of the sphere.

  • Tkin (float or None) – The kinetic temperature of the gas in [K]. Defaults to None (i.e. do not update).

  • collider_densities (dict or None) – A dictionary of the number densities of each collider that should be considered, in units of [m-3]. The following keys are recognised: “H2”, “para-H2”, “ortho-H2”, “e”, “H”, “He”, “H+”. Defaults to None (i.e. do not update).

  • T_dust (func, number or None) – The dust temperature in [K] as a function of frequency. It is assumed that the source function of the dust is a black body at temperature T_dust. A single number is interpreted as a constant temperature for all frequencies. Can only be used with static geometries (i.e. not with LVG geometries). Defaults to None (i.e. do not update). For a model without dust, put this parameter to 0.

  • tau_dust (func, number or None) – optical depth of the dust as a function of frequency. A single number is interpreted as a constant optical depth for all frequencies. Can only be used with static geometries (i.e. not with LVG geometries). Defaults to None (i.e. do not update). For a model without dust, put this parameter to 0. For a static sphere, this corresponds to the optical depth along the diameter of the sphere.

solve_radiative_transfer()

Solves the radiative transfer.

frequency_integrated_emission(output_type, transitions=None, solid_angle=None)
Calculates the frequency-integrated emission of individual transitions.

This calculation is only easily possible if the dust is optically thin (i.e. the dust does not hinder line photons from escaping the source). Thus, this function throws an error if the dust is not optically thin. Similarly, the calculation is not possible when lines are overlapping and are not optically thin. The user needs to choose an appropriate observational quantity to be compared to the line fluxes calculated here. In particular, for optically thin lines, the continuum-subtracted observation might be appropriate. On the other hand, for optically thick lines, the non-continuum-subtracted observations might be more appropriate (because the optically thick line blocks the continuum at the line enter; see e.g. Weaver et al. 2018)

Parameters:

  • output_type (str) – Specifies the type of the output. Can either be “intensity” (in [W/m2/sr]) or “flux” (in [W/m2]; solid_angle needs to be specified)

  • transitions (0- or 1-dimensional array_like (dytpe int), or None) – The index or indices of the transitions for which to calculate the emission. For a single transition, an integer can be provided. For several transitions, a list of integers is provided. If None, then the emission of all transitions is calculated. Defaults to None. The indices correspond to the list of transitions in the LAMDA-formatted file, with the first transition having index 0.

  • solid_angle (float) – The solid angle of the source in [sr]. Needed for output_type “flux”. Defaults to None.

Returns:

An array of intensities or fluxes corresponding to the input list of requested transitions. If no specific transitions where requested (transitions=None), then the list of fluxes corresponds to the transitions as listed in the LAMDA file. The shape of the returned array is the same as the input transitions.

Return type:

np.ndarray

tau(nu)

Calculate the total optical depth (all lines plus dust) at each input frequencies. For spherical geometries, the returned optical depth corresponds to the diameter of the sphere.

Parameters:

  • nu (0- or 1-dimensional array_like) – The frequencies in [Hz]

  • number (for which the optical depth should be calculated. An single)

  • allowed. (or a 1D array are)

Returns:

The total optical depth at the input frequencies. The shape of the array is the same as nu.

Return type:

np.ndarray

spectrum(nu, output_type, solid_angle=None)

Calculate the emission (lines + dust) as a function of frequency.

Parameters:

  • nu (0- or 1-dimensional array_like) – The frequencies in [Hz] for which the spectrum should be calculated. An single number or a 1D array are allowed.

  • output_type (str) – Specifies the type of the output spectrum. Possible choices are “specific intensity” (in [W/m2/Hz/sr]), “flux density” (in [W/m2/Hz]; solid_angle needs to be specified), “Rayleigh-Jeans” (Rayleigh-Jeans brightness temperature in [K]), “Planck” (brightness temperature calculated using the Planck function, in [K]).

  • solid_angle (float) – The solid angle of the source in [sr]. Needed for output_type “flux density”. Defaults to None.

Returns:

The emission for each input frequency. The shape of the array is the same as nu.

Return type:

np.ndarray

emission_at_line_center(output_type, transitions=None, solid_angle=None)

Calculate the emission at the line center (rest frequency) for the specified transitions. The output includes contributions from dust and overlapping lines.

Parameters:

  • transitions (0- or 1-dimensional array_like (dytpe int), or None) – The index or indices of the transitions for which to calculate the emission. For a single transition, an integer can be provided. For several transitions, a list of integers is provided. If None, then the emission of all transitions is calculated. Defaults to None. The indices correspond to the list of transitions in the LAMDA-formatted file, with the first transition having index 0.

  • output_type (str) – Specifies the type of the output. Possible choices are “specific intensity” (in [W/m2/Hz/sr]), “flux density” (in [W/m2/Hz]; solid_angle needs to be specified), “Rayleigh-Jeans” (Rayleigh-Jeans brightness temperature in [K]), “Planck” (brightness temperature calculated using the Planck function, in [K]).

  • solid_angle (float) – The solid angle of the source in [sr]. Needed for output_type “flux density”. Defaults to None.

Returns:

The list of emission values corresponding to the input list of requested transitions. If no specific transitions where requested (transitions=None), then the list corresponds to all transitions as listed in the LAMDA file. The shape of the returned array is the same as transitions.

Return type:

np.ndarray

print_results()

Prints the results from the radiative transfer computation.

Reading LAMDA files

pyhonradex provides a convenient function in the LAMDA_file module to read files that follow the LAMDA format, for example from the EMAA or LAMDA databases:

pythonradex.LAMDA_file.read(datafilepath, read_frequencies, read_quantum_numbers=False)

Read a data file that follows the LAMDA format (https://home.strw.leidenuniv.nl/~moldata/molformat.html). Such files can for example be downloaded from the EMAA (https://emaa.osug.fr/) or the LAMDA (http://home.strw.leidenuniv.nl/~moldata) databases.

Parameters:

  • datafilepath (str) – The filepath to the LAMDA file.

  • read_frequencies (bool) – Whether to read the frequencies of the radiative transitions from the file or not. If False, calculates the frequencies from the level energies given in the file. Setting this to True can be useful since frequencies are sometimes given with more significant digits than level energies. However, the LAMDA format does not force a file to contain the frequencies, so they might not be present.

  • read_quantum_numbers (bool) – Whether to read the quantum numbers from the file. Defaults to False. The LAMDA format does not force a file to list quantum numbers, so they might not be present.

Returns:

A dictionary containing the data read from the file.

The following keys give acces to lists containing the data. The elements of these lists are in the order they appear in the file. ‘levels’ (a list of pythonradex.atomic_transition.Level objects); ‘radiative transitions’ (a list of pythonradex.atomic_transitions.RadiativeTransition objects); ‘collisional transitions’ (a list of pythonradex.atomic_transition.CollisionalTransition objects); ‘quantum numbers’ (list of str, empty if read_quantum_numbers was set to False)

Return type:

dict

Representation of molecular levels and transitions

pyhonradex contains a number of classes to represent molecular data such as the energy levels and transitions between these levels. The molecular data is typically read from a LAMDA file.

class pythonradex.atomic_transition.Level(g, E, index)

Represents an atomic / molecular level.

g

the statistical weight of the level

Type:

float

E

the energy of the level in [J]

Type:

float

index

the index of the level; if constructed from a LAMDA-formatted file, this index indicates the postiion in the file, with the first level listed in the file having index 0.

Type:

int

Boltzmann_level_population(Z, T)
Calculates the fractional population of the level using a Boltzmann

distribution.

Parameters:

  • Z (float) – The partition function.

  • T (float) – The temperature in [K].

Returns:

The fractional population of the level using a Boltzmann

distribution.

Return type:

float

class pythonradex.atomic_transition.RadiativeTransition(up, low, A21, nu0=None)

Represents the radiative transition between two energy levels.

up

the upper level of the transition

Type:

pythonradex.atomic_transition.Level

low

the lower level of the transition

Type:

pythonradex.atomic_transition.Level

Delta_E

the energy difference between the upper and lower level

Type:

float

name

name of the transition

Type:

str

nu0

rest frequency in [Hz]

Type:

float

A21

Einstein A21 coefficient in [s-1]

Type:

float

B21

Einstein B21 coefficient in [sr m2 Hz / Jy]

Type:

float

B12

Einstein B12 coefficient in [sr m2 Hz / Jy]

Type:

float

Tex(x1, x2)

Computes the excitation temperature.

Parameters:

  • x1 – (numpy.ndarray): fractional population of the lower level

  • x2 – (numpy.ndarray): fractional population of the upper level

Returns:

excitation temperature in [K]

Return type:

numpy.ndarray

class pythonradex.atomic_transition.EmissionLine(up, low, A21, line_profile_type, width_v, nu0=None)

Represents an emission line arising from the radiative transition between two levels

up

the upper level of the transition

Type:

pythonradex.atomic_transition.Level

low

the lower level of the transition

Type:

pythonradex.atomic_transition.Level

Delta_E

the energy difference between the upper and lower level in [J]

Type:

float

name

name of the transition

Type:

str

nu0

rest frequency in [Hz]

Type:

float

A21

Einstein A21 coefficient in [s-1]

Type:

float

B21

Einstein B21 coefficient in [sr m2 Hz / Jy]

Type:

float

B12

Einstein B12 coefficient in [sr m2 Hz / Jy]

Type:

float

line_profile

object representing the shape of the line profile

Type:

pythonradex.atomic_transition.LineProfile

tau(N1, N2, nu)

Computes the optical depth

Parameters:

  • N1 – (float): column density of molecules in the lower level in [m-2]

  • N2 – (float): column density of molecules in the upper level in [m-2]

  • nu – (numpy.ndarray): frequencies in [Hz]

Returns:

the optical depth at the requested frequencies

Return type:

numpy.ndarray

tau_nu0(N1, N2)

Computes the optical depth at the rest frequency

Parameters:

  • N1 – (float or numpy.ndarray): column density of molecules in the lower level in [m-2]

  • N2 – (float or numpy.ndarray): column density of molecules in the upper level in [m-2]

Returns:

the optical depth at the rest frequency

Return type:

float or numpy.ndarray

Tex(x1, x2)

Computes the excitation temperature.

Parameters:

  • x1 – (numpy.ndarray): fractional population of the lower level

  • x2 – (numpy.ndarray): fractional population of the upper level

Returns:

excitation temperature in [K]

Return type:

numpy.ndarray

class pythonradex.atomic_transition.CollisionalTransition(up, low, K21_data, Tkin_data)

Represents the collisional transition between two energy levels

up

the upper level of the transition

Type:

pythonradex.atomic_transition.Level

low

the lower level of the transition

Type:

pythonradex.atomic_transition.Level

Delta_E

the energy difference between the upper and lower level in [J]

Type:

float

name

name of the transition

Type:

str

Tex(x1, x2)

Computes the excitation temperature.

Parameters:

  • x1 – (numpy.ndarray): fractional population of the lower level

  • x2 – (numpy.ndarray): fractional population of the upper level

Returns:

excitation temperature in [K]

Return type:

numpy.ndarray

coeffs(Tkin)

Computes the collisional coefficients

Parameters:

Tkin (float or numpy.ndarray) – kinetic temperature in [K]

Returns:

The collision coefficients K12 and K21 in [m3/s] at the requested temperature(s)

Return type:

tuple

Raises:

AssertionError – If Tkin is outside the available temperature range.

class pythonradex.molecule.Molecule(datafilepath, partition_function=None)

Represents an atom or molecule with data read from a LAMDA file

levels

The energy levels of the molecule, in the same order as in the LAMDA file.

Type:

list of pythonradex.atomic_transition.Level

rad_transitions

The radiative transitions of the molecule, in the same order as in the LAMDA file.

Type:

list of pythonradex.atomic_transition.RadiativeTransition

coll_transitions

The collisional transitions of the molecule. The dictionary keys correspond to the different colliders. Each entry of the dictionary is a list of pythonradex.atomic_transition.CollisionalTransition objects, in the same order as in the LAMDA file.

Type:

dict

n_levels

the total number of levels

Type:

int

n_rad_transitions

the total number of radiative transitions

Type:

int

__init__(datafilepath, partition_function=None)

Constructs a new instance of the Molecule class using a LAMDA datafile

Parameters:

  • datafilepath (str) – The filepath to the LAMDA file.

  • partition_function (func) – A user-supplied partition function of one argument (temperature). Defaults to None. If equal to None, the partition function will be calculated by using the data from the provided LAMDA file.

Boltzmann_level_population(T)
Computes the level populations for all levels using a Boltzmann

distribution (e.g. LTE).

Parameters:

T (float or numpy.ndarray) – The temperature.

Returns:

The fractional level population. If only one temperature was given as input, the output array is one-dimensional, with the level populations corresponding to the levels in the order of the LAMDA file. If an array of temperatures was given as input, the output array has two dimensions, with the second corresponding to the different temperatures.

Return type:

numpy.ndarray

class pythonradex.molecule.EmittingMolecule(datafilepath, line_profile_type, width_v, read_frequencies=False, partition_function=None)

Represents a an emitting molecule, i.e. a molecule with a specified line profile

levels

The energy levels of the molecule, in the same order as in the LAMDA file.

Type:

list of pythonradex.atomic_transition.Level

rad_transitions

The radiative transitions of the molecule, in the same order as in the LAMDA file.

Type:

list of pythonradex.atomic_transition.EmissionLine

coll_transitions

The collisional transitions of the molecule. The dictionary keys correspond to the different colliders. Each entry of the dictionary is a list of pythonradex.atomic_transition.CollisionalTransition objects, in the same order as in the LAMDA file.

Type:

dict

n_levels

the total number of levels

Type:

int

n_rad_transitions

the total number of radiative transitions

Type:

int

__init__(datafilepath, line_profile_type, width_v, read_frequencies=False, partition_function=None)

Constructs a new instance of the EmittingMolecule class using a LAMDA datafile

Parameters:

  • datafilepath (str) – The filepath to the LAMDA file.

  • line_profile_type (str) – The type of the line profile. Either ‘rectangular’ or ‘Gaussian’

  • width_v (float) – The width of the line profile in [m/s]. For a Gaussian line profile, this corresponds to the FWHM.

  • read_frequencies (bool) – Whether to read the frequencies of the radiative transitions from the file or not. If False, calculates the frequencies from the level energies given in the file. Setting this to True can be useful since frequencies are sometimes given with more significant digits than level energies. However, the LAMDA format does not force a file to contain the frequencies, so they might not be present.

  • partition_function (func) – A user-supplied partition function of one argument (temperature). Defaults to None. If equal to None, the partition function will be calculated by using the data from the provided LAMDA file.

get_tau_nu0_lines(N, level_population)

Compute the optical depth at the rest frequency of all lines (dust and overlapping lines are ignored)

Parameters:

  • N (float) – the column density in [m-2]

  • level_population (numpy.ndarray) – the fractional population of each level, where the levels are in the order of the LAMDA file

Returns:

the optical depth at the rest frequency

Return type:

numpy.ndarray

get_tau_nu0_lines_LTE(N, T)

Compute the optical depth at the rest frequency in LTE for all lines (dust and overlapping lines are ignored)

Parameters:

  • N (float) – the column density in [m-2]

  • T (float) – the temperature in [K]

Returns:

the optical depth at the rest frequency assuming LTE

Return type:

numpy.ndarray

get_Tex(level_population)

Compute the excitation temperature for all radiative transitions

Parameters:

level_population (numpy.ndarray) – the fractional population of each level, where the levels are in the order of the LAMDA file

Returns:

the excitation temperature for each radiative transition, in the order as in the LAMDA file

Return type:

numpy.ndarray

Representation of line profiles

pyhonradex allows two types of line profiles: Gaussian and rectangular. These are represented by the following classes.

class pythonradex.atomic_transition.GaussianLineProfile(nu0, width_v)

Represents a Gaussian line profile

nu0

rest frequency in [Hz]

Type:

float

width_nu

FWHM in [Hz]

Type:

float

width_v

FWHM in [m/s]

Type:

float

phi_nu(nu)

The value of the line profile in frequency space.

The line profile is normalised such that its integral over frequency equals 1.

Parameters:

nu (float or numpy.ndarray) – frequency in [Hz]

Returns:

The line profile in [Hz-1]

Return type:

float or numpy.ndarray

phi_v(v)

The value of the line profile in velocity space.

The line profile is normalised such that its integral over velocity equals 1.

Parameters:

v (float or numpy.ndarray) – velocity in [m/s]

Returns:

The line profile in [(m/s)-1]

Return type:

float or numpy.ndarra

class pythonradex.atomic_transition.RectangularLineProfile(nu0, width_v)

Represents a rectangular line profile, i.e. constant over width_v, 0 outside

phi_nu(nu)

The value of the line profile in frequency space.

The line profile is normalised such that its integral over frequency equals 1.

Parameters:

nu (float or numpy.ndarray) – frequency in [Hz]

Returns:

The line profile in [Hz-1]

Return type:

float or numpy.ndarray

phi_v(v)

The value of the line profile in velocity space.

The line profile is normalised such that its integral over velocity equals 1.

Parameters:

v (float or numpy.ndarray) – velocity in [m/s]

Returns:

The line profile in [(m/s)-1]

Return type:

float or numpy.ndarra

Convenience functions

The helpers module provides a number of convenience functions.

pythonradex.helpers.B_nu(nu, T)

Planck function (black body)

Parameters:

  • nu (float or numpy.ndarray) – frequency in [Hz]

  • T (float or numpy.ndarray) – temperature in [K]

Returns:

value of Planck function in [W/m2/Hz/sr]

Return type:

float or numpy.ndarray

pythonradex.helpers.generate_CMB_background(z=0)

generates a function that gives the CMB background at redshift z

Parameters:

z – (float): redshift

Returns:

a function giving CMB background in [W/m2/Hz/sr] for an input frequency in [Hz]

Return type:

func

pythonradex.helpers.FWHM2sigma(FWHM)

Convert FWHM of a Gaussian to standard deviation.

Parameters:

FWHM (float or numpy.ndarray) – FWHM of the Gaussian

Returns:

the standard deviation corresponding to the input FWHM

Return type:

float or numpy.ndarray

pythonradex.helpers.RJ_brightness_temperature(specific_intensity, nu)

calculates the Rayleigh-Jeans brightness temperature

Parameters:

  • specific_intensity (float or numpy.ndarray) – the specific intensity in [W/m2/Hz/sr]

  • nu (float or numpy.ndarray) – the frequency in [Hz]

Returns:

the Rayleigh-Jeans brightness temperature in [K]

Return type:

float or numpy.ndarray

pythonradex.helpers.Planck_brightness_temperature(specific_intensity, nu)

calculates the Planck brightness temperature

Parameters:

  • specific_intensity (float or numpy.ndarray) – the specific intensity in [W/m2/Hz/sr]

  • nu (float or numpy.ndarray) – the frequency in [Hz]

Returns:

the Planck brightness temperature in [K]

Return type:

float or numpy.ndarray