Parameters Reference¶

This page provides a complete reference for all keyword arguments accepted by PyExoCross API functions. Parameters are organized by category.

Species Identification¶

Parameter	Type	Default	Description	Databases
`database`	`str`	`'ExoMol'`	Database type	All
`molecule`	`str`	`None`	Molecule name (e.g. `'H2O'`, `'MgH'`, `'NO'`)	ExoMol, HITRAN, HITEMP
`atom`	`str`	`None`	Atom name (e.g. `'Ar'`, `'Li'`, `'Al'`)	ExoAtom
`isotopologue`	`str`	`None`	Isotopologue (e.g. `'1H2-16O'`, `'24Mg-1H'`)	ExoMol, HITRAN, HITEMP
`dataset`	`str`	`None`	Dataset name (e.g. `'POKAZATEL'`, `'XAB'`, `'NIST'`)	All
`species_id`	`int`	`0`	Numeric species identifier	All

`database` Accepted Values¶

Value	Description
`'ExoMol'`	ExoMol molecular database (default)
`'ExoAtom'`	ExoAtom atomic database
`'HITRAN'`	HITRAN molecular spectroscopic database
`'HITEMP'`	HITEMP high-temperature extension of HITRAN

`species_id` Encoding¶

The species_id is a compact numeric identifier. The first digit(s) encode the species main ID and the last digit encodes the species sub ID:

species_id = species_main_id * 10 + species_sub_id

Database	Example	`species_id`	Main ID	Sub ID	Meaning
ExoMol	MgH (24Mg-1H)	`501`	`50`	`1`	HITRAN molecule ID #50, isotopologue ID #1
ExoAtom	Ar	`601`	`60`	`1`	HITRAN atom ID #60, isotope ID #1
HITRAN	H2O (1H2-16O)	`11`	`1`	`1`	HITRAN molecule ID #1, isotopologue ID #1
HITRAN	CO2 (12C-16O2)	`21`	`2`	`1`	HITRAN molecule ID #2, isotopologue ID #1
HITRAN	NO (14N-16O)	`81`	`8`	`1`	HITRAN molecule ID #8, isotopologue ID #1
HITRAN	C2H2	`261`	`26`	`1`	HITRAN molecule ID #26, isotopologue ID #1

File Paths¶

Parameter	Type	Default	Description
`read_path`	`str`	`'./'`	Path to input data
`save_path`	`str`	`'./output/'`	Path for output files
`logs_path`	`str`	`None`	Log file path; `None` to skip logging

`read_path` Conventions¶

Database	`read_path` Format	Example
ExoMol	Root directory of ExoMol database	`'/data/ExoMol/'`
ExoAtom	Root directory of ExoAtom database	`'/data/ExoAtom/'`
HITRAN	Root directory of HITRAN database	`'/data/HITRAN/'`
HITEMP	Root directory of HITEMP database	`'/data/HITEMP/'`

For ExoMol, the code automatically resolves the full path as:

{read_path}/{molecule}/{isotopologue}/{dataset}/

For ExoAtom:

{read_path}/{atom}/{dataset}/

For HITRAN/HITEMP:

  {read_path}/{molecule}/{isotopologue}/

Computing Resources¶

Parameter	Type	Default	Description
`ncputrans`	`int`	`4`	Number of CPU cores for processing each transitions file
`ncpufiles`	`int`	`1`	Number of transitions files processed simultaneously
`chunk_size`	`int`	`100000`	Chunk size when reading/calculating transitions
`run_mode`	`str`	`'CPU'`	Compute backend mode: `'CPU'` (default) or `'GPU'`
`gpu_backend`	`str`	`'AUTO'`	GPU backend policy when `run_mode='GPU'`: `'AUTO'`, `'CUDA'`, `'PyTorch-CUDA'`, `'CuPy-CUDA'`, or `'MPS'`
`gpu_batch_lines`	`int`	`8192`	Max number of lines per GPU batch (memory-control knob)
`gpu_batch_grid`	`int`	`256`	Max number of grid points per GPU batch (memory-control knob)

GPU acceleration scope:

Enabled for cooling_functions, stick_spectra, cross_sections, and stick_spectra_cross_section
Other functions are CPU formula based

gpu_backend behavior:

'AUTO' (recommended): PyTorch-CUDA -> CuPy-CUDA -> MPS -> CPU fallback
'CUDA': PyTorch-CUDA -> CuPy-CUDA -> MPS -> CPU fallback
'PyTorch-CUDA': NVIDIA PyTorch CUDA only; otherwise CPU fallback
'CuPy-CUDA': NVIDIA CuPy CUDA only; otherwise CPU fallback
'MPS': Apple Metal (MPS) only; otherwise CPU fallback

Typical usage:

# CPU (default)
run_mode='CPU'

# GPU (auto backend)
run_mode='GPU'
gpu_backend='AUTO'
gpu_batch_lines=8192
gpu_batch_grid=256

# GPU (auto CUDA provider priority: PyTorch first, then CuPy)
run_mode='GPU'
gpu_backend='CUDA'

