vSmartMOM

Appearance

Absorption API ​

Internal absorption API is deprecated

AtmosphericAbsorption.jl is the supported absorption dependency for vSmartMOM going forward. The standalone line-by-line model here (make_hitran_model, HitranModel) is deprecated in 2.2 and will be removed in 3.0; use AtmosphericAbsorption.jl for line-by-line calculations, ABSCO HDF tables, and GPU execution. YAML LUTfiles read OCO-2 ABSCO HDF files, AtmosphericAbsorption .absco tables, and vSmartMOM JLD2 tables from make_interpolation_model, which remains the table builder in 2.x.

vSmartMOM.Absorption Module

Legacy internal absorption implementation.

AtmosphericAbsorption.jl is the sole supported absorption dependency for vSmartMOM going forward. This module remains temporarily for compatibility and will be removed in a future release; new code should use AtmosphericAbsorption directly.

source

Absorption provides HITRAN line-list reading, line-shape models, interpolation models, and absorption cross-section evaluation for legacy callers.

HITRAN Data Management ​

vSmartMOM.artifact Function
julia
artifact(molecule::AbstractString, database::AbstractString = "hitran")

Given a molecule name, retrieve the path to its HITRAN line-by-line .par file.

The data source depends on the active HITRAN edition (see set_hitran_edition!):

  • "artifact" (default): Uses legacy HITRAN 2016 data from Julia Artifacts

  • Any other edition (e.g., "HITRAN2024"): Uses data downloaded from hitran.org. The cached file is used only if it verifiably holds the full dataset (0–150000 cm⁻¹, all isotopologues of the molecule) and its SHA-256 matches its metadata. Otherwise the full dataset is downloaded; if that fails, an error explains why the cache was rejected. A narrower file written by fetch_hitran(...; numin, numax) under the same edition is not accepted.

Example

julia
# Default: HITRAN 2016 from Artifacts
path = artifact("CO2")

# After switching edition:
set_hitran_edition!("HITRAN2024")
path = artifact("CO2")  # downloads from hitran.org on first call
source
vSmartMOM.fetch_hitran Function
julia
fetch_hitran(molecule::AbstractString; numin=0, numax=150000,
                edition="HITRAN2024", force=false)

Download HITRAN line-by-line data for a molecule directly from hitran.org.

Analogous to HAPI's fetch(). Resolves the molecule name to all its isotopologue global IDs and queries the HITRAN API. Data is cached locally; subsequent calls return the cached path unless force=true or the cache cannot be verified for this request (see fetch_hitran_by_ids).

Arguments

  • molecule: Molecule name (e.g., "CO2", "H2O", "O3")

  • numin: Lower wavenumber bound in cm⁻¹ (default: 0)

  • numax: Upper wavenumber bound in cm⁻¹ (default: 150000)

  • edition: Cache/provenance label for this download (default: "HITRAN2024"). hitran.org always serves its current database; the label names the local cache directory and does not select or prove a historical HITRAN edition.

  • force: Re-download even if cached (default: false)

Returns

  • Path to the downloaded .par file

Example

julia
path = fetch_hitran("CO2")
path = fetch_hitran("O3"; numin=500, numax=3000, edition="HITRAN2024")
source
vSmartMOM.fetch_hitran_by_ids Function
julia
fetch_hitran_by_ids(name::AbstractString, iso_ids::Vector{Int};
                numin=0, numax=150000, edition="HITRAN2024", force=false)

Download HITRAN data using explicit global isotopologue IDs.

Lower-level variant of fetch_hitran for when you need specific isotopologues. Global IDs can be looked up via Absorption.mol_globalID(mol, iso).

A cached file under the same name and edition is reused only if its metadata covers [numin, numax], includes every requested isotopologue, and records a SHA-256 that matches the file. A reused file may therefore contain a wider band or additional isotopologues. Missing or inconsistent metadata triggers a fresh download.

A download is written to a temporary file and checked (non-empty, well-formed fixed-width HITRAN records, only requested isotopologues within the requested band) before it replaces the cache. If the download or check fails, an existing cache is left unchanged. After a replacement, the process-local parsed spectroscopy cache (clear_spectroscopy_cache!) is cleared.

Arguments

  • name: Label for the file (typically molecule name)

  • iso_ids: Vector of HITRAN global isotopologue IDs

  • numin, numax, edition, force: Same as fetch_hitran

Returns

  • Path to the downloaded .par file
source
vSmartMOM.set_hitran_edition! Function
julia
set_hitran_edition!(edition::AbstractString)

