Functions Reference¶

All functions are accessible from the top-level pyexocross namespace:

import pyexocross as px

Every function accepts either:

An .inp file path via inp_filepath, or
Keyword arguments (**kwargs), or
Both (keyword arguments override .inp file values).

Common CPU/GPU Compute Kwargs¶

PyExoCross uses CPU by default. You can explicitly select compute mode with:

Kwarg	Type	Default	Description
`run_mode`	`str`	`'CPU'`	`'CPU'` or `'GPU'`
`gpu_backend`	`str`	`'AUTO'`	GPU backend policy: `'AUTO'`, `'CUDA'`, `'PyTorch-CUDA'`, `'CuPy-CUDA'`, or `'MPS'`
`gpu_batch_lines`	`int`	`8192`	GPU line-batch size for memory control
`gpu_batch_grid`	`int`	`256`	GPU grid-batch size for memory control

GPU acceleration is available for:

px.cooling_functions
px.stick_spectra
px.cross_sections
px.stick_spectra_cross_section

CPU formulas are used for:

px.conversion
px.partition_functions
px.specific_heats
px.lifetimes
px.oscillator_strengths

If run_mode='GPU' but no compatible backend is available, PyExoCross falls back to CPU formulas.

# Default CPU mode
px.cross_sections(..., run_mode='CPU')

# GPU mode (auto backend)
px.cross_sections(
    ...,
    run_mode='GPU',
    gpu_backend='AUTO',
    gpu_batch_lines=8192,
    gpu_batch_grid=256,
)

# CUDA policy: PyTorch-CUDA -> CuPy-CUDA -> MPS -> CPU fallback
px.cross_sections(..., run_mode='GPU', gpu_backend='CUDA')

# Force PyTorch CUDA only
px.cross_sections(..., run_mode='GPU', gpu_backend='PyTorch-CUDA')

# Force CuPy CUDA only
px.cross_sections(..., run_mode='GPU', gpu_backend='CuPy-CUDA')

# Force PyTorch MPS only
px.cross_sections(..., run_mode='GPU', gpu_backend='MPS')

`px.run`¶

px.run(inp_filepath, force_reload=False)

Run all enabled functions from an .inp configuration file. This is the programmatic equivalent of running python3 run.py -p <inp_filepath> from the command line.

Parameters

Parameter	Type	Required	Description
`inp_filepath`	`str`	Yes	Path to the `.inp` configuration file
`force_reload`	`bool`	No	Force re-parse of `.inp` even when cached in current Python process (default: `False`)

:::{note} If you edit the same .inp file repeatedly in a long-lived session (e.g. Jupyter), use force_reload=True to avoid reusing stale cached parameters. :::

Example

px.run('/path/to/MgH_ExoMol.inp')

# Re-read updated .inp content in the same session
px.run('/path/to/MgH_ExoMol.inp', force_reload=True)

`px.conversion`¶

px.conversion(inp_filepath=None, **kwargs)

Convert between ExoMol/ExoAtom and HITRAN line-list formats.

Parameters

