Top-Level API

These are the functions and types most users call directly after using vSmartMOM. They load a scene, construct an RT model, run the solver, and select the compute architecture.

Scene Loading

vSmartMOM.IO.read_parameters Function

read_parameters(x)

Multi-dispatch convenience wrapper:

• String (file path) → parameters_from_file

• IOSource → parameters_from_source

• Dict → parameters_from_dict

• vSmartMOM_Parameters → pass-through

source

vSmartMOM.IO.parameters_from_file Function

parameters_from_file(path::AbstractString) -> vSmartMOM_Parameters

Load a registered configuration file and return a fully populated vSmartMOM_Parameters object.

The file format is selected by extension through the Formats.load_config registry. Built-in extensions are .yaml, .yml, and .toml. The loaded document must contain the same parameter schema accepted by parameters_from_dict.

Arguments

• path::AbstractString: Path to a registered configuration file.

Returns

• params::vSmartMOM_Parameters{FT}: Parsed parameter struct ready for model_from_parameters.

Example

using vSmartMOM
params = parameters_from_file("config/my_scene.toml")
params.architecture = vSmartMOM.Architectures.CPU()
model = model_from_parameters(params)

See also

• parameters_from_source for typed sources such as GEOS-Chem NetCDF.

• parameters_from_dict for loading from an in-memory Dict.

• parameters_from_yaml for the legacy YAML-specific wrapper.

• model_from_parameters to build the RT model.

source

vSmartMOM.IO.parameters_from_source Function

parameters_from_source(src::Formats.IOSource) -> vSmartMOM_Parameters

Load parameters from a typed IO source.

This is the extension point for non-file or domain-specific inputs: implement Formats.load_config(src::MySource) to return a configuration Dict, then parameters_from_source(src) will reuse the shared parameter parser.

source

vSmartMOM.IO.parameters_from_dict Function

parameters_from_dict(params_dict::Dict) -> vSmartMOM_Parameters

Convert a configuration Dict (e.g., loaded from YAML) into vSmartMOM_Parameters. Validates schema and parses radiative_transfer, geometry, atmospheric_profile, and optional absorption/scattering sections.

source

vSmartMOM.IO.parameters_from_yaml Function

parameters_from_yaml(path::AbstractString) -> vSmartMOM_Parameters

Compatibility wrapper for YAML parameter files.

New code should prefer parameters_from_file, which also supports TOML and any future registered file formats.

source

vSmartMOM.CoreRT.default_parameters Function

Generate default set of parameters for Radiative Transfer calculations (from ModelParameters/)

source

vSmartMOM.CoreRT.copy_parameters Function

copy_parameters(params::vSmartMOM_Parameters; share_luts=false)

Copy a parameter template for an independent trial state. By default this is equivalent to deepcopy(params).

With share_luts=true, reuse the storage of loaded absorption tables in absorption_params.luts and absorption_params.h2o_lut. The per-band LUT lists, H₂O settings list, atmospheric profiles, VMR dictionary, aerosols, surfaces and other parameter state are still deep-copied. Aliases within the copied state are preserved, as with ordinary deepcopy.

Shared LUTs and everything they reference must remain read-only for the lifetime of both templates. Replacing a copied list entry is safe; changing a shared table's coefficients, grids or mutable metadata affects every owner. Model construction and cross-section evaluation read the supplied tables without modifying their storage. This option does not cache atmospheric optical depths or change the behavior of deepcopy for any existing type.

source

Model Construction and Solver Entry Points

vSmartMOM.CoreRT.model_from_parameters Function

model_from_parameters(params::vSmartMOM_Parameters;
                      sources=SolarBeam(), external_solar=false) -> RTModel

Construct an RTModel from user-supplied vSmartMOM_Parameters.

Computes all derived quantities needed by the RT solver:

• Observation geometry and quadrature points

• Rayleigh scattering coefficients (Greek/Cabannes)

• Aerosol optics via Mie theory with δ-M truncation

• Gas absorption cross-sections and optical depth profiles

• Per-band Fourier truncation limits

Arguments