# GPU (force PyTorch CUDA only)
run_mode='GPU'
gpu_backend='PyTorch-CUDA'

# GPU (force CuPy CUDA only)
run_mode='GPU'
gpu_backend='CuPy-CUDA'

# GPU (force MPS)
run_mode='GPU'
gpu_backend='MPS'

:::{tip} For large line lists (e.g. H2O with billions of lines), increase chunk_size to reduce I/O overhead. Set ncpufiles > 1 if the species has many separate .trans files (common for ExoMol). :::

Conversion Parameters¶

Used by px.conversion().

Parameter	Type	Default	Description
`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`	Max uncertainty (cm⁻¹); `None` disables
`conversion_threshold`	`float` or `None`	`None`	Min intensity (cm/molecule); `None` disables
`global_qn_label_list`	`list[str]`	`[]`	Global QN labels for HITRAN output
`global_qn_format_list`	`list[str]`	`[]`	Global QN Fortran-style formats
`local_qn_label_list`	`list[str]`	`[]`	Local QN labels for HITRAN output
`local_qn_format_list`	`list[str]`	`[]`	Local QN Fortran-style formats

Quantum Number Formats¶

The global and local quantum number format strings follow HITRAN2004 convention. Each format field is a C/Fortran-style specifier:

global_qn_label_list  = ['ElecState', 'v', 'Omega']
global_qn_format_list = ['%9s', '%2d', '%4s']    # Total: 15 chars

local_qn_label_list   = ['J', 'e/f']
local_qn_format_list  = ['%5.1f', '%2s']         # Total: 15 chars (padded)

:::{important} For HITRAN2004 format, both global and local quantum number fields are exactly 15 characters each. Ensure the sum of format widths matches. :::

Partition Function / Specific Heat / Cooling Function Parameters¶

Used by px.partition_functions(), px.specific_heats(), px.cooling_functions().

Parameter	Type	Default	Description
`ntemp`	`int`	`1`	Temperature step interval in K
`tmax`	`int`	`5000`	Maximum temperature in K

The calculation produces values at every ntemp K from 1 K to tmax K.

Lifetime Parameters¶

Used by px.lifetimes().

Parameter	Type	Default	Description
`compress`	`bool`	`False`	`True` saves output as `.states.bz2`; `False` as `.states`

Oscillator Strength Parameters¶

Used by px.oscillator_strengths().

Parameter	Type	Default	Description
`gf_or_f`	`str`	`'f'`	`'gf'` for weighted oscillator strength, `'f'` for \(f\)-value

Physical Conditions¶

Used by px.stick_spectra(), px.cross_sections(), and px.stick_spectra_cross_section().

Parameter	Type	Default	Description
`temperatures`	`list[float]`	`[1000]`	Temperature(s) in K
`pressures`	`list[float]`	`[1.0]`	Pressure(s) in bar (cross sections only)
`wn_wl`	`str`	`'WN'`	`'WN'` = wavenumber, `'WL'` = wavelength
`wn_wl_unit`	`str`	`'cm-1'`	Unit: `'cm-1'`, `'um'` (micron), or `'nm'`
`min_range`	`float`	`0`	Minimum of range (in `wn_wl_unit`)
`max_range`	`float`	`30000`	Maximum of range (in `wn_wl_unit`)
`abs_emi`	`str`	`'Ab'`	`'Ab'` = absorption, `'Em'` = emission

Non-LTE Parameters¶

Used by px.stick_spectra(), px.cross_sections(), and px.stick_spectra_cross_section() when nlte_method != 'L'.

Parameter	Type	Default	Description
`nlte_method`	`str`	`'L'`	Non-LTE method (see table below)
`tvib_list`	`list[float]`	`[]`	Vibrational temperature(s) in K
`trot_list`	`list[float]`	`[]`	Rotational temperature(s) in K
`vib_label`	`list[str]`	`[]`	Vibrational quantum number labels
`rot_label`	`list[str]`	`[]`	Rotational quantum number labels
`nlte_path`	`str`	`None`	Path to NLTE data file

Non-LTE Methods¶

Value	Name	Description	Required Parameters
`'L'`	LTE	Local thermodynamic equilibrium (default)	`temperatures`
`'T'`	Treanor	Two-temperature model	`temperatures`, `tvib_list`, `trot_list`, `vib_label`, `rot_label`
`'D'`	Density	Number density NLTE	`temperatures`, `trot_list`, `nlte_path`
`'P'`	Population	Population NLTE	`temperatures`, `nlte_path`

Filter Parameters¶

Used by px.stick_spectra(), px.cross_sections(), and px.stick_spectra_cross_section().

Parameter	Type	Default	Description
`threshold`	`float` or `None`	`None`	Minimum intensity threshold (cm/molecule)
`unc_filter`	`float` or `None`	`None`	Maximum uncertainty filter (cm⁻¹)
`qns_filter`	`dict` or `None`	`None`	Quantum number filter dictionary

`qns_filter` Format¶

A dictionary mapping quantum number label to a list of accepted value patterns. An empty list [] means “accept all values”.