Parameter	Type	Default	Description
`inp_filepath`	`str`	`None`	Path to `.inp` file
`database`	`str`	`'ExoMol'`	`'ExoMol'`, `'ExoAtom'`, `'HITRAN'`, or `'HITEMP'`
`molecule`	`str`	`None`	Molecule name (e.g. `'MgH'`, `'NO'`)
`atom`	`str`	`None`	Atom name for ExoAtom (e.g. `'Ar'`, `'Li'`)
`isotopologue`	`str`	`None`	Isotopologue (e.g. `'24Mg-1H'`, `'14N-16O'`)
`dataset`	`str`	`None`	Dataset name (e.g. `'XAB'`, `'NIST'`)
`species_id`	`int`	`0`	Species identifier (e.g. `501`, `81`)
`read_path`	`str`	`'./'`	Path to input database
`save_path`	`str`	`'./output/'`	Path for output files
`logs_path`	`str`	`None`	Log file path
`conversion_format`	`str`	`None`	`'ExoMo'` = HITRAN/HITEMP -> ExoMol/ExoAtom, `'HITRAN'` = ExoMol/ExoMolHR/ExoAtom -> HITRAN/HITEMP
`conversion_min_freq`	`float`	`0`	Minimum frequency in cm⁻¹
`conversion_max_freq`	`float`	`30000`	Maximum frequency in cm⁻¹
`conversion_unc`	`float` or `None`	`None`	Uncertainty filter (cm⁻¹); `None` to disable
`conversion_threshold`	`float` or `None`	`None`	Intensity threshold (cm/molecule); `None` to disable
`global_qn_label_list`	`list[str]`	`[]`	Global quantum number labels for HITRAN output
`global_qn_format_list`	`list[str]`	`[]`	Global QN format specifiers (total 15 chars in HITRAN2004)
`local_qn_label_list`	`list[str]`	`[]`	Local quantum number labels for HITRAN output
`local_qn_format_list`	`list[str]`	`[]`	Local QN format specifiers (total 15 chars in HITRAN2004)
`qnslabel_list`	`list[str]`	`[]`	Quantum number labels from `.states` file
`qnsformat_list`	`list[str]`	`[]`	Quantum number format specifiers
`ncputrans`	`int`	`4`	CPU cores for processing transitions
`ncpufiles`	`int`	`1`	Files processed simultaneously
`chunk_size`	`int`	`100000`	Chunk size for transitions

Legacy Aliases

px.convert_exomol_to_hitran(...)     # Sets conversion_format='HITRAN'
px.convert_exomolhr_to_hitran(...)   # Sets conversion_format='HITRAN'
px.convert_exoatom_to_hitran(...)    # Sets conversion_format='HITRAN'
px.convert_hitran_to_exomol(...)     # Sets conversion_format='ExoMol'

Example

px.conversion(
    database='ExoMol',
    molecule='MgH',
    isotopologue='24Mg-1H',
    dataset='XAB',
    species_id=501,
    read_path='/path/to/ExoMol/',
    save_path='/path/to/output/',
    conversion_format='HITRAN',
    global_qn_label_list=['ElecState', 'v', 'Omega'],
    global_qn_format_list=['%9s', '%2d', '%4s'],
    local_qn_label_list=['J', 'e/f'],
    local_qn_format_list=['%5.1f', '%2s'],
)

`px.partition_functions`¶

px.partition_functions(inp_filepath=None, **kwargs)

Calculate partition functions $Q(T) = \sum_n g_n^{\text{tot}} \exp(-c_2 \tilde{E}_n / T)$.

Parameters

Parameter	Type	Default	Description
`inp_filepath`	`str`	`None`	Path to `.inp` file
`database`	`str`	`'ExoMol'`	Database name
`molecule`	`str`	`None`	Molecule name
`atom`	`str`	`None`	Atom name (ExoAtom)
`isotopologue`	`str`	`None`	Isotopologue
`dataset`	`str`	`None`	Dataset name
`species_id`	`int`	`0`	Species identifier
`read_path`	`str`	`'./'`	Input database path
`save_path`	`str`	`'./output/'`	Output path
`logs_path`	`str`	`None`	Log file path
`ntemp`	`int`	`1`	Temperature step in K
`tmax`	`int`	`5000`	Maximum temperature in K
`ncputrans`	`int`	`4`	CPU cores for transitions
`ncpufiles`	`int`	`1`	Files processed simultaneously
`chunk_size`	`int`	`100000`	Chunk size

Legacy Alias: px.partition_function

Example

px.partition_functions(
    database='ExoMol',
    molecule='MgH',
    isotopologue='24Mg-1H',
    dataset='XAB',
    species_id=501,
    read_path='/path/to/ExoMol/',
    save_path='/path/to/output/',
    ntemp=1,
    tmax=5000,
)

`px.specific_heats`¶

px.specific_heats(inp_filepath=None, **kwargs)

Calculate specific heat capacities $C_p(T)$ using partition function derivatives.

Parameters: Same as px.partition_functions.