• params::vSmartMOM_Parameters: Configuration struct (typically from parameters_from_yaml).

• external_solar::Bool=false: When true, keep the direct solar direction outside the diffuse operator (rectangular Z₀ source columns instead of an embedded zero-weight μ₀ node). This is an opt-in, TOA-only fast path — it requires Gauss quadrature and is consumed through rt_run_toa. The default embedded-μ₀ mode supports every entry point: full R, T output, interior/BOA observer heights, the atmosphere/surface split, and Radau quadrature. Retrieval workflows that require the compact external-solar operator should pass external_solar=true explicitly.

• aerosol_anchor_bands=nothing: Optional vector of canonical wavenumber grids, one per solve band. Aerosol phase, extinction, and single-scattering albedo endpoint calculations use these grids while the interpolated result is evaluated on params.spec_bands. Supply this when a solve grid is a spectral chunk or includes Raman/ILS shoulders, so changing those temporary endpoints cannot change aerosol optics in the retained physical band.

Returns

• model::RTModel{ARCH, FT}: Hierarchical model ready for rt_run(model).

See also

• model_from_parameters(LinMode(), params) for the linearized (Jacobian) variant.

• parameters_from_yaml(path) to load parameters from a YAML file.

source

model_from_parameters(rs::Union{VS_0to1_plus, VS_1to0_plus}, λ₀, params; sources)

Fill the vibrational Raman state of rs for the incident wavelength λ₀ (nm) and build the RTModel on its bands (the incident wavelength and the N₂/O₂ target bands). Rayleigh and Cabannes depolarizations follow the standard model_from_parameters (depol: -1 takes them from the molecular constants, the Rayleigh one with params.rayleigh_anisotropy). params is not modified.

source

model_from_parameters(::LinMode, params::vSmartMOM_Parameters;
                      sources = SolarBeam(), external_solar = false,
                      aerosol_anchor_bands = nothing,
                      compute_aerosol_microphysics_jacobians = true,
                      compute_h2o_jacobians = true,
                      compute_pressure_jacobians = true,
                      abundance_jacobians = :complete,
                      vertical_grid = FixedPressureGrid())

Construct both the forward RTModel and the linearized RTModelLin objects from the input parameters, for use in linearized (Jacobian) RT computations.

This is the linearized counterpart of model_from_parameters(params). It computes:

1. Forward optical properties (same as the forward-only model):

   • Rayleigh optical depth per layer and spectral point.

   • Aerosol optical properties (via Mie theory) with δ-M truncation.

   • Trace gas absorption cross-sections and optical depths.

2. Linearized optical properties (derivatives of the above):

   • τ̇_aer[iB][iaer, 7, nSpec, nLayers]: Derivatives of aerosol τ w.r.t. 7 sub-parameters [τ_ref, nᵣ, nᵢ, rₘ, σᵣ, p₀, σp] per aerosol type.

   • τ̇_abs[iB][NGas*Nz, nSpec, Nz]: Layer-resolved derivatives of gas absorption τ w.r.t. VMR(gas, z), flattened species-major.

   • lin_aerosol_optics[iB][iaer]: Derivatives of Mie properties (ω̃, fᵗ, greek coefficients) w.r.t. Mie parameters [nᵣ, nᵢ, rₘ, σᵣ].

Returns

• model::RTModel: Forward model (optical properties, geometry, quadrature).

• lin_model::RTModelLin: Linearized model (all derivative arrays).

Notes

• Strict-interior observer heights are inserted as exact atmospheric interfaces during model construction and are supported by the elastic analytic-linearized solver.

• Aerosol Mie derivatives of the extinction cross-section, single-scattering albedo, truncation factor and greek coefficients with respect to [nᵣ, nᵢ, rₘ, σᵣ] come from the analytic linearized NAI-2 calculation (compute_aerosol_optical_properties(LinMode(), mie_model, FT)), which runs on the CPU.

• Set compute_aerosol_microphysics_jacobians=false when all four Mie parameters are fixed. The forward aerosol optics are retained and structurally valid zero tangents are supplied to the downstream mixer.

