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

> Understand ExoJAX's molecular, atomic, and continuum database classes: MdbExomol, AdbVald, and CdbCIA. Learn their data formats, caching, and GPU workflows for radiative transfer.

- Repository: [Hajime Kawahara/exojax](https://github.com/hajimekawahara/exojax)
- Tags: deep-dive
- Published: 2026-03-03

---

**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`](https://github.com/hajimekawahara/exojax/blob/main/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`](https://github.com/hajimekawahara/exojax/blob/main/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`](https://github.com/hajimekawahara/exojax/blob/main/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

```python
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

```python
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

```python
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.