Legacy Alias: px.specific_heat

Example

px.specific_heats(
    database='ExoMol',
    molecule='MgH',
    isotopologue='24Mg-1H',
    dataset='XAB',
    species_id=501,
    read_path='/path/to/ExoMol/',
    save_path='/path/to/output/',
    ntemp=1,
    tmax=5000,
)

`px.cooling_functions`¶

px.cooling_functions(inp_filepath=None, **kwargs)

Calculate cooling functions:

\[W(T) = \frac{1}{4\pi Q(T)} \sum_{f,i} A_{fi}\, h c \tilde{\nu}_{fi}\, g'\, \exp\!\left(-\frac{c_2 \tilde{E}'}{T}\right)\]

Parameters

Same as px.partition_functions, plus optional compute backend kwargs:

Parameter	Type	Default	Description
`run_mode`	`str`	`'CPU'`	`'CPU'` or `'GPU'`
`gpu_backend`	`str`	`'AUTO'`	`'AUTO'`, `'CUDA'`, `'PyTorch-CUDA'`, `'CuPy-CUDA'`, or `'MPS'`
`gpu_batch_lines`	`int`	`8192`	GPU line-batch size (memory control)
`gpu_batch_grid`	`int`	`256`	GPU grid-batch size (memory control)

Legacy Alias: px.cooling_function

Example

px.cooling_functions(
    database='ExoMol',
    molecule='MgH',
    isotopologue='24Mg-1H',
    dataset='XAB',
    species_id=501,
    read_path='/path/to/ExoMol/',
    save_path='/path/to/output/',
    ntemp=1,
    tmax=5000,
    run_mode='CPU',
)

`px.lifetimes`¶

px.lifetimes(inp_filepath=None, **kwargs)

Calculate radiative lifetimes: $$\tau_i = 1 / \sum_f A_{fi}$$

Parameters

Parameter	Type	Default	Description
`inp_filepath`	`str`	`None`	Path to `.inp` file
`database`	`str`	`'ExoMol'`	Database name
`molecule`	`str`	`None`	Molecule name
`atom`	`str`	`None`	Atom name (ExoAtom)
`isotopologue`	`str`	`None`	Isotopologue
`dataset`	`str`	`None`	Dataset name
`species_id`	`int`	`0`	Species identifier
`read_path`	`str`	`'./'`	Input database path
`save_path`	`str`	`'./output/'`	Output path
`logs_path`	`str`	`None`	Log file path
`compress`	`bool`	`False`	`True` to save as `.bz2`; `False` for uncompressed
`ncputrans`	`int`	`4`	CPU cores for transitions
`ncpufiles`	`int`	`1`	Files processed simultaneously
`chunk_size`	`int`	`100000`	Chunk size

Legacy Alias: px.lifetime

Example

px.lifetimes(
    database='ExoMol',
    molecule='MgH',
    isotopologue='24Mg-1H',
    dataset='XAB',
    species_id=501,
    read_path='/path/to/ExoMol/',
    save_path='/path/to/output/',
    compress=False,
)

`px.oscillator_strengths`¶

px.oscillator_strengths(inp_filepath=None, **kwargs)

Calculate oscillator strengths: weighted $gf = g_{\text{tot}}' A_{fi} / (c \tilde{\nu}_{fi})^2$ or unweighted $f$-values.

Parameters

Parameter	Type	Default	Description
`inp_filepath`	`str`	`None`	Path to `.inp` file
`database`	`str`	`'ExoMol'`	Database name
`molecule`	`str`	`None`	Molecule name
`atom`	`str`	`None`	Atom name (ExoAtom)
`isotopologue`	`str`	`None`	Isotopologue
`dataset`	`str`	`None`	Dataset name
`species_id`	`int`	`0`	Species identifier
`read_path`	`str`	`'./'`	Input database path
`save_path`	`str`	`'./output/'`	Output path
`logs_path`	`str`	`None`	Log file path
`gf_or_f`	`str`	`'f'`	`'gf'` for weighted, `'f'` for unweighted
`ncputrans`	`int`	`4`	CPU cores for transitions
`ncpufiles`	`int`	`1`	Files processed simultaneously
`chunk_size`	`int`	`100000`	Chunk size
`plot`	`bool`	`False`	Whether to generate a plot
`plot_method`	`str`	`'log'`	`'log'` or `'linear'`
`plot_wn_wl`	`str`	`'WN'`	`'WN'` (wavenumber) or `'WL'` (wavelength)
`plot_unit`	`str`	`'cm-1'`	`'cm-1'`, `'um'`, or `'nm'`
`limit_yaxis`	`float`	`1e-30`	Lower limit for y-axis

