Python API Reference

PyExoCross provides a full-featured Python API for programmatic access to all functionalities. Instead of writing .inp configuration files, you can call functions directly from Python scripts, Jupyter notebooks, or any other Python environment.

pip install pyexocross

import pyexocross as px

PyExoCross Documentation Homepage

Find more details of input parameters from PyExoCross Documentation Homepage.

Overview

Function

Description

px.run

Run all enabled functions from an .inp file

px.load

Load and preprocess reusable line-list data

px.conversion

Convert between ExoMol and HITRAN data formats

px.partition_functions

Calculate partition functions \(Q(T)\)

px.specific_heats

Calculate specific heats \(C_p(T)\)

px.cooling_functions

Calculate cooling functions \(W(T)\)

px.lifetimes

Calculate radiative lifetimes \(\tau\)

px.oscillator_strengths

Calculate oscillator strengths \(gf\) or \(f\)

px.stick_spectra

Calculate LTE / Non-LTE stick spectra

px.cross_sections

Calculate LTE / Non-LTE cross sections

px.stick_spectra_cross_section

Calculate LTE / Non-LTE stick spectra and cross sections simultaneously

px.download

Download database files (ExoMol, ExoAtom, ExoMolHR, HITRAN)

Supported Databases

Database

Keyword

Species Identifier

ExoMol

database='ExoMol'

molecule, isotopologue, dataset

ExoMolHR

database='ExoMolHR'

molecule, isotopologue

ExoAtom

database='ExoAtom'

atom, dataset

HITRAN

database='HITRAN'

molecule, isotopologue, dataset

HITEMP

database='HITEMP'

molecule, isotopologue, dataset

All listed databases support cache='auto', cache='parquet', and cache='none'. ExoMol/ExoAtom use transition caches; HITRAN/HITEMP cache the normalized fixed-width line list; ExoMolHR caches the normalized CSV line list.

Two Ways to Use PyExoCross Python Package

1. From an .inp file (traditional)

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

# Force re-parse when the same .inp file was edited in this session
px.run('/path/to/config.inp', force_reload=True)

3. Reuse loaded data

data = px.load(
    database='ExoMol',
    molecule='MgH',
    isotopologue='24Mg-1H',
    dataset='XAB',
    read_path='/path/to/ExoMol/',
    min_range=0,
    max_range=10000,
    cache='auto',
)

px.conversion(data=data, conversion_format='HITRAN')
px.lifetimes(data=data)
px.cooling_functions(data=data)
px.oscillator_strengths(data=data)
px.stick_spectra(data=data, temperatures=[296, 1000])
px.cross_sections(data=data, temperatures=[1000], pressures=[0.1, 1.0])
px.stick_spectra_cross_section(data=data, temperatures=[1000], pressures=[0.1, 1.0])

cache accepts auto, parquet, or none. Range changes reuse loaded data while they remain covered by the transition files selected by px.load. These options can also be passed directly to transition-based calculation functions without calling px.load first. By default, persistent caches are stored in <read_path>/<data_info>/.pyexocross_cache/. For ExoMol/ExoAtom, lifetimes, cooling functions, and oscillator strengths automatically expand range-loaded data to all transitions on first use. all_transitions=True remains available for eager loading. Partition functions and specific heats do not use transition-loaded data.

CPU / GPU Compute Mode

PyExoCross uses CPU mode by default. You can switch to GPU mode with device='GPU' and optionally select a backend with gpu_backend. run_mode remains a compatibility alias, same as device.

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

# Auto-select GPU backend (recommended)
# Priority: PyTorch-CUDA -> CuPy-CUDA -> MPS -> CPU fallback
px.cross_sections(..., device='GPU', gpu_backend='AUTO')

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

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

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

# Force Apple Metal (MPS)
px.cross_sections(..., device='GPU', gpu_backend='MPS')

GPU memory-control knobs:

px.cross_sections(
    ...,
    device='GPU',
    gpu_backend='AUTO',   # AUTO (recommended), CUDA, PyTorch-CUDA, CuPy-CUDA, or MPS
    gpu_batch_lines=8192,
    gpu_batch_grid=256,
)

Notes:

  • If GPU backend is unavailable, execution falls back to CPU formulas.

  • AUTO order: PyTorch-CUDA -> CuPy-CUDA -> MPS -> CPU.

  • CUDA order: PyTorch-CUDA -> CuPy-CUDA -> MPS -> CPU.

  • On Apple Silicon, MPS uses float32 kernels so tiny numeric differences vs CPU/CUDA are expected.

  • GPU acceleration applies to: cooling_functions, stick_spectra, cross_sections, stick_spectra_cross_section.

You can also mix the two approaches – pass an .inp file and override individual parameters with keyword arguments:

px.cross_sections(
    inp_filepath='/path/to/base_config.inp',
    temperatures=[3000],          # override .inp value
    pressures=[0.1, 1.0, 10.0],   # override .inp value
)

PyExoCross Python Package Documentation Contents