Source terms

vSmartMOM v0.6 introduces a first-class source-term abstraction. Solar beams, surface fluorescence, atmospheric thermal emission, and future lidar pulses are all concrete subtypes of AbstractSource, composed via +, and dispatched per layer through multiple dispatch — no if SFI branching, no RS_type.F₀/RS_type.SIF₀ ownership leak.

The MOM solver is mathematically affine:

optical properties define the operator A
sources         define the additive RHS b

Doubling and adding propagate (A, b) generically. The new design makes that explicit at the type level.

User API

julia

using vSmartMOM
using vSmartMOM.CoreRT

params = read_parameters(joinpath(pkgdir(vSmartMOM), "config", "quickstart.yaml"))
model  = model_from_parameters(params)

# Default — RTModel.sources defaults to a SolarBeam (unit Stokes I irradiance).
R, T = rt_run(model)

# Explicit solar beam with custom F₀ (irradiance, mW · m⁻² · cm⁻¹).
R, T = rt_run(model; sources = SolarBeam(F₀ = solar_irradiance))

# Solar + surface fluorescence (Lambertian-only emission at m=0).
R, T = rt_run(model; sources = SolarBeam() + SurfaceSIF(SIF₀ = sif_spec))

# Thermal-IR / Carbon-I-style scene (1500 K blackbody source at 2-2.4 µm).
spec_band = collect(model.atmosphere.spec_bands[1])   # cm⁻¹
sources   = BlackbodySource(1500, spec_band; pol_n=params.polarization_type.n)          # SolarBeam with Planck F₀
R, T = rt_run(model; sources = sources)

sources can also be set at model build time:

julia

model = model_from_parameters(params; sources = SolarBeam() + SurfaceSIF())

The sources= kwarg on rt_run overrides model.sources for that specific solve; both flow through the same dispatch.

Entry points that take an explicit mode object (rt_run(rs, model, i_band), rt_run_ss(rs, model, i_band), rt_run_toa(rs::RRS, model) and the linearized rt_run(rs, model, lin_model, NAer, NGas, NSurf, i_band)) also accept the legacy preset rs.F₀ = F (a nonzero (nStokes, nSpec) matrix). The solar F₀ of a solve is then, in order of precedence: the SolarBeam of an explicit sources= keyword, the preset rs.F₀, then model.sources. A sources= keyword applies to its own call only: rs.F₀ is left as it was, so the next call without sources= uses the preset again (or model.sources when there is none).

At solve time, an explicit SolarBeam.sza must match the model geometry. Change params.sza before construction or use remake_geometry to change the illumination angle. Multiple solar/blackbody beams throw ArgumentError; for one geometry, sum their irradiance matrices into one SolarBeam. These checks also cover linearized, single-scatter, TOA and split solves.

Composition

Sources compose via + and are stored as a type-stable SourceSet of concrete prepared types in the hot loop:

Expression	Result
`NoSource() + s`	`s`
`SolarBeam() + SurfaceSIF()`	`SourceSet((SolarBeam, SurfaceSIF))`
`(SolarBeam() + SurfaceSIF()) + ThermalEmission()`	`SourceSet((SolarBeam, SurfaceSIF, ...))`
`SourceSet + SourceSet`	flattened — no nesting

SourceSet iteration is unrolled at compile time, so dispatching to per- source kernels is type-stable on both CPU and GPU.

Built-in source types (v0.6)

Type	Where it contributes	Math
`NoSource`	nowhere	identity for source composition
`SolarBeam`	atmospheric layer `j₀±` per Fourier moment	exact finite-δ single-scatter (Fell 1997 Eqs. 1.52-1.54)
`BlackbodySource`	atmospheric layer `j₀±`	sugar around `SolarBeam` with `F₀ = factor · scale · B(ν, T)`
`SurfaceSIF`	surface layer `j₀⁻` at m=0	factor-2 broadcast across Nquad streams (Lambertian only)