Legacy Alias: px.oscillator_strength

Example

px.oscillator_strengths(
    database='ExoMol',
    molecule='MgH',
    isotopologue='24Mg-1H',
    dataset='XAB',
    species_id=501,
    read_path='/path/to/ExoMol/',
    save_path='/path/to/output/',
    gf_or_f='f',
    plot=True,
    plot_method='log',
    plot_wn_wl='WN',
    plot_unit='cm-1',
    limit_yaxis=1e-30,
)

`px.stick_spectra`¶

px.stick_spectra(inp_filepath=None, **kwargs)

Calculate LTE or Non-LTE stick spectra (absorption or emission).

Parameters

Parameter	Type	Default	Description
`inp_filepath`	`str`	`None`	Path to `.inp` file
Species
`database`	`str`	`'ExoMol'`	`'ExoMol'`, `'ExoAtom'`, `'HITRAN'`, or `'HITEMP'`
`molecule`	`str`	`None`	Molecule name
`atom`	`str`	`None`	Atom name (ExoAtom)
`isotopologue`	`str`	`None`	Isotopologue
`dataset`	`str`	`None`	Dataset name
`species_id`	`int`	`0`	Species identifier
Paths
`read_path`	`str`	`'./'`	Input database path
`save_path`	`str`	`'./output/'`	Output path
`logs_path`	`str`	`None`	Log file path
Physical conditions
`temperatures`	`list[float]`	`[1000]`	Temperature(s) in K
`wn_wl`	`str`	`'WN'`	`'WN'` (wavenumber) or `'WL'` (wavelength)
`wn_wl_unit`	`str`	`'cm-1'`	`'cm-1'`, `'um'`, or `'nm'`
`min_range`	`float`	`0`	Minimum range value (in `wn_wl_unit`)
`max_range`	`float`	`30000`	Maximum range value (in `wn_wl_unit`)
`abs_emi`	`str`	`'Ab'`	`'Ab'` for absorption, `'Em'` for emission
Non-LTE
`nlte_method`	`str`	`'L'`	`'L'`=LTE, `'T'`=Treanor, `'D'`=Density, `'P'`=Population
`tvib_list`	`list[float]`	`[]`	Vibrational temperatures for method `'T'`
`trot_list`	`list[float]`	`[]`	Rotational temperatures for method `'T'` or `'D'`
`vib_label`	`list[str]`	`[]`	Vibrational QN labels for method `'T'`
`rot_label`	`list[str]`	`[]`	Rotational QN labels for method `'T'`
`nlte_path`	`str`	`None`	Path to NLTE data file (methods `'D'` and `'P'`)
Filters
`threshold`	`float` or `None`	`None`	Intensity threshold (cm/molecule); `None` to disable
`unc_filter`	`float` or `None`	`None`	Uncertainty filter (cm⁻¹); `None` to disable
`qns_filter`	`dict` or `None`	`None`	Quantum number filter (see below)
Quantum numbers
`qnslabel_list`	`list[str]`	`[]`	QN labels from `.states` file
`qnsformat_list`	`list[str]`	`[]`	QN format specifiers
Computing
`ncputrans`	`int`	`4`	CPU cores for transitions
`ncpufiles`	`int`	`1`	Files processed simultaneously
`chunk_size`	`int`	`100000`	Chunk size
`run_mode`	`str`	`'CPU'`	`'CPU'` or `'GPU'`
`gpu_backend`	`str`	`'AUTO'`	`'AUTO'`, `'CUDA'`, `'PyTorch-CUDA'`, `'CuPy-CUDA'`, or `'MPS'`
`gpu_batch_lines`	`int`	`8192`	GPU line-batch size (memory control)
`gpu_batch_grid`	`int`	`256`	GPU grid-batch size (memory control)
Plotting
`plot`	`bool`	`False`	Whether to generate a plot
`plot_method`	`str`	`'log'`	`'log'` or `'linear'`
`plot_wn_wl`	`str`	`'WN'`	X-axis: `'WN'` or `'WL'`
`plot_unit`	`str`	`'cm-1'`	`'cm-1'`, `'um'`, or `'nm'`
`limit_yaxis`	`float`	`1e-30`	Lower limit for y-axis (cm/molecule)