• Set compute_h2o_jacobians=false when the q-driven H2O profile is fixed. Its forward absorption is retained without generating H2O tangent entries.

• Without an absorption block the model has no gas absorption, as in the forward constructor (q still sets the dry-air column).

• Native gas columns are the partial ∂τ/∂VMR = σ·N_dry: line cross sections and the CIA and MT_CKD optical depths are held fixed. The one exception is ABSCO tables with an H₂O-broadener axis: the q-driven H₂O columns include every such table's response to the H₂O abundance (exact for the linear interpolation in the tabulated VMR). Where the forward absorption responds to an abundance in another way (line-by-line H₂O self broadening, MT_CKD, CIA colliders), the default abundance_jacobians=:complete rejects solves or plans requesting those columns. Pass abundance_jacobians=:frozen_cross_section to accept these omissions explicitly; tangent values are identical in both settings.

• Set compute_pressure_jacobians=false for a retrieval with fixed pressure. Pressure tangent fields are then nothing, not zero sensitivities; use a PlannedRTModelLin whose layout omits pressure. Full-layout solves reject these models. Forward-only absorber extensions remain usable in such plans.

• vertical_grid selects how the vertical grid responds to surface pressure in the surface-pressure tangents: FixedPressureGrid (default; only the bottom boundary moves) or FixedAltitudeGrid (every interface fixed in geometric altitude, so every interface pressure scales with p_surf). The forward optics do not depend on it. A retrieval that varies p_surf must rebuild params.p with the same convention, via surface_pressure_interfaces, for the Jacobian to be the derivative of its forward model.

• aerosol_anchor_bands has the same meaning as in the forward constructor: it fixes aerosol spectral endpoint calculations to canonical full-band grids while evaluating the interpolated optics on chunked or shoulder-expanded solve grids. Forward and tangent optics always share the same anchors.

source

model_from_parameters(flavor::AbstractJacobianFlavor, params; kwargs...)

Build the ordinary forward/linearized optical models, compile flavor, and return a PlannedRTModelLin that activates compact propagation in rt_run.

source

vSmartMOM.CoreRT.rt_run Function

rt_run(model::RTModel; i_band=1) -> ObserverRTResult

Run the forward radiative transfer solver for the selected spectral band.

Performs polarized adding-doubling RT through the atmosphere defined in model, computing top-of-atmosphere (TOA) upwelling and bottom-of-atmosphere (BOA) downwelling Stokes radiances. The solver iterates over azimuthal Fourier orders m = 0, …, CoreRT.m_max_bands(model)[i_band] (derived per band from the stream count, the phase-function expansions, the surface and the sources; see model_from_parameters), and may stop earlier when the configured Fourier-convergence criterion is met. For each order it builds layer R/T/J matrices via elemental → doubling → interaction steps, then applies surface coupling and postprocessing.

Equivalent to rt_run(noRS(), model, i_band) (no Raman scattering).

Arguments

• model::RTModel: Pre-built model from model_from_parameters.

• i_band::Integer=1: Spectral band index to compute.

Returns

An ObserverRTResult. With the default obs_alt: [0], its toa and boa fields contain TOA upwelling and BOA downwelling radiances, each shaped [nVZA × nStokes × nSpec]. Strict-interior outputs are stored in result.levels as LevelRadiance records. Over a CoxMunkSurface the exact direct-solar glint correction (apply_ss_correction!) is added to the TOA radiance only; interior upwelling levels carry the Fourier-series glint.

The result retains the historical seven-slot iteration order, so ordinary endpoint code remains valid:

R, T = rt_run(model)

Example

params = parameters_from_yaml(joinpath(pkgdir(vSmartMOM), "config", "quickstart.yaml"))
model = model_from_parameters(params)
R, T = rt_run(model)
R[1, 1, :]  # Stokes-I TOA radiance at first VZA across the spectrum

See also

• rt_run(model, lin_model, NAer, NGas, NSurf) for linearized RT with Jacobians.

• model_from_parameters to build the model from parameters.

