API reference

Line lists & data sources

AtmosphericAbsorption.LineLists.LineDatabase Type

julia

LineDatabase{FT}

Struct-of-arrays line list holding the union of parameters every profile needs. Core Voigt columns are always present; advanced columns (speed-dependence, velocity changing, line mixing) default to zero so one layout and one kernel serve every profile. All float columns share element type FT; all share length length(db).

The list is host-resident (built on CPU by a Port); only the prepared per-line parameters are uploaded to the device. ν0 is expected sorted ascending so Ports and the pre-pass can window with binary search.

Construct with the keyword builder LineDatabase(; mol, iso, ν0, …) — advanced columns omitted are zero-filled. The partition function Q(T) for the source rides along (partition; set by the Port), so a model needs no separate one.

AtmosphericAbsorption.LineLists.SourceMetadata Type

julia

SourceMetadata

Provenance and reference state for a line list, carried alongside the columns.

AtmosphericAbsorption.LineLists.load_lines Function

julia

load_lines(port; mol=:ALL, iso=:ALL, ν_min, ν_max, min_strength=0.0, FT=Float64) -> LineDatabase{FT}

Load and filter a line list from port into the uniform columnar layout, with the source's partition function attached (db.partition). mol/iso accept the generic notation (a symbol :CO2/:main, a string, an integer id, or :ALL for "all"); lines are kept where ν_min ≤ ν0 ≤ ν_max and S ≥ min_strength. Implementations resolve selectors via resolve_molecule/resolve_isotopologue.

AtmosphericAbsorption.LineLists.source_metadata Function

julia

source_metadata(port, mol, iso) -> SourceMetadata

Reference state and provenance for (mol, iso).

AtmosphericAbsorption.LineLists.HitranPort Type

julia

HitranPort(path; edition="HITRAN2016")    # a local `.par` file
HitranPort(; edition="HITRAN2020")        # the HITRAN database, fetched on demand

A HITRAN line-list source. Two flavours, both consumed the same way by load_lines:

HitranPort("co2.par") wraps a local .par file — load_lines parses and filters it.
HitranPort(; edition) is a remote handle carrying only the edition; the molecule and band live on the load_lines call (which downloads them, cached). Define the handle once and reuse it to pull as many molecules / bands as you like:
julia
```
port = HitranPort(; edition="HITRAN2020")
co2  = load_lines(port; mol=:CO2, ν_min=6300, ν_max=6400)
h2o  = load_lines(port; mol=:H2O, ν_min=7000, ν_max=7100)
```

Advanced (HT/SDV/line-mixing) columns are left at zero — HITRAN .par is Voigt-parameterized; see load_hitran_nonvoigt for those. The empty path is the remote sentinel.

AtmosphericAbsorption.LineLists.fetch_hitran Function

julia

fetch_hitran(molecule; numin=0, numax=150000, edition="HITRAN2020", force=false) -> path

Download HITRAN .par line data for molecule (all isotopologues) over [numin, numax] cm⁻¹ from hitran.org, caching it in a Scratch dir with provenance. Returns the local .par path. edition is the cache label; the public API serves the current HITRAN. Wrap the result in a HitranPort to load it.

AtmosphericAbsorption.LineLists.load_hitran Function

julia

load_hitran(molecule; numin=0, numax=150000, edition="HITRAN2020",
            iso=:ALL, min_strength=0.0, force=false, FT=Float64) -> LineDatabase{FT}

One-call HITRAN fetch + parse: download molecule over [numin, numax] from the named edition (cached) and return a LineDatabase. Sugar for load_lines(HitranPort(; edition); mol=molecule, ν_min=numin, ν_max=numax, …) — use the explicit two-step when you want to reuse one HitranPort(; edition) handle across several molecules/bands.

AtmosphericAbsorption.LineLists.ExoMolPort Type

julia

ExoMolPort(molecule, iso_slug, linelist; hitran_mol, hitran_iso)

An ExoMol line list as a data source, e.g. ExoMolPort("CO", "12C-16O", "Li2015"; hitran_mol=5, hitran_iso=1). The HITRAN (mol, iso) ids supply the terrestrial abundance and label the output lines.

AtmosphericAbsorption.LineLists.activate_hitran! Function