Set the active HITRAN edition. Valid values:

  • "artifact" — use legacy HITRAN 2016 data from Julia Artifacts (default)

  • Any other string (e.g., "HITRAN2024") — use data downloaded from hitran.org, stored in a local scratch-space cache. Data is auto-downloaded on first access.

A downloaded edition string is a cache/provenance label, not a database selector: hitran.org serves only its current edition, so a label such as "HITRAN2020" does not prove that the cached lines come from HITRAN2020. The SHA-256, download date and source URL shown by hitran_info record what was downloaded. hitran_info reports the metadata as stored and does not check it against the data file; hitran_is_cached and artifact do.

Example

julia
set_hitran_edition!("HITRAN2024")  # switch to latest HITRAN
set_hitran_edition!("artifact")    # back to legacy
source
vSmartMOM.get_hitran_edition Function
julia
get_hitran_edition()

Return the currently active HITRAN edition string.

source
vSmartMOM.available_hitran_editions Function
julia
available_hitran_editions()

List all locally available HITRAN editions. Always includes "artifact" (legacy HITRAN 2016). Additional editions appear as they are downloaded to the scratch cache.

source
vSmartMOM.hitran_info Function
julia
hitran_info(molecule::AbstractString)

Return metadata for the given molecule under the current HITRAN edition.

For "artifact" edition, returns basic info. For downloaded editions, returns the full metadata from the .meta.toml file (edition, download date, wavenumber range, SHA256, source URL). The metadata is returned as recorded; it is not checked against the data file here (see hitran_is_cached).

source
vSmartMOM.hitran_is_cached Function
julia
hitran_is_cached(molecule::AbstractString, edition=get_hitran_edition())

Return true when artifact(molecule) would use a downloaded file for edition without downloading: the cached file must cover the full spectral range and all isotopologues of the molecule, and its SHA-256 must match its metadata. A narrower or unverified file returns false.

source

Cross-Section Workflow ​

vSmartMOM.Absorption.compute_absorption_cross_section Function
julia
compute_absorption_cross_section(model::HitranModel, grid, pressure, temperature; wavelength_flag=false)

Compute absorption cross-section from HITRAN line-by-line data.

Sums Voigt (or Doppler/Lorentz) line shapes over all transitions in the HITRAN table within the grid range. Uses a batched kernel to process all lines in a single launch for efficient GPU/CPU execution.

Arguments

  • model::HitranModel: Model with HITRAN data, broadening, wing_cutoff, CEF

  • grid: Wavenumber [cm⁻¹] or wavelength [nm] grid

  • pressure::Real: Pressure (hPa)

  • temperature::Real: Temperature (K)

  • wavelength_flag::Bool=false: If true, grid is wavelength in nm

Returns

  • Array: Absorption cross-section (cm²/molecule) at each grid point
source
julia
compute_absorption_cross_section(model::InterpolationModel, grid, pressure, temperature; wavelength_flag=false)

Compute absorption cross-section by interpolating a pre-computed lookup table.

Uses BSpline interpolation over (ν, p, T). Faster than line-by-line for repeated calls.

Arguments

  • model::InterpolationModel: Pre-computed interpolator with ν_grid, p_grid, t_grid

  • grid: Wavenumber [cm⁻¹] or wavelength [nm] grid

  • pressure::Real: Pressure (hPa)

  • temperature::Real: Temperature (K)

  • wavelength_flag::Bool=false: If true, grid is wavelength in nm

Returns

  • Array: Interpolated absorption cross-section (cm²/molecule) at each grid point
source
vSmartMOM.Absorption.absorption_cross_section Function
julia
absorption_cross_section(model, grid, pressure, temperature;
                         wavelength_flag=false)

Calculate absorption cross-section. Convenience wrapper around compute_absorption_cross_section.

Arguments

  • model::AbstractCrossSectionModel: HitranModel or InterpolationModel

  • grid: Wavelength [nm] or wavenumber [cm⁻¹] grid (see wavelength_flag)

  • pressure::Real: Pressure (hPa)

  • temperature::Real: Temperature (K)

  • wavelength_flag::Bool=false: If true, grid is wavelength in nm; else wavenumber in cm⁻¹

  • vmr=model.vmr: Additional keyword accepted by the AtmosphericAbsorption.LineByLineModel dispatch. This is the absorber's moist-air mole fraction used to mix foreign and self broadening.

Returns

  • Vector: Absorption cross-sections (cm²/molecule) at each grid point
source
vSmartMOM.Absorption.read_hitran Function
julia
read_hitran(filepath; mol=-1, iso=-1, ν_min=0, ν_max=Inf, min_strength=0)

Read and parse a HITRAN line-by-line data file into a HitranTable.