• rt_run_atmosphere / rt_run_surface / rt_run_multi_surface to amortize the layer-accumulation cost across many surfaces over the same atmosphere. They are implemented on top of the atm_snapshot_callback / stop_after_atmosphere / m_max_override keywords below — most callers should use the higher-level functions rather than these directly.

source

rt_run(RS_type, model, iBand; sources=nothing) -> ObserverRTResult

Run height-aware forward RT with an explicit Raman type. The observer convention stored in model.obs_geom selects optional TOA/BOA endpoints and any exact interior interfaces. See ObserverRTResult.

Solar F₀, in order of precedence: the first SolarBeam of an explicit sources= keyword, a user preset RS_type.F₀ (nonzero, shaped (nStokes, nSpec)), then model.sources. An explicit sources= applies to this call only: RS_type.F₀ is left as it was before the call (a preset is not overwritten), so a following call without sources= uses the preset, or model.sources when there is none. Other RS_type fields are working state that every solve updates, with or without sources=.

Advanced keywords:

• sources, streams_callback: forwarded to the column core — see _rt_run_column.

• Atmosphere/surface-split hooks (atm_snapshot_callback, stop_after_atmosphere, m_max_override): when any is active, the call routes straight to the column core so rt_run_atmosphere can capture per-moment snapshots. These are mutually exclusive with interior sensor levels (an ArgumentError is thrown); under stop_after_atmosphere the raw column tuple is returned unwrapped, since the caller consumes the snapshots, not the radiances.

source

rt_run(model, lin_model::PlannedRTModelLin; i_band=1, sources=nothing)

Run a retrieval-selected linearized calculation. The selected band layout is compiled by the retrieval flavour and its compact tangent dimension is used throughout the MOM kernels. Use globalize_jacobian to scatter the returned band-local Jacobian into the shared retrieval state.

source

vSmartMOM.CoreRT.rt_run_toa Function

rt_run_toa(model; i_band=1, sources=nothing)

Run the lean, forward-elastic SFI path and return only directional upwelling Stokes radiance at TOA. This entry point is intended for disk-integrated exoplanet calculations using QuadPoints.external_solar=true: the collimated solar direction is not a diffuse stream, and BOA, HDR, BHR, and inelastic output arrays are neither allocated nor postprocessed. Atmospheric and surface interactions are still solved in full because both contribute to TOA radiance.

source

rt_run_toa(rs::RRS, model; i_band=1, sources=nothing)

Run TOA-only rotational Raman SFI with an external solar direction. Returns a named tuple (elastic, inelastic); the latter sums the Raman-transition axis in the same manner as the full-column Raman postprocessor. Solar F₀ precedence and the call-only effect of sources= are as for rt_run(RS_type, model, iBand).

source

Batch Scene Processing

Process many scenes without rebuilding the model — full reference on the CoreRT API page: BatchContext, update_model!, update_aerosol_loading!, update_aerosol_microphysics!.

Architectures

vSmartMOM.Architectures.CPU Type

CPU <: AbstractArchitecture

Run on a single-core of a CPU.

source

vSmartMOM.Architectures.GPU Type

GPU <: AbstractArchitecture

Run on a single NVIDIA CUDA GPU.

source

vSmartMOM.Architectures.MetalGPU Type

MetalGPU <: AbstractArchitecture

Run on an Apple Silicon GPU through Metal.jl. Metal support is loaded through the optional vSmartMOMMetalExt package extension and requires Float32 arrays. The current Metal batched inverse path uses a conservative 32 KiB threadgroup memory guard, so large stream/Stokes matrices should use CPU or CUDA until a global-memory fallback lands.

source

vSmartMOM.Architectures.default_architecture Function

default_architecture()

Return GPU() if CUDA is available, MetalGPU() if Metal is available, and otherwise CPU().

source

vSmartMOM.Architectures.array_type Function

array_type(arch::AbstractArchitecture)

Return the array constructor for the given architecture (Array for CPU, CuArray for CUDA GPU, and MtlArray for MetalGPU when the matching optional backend extension is loaded).

source

Return the array constructor for the model's architecture

source