# Accept only v' = 0, 1, 2; v" = 5; v' = 7 and v" = 7, and all parities
qns_filter = {
    'v': ['0,', '1,', '2,', ',5', '7,7'],
    '+/-': [],
}

# Accept all configuration, Multiple, and parity
qns_filter = {
    'configuration': [],
    'Multiple': [],
    'parity': [],
}

Quantum Number Parameters¶

Parameter	Type	Default	Description
`qnslabel_list`	`list[str]`	`[]`	Quantum number column labels
`qnsformat_list`	`list[str]`	`[]`	Quantum number format specifiers

The labels and formats must correspond to the columns in the .states file after the standard columns (ID, energy, degeneracy, lifetime).

ExoMolHR No need.

ExoMol Example (MgH XAB):

qnslabel_list  = ['+/-', 'e/f', 'ElecState', 'v', 'Lambda', 'Sigma', 'Omega']
qnsformat_list = ['%1s', '%1s', '%12s', '%3d', '%3d', '%5.1f', '%5.1f']

ExoAtom Example (Ar NIST):

qnslabel_list  = ['configuration', 'Multiple', 'parity']
qnsformat_list = ['%20s', '%10s', '%2s']

HITRAN Example (NO):

qnslabel_list  = ['J', 'X', 'Omega', 'v1', 'Sym', 'F']
qnsformat_list = ['%5.1f', '%2s', '%3s', '%2d', '%1s', '%5s']

Line Profile Parameters¶

Used by px.cross_sections().

Parameter	Type	Default	Description
`profile`	`str`	`'Gaussian'`	Line profile type
`cutoff`	`float` or `None`	`None`	Wing cutoff distance (cm⁻¹); `None` for no cutoff
`predissociation`	`bool`	`False`	Include predissociation lifetimes for Voigt width

Broadening Parameters¶

Used by px.cross_sections().

Parameter	Type	Default	Description
`broadeners`	`list[str]`	`['Default']`	Broadening species (e.g. `['H2', 'He']`)
`ratios`	`list[float]`	`[1.0]`	Mixing ratios (must sum to 1.0)
`alpha_hwhm`	`float` or `None`	`3.0`	Constant Doppler HWHM (cm⁻¹); `None` to auto-calculate
`gamma_hwhm`	`float` or `None`	`None`	Constant Lorentzian HWHM (cm⁻¹); `None` to auto-calculate

:::{tip} Set alpha_hwhm=None and gamma_hwhm=None to let PyExoCross calculate HWHMs from broadening parameters in the database. Use constant values for quick testing or when database broadening files are unavailable. :::

Grid Parameters¶

Used by px.cross_sections().

Parameter	Type	Default	Description
`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`)

:::{note} If both bin_size and n_point are specified, n_point takes precedence and bin_size is calculated from the range. :::

Plotting Parameters¶

Used by px.oscillator_strengths(), px.stick_spectra(), px.cross_sections(), and px.stick_spectra_cross_section().

Parameter	Type	Default	Description
`plot`	`bool`	`False`	Whether to generate a plot
`plot_method`	`str`	`'log'`	`'log'` or `'linear'` scale
`plot_wn_wl`	`str`	`'WN'`	X-axis: `'WN'` (wavenumber) or `'WL'` (wavelength)
`plot_unit`	`str`	`'cm-1'`	X-axis unit: `'cm-1'`, `'um'`, or `'nm'`
`limit_yaxis`	`float`	`1e-30`	Lower limit for y-axis

:::{note} These are convenience kwargs that get remapped internally to function-specific names. For example, plot=True in px.cross_sections() becomes plot_cross_section=True. :::

Parameters Reference¶

Species Identification¶

`database` Accepted Values¶

`species_id` Encoding¶

File Paths¶

`read_path` Conventions¶

Computing Resources¶

Conversion Parameters¶

Quantum Number Formats¶

Partition Function / Specific Heat / Cooling Function Parameters¶

Lifetime Parameters¶

Oscillator Strength Parameters¶

Physical Conditions¶

Non-LTE Parameters¶

Non-LTE Methods¶

Filter Parameters¶

`qns_filter` Format¶

Quantum Number Parameters¶

Line Profile Parameters¶

Broadening Parameters¶

Grid Parameters¶

Plotting Parameters¶

Table of Contents

Previous topic

Next topic

This Page

Parameters Reference¶

Species Identification¶

database Accepted Values¶

species_id Encoding¶

File Paths¶

read_path Conventions¶

Computing Resources¶

Conversion Parameters¶

Quantum Number Formats¶

Partition Function / Specific Heat / Cooling Function Parameters¶

Lifetime Parameters¶

Oscillator Strength Parameters¶

Physical Conditions¶

Non-LTE Parameters¶

Non-LTE Methods¶

Filter Parameters¶

qns_filter Format¶

Quantum Number Parameters¶

Line Profile Parameters¶

Broadening Parameters¶

Grid Parameters¶

Plotting Parameters¶

`database` Accepted Values¶

`species_id` Encoding¶

`read_path` Conventions¶

`qns_filter` Format¶