ExoJAX Molecular, Atomic, and Continuum Database Classes: Key Differences Explained

ExoJAX provides three specialized database classes—MdbExomol for molecular line lists, AdbVald for atomic transitions, and CdbCIA for collision-induced absorption—that handle distinct data formats, caching strategies, and GPU conversion workflows for radiative-transfer calculations.

ExoJAX unifies opacity calculations for exoplanet atmospheres through high-level Python wrappers that abstract the complexity of spectroscopic data sources. The library’s database architecture separates molecular line-by-line data (ExoMol), atomic transitions (VALD3), and continuum absorption (HITRAN-CIA) into three distinct classes with unique loading mechanisms, attribute structures, and masking capabilities.

Overview of the Three Database Classes

Class	Source File	Data Source	Primary Use Case
MdbExomol	src/exojax/database/exomol/api.py	ExoMol .trans and .states files	High-resolution molecular opacity (H₂O, CO, CH₄)
AdbVald / AdbSepVald	src/exojax/database/vald/api.py	VALD3 "Long format" line lists	Atomic line absorption (Fe I, Na I, Ca II)
CdbCIA	src/exojax/database/cia/api.py	HITRAN-CIA .cia files	Continuum opacity (H₂–H₂, H₂–He)

Data Loading and Conversion Architectures

Each database class implements a distinct strategy for handling its underlying file format, memory management, and GPU transfer.

Molecular Database (MdbExomol)

MdbExomol wraps the RADIS C-API to leverage lazy loading for massive ExoMol line lists. The class reads binary .trans files and ASCII .states files on demand, utilizing RADIS internal caching rather than explicit HDF5 conversion.

• Partition functions: Interpolated dynamically using self.T_gQT and self.gQT grids inherited from RADIS.
• GPU transfer: Optional gpu_transfer=True flag creates dev_nu_lines, dev_Sij0, and other JAX arrays for GPU computation.

Atomic Database (AdbVald)

AdbVald handles VALD3 text exports by converting them to HDF5 for fast subsequent access. The constructor checks for an existing .hdf5 cache; if absent, it parses the raw "Long format" file using vaex or pandas, then writes the HDF5 representation.

• Partition functions: Loads the 284-species atomic partition-function grid from Barklem & Collet (2016) via load_pf_Barklem2016. Also supports Irwin tables for specific species.
• Masking: Applied via masking() method before JAX conversion to filter by wavenumber range and line strength.

Continuum Database (CdbCIA)

CdbCIA provides a minimal wrapper around HITRAN-CIA files. It reads the entire .cia file via exojax.database.cia.io.read_cia into memory as a wavenumber-temperature grid.

• No caching: The file is read fresh each instantiation; no HDF5 conversion occurs.
• No partition function: CIA opacity requires no internal partition-function calculation.
• Structure: Stores nucia (wavenumber grid), tcia (temperature grid), and logac (log₁₀ absorption coefficient).

Attribute Layout Comparison

The internal data structures differ significantly based on the physics requirements of each data type.

Attribute	MdbExomol	AdbVald	CdbCIA
Line centers	nu_lines (numpy), dev_nu_lines (jax)	nu_lines, dev_nu_lines	nucia (numpy → jax)
Line strength	Sij0, logsij0	Sij0, logsij0	N/A (continuum)
Absorption coeff	N/A (computed on fly)	N/A (computed on fly)	logac (log₁₀ cm⁵ molecule⁻²)
Lower energy	elower	elower	N/A
Einstein A	A (jnp)	A (jnp)	N/A
Broadening	alpha_ref, n_Texp (RADIS)	gamRad, gamSta, vdWdamp	N/A
Species ID	simple_molecule_name	ielem, iion	N/A (pair defined by file)
Partition func	T_gQT, gQT	T_gQT, gQT_284species	N/A

Masking and Filtering Capabilities

Each class implements data reduction to handle memory constraints and computational efficiency.

Molecular Line Masking (MdbExomol)

The compute_load_mask method constructs a boolean mask based on:

• Wavenumber range (nurange)
• Reference line-strength cutoff (crit)
• Temperature-dependent line strength (optional)
• Upper energy limit (elower_max)

After activation, apply_mask_mdb updates all attributes (nu_lines, Sij0, elower, etc.) to remove masked lines in a single vectorized operation.

Atomic Line Masking (AdbVald)

AdbVald applies masking via the masking method after loading the raw VALD table. The mask filters by:

• Wavenumber range with margin
• Line strength threshold (crit)