julia

activate_hitran!(key)

Store your HITRAN API key for this session (from your user profile at https://hitran.org). Required for authenticated fetches of non-Voigt (Hartmann-Tran / speed-dependent / line- mixing) parameters. The key lives in memory only — it is never written to disk or committed. Alternatively, set the HITRAN_API_KEY environment variable.

julia

activate_hitran!("xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

AtmosphericAbsorption.LineLists.fetch_hitran_nonvoigt Function

julia

fetch_hitran_nonvoigt(molecule; numin, numax, edition="HITRAN-HT", force=false) -> path

Download HITRAN line data with non-Voigt (HT/SDV) parameters for molecule over [numin, numax] via the authenticated API, caching the result with provenance. Needs an API key. Returns the local data-file path.

AtmosphericAbsorption.LineLists.load_hitran_nonvoigt Function

julia

load_hitran_nonvoigt(molecule; numin=0, numax=Inf, min_strength=0.0, FT=Float64,
                     edition="HITRAN-HT", force=false) -> LineDatabase{FT}

Fetch and parse HITRAN data with non-Voigt parameters into a LineDatabase{FT} whose advanced columns (γ2_air, δ2_air, η, νVC) are populated where HITRAN provides them; the speed-averaged width/shift (γ_air, δ_air) use the HT values when present, else the Voigt ones. The first-order line-mixing coefficient Y_LM is filled from HITRAN's Y_HT_air_296 (falling back to Y_SDV_air_296) where present, so line mixing is active for these lines. The self-broadening temperature exponent (n_self) and pressure shift (δ_self) — absent from the basic .par format — are also pulled, defaulting to n_air and 0 respectively when HITRAN does not provide them. Pair with profile = SpeedDependentVoigt() or HartmannTran().

Species notation

Name molecules and isotopologues with the backend-agnostic notation (see the Species & isotopologues table); the mapping is overridable.

AtmosphericAbsorption.LineLists.molecules Function

julia

molecules(db) -> Vector{Symbol}

The distinct molecules present in db, as formula symbols (e.g. [:H2O, :CO2]) — the "which species did this band pick up?" query.

AtmosphericAbsorption.LineLists.molecule_number Function

julia

molecule_number(m) -> Int

HITRAN molecule id for a symbol/string formula (:CO2/"CO2" → 2) or integer (passthrough).

AtmosphericAbsorption.LineLists.molecule_symbol Function

julia

molecule_symbol(id) -> Symbol

Formula symbol for a HITRAN molecule id (2 → :CO2). Inverse of molecule_number.

AtmosphericAbsorption.LineLists.isotopologue Function

julia

isotopologue(mol, iso) -> String

Chemical formula of HITRAN isotopologue (mol, iso) (e.g. (2, 1) → "(12C)(16O)2"); falls back to "iso N" when not tabulated.

AtmosphericAbsorption.LineLists.register_molecule! Function

julia

register_molecule!(sym, id)

Register or override the molecule symbol sym ↦ HITRAN molecule id id (e.g. register_molecule!(:HDO, 1)). Affects resolve_molecule/molecule_symbol thereafter.

AtmosphericAbsorption.LineLists.register_isotopologue! Function

julia

register_isotopologue!(mol, code, local_iso)

Register or override a named isotopologue code for molecule mol (id or symbol) ↦ HITRAN local isotopologue id local_iso (e.g. register_isotopologue!(:CO2, Symbol("636"), 2)).

Cross-section model

AtmosphericAbsorption.Crosssections.LineByLineModel Type

julia

LineByLineModel(lines, partition; profile=Voigt(), cpf=HumlicekWeideman32(),
                wing_cutoff=40.0, vmr=0.0, architecture=default_architecture())

A line-by-line cross-section model: a LineDatabase, its partition function, the line profile and complex-probability strategy cpf, plus the wing cutoff [cm⁻¹], broadening vmr, and compute architecture. Singleton profile/cpf types let the kernel specialize at compile time.

AtmosphericAbsorption.Crosssections.compute_cross_section Function

julia

compute_cross_section(model, grid, pressure, temperature; vmr=model.vmr) -> Vector

Absorption cross-section [cm²/molecule] on grid [cm⁻¹] at pressure [hPa] and temperature [K]. Result lives on the model's architecture (host Array for CPU).

vmr is the volume mixing ratio of the absorbing gas, used to blend self- and foreign(air)-broadening: width and shift are (1-vmr)·foreign + vmr·self. It defaults to the model's vmr, but can be overridden per call — e.g. to sweep the H₂O cross-section over humidity without rebuilding the model. vmr=0 is pure foreign (air) broadening.

julia

compute_cross_section(model::TabulatedCrossSection, grid, p, T) -> Vector

Cross-section [cm²/molecule] on grid [cm⁻¹] at pressure p [hPa], temperature T [K], interpolated from the tabulated .xsc panels.

julia

compute_cross_section(im::InterpolationModel, grid, pressure, temperature) -> array

Cross-section [cm²/molecule] on grid [cm⁻¹] at pressure [hPa], temperature [K], bilinearly interpolated in (p, T) — clamped to the tabulated range — then linearly resampled in ν (zero outside the table's ν range). vmr is fixed at build time. Runs on the table's architecture and returns an array there (host Array for CPU(), device array for a GPU). Querying on the table's own ν skips the ν resample.

julia

compute_cross_section(lut::AbscoLUT, grid, pressure, temperature; vmr=0, interp=:linear) -> array

Cross-section [cm²/molecule] on grid [cm⁻¹] at pressure [hPa], temperature [K] and H₂O broadener vmr, looked up from the ABSCO table: interpolated in pressure, in each bracketing pressure's own temperature axis, and in the broadener VMR (all clamped to the tabulated range), then linear in ν (zero outside the table's ν range). interp selects the temperature interpolation — :linear (default) or :cubic (smooth Catmull-Rom); both are exact at nodes. Runs on the table's architecture and returns an array there; querying on the table's own ν skips the ν resample.

Interpolation tables (precomputed LUTs)

AtmosphericAbsorption.Crosssections.InterpolationModel Type

julia

InterpolationModel{FT}

A tabulated cross-section cube σ[iν, ip, iT] built from a LineByLineModel, with its node vectors ν [cm⁻¹], p [hPa], T [K], the vmr it was built at, and the architecture it lives on. compute_cross_section(im, grid, p, T) interpolates it (bilinear in (p, T), linear in ν, clamped in p/T and zero outside the ν range) on that architecture — fast, no line-by-line work. The σ/ν arrays are CPU Arrays for CPU() and device arrays for GPU()/MetalGPU(). The table is vmr-specific (vmr is fixed at build time). Build it with build_interpolation_model; persist with save_interpolation_model.

AtmosphericAbsorption.Crosssections.build_interpolation_model Function

julia

build_interpolation_model(model::LineByLineModel, ν, pressures, temperatures;
                          vmr=model.vmr, architecture=model.architecture) -> InterpolationModel

Evaluate the line-by-line model on wavenumber grid ν at every (pressure, temperature) node and store the cube for fast interpolation later. pressures [hPa] and temperatures [K] are the ascending interpolation nodes; the (expensive) line-by-line summation runs once, here. The resulting table lives on architecture (defaults to the model's), so queries run there. Choose nodes fine enough that interpolation between them is accurate for your use.

AtmosphericAbsorption.Crosssections.save_interpolation_model Function

julia

save_interpolation_model(path, im)
load_interpolation_model(path) -> InterpolationModel

Persist / restore an interpolation table to/from path (via Julia Serialization). Saving copies the table to the host (CPU()), so the file is portable; move it back with architecture= on a rebuild if you need it on a GPU. The format is tied to the Julia version that wrote it — rebuild the table after a Julia upgrade.

Tabulated cross-sections (HITRAN `.xsc`)

AtmosphericAbsorption.Crosssections.TabulatedCrossSection Type

julia

TabulatedCrossSection{FT}

A pre-computed cross-section source for one molecule, holding the .xsc panels over (wavenumber, temperature, pressure). compute_cross_section(model, grid, p, T) interpolates σ onto grid — linear in ν, linear in T at the nearest tabulated p (full (T, p) bilinear interpolation is not done). It always returns a CPU Vector{FT}; wrap it with array_type(arch)(...) to move it onto a device.

AtmosphericAbsorption.Crosssections.XscBand Type

julia

XscBand{FT}

One tabulated cross-section panel: σ(ν) sampled at length(σ) points evenly spanning [νmin, νmax] cm⁻¹, measured at temperature T [K] and pressure p [hPa].

AtmosphericAbsorption.Crosssections.read_xsc Function

julia

read_xsc(path; FT=Float64) -> Vector{XscBand{FT}}

Parse a HITRAN cross-section (.xsc) file — one or more (T, p) panels — into XscBands.

AtmosphericAbsorption.Crosssections.load_xsc Function

julia

load_xsc(path; FT=Float64) -> TabulatedCrossSection

Read a HITRAN .xsc file into a tabulated cross-section model.

AtmosphericAbsorption.Crosssections.fetch_hitran_xsc Function

julia

fetch_hitran_xsc(filename; force=false) -> path

Download a HITRAN cross-section file by its .xsc filename (as listed on hitran.org) into the scratch cache, returning the local path. Reused on subsequent calls.

Line shapes

AtmosphericAbsorption.LineShapes.Doppler Type

Gaussian thermal (Doppler) profile.

AtmosphericAbsorption.LineShapes.Lorentz Type

Lorentzian pressure-broadened profile.

AtmosphericAbsorption.LineShapes.Voigt Type

Voigt profile — Doppler⊗Lorentz convolution via the complex probability function.

AtmosphericAbsorption.LineShapes.SpeedDependentVoigt Type

Speed-dependent Voigt profile (quadratic speed dependence of width/shift).

AtmosphericAbsorption.LineShapes.Rautian Type

Rautian profile — Voigt with Dicke (velocity-changing collision) narrowing of the core.

AtmosphericAbsorption.LineShapes.SpeedDependentRautian Type

Speed-dependent Rautian profile — speed dependence + Dicke narrowing, no correlation.

AtmosphericAbsorption.LineShapes.HartmannTran Type

Hartmann-Tran (HTP) profile — speed dependence + velocity-changing collisions.

AtmosphericAbsorption.LineShapes.doppler Function

Gaussian profile of HWHM-related width γd (the Doppler HWHM).

AtmosphericAbsorption.LineShapes.lorentz Function

Lorentzian profile of HWHM γl.

AtmosphericAbsorption.LineShapes.voigt Function

Voigt profile from Doppler HWHM γd and width ratio y = √ln2·γl/γd.

AtmosphericAbsorption.LineShapes.HumlicekWeideman32 Type

julia

HumlicekWeideman32()

Region-split w(z): Humlíček (1982) region-II rational for |x|+y ≥ 8, Weideman (1994) 32-term rational otherwise. Allocation-free and GPU-safe — the default everywhere.

AtmosphericAbsorption.LineShapes.ErfcxCPF Type

julia

ErfcxCPF()

Reference w(z) = erfcx(-iz) via SpecialFunctions. Accurate but CPU-only (scalar special function) — used to validate HumlicekWeideman32.

Partition functions (advanced)

Normally the partition function rides on the LineDatabase (set by the port) and the model picks it up automatically — you only reach for these to pin a specific edition.

AtmosphericAbsorption.LineLists.partition_function Function

julia

partition_function(port, mol, iso) -> AbstractPartitionFunction

Partition function Q(T) for (mol, iso) as provided by this source. load_lines attaches its result to the returned LineDatabase, so callers rarely need it directly.

AtmosphericAbsorption.PartitionFunctions.AbstractPartitionFunction Type

Supertype for partition-function backends. Implement Q(pf, T); Q_ratio follows.

AtmosphericAbsorption.PartitionFunctions.TIPS2021PF Type

julia

TIPS2021PF()

HITRAN partition functions from the latest edition, TIPS-2021 (Gamache et al. 2021) — the HitranPort default. Iso-aware via Q_ratio(pf, mol, iso, T, T_ref). For the few isotopologues not yet in HITRAN's online Q-files it falls back to TIPS-2017.

AtmosphericAbsorption.PartitionFunctions.TIPS2017PF Type

julia

TIPS2017PF()

HITRAN partition functions from TIPS-2017 (Gamache et al. 2017). Iso-aware via Q_ratio(pf, mol, iso, T, T_ref). Retained mainly for HAPI cross-validation; new work should prefer the latest edition, TIPS2021PF.

AtmosphericAbsorption.PartitionFunctions.TabulatedPF Type

julia

TabulatedPF(T, Q)

Partition sum from a tabulated (T, Q) grid, interpolated with a cubic spline. Works for any source that ships Q(T) values (e.g. ExoMol .pf).

AtmosphericAbsorption.PartitionFunctions.Q_ratio Function

julia

Q_ratio(pf, T, T_ref)

Partition-sum ratio Q(T_ref)/Q(T) — the temperature correction applied to line intensities. Defined in terms of Q(pf, T); backends may override for speed.

julia

Q_ratio(pf, mol, iso, T, T_ref)

Per-line ratio used in the pre-pass. The default ignores (mol, iso); iso-aware backends (e.g. TIPS over a whole molecule) override this method.

julia

Q_ratio(pf::Union{TIPS2017PF,TIPS2021PF}, mol, iso, T, T_ref) -> Float64

Partition-sum ratio Q(T_ref)/Q(T) for (mol, iso), cubic-splined in temperature. Throws if either T or T_ref is outside the tabulated range.

AtmosphericAbsorption.PartitionFunctions.pf_name Function

julia

pf_name(pf) -> String

Short human-readable name of a partition-function backend (for display), e.g. "TIPS-2021", "tabulated". Defaults to the type name.

Continuum

AtmosphericAbsorption.Continuum.load_mtckd Function

julia

load_mtckd(path = bundled) -> MTCKDTable

Load MT_CKD reference coefficients from an Arrow file (defaults to the bundled AER v4.2 table). p_ref/T_ref come from the file's Arrow metadata.

AtmosphericAbsorption.Continuum.build_mtckd_band Function

julia

build_mtckd_band(table, ν_grid) -> MTCKDBand

Linearly interpolate the table onto ν_grid; coefficients are zero where ν_grid falls outside the table's range (no continuum in the UV/Vis above ~500 nm).

AtmosphericAbsorption.Continuum.h2o_continuum Function

julia

h2o_continuum(band, T, p_h2o, p_dry) -> Vector{Float64}

Allocating form of h2o_continuum!.

AtmosphericAbsorption.Continuum.h2o_continuum! Function

julia

h2o_continuum!(σ_out, band, T, p_h2o, p_dry) -> σ_out

Total (self + foreign) H₂O continuum cross-section [cm²/molecule] on band.ν at temperature T [K] with H₂O and dry-air partial pressures p_h2o, p_dry [hPa].

AtmosphericAbsorption.Continuum.load_cia Function

julia

load_cia(path, ν_grid) -> CIATable

Parse a .cia file and project it onto ν_grid.

AtmosphericAbsorption.Continuum.parse_cia_file Function

julia

parse_cia_file(path) -> Vector{CIABlock{Float64}}

Read a HITRAN .cia file: each block is a header line then n_pts (ν σ) rows. Header (fixed columns): formula [1:20], n_pts [41:47], T [48:54].

AtmosphericAbsorption.Continuum.cia_cross_section Function

julia

cia_cross_section(table, T) -> Vector{Float64}

Allocating form of cia_cross_section!.

AtmosphericAbsorption.Continuum.cia_cross_section! Function

julia

cia_cross_section!(σ_out, table, T) -> σ_out

Binary CIA cross-section σ(ν, T) [cm⁵/molecule²] on the table's ν grid. Temperature interpolation is per frequency over only the blocks covering it (linear; constant extrapolation; zero where no block covers the frequency).

Compute backends

AtmosphericAbsorption.Architectures.CPU Type

Single-threaded / multithreaded CPU execution.

AtmosphericAbsorption.Architectures.GPU Type

NVIDIA CUDA GPU (bindings from the CUDA extension).

AtmosphericAbsorption.Architectures.MetalGPU Type

Apple-Silicon GPU via Metal (Float32 only; bindings from the Metal extension).

AtmosphericAbsorption.Architectures.default_architecture Function

Return GPU() if CUDA is functional, MetalGPU() if Metal is, else CPU().