BlackbodySource(T, spec_band) is a constructor that returns a SolarBeam with F₀ filled from the Planck spectrum at temperature T. Use it for Carbon-I-like scenes (hot lab source illuminating CO₂/CH₄/H₂O absorption in the 2-2.4 µm range).

ThermalEmission implements the atmospheric volume Planck source in forward RT. Its end-to-end Jacobians remain unsupported. DiffuseBoundary and LidarPulse are future source types.

Units convention

Quantity	Unit
`SolarBeam.F₀`	mW · m⁻² · cm⁻¹
`SurfaceSIF.SIF₀`	mW · m⁻² · cm⁻¹
`SurfaceSIF.SIF755`	same radiance unit as output Stokes I/Q/U/V
`SurfaceSIF.slope`	output radiance unit per nm
`rt_run` output (R, T, J)	mW · m⁻² · sr⁻¹ · cm⁻¹
`SolarBeam(F₀ = ones(...))`	1 mW · m⁻² · cm⁻¹ per spectral pt

All sources in a SourceSet should share these units so additive composition makes physical sense. BlackbodySource defaults to factor = π, which gives πB, the exitance of a Lambertian emitter at T; for the irradiance from a distant disk of radius R at distance d, also set scale = (R/d)² (2.1629e-5 for the Sun at 1 AU). SolarBeam.F₀ is an irradiance, so factor = 1 alone does not describe a collimated lab beam (it leaves the radiance B in F₀); for lab illumination set factor · scale to the solid angle subtended by the source, or the throughput of the optics, that converts B into the irradiance of the beam.

For retrievals, SurfaceSIF(SIF755=..., slope=..., wavelength_nm=...) uses L_SIF(λ) = SIF755 + slope*(λ_nm-755). These two values are state-vector parameters in radiance units. A nonzero SIF amplitude or slope requires an explicit non-unit Fraunhofer spectrum in SolarBeam(F₀=...); the unit default is rejected. This checks for supplied non-unit irradiance; it does not validate calibration or Fraunhofer structure. The modern OCO parameterization uses SIF760, mSIF, and wavenumber_cm1; see the source configuration reference for both coordinate conventions, units, and current composition restrictions.

Differentiation

Forward source support and a declared AD mode do not establish end-to-end Jacobian support. The current linearized driver accepts SolarBeam, SurfaceSIF, NoSource, and compositions of these. It rejects thermal and other source types whose complete tangent propagation is not implemented. The opt-in jacobian_adding=:source path additionally restricts surfaces and observers to its supported Lambertian endpoint configurations.

To extend this support, implement source values and derivatives through elemental construction, doubling, adding, surface coupling, and output reconstruction, then validate against forward finite differences. Merely declaring AnalyticSourceJacobian or ForwardDiffSourceJacobian is insufficient.

AbstractSourceADMode traits declare how each source's parameters participate in linearized RT:

julia

abstract type AbstractSourceADMode end
struct AnalyticSourceJacobian   <: AbstractSourceADMode end
struct ForwardDiffSourceJacobian <: AbstractSourceADMode end   # reserved for v0.7+
struct NoSourceJacobian          <: AbstractSourceADMode end

The AD seam is prepare_source(::AbstractSource, FT, pol_n, nSpec, arr_type). Above the seam, a future prepare_source_with_tangent can trace through user parameters with ForwardDiff. Below, the kernels run on plain FT arrays and the analytic Sanghavi 2014 App. C tangents (for SolarBeam) — bit-equal to today's hand-written linearization.

Dispatch architecture (for software folks)

                      AbstractSource
                            ▲
              ┌─────────────┼──────────────────────┐
              │             │                      │
        NoSource    SourceSet{S<:Tuple}     concrete sources
                                              ▲
                              ┌───────────────┼─────────────────┐
                          SolarBeam    SurfaceSIF     (ThermalEmission, ...)