Quantum Number Filter (`qns_filter`)¶

The qns_filter parameter accepts a dictionary where keys are quantum number labels and values are lists of accepted value patterns. Use an empty list [] to accept all values for that label.

qns_filter={
    '+/-': [],                    # accept all parities
    'v': ['0,', '1,', '2,'],      # only v' = 0, 1, 2
    'ElecState': [],              # accept all electronic states
}

Example

px.stick_spectra(
    database='ExoMol',
    molecule='MgH',
    isotopologue='24Mg-1H',
    dataset='XAB',
    species_id=501,
    read_path='/path/to/ExoMol/',
    save_path='/path/to/output/',
    temperatures=[1000, 2000],
    wn_wl='WN',
    wn_wl_unit='cm-1',
    min_range=0,
    max_range=30000,
    abs_emi='Ab',
    run_mode='CPU',
)

`px.cross_sections`¶

px.cross_sections(inp_filepath=None, **kwargs)

Calculate LTE or Non-LTE cross sections with a choice of line profiles.

Parameters

All parameters from px.stick_spectra, plus:

Parameter	Type	Default	Description
Grid
`pressures`	`list[float]`	`[1.0]`	Pressure(s) in bar
`bin_size`	`float`	`0.1`	Bin size (in `wn_wl_unit`); mutually exclusive with `n_point`
`n_point`	`int`	`None`	Number of grid points; mutually exclusive with `bin_size`
Line profile
`profile`	`str`	`'Gaussian'`	Line profile (see table below)
`cutoff`	`float` or `None`	`None`	Wing cutoff in cm⁻¹; `None` to disable
`predissociation`	`bool`	`False`	Use predissociation lifetimes for Voigt width
Broadening
`broadeners`	`list[str]`	`['Default']`	Broadening species
`ratios`	`list[float]`	`[1.0]`	Broadener mixing ratios (must sum to 1.0)
`alpha_hwhm`	`float` or `None`	`3.0`	Constant Doppler HWHM; `None` to calculate
`gamma_hwhm`	`float` or `None`	`None`	Constant Lorentzian HWHM; `None` to calculate
Plotting
`plot`	`bool`	`False`	Whether to generate a plot
`plot_method`	`str`	`'log'`	`'log'` or `'linear'`
`plot_wn_wl`	`str`	`'WN'`	X-axis: `'WN'` or `'WL'`
`plot_unit`	`str`	`'cm-1'`	`'cm-1'`, `'um'`, or `'nm'`
`limit_yaxis`	`float`	`1e-30`	Lower limit for y-axis (cm$^2$/molecule)

Available Line Profiles¶

