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, ExoMolHR, HITRAN, HITEMP
`atom`	`str`	`None`	Atom name (e.g. `'Ar'`, `'Li'`, `'Al'`)	ExoAtom
`isotopologue`	`str`	`None`	Isotopologue (e.g. `'1H2-16O'`, `'24Mg-1H'`)	ExoMol, ExoMolHR, 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
`'ExoMolHR'`	ExoMolHR molecular database
`'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
ExoMolHR	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/'`
ExoMolHR	Root directory of ExoMolHR database	`'/data/ExoMolHR/'`
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:

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

For ExoMolHR, this folder should contain only one .csv file:

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

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
`device` or `run_mode`	`str`	`'CPU'`	Compute backend mode: `'CPU'` or `'GPU'`
`gpu_backend`	`str`	`'AUTO'`	GPU backend policy when `device='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)
`cache`	`str`	`'auto'`	Transition cache: small inputs use memory and large inputs use Parquet; alternatives are `'parquet'` and `'none'`
`cache_dir`	`str` or `None`	`None`	Cache directory; `None` uses a source-adjacent `.pyexocross_cache/` directory
`max_memory`	`int`	`512`	Maximum transition data retained by `cache='auto'`, in MB; internally converted with `1024**2` bytes per MB
`refresh`	`bool`	`False`	Rebuild matching Parquet cache files
`all_transitions`	`bool`	`False`	`px.load` only: eagerly load every transition file; whole-list functions expand automatically when needed

GPU acceleration scope:

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

Parquet caches are shared by CPU and GPU modes. PyArrow currently reads and decodes Parquet on the CPU, and the selected arrays are then transferred to the GPU. GPU mode accelerates supported numerical kernels; it does not currently accelerate file I/O or Parquet decoding.

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)
device='CPU'

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

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

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

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

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

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:

For ExoMol, ExoMolHR, and ExoAtom input, global_qn_format_list and local_qn_format_list can be omitted when all requested labels are available in the definition metadata. Metadata namespaces are shortened before matching, so labels such as Herzberg:n1 are requested as n1. \

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)

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
`abundance`	`float`	`1.0`	Optional isotopic abundance multiplier

Note

wn_wl and wn_wl_unit define the calculation and saved-output coordinate, not just labels.
With wn_wl='WN', saved .stick and .xsec files use wavenumber as the first column.
With wn_wl='WL', saved files use wavelength as the first column in wn_wl_unit.
Plotting parameters can use a different coordinate and only affect figure x-axes.

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]`	`[]`	Optional quantum number label
`qnsformat_list`	`list[str]`	`[]`	Optional quantum number format

For ExoMol and ExoAtom input, the labels and formats are read from the definition metadata (.def.json, .def, or .adef.json) by default.
For ExoMolHR input, the labels and formats are read from the default metadata automatically.
Namespace prefixes are removed, for example Herzberg:n1 becomes n1 and qn:configuration becomes configuration. Optional state columns such as uncertainty, lifetime, and oscillator strength are not added to the automatic quantum number list.

Provide qnslabel_list and qnsformat_list only for custom/legacy files or when you need to override the metadata. In that case, the labels and formats must correspond to the quantum number columns in the .states file.

ExoMolHR No need.

ExoMol override example (MgH XAB):

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

ExoAtom override 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`	`None`	Constant Doppler HWHM (cm⁻¹); `None` to auto-calculate
`gamma_hwhm`	`float` or `None`	`None`	Constant Lorentzian HWHM (cm⁻¹); `None` to auto-calculate

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.

For HITRAN and HITEMP, Default uses air broadening (gamma_air), consistent with the standard HAPI convention (GammaL='gamma_air').

For standard HITRAN air-broadened calculations, use:

broadeners=['Air'],
ratios=[1.0],

To mix air and self broadening, use for example:

broadeners=['Air', 'Self'],
ratios=[0.7, 0.3],

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.
For wavelength calculations, bin_size is a wavelength interval.
For example, wn_wl='WL', wn_wl_unit='nm', and bin_size=0.01 means a 0.01 nm grid spacing.
cutoff, alpha_hwhm, and gamma_hwhm remain in cm⁻¹ because line profiles are evaluated in wavenumber space internally.

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¶