prepare_source lifts each user-facing source to a Prepared* form on the model's arr_type and FT:

                  AbstractPreparedSource
                            ▲
              ┌─────────────┼──────────────────────┐
              │             │                      │
        NoSource    SourceSet           concrete prepared sources
                                              ▲
                              ┌───────────────┼─────────────────┐
                     PreparedSolarBeam   PreparedSurfaceSIF      ...

The hot loop calls one of two dispatchers:

contribute!(prepared_sources, j₀⁺, j₀⁻, layer_ctx...)         # forward
source_tangent!(prepared_sources, j₀⁺, j₀⁻, J̇₀⁺, J̇₀⁻, ap..., layer_ctx...)  # linearized

NoSource → no-op; SourceSet → unrolled tuple iteration with per- source dispatch; concrete prepared → kernel call.

For surface contributions, the same pattern applies but with double- dispatch on (source-type, surface-type):

surface_source_contribute!(prepared_sources, surface, surface_added_layer, m, pol_type, arch)

The dispatch table below shows how each (source × surface) pair is handled:

Source	Surface	Body
`PreparedNoSource`	any	no-op
`PreparedSourceSet`	any	iterate
`PreparedSolarBeam`	any	(currently in `create_surface_layer!`; will move to dispatch in a later sub-phase)
`PreparedSurfaceSIF`	`LambertianSurface*`	factor-2 SIF₀ broadcast (m=0 only)
`PreparedSurfaceSIF`	non-Lambertian	nonzero/retrievable SIF rejected at solve time

Zero prescribed SIF is a valid placeholder on any surface. Retrievable SIF requires injection support even at zero amplitude because its derivatives are nonzero. Split surface replay validates the cached prepared sources against the replacement surface.

To support fluorescence on a new surface, implement both surface_source_contribute! and surface_source_contribute_lin! for PreparedSurfaceSIF and your surface type, then specialize CoreRT.supports_surface_sif(::YourSurface) = true. The shared validation uses this trait before entering the kernels.

Architecture invariants

Sources only contribute on the elemental / surface step. Doubling and interaction propagate j₀± and J̇₀± affinely without knowing which source produced them. This is why the elastic linearized path is fully if SFI-free in v0.6: the math handles j₀±=0 as a natural no-op.
Per-Fourier-moment cleanliness. Sources are prepared once before the Fourier loop; each m runs through the same operator → source- contribution → propagation pipeline.
AD seam at prepare_source. User-parameter space (potentially Dual) lives above; kernel-space (plain FT) lives below.
RTModel.sources is the source of truth. Defaults to SolarBeam() to preserve historical unit-Stokes-I behavior; users override at construction or per-rt_run call.

API reference

Source vocabulary

vSmartMOM.CoreRT.AbstractSource Type

julia

AbstractSource

Top-level abstract type for v0.6 first-class source terms (solar, thermal, surface fluorescence, lidar, …). Distinct from the legacy AbstractSourceType (which has unused subtypes DNI / SFI and is the type slot reserved by the v0.5 dispatch design for future thermal RT — left untouched in v0.6 to avoid breaking external code).

A concrete source must satisfy the contract documented in src/CoreRT/Sources/types.jl: user-facing configuration that round-trips through prepare_source into a AbstractPreparedSource before reaching kernel code.

Source terms ​

User API ​

Composition ​

Built-in source types (v0.6) ​

Units convention ​

Differentiation ​

Dispatch architecture (for software folks) ​

Architecture invariants ​

See also ​

API reference ​

Source vocabulary ​

Concrete sources ​

AD-mode traits ​

Dispatch entry points ​

Source terms

User API

Composition

Built-in source types (v0.6)

Units convention

Differentiation

Dispatch architecture (for software folks)

Architecture invariants

See also

API reference

Source vocabulary

Concrete sources

AD-mode traits

Dispatch entry points