Unlike the molecular class, masking in AdbVald occurs before JAX array generation. The generate_jnp_arrays method converts the filtered numpy arrays to JAX device arrays only after masking is complete.

Continuum Data Handling (CdbCIA)

CdbCIA does not implement per-line masking because CIA data are pre-tabulated on a fixed wavenumber-temperature grid. The margin parameter simply expands the wavenumber interval when reading the file, ensuring the requested nurange is covered by the grid boundaries.

Practical Usage Examples

Loading Molecular Opacity from ExoMol

from exojax.database.exomol.api import MdbExomol

mdb = MdbExomol(
    path="~/exojax/data/CO/12C-16O/line_list",
    nurange=[2000.0, 2500.0],  # cm^-1

    crit=1e-30,                # Line strength cutoff

    bkgdatm="H2",              # Broadening species

    gpu_transfer=True          # Convert to JAX arrays

)

# Compute temperature-dependent line strength

S_at_1500K = mdb.line_strength(T=1500.0)

Loading Atomic Data from VALD3

from exojax.database.vald.api import AdbVald, AdbSepVald

# Load VALD3 "Long format" file

adb = AdbVald(
    path="~/exojax/data/VALD3/FeI.long",
    nurange=[2000.0, 2500.0],
    crit=1e-30,
    gpu_transfer=True
)

# Create species-separated view for multi-atom calculations

adb_sep = AdbSepVald(adb)

# Interpolate partition function for Fe I at 1500 K

QT_fe = adb.QT_interp("Fe 1", T=1500.0)

Loading Continuum CIA Data

from exojax.database.cia.api import CdbCIA

cdb = CdbCIA(
    path="~/exojax/data/CIA/H2-H2_2011.cia",
    nurange=[4000.0, 4200.0]
)

# Access log10 of absorption coefficient

# Shape: (n_wavenumber, n_temperature)

log_absorption = cdb.logac
temperature_grid = cdb.tcia
wavenumber_grid = cdb.nucia

Summary

• MdbExomol handles massive molecular line lists from ExoMol via lazy loading through RADIS, supports temperature-dependent line strength calculations, and offers comprehensive GPU transfer capabilities for JAX acceleration.

• AdbVald and AdbSepVald manage atomic transition data from VALD3, converting text exports to HDF5 for performance, implementing species-specific partition functions from Barklem & Collet (2016), and providing species-separated views for multi-atom opacity calculations.

• CdbCIA provides a lightweight interface to HITRAN collision-induced absorption data, exposing pre-tabulated continuum opacity grids without requiring line-by-line masking or partition function calculations.

Frequently Asked Questions

When should I use MdbExomol versus AdbVald?

Use MdbExomol when calculating opacity for molecular species such as water (H₂O), carbon monoxide (CO), or methane (CH₄) using ExoMol line lists. Use AdbVald when modeling atomic absorption from species like iron (Fe I), sodium (Na I), or ionized calcium (Ca II) using VALD3 atomic line data. The choice depends entirely on whether your atmospheric model requires molecular or atomic opacity sources.

What is the difference between AdbVald and AdbSepVald?

AdbVald stores all atomic transitions in unified arrays, which is efficient when calculating total opacity from a single species or when species are treated together. AdbSepVald takes an AdbVald instance and reorganizes the data into species-separated arrays, creating distinct logsij0, nu_lines, and elower arrays for each atomic species. This separation is essential when computing individual contributions from multiple atoms in a mixed atmosphere or when applying species-specific abundance weighting.

How does CdbCIA handle data differently from line-list databases?

Unlike MdbExomol and AdbVald, which manage discrete spectral lines requiring masking, partition functions, and temperature-dependent line strength calculations, CdbCIA loads collision-induced absorption data as a pre-computed continuum grid. It reads HITRAN .cia files into fixed wavenumber-temperature arrays (nucia, tcia, logac) without implementing per-line filtering or partition function interpolation. This design reflects the nature of CIA opacity, which is inherently continuous and depends only on the colliding pair (e.g., H₂–H₂) and the thermodynamic conditions.

Can I convert database outputs to JAX arrays for GPU acceleration?

Yes, all three database classes support JAX array conversion for GPU computation. MdbExomol and AdbVald provide a gpu_transfer=True initialization parameter that automatically creates device arrays (prefixed with dev_, such as dev_nu_lines and dev_Sij0) upon instantiation. For MdbExomol, you can also call generate_jnp_arrays() manually after masking. CdbCIA automatically stores data as JAX-compatible arrays (logac, nucia, tcia) suitable for direct use in jax.numpy operations without explicit conversion methods.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}