Filters lines by molecule, isotopologue, wavenumber range, and minimum line strength. Uses fixed-width column parsing per the HITRAN format specification.

Arguments

  • filepath::String: Path to HITRAN .par or .hitran file

  • mol::Int=-1: Filter by molecule ID (-1 = all)

  • iso::Int=-1: Filter by isotopologue ID (-1 = all)

  • ν_min::Real=0: Minimum wavenumber (cm⁻¹)

  • ν_max::Real=Inf: Maximum wavenumber (cm⁻¹)

  • min_strength::Real=0: Minimum line intensity at 296 K

Returns

  • HitranTable: Struct with line parameters (νᵢ, Sᵢ, γ_air, γ_self, E″, etc.)

Throws

  • HitranEmptyError: If no lines match the filter criteria

  • ArgumentError: If a record is short, non-ASCII, or contains a malformed required numeric field. Blank upper/lower degeneracies are accepted as zero.

source
vSmartMOM.Absorption.make_hitran_model Function
julia
make_hitran_model(hitran::HitranTable, 
                  broadening::AbstractBroadeningFunction; 
                  wing_cutoff::Real=40, 
                  vmr::Real=0, 
                  CEF::AbstractComplexErrorFunction=HumlicekWeidemann32SDErrorFunction(), 
                  architecture::AbstractArchitecture = default_architecture())

Convenience function to make a HitranModel out of the parameters (Matches make_interpolation_model)

Deprecated

The standalone line-by-line model is deprecated and will be removed in vSmartMOM 3.0; use AtmosphericAbsorption.LineByLineModel (see load_lines, compute_cross_section). A one-time notice with the corresponding calls and their convention differences is logged on first use.

source
vSmartMOM.Absorption.make_interpolation_model Function
julia
make_interpolation_model(hitran::HitranTable, 
                broadening::AbstractBroadeningFunction, 
                wave_grid::AbstractRange{<:Real}, 
                p_grid::AbstractRange{<:Real},
                t_grid::AbstractRange{<:Real}; 
                wavelength_flag::Bool=false,
                wing_cutoff::Real=40, 
                vmr::Real=0, 
                CEF::AbstractComplexErrorFunction=HumlicekWeidemann32SDErrorFunction(),
                architecture::AbstractArchitecture = default_architecture())

Using a HitranModel, create an InterpolationModel by interpolating the lineshape function at the given pressure and temperature grids. vmr is the absorber's volume mixing ratio passed to the underlying line model; in this engine it mixes only the Lorentz widths (self vs. air), while the pressure shift and temperature exponent stay air-only. The resulting table is specific to that value.

The table is built on a uniform wavenumber grid (cm⁻¹). wavelength_flag=true is rejected: a uniform wavelength grid maps to a non-uniform wavenumber grid, which the interpolation table cannot store. Build the table on a uniform wavenumber grid whose ends lie outside the band, e.g. wave_grid = range(floor(1e7/λ_max_nm/Δν)*Δν, ceil(1e7/λ_min_nm/Δν)*Δν; step=Δν), and query it in wavelength with absorption_cross_section(model, λ_nm, p, T; wavelength_flag=true), which remains supported.

Line engine

The tables are computed with the deprecated standalone line-by-line model. They remain a supported format for YAML LUTfiles throughout vSmartMOM 2.x. Tables saved with AtmosphericAbsorption's save_interpolation_model use a different format that this loader does not read; AtmosphericAbsorption .absco tables (save_absco_lut) are read.

source
julia
make_interpolation_model(absco::AbscoTable, wave_grid, p_grid, t_grid; 
                         wavelength_flag=false, architecture=default_architecture())

Create an InterpolationModel from ABSCO tabulated cross-section data.

Linearly interpolates the pre-computed cross-sections onto the specified pressure and temperature grids. Uses the ABSCO table layout σ(ν, broadener VMR, T, p). Only the first broadener slice (σ[:, 1, :, :], H₂O VMR = 0 in OCO-2 ABSCO tables) is used, so the result has no H₂O broadening. Listing the original .hdf file in absorption.LUTfiles keeps the H₂O-broadener axis instead.

Arguments

  • absco::AbscoTable: ABSCO table with cross-sections σ(ν, broadener VMR, T, p)

  • wave_grid: uniform wavenumber grid in cm⁻¹; wavelength_flag=true is rejected (see the HITRAN method)

  • p_grid: Pressure grid (hPa)

  • t_grid: Temperature grid (K)

Returns

  • InterpolationModel: Interpolator for absorption cross-sections
source

Line-Shape Types ​