Profile Name	Description
`'Doppler'`	Pure Doppler profile
`'Gaussian'`	Gaussian profile
`'Lorentzian'`	Lorentzian profile
`'SciPyVoigt'`	Voigt via SciPy `wofz` (recommended)
`'SciPyWofzVoigt'`	Voigt via SciPy `wofz` (alternative)
`'HumlicekVoigt'`	Humlicek algorithm for Voigt
`'PseudoVoigt'`	Generic pseudo-Voigt
`'PseudoThompsonVoigt'`	Thompson pseudo-Voigt approximation
`'PseudoKielkopfVoigt'`	Kielkopf pseudo-Voigt approximation
`'PseudoOliveroVoigt'`	Olivero pseudo-Voigt approximation
`'PseudoLiuLinVoigt'`	Liu-Lin pseudo-Voigt approximation
`'PseudoRoccoVoigt'`	Rocco pseudo-Voigt approximation
`'BinnedDoppler'`	Binned Doppler profile
`'BinnedGaussian'`	Binned Gaussian profile
`'BinnedLorentzian'`	Binned Lorentzian profile
`'BinnedVoigt'`	Binned Voigt profile

Available Broadeners¶

Broadener	Description
`'Default'`	Default broadening parameters
`'Air'`	Air broadening (N$_2$ + O$_2$)
`'Self'`	Self broadening
`'H2'`	Hydrogen broadening
`'He'`	Helium broadening
`'CO2'`	CO$_2$ broadening
`'H2O'`	Water broadening

Legacy Alias: px.cross_section

Example

px.cross_sections(
    database='ExoMol',
    molecule='MgH',
    isotopologue='24Mg-1H',
    dataset='XAB',
    species_id=501,
    read_path='/path/to/ExoMol/',
    save_path='/path/to/output/',
    temperatures=[1000, 2000],
    pressures=[1.0],
    wn_wl='WN',
    wn_wl_unit='cm-1',
    min_range=0,
    max_range=30000,
    bin_size=0.1,
    profile='SciPyVoigt',
    run_mode='GPU',
    gpu_backend='AUTO',
    gpu_batch_lines=8192,
    gpu_batch_grid=256,
    broadeners=['Default'],
    ratios=[1.0],
    cutoff=25.0,
    plot=True,
    plot_method='log',
)

`px.stick_spectra_cross_section`¶

px.stick_spectra_cross_section(inp_filepath=None, **kwargs)

Calculate LTE or Non-LTE stick spectra and cross sections simultaneously.

Parameters

All parameters from px.stick_spectra and px.cross_sections.

Example

px.stick_spectra_cross_section(
    database='ExoMol',
    molecule='MgH',
    isotopologue='24Mg-1H',
    dataset='XAB',
    species_id=501,
    read_path='/path/to/ExoMol/',
    save_path='/path/to/output/',
    temperatures=[1000, 2000],
    pressures=[1.0],
    wn_wl='WN',
    wn_wl_unit='cm-1',
    min_range=0,
    max_range=30000,
    bin_size=0.1,
    profile='SciPyVoigt',
    run_mode='GPU',
    gpu_backend='AUTO',
    gpu_batch_lines=8192,
    gpu_batch_grid=256,
    plot=True,
)

Functions Reference¶

Common CPU/GPU Compute Kwargs¶

`px.run`¶

`px.conversion`¶

`px.partition_functions`¶

`px.specific_heats`¶

`px.cooling_functions`¶

`px.lifetimes`¶

`px.oscillator_strengths`¶

`px.stick_spectra`¶

Quantum Number Filter (`qns_filter`)¶

`px.cross_sections`¶

Available Line Profiles¶

Available Broadeners¶

`px.stick_spectra_cross_section`¶

Table of Contents

Previous topic

Next topic

This Page

Functions Reference¶

Common CPU/GPU Compute Kwargs¶

px.run¶

px.conversion¶

px.partition_functions¶

px.specific_heats¶

px.cooling_functions¶

px.lifetimes¶

px.oscillator_strengths¶

px.stick_spectra¶

Quantum Number Filter (qns_filter)¶

px.cross_sections¶

Available Line Profiles¶

Available Broadeners¶

px.stick_spectra_cross_section¶

`px.run`¶

`px.conversion`¶

`px.partition_functions`¶

`px.specific_heats`¶

`px.cooling_functions`¶

`px.lifetimes`¶

`px.oscillator_strengths`¶

`px.stick_spectra`¶

Quantum Number Filter (`qns_filter`)¶

`px.cross_sections`¶

`px.stick_spectra_cross_section`¶