vSmartMOM.Absorption.AbstractBroadeningFunction Type
julia
type AbstractBroadeningFunction

Abstract Broadening Function type for generic line broadening function

source
vSmartMOM.Absorption.Voigt Type

Voigt line broadening

source
vSmartMOM.Absorption.Lorentz Type

Lorentz line broadening

source
vSmartMOM.Absorption.Doppler Type

Doppler line broadening

source

HITRAN Data Structure ​

vSmartMOM.Absorption.HitranTable Type
julia
struct HitranTable{FT}

A struct, which provides all HITRAN line parameters needed to compute absorption cross sections

See https://hitran.org/docs/definitions-and-units/ for details

Fields

  • mol: The molecular species identification (ID) number

  • iso: The isotopologue ID number

  • νᵢ: The wavenumber of the spectral line transition (cm-1) in vacuum

  • Sᵢ: The spectral line intensity (cm−1/(molecule·cm−2)) at Tref=296K

  • Aᵢ: The Einstein-A coefficient (s-1) of a transition

  • γ_air: The air-broadened half width at half maximum (HWHM) (cm−1/atm) at Tref=296K and reference pressure pref=1atm

  • γ_self: The self-broadened half width at half maximum (HWHM) (cm−1/atm) at Tref=296K and reference pressure pref=1atm

  • E″: The lower-state energy of the transition (cm-1)

  • n_air: The coefficient of the temperature dependence of the air-broadened half width

  • δ_air: The pressure shift (cm−1/atm) at Tref=296K and pref=1atm of the line position with respect to the vacuum transition wavenumber νij

  • global_upper_quanta: The electronic and vibrational quantum numbers and labels for the upper state of a transition

  • global_lower_quanta: The electronic and vibrational quantum numbers and labels for the lower state of a transition

  • local_upper_quanta: Rotational, hyperfine and other quantum numbers and labels for the upper state of a transition

  • local_lower_quanta: Rotational, hyperfine and other quantum numbers and labels for the lower state of a transition

  • ierr: Ordered list of indices corresponding to uncertainty estimates of transition parameters

  • iref: Ordered list of reference identifiers for transition parameters

  • line_mixing_flag: A flag indicating the presence of additional data and code relating to line-mixing

  • g′: The upper state degeneracy

  • g″: The lower state degeneracy

source

Cross-Section Model Types ​

vSmartMOM.Absorption.HitranModel Type
julia
struct HitranModel{FT}

Deprecated

Part of the standalone line-by-line engine, deprecated in vSmartMOM 2.2 and planned for removal in 3.0; use AtmosphericAbsorption.LineByLineModel. See make_hitran_model.

A struct which provides all model parameters needed for cross-section calculations using HITRAN data

Fields

  • hitran: Struct with hitran data

  • broadening: Broadening function (Doppler/Lorentz/Voigt)

  • wing_cutoff: Wing cutoff [cm-1]

  • vmr: VMR of gas itself [0-1]

  • CEF: Complex Error Function to Use

  • architecture: Computer Architecture on which Model is run

source
vSmartMOM.Absorption.InterpolationModel Type
julia
struct InterpolationModel{FT}

A struct which provides all model parameters needed for cross-section calculations using an Interpolator

Fields

  • itp: The interpolator

  • mol: The molecular species identification (ID) number

  • iso: The isotopologue ID number

  • ν_grid: Wavelength grids

  • p_grid: Wavelength grids

  • t_grid: Wavelength grids

source

Complex Error Function Types ​

The complex error function evaluated inside the Voigt line shape is selectable via the CEF field on make_hitran_model / absorption.CEF.

vSmartMOM.Absorption.HumlicekErrorFunction Type

Humlicek only formulation for Complex Error Function

source
vSmartMOM.Absorption.HumlicekWeidemann32VoigtErrorFunction Type

Mix of Humlicek and Weidemann (N=32) Error Function, suggested for Voigt function

source
vSmartMOM.Absorption.HumlicekWeidemann32SDErrorFunction Type

Mix of Humlicek and Weidemann (N=32) Error Function, suggested for Speed Dependent Voigt function

source
vSmartMOM.Absorption.CPF12ErrorFunction Type

Humlicek with a single rational approximation.

source
vSmartMOM.Absorption.ErfcHumliErrorFunctionVoigt Type

Mix of Humplicek and erfc Special Function for Voigt

source
vSmartMOM.Absorption.ErfcHumliErrorFunctionSD Type

Mix of Humplicek and erfc Special Function for Voigt

source
vSmartMOM.Absorption.ErfcErrorFunction Type

erfc Special Function for Voigt

source