MetDrivers API

For narrative coverage of the transport-binary format and the replay-gate contract, see Binary format.

AtmosTransport.MetDrivers Module

MetDrivers

Meteorological data adapters for the basis-explicit transport architecture.

Provides:

• abstract driver types with capability traits;

• topology-generic transport-binary readers; and

• ERA5 native reduced-Gaussian GRIB geometry helpers.

source

AtmosTransport.MetDrivers.AbstractColumnClosureHeader Type

Column closure of a cubed-sphere transport binary, decoded from its column_closure_* header keys: ColumnClosureHeader when the writer column-balanced its fluxes and recorded the closure, NoColumnClosureHeader when the keys are absent (no cubed-sphere column balance ran, or the binary predates the record).

source

AtmosTransport.MetDrivers.AbstractMassFluxMetDriver Type

AbstractMassFluxMetDriver <: AbstractMetDriver

Reads pre-computed mass fluxes (am, bm, cm, m).

source

AtmosTransport.MetDrivers.AbstractMetDriver Type

AbstractMetDriver

Supertype for all meteorological data drivers.

Required methods

total_windows(driver) -> Int
window_dt(driver) -> FT (seconds per met window)
steps_per_window(driver) -> Int
steps_per_window(driver, win_index) -> Int
steps_per_window_schedule(driver) -> Vector{Int}
load_transport_window(driver, win_index)
driver_grid(driver)
air_mass_basis(driver)
surface_pressure_basis(driver)

Custom drivers that do not override surface_pressure_basis retain the historical interpretation that their window surface_pressure is total (moist-air) pressure. Drivers carrying dry pressure must return DrySurfacePressure() explicitly.

source

AtmosTransport.MetDrivers.AbstractTransportBinaryGeometry Type

AbstractTransportBinaryGeometry

Geometry metadata embedded in a version-4 transport binary. Concrete geometry types carry only the fields meaningful for their topology; reader and grid construction code dispatches on this type instead of branching on string tags.

source

AtmosTransport.MetDrivers.ColumnClosureHeader Type

Recorded column closure (docs/src/concepts/binary_format.md): the rule of the per-cell tolerance τ_c, the windows covered, and the maxima over windows of the projected column residual |r_c^⊥| [kg], its ratio to τ_c, the residual folded into cm [kg] and its ratio to its tolerance. Both ratios are at most 1 in a binary that loads.

source

AtmosTransport.MetDrivers.ConvectionForcing Type

ConvectionForcing{CM, DT, TM, CB}

Container for one window (or one substep) of convective mass-flux forcing. Four optional payload slots:

• cmfmc — cloud updraft mass flux at level interfaces. Supported layouts are structured (Nx, Ny, Nz+1), face-indexed (ncell, Nz+1), and cubed-sphere panel tuples NTuple{6, <:AbstractArray{FT, 3}} with per-panel shape (Nc, Nc, Nz+1). GCHP / CMFMCConvection consumer.

• dtrain — detraining mass flux at layer centers. Supported layouts match cmfmc, with layer-center shape (Nx, Ny, Nz), (ncell, Nz), or NTuple{6} of (Nc, Nc, Nz). When nothing, CMFMCConvection falls through to Tiedtke-style single-flux transport.

• tm5_fields :: Union{Nothing, NamedTuple{(:entu, :detu, :entd, :detd)}} — four-field entrainment/detrainment arrays at layer centers (Nx, Ny, Nz). TM5 / TM5Convection consumer.

• cloud_base — convective cloud-base layer (top-down index stored as a float), 2-D like the surface fields (NTuple{6} of (Nc, Nc) on the cube), or nothing. GEOS-Chem takes it from DQRCU; CMFMCConvection otherwise derives it from the lowest non-zero CMFMC edge. Requires cmfmc.

Invariants (enforced by the inner constructor)

• DTRAIN requires CMFMC. dtrain !== nothing ⇒ cmfmc !== nothing. DTRAIN without CMFMC is meaningless (DTRAIN detrains from the updraft mass flux; no mass flux, nothing to detrain).

• Dual capability is allowed. A binary may carry both CMFMC and TM5 payloads simultaneously; the sim selects which capability to consume based on the installed operator. The invariant here only enforces the load-bearing constraint above.

• Capability is INVARIANT for the lifetime of a DrivenSimulation. copy_convection_forcing! enforces strict tuple match between dst and src so a mid-run capability toggle raises an error — catches both "stale values" (dst has a field src doesn't) and "missing destination" (src has a field dst doesn't).

Default construction

ConvectionForcing() produces an all-nothing placeholder. This is the initial value of TransportModel.convection_forcing; DrivenSimulation allocates real buffers at construction via allocate_convection_forcing_like.

See also

• has_convection_forcing — capability probe.

• copy_convection_forcing! — per-window refresh copy.

• allocate_convection_forcing_like — sim-construction allocation.

source

AtmosTransport.MetDrivers.CubedSphereBinaryGeometry Type

Geometry metadata for a six-panel cubed-sphere binary.

source

AtmosTransport.MetDrivers.CubedSphereFluxDeltas Type

CubedSphereFluxDeltas

Replay delta for panel-native cubed-sphere air mass. Canonical cubed-sphere forcing keeps face fluxes constant within a meteorological window.

source

AtmosTransport.MetDrivers.FaceIndexedFluxDeltas Type

Replay deltas for face-indexed horizontal flux, vertical flux, and air mass.

source

AtmosTransport.MetDrivers.FluxFidelityHeader Type

Typed horizontal-flux certificate decoded from the flat binary header.

status and kind are nominal types. A FidelityPassed certificate is always WindRederivedFidelity and carries every numeric metric (finite); NativePassthroughFidelity (GEOS native fluxes) is FidelityNotApplicable and carries only the balance-correction metrics; NoFluxFidelityKind has no samples. time_sampling is the windows' common effective sampling or "mixed", in which case time_sampling_by_window lists every window's. The balance-correction metrics measure the column-balance correction Δ = F_balanced − F of the sampled pre-balance amounts F, flux-weighted: balance_correction_rms_relative = RMS(Δ)/RMS(F) over all samples, and the largest per-level value with its level (balance_correction_max_level, 1 = top).

source

AtmosTransport.MetDrivers.LatLonBinaryGeometry Type

Geometry metadata for a regular longitude-latitude binary.

source

AtmosTransport.MetDrivers.OmegaFidelityHeader Type

Typed source-OMEGA certificate decoded from the flat binary header. A FidelityPassed certificate has samples, finite metrics, passed == true and satisfies its own gates: nrmse < nrmse_limit, correlation > correlation_min, slope_min < slope < slope_max.

source

AtmosTransport.MetDrivers.PBLSurfaceForcing Type

PBLSurfaceForcing(pblh, ustar, hflux, t2m[, eflux])

Container for raw surface fields used by the PBL diffusion closure.

Fields are topology-shaped 2D arrays:

• structured: (Nx, Ny)

• face-indexed: (ncell,) when such a path is added

• cubed sphere: NTuple{6, <:AbstractMatrix} with one (Nc, Nc) panel

Units follow the canonical runtime contract:

• pblh - boundary-layer height [m]

• ustar - friction velocity [m s^-1]

• hflux - upward sensible heat flux [W m^-2]

• t2m - 2 m air temperature [K]

• eflux - upward latent heat flux [W m^-2], or nothing (only GEOS-Chem's non-local VDIFF scheme needs it)

source

AtmosTransport.MetDrivers.ReducedGaussianBinaryGeometry Type

Geometry metadata for a face-indexed reduced-Gaussian binary.

source

AtmosTransport.MetDrivers.ReplayScratch Type

ReplayScratch(dims)

Per-cell work arrays of the replay check, of shape dims (the air-mass shape): div, the net horizontal outflow of each cell, and mag, the sum of the magnitudes of its horizontal face fluxes. Allocate one per grid and reuse it across windows.

source

AtmosTransport.MetDrivers.StreamingTransportBinaryWriter Type

StreamingTransportBinaryWriter{FT}

Handle for incrementally writing transport-binary windows to disk without holding all windows in memory. Created by open_streaming_transport_binary, each window is written via write_streaming_window!, and the file is finalised by close_streaming_transport_binary!.

Memory footprint: one elems_per_window-length pack buffer (Vector{FT}) plus the open IOStream. All other per-window data is owned by the caller.

The windows go to staging_path, a staging file next to path from AtomicFiles.open_atomic_staging (O_EXCL, mode 0o666 & ~umask). Closing a complete stream renames it onto path; an incomplete or failed stream is removed and a previous path is left untouched.

source

AtmosTransport.MetDrivers.StructuredFluxDeltas Type

Replay deltas for directional lat-lon face fluxes and cell air mass.

source

AtmosTransport.MetDrivers.TransportBinaryContract Type

TransportBinaryContract(; source_flux_sampling, air_mass_sampling,
                          flux_sampling, flux_kind, delta_semantics,
                          humidity_sampling,
                          poisson_balance_target_scale,
                          poisson_balance_target_semantics)

Self-describing transport-binary timing/basis contract. All eight fields are required — no defaults — so a writer cannot produce an ambiguous binary. Readers call validate_transport_contract! on the parsed header to decide whether the file is trustworthy.

Canonical usage: construct via canonical_window_constant_contract for window-constant, per-substep mass fluxes.

Symbol fields are validated against the _TRANSPORT_ALLOWED_* tuples at construction time. Combinations are also checked:

• delta_semantics === :forward_window_endpoint_difference requires the payload to carry dm (or dm + dhflux); the writer is responsible for honoring this.

• humidity_sampling === :window_endpoints requires qv_start + qv_end in the payload; :none requires neither.

source

AtmosTransport.MetDrivers.TransportBinaryDriver Type

TransportBinaryDriver

Meteorological driver backed by a validated version-4 transport binary. Geometry dispatch reconstructs the appropriate grid and loads structured, face-indexed, or panel-native windows through the same public interface.

source

AtmosTransport.MetDrivers.TransportBinaryDriver Method

TransportBinaryDriver(reader; arch=CPU(), Hp=1,
                      validate_windows=true, validate_replay=false)
TransportBinaryDriver(path; FT=Float64, arch=CPU(), Hp=1,
                      validate_windows=true, validate_replay=false)

Open a version-4 binary and construct its runtime grid. Hp is the horizontal halo width for cubed-sphere grids and is ignored by other geometries. Optional validation checks vertical-flux magnitude for LL/RG and replay continuity for all geometries. The path constructor closes its internally opened reader if construction fails; callers retain ownership of a reader passed directly.

source

AtmosTransport.MetDrivers.TransportBinaryHeader Type

TransportBinaryHeader{G<:AbstractTransportBinaryGeometry}

Validated metadata for the current transport-binary format. geometry selects the horizontal topology through dispatch, while the remaining fields describe the common timing, vertical coordinate, mass basis, and payload contract.

planet_radius_m is the radius of the sphere on which the preprocessor computed cell areas, and so the air masses from pressure thickness (m = Δp A / g); the runtime builds its mesh with it. Binaries written before the key existed read as EARTH_RADIUS, the radius the runtime used for them.

A_ifc and B_ifc define interface pressure as p_half[k] = A_ifc[k] + B_ifc[k] * surface_pressure, with k = 1 at the top of atmosphere. flux_kind distinguishes mass per transport substep from a full-window mass amount.

flux_fidelity, omega_fidelity and column_closure are the write-time certificate and column-closure record, checked for consistency when the header is parsed.

source

AtmosTransport.MetDrivers.TransportBinaryReader Type

TransportBinaryReader{FT, DiskFT, G}

Memory-mapped reader for the current transport-binary format.

FT is the element type produced by window loaders, DiskFT is the mmap element type, and G is the concrete geometry metadata type. Payloads remain in their native topology: structured arrays for lat-lon, face-indexed arrays for reduced Gaussian, and six panel arrays for cubed sphere.

source

AtmosTransport.MetDrivers.TransportWindow Type

TransportWindow

A decoded version-4 forcing interval. The concrete flux and delta types encode the horizontal topology, while optional fields describe physical capabilities: humidity endpoints, convection, PBL surface forcing, GCHP VDIFF state, and precomputed TM5 interface diffusion exchange dkg [kg s⁻¹]. A window owns no prognostic tracer state.

source

AtmosTransport.MetDrivers.air_mass_basis Method

Return the binary's declared air-mass basis (:dry or :moist).

source

AtmosTransport.MetDrivers.allocate_convection_forcing_like Method

allocate_convection_forcing_like(src::ConvectionForcing, backend_hint) -> ConvectionForcing

Build a destination ConvectionForcing whose array fields are similar(src_field) — same shape, same element type, same backend (inferred from backend_hint, typically model.state.air_mass). Capability (which fields are non-nothing) exactly matches src.

Used by DrivenSimulation construction to seed model.convection_forcing from the first loaded window. After this step, copy_convection_forcing! reuses the same buffers across all subsequent substeps.

The all-nothing placeholder ConvectionForcing() produces another all-nothing placeholder when run through this helper.

source

AtmosTransport.MetDrivers.binary_capabilities Method

binary_capabilities(reader) -> NamedTuple

Summarise what operators this binary can drive. Geometry-specific advection requirements are selected through the reader's geometry type. Fields:

• advection :: Bool — all geometry-required advection sections present (m, am, bm, cm on LL/CS; m, hflux, cm on RG).

• replay_gate :: Bool — any flux-delta section (dam/dbm/dcm/dm/dhflux) present.

• tm5_convection :: Bool — entu/detu/entd/detd all present.

• tm5_convection_mass_basis :: Union{Nothing, AbstractMassBasis} — typed basis of the TM5 sections (DryBasis()/MoistBasis()); nothing without TM5 sections or when the binary predates the record (moist fluxes, see TM5_CONVECTION_MASS_BASIS_KEY).

• tm5_convection_provenance :: Vector{Pair{String, String}} — the recorded source of the TM5 sections (TM5_CONVECTION_SOURCE_KEY, TM5_EC2TM_CONVENTION_KEY, convection_attachment), empty when none is recorded or the binary has no TM5 sections.

• cmfmc_convection :: Bool — cmfmc present (CS only; LL/RG returns false).

• pbl_diffusion :: Bool — complete runnable PBL forcing (CS only).

• gchp_vdiff :: Bool — complete runnable GCHP VDIFF forcing (CS only).

• gchp_nonlocal_vdiff :: Bool — GCHP VDIFF forcing plus latent heat flux pbl_eflux, as GEOS-Chem's non-local PBL scheme needs (CS only).

• cmfmc_cloud_base :: Bool — convective cloud base present.

• surface_pressure :: Bool — ps present.

• humidity :: Bool — qv_start/qv_end present.

• mass_basis :: Symbol — :dry or :moist.

• surface_pressure_basis :: AbstractSurfacePressureBasis — typed meaning of the stored ps payload.

• grid_type :: Symbol — :latlon / :reduced_gaussian / :cubed_sphere.

• nlevel, steps_per_window — header values.

• variable_step_schedule :: Bool — per-window substep counts differ.

• flux_kind :: Symbol — stored mass-flux normalization contract.

• preprocessor_contract, vertical_Nz_output, adaptive_substeps — raw header values, nothing when absent.

• dry_mass_target_ps_pa, dry_mass_target_source, dry_mass_pinned — the pinned header target or carried window-1 mass, its provenance, and pin state (nothing for legacy files whose state is not recorded).

• payload_sections :: Vector{Symbol} — raw set for debugging.

source

AtmosTransport.MetDrivers.canonical_window_constant_contract Method

canonical_window_constant_contract(; steps_per_window,
                                     humidity_sampling = :none,
                                     source_flux_sampling = :window_start_endpoint,
                                     include_flux_delta = true) -> TransportBinaryContract

Build the canonical contract for window-constant, per-substep mass amounts. The Poisson target scale is 1 / (2 * steps_per_window) — matching the TM5 r1112 horizontal-sweep count of 2 * steps_per_window per window.

include_flux_delta = true implies delta_semantics = :forward_window_endpoint_difference (the writer must include dm in the payload); false implies :none.

source

AtmosTransport.MetDrivers.close_streaming_transport_binary! Method

close_streaming_transport_binary!(writer) -> String

Flush and close the streaming transport binary. Returns the file path. An incomplete stream is closed and rejected without publishing a final header.

source

AtmosTransport.MetDrivers.copy_convection_forcing! Method

copy_convection_forcing!(dst::ConvectionForcing, src::ConvectionForcing) -> dst

Copy src's arrays into dst's preallocated buffers in place. Preserves === identity of the destination's arrays — this is what makes the per-window refresh zero-allocation after the sim-construction allocation step.

Enforces strict capability match first: both sides must have identical _cap(...) tuples. Otherwise throws ArgumentError. This catches both directions of mismatch (dst has a field src lacks, or vice versa) — both are silent correctness hazards.

Used by DrivenSimulation._refresh_forcing! to populate sim.model.convection_forcing from sim.window.convection at the first substep of each window.

source

AtmosTransport.MetDrivers.current_time Method

current_time(meteo) -> Float64

Simulation time [s] at the start of the next step. Threaded through operator apply! methods:

apply!(state, meteo, grid, op, dt; workspace)

Every operator that consumes time (ExponentialDecay rates, ImplicitVerticalDiffusion Kz refresh, future emission-rate StepwiseFields, etc.) reads current_time(meteo) once per call and passes the resulting scalar to each update_field!(f, t).

Canonical usage

• Production: meteo = sim::DrivenSimulation; returns sim.time (Float64), set from the window and step counters after each step!(sim). See src/Models/driven_stepping.jl.

• Unit tests without a sim: meteo = nothing; returns 0.0.

source

AtmosTransport.MetDrivers.driver_grid Method

Return the grid reconstructed and owned by the runtime driver.

source

AtmosTransport.MetDrivers.flux_application_seconds Method

flux_application_seconds(dt_seconds, steps, fk::Symbol) -> Float64

Seconds spanned by ONE stored flux amount — the normalization interval for converting stored am/bm/cm mass amounts [kg] to rates or winds. Per-substep storage: one palindrome application = dt / (2 * steps). Full-window storage: the full met window = dt. Every diagnostic that divides a stored flux by a time interval must use this (not a hand-rolled dt/(2*steps)), or it is wrong by 2 * steps on full-window binaries.

source

AtmosTransport.MetDrivers.flux_interpolation_mode Method

How should flux forcing vary within a met window?

source

AtmosTransport.MetDrivers.flux_storage_substep_scale Method

flux_storage_substep_scale(::Type{FT}, steps, fk::Symbol) -> FT

Multiplier converting STORED flux amounts to per-palindrome-application amounts (what the transport kernels consume): 1 for per-substep storage, 1/(2*steps) for full-window storage. Transport-style script consumers that feed raw window fluxes into kernels must scale by this (the runtime's DrivenSimulation does so automatically at every forcing refresh).

source

AtmosTransport.MetDrivers.has_convection_forcing Method

has_convection_forcing(forcing::ConvectionForcing) -> Bool

Whether forcing carries any non-nothing payload. Returns false for the all-nothing placeholder. Used by _refresh_forcing! as a gate so the copy path is skipped for models without an active convection operator.

The window-level overload has_convection_forcing(window) = window.convection !== nothing is defined in transport_binary/window.jl alongside the window struct extensions.

source

AtmosTransport.MetDrivers.has_qv_endpoints Method

Return true when both specific-humidity endpoint sections are present.

source

AtmosTransport.MetDrivers.has_tm5_convection Method

has_tm5_convection(r::TransportBinaryReader) -> Bool

true if the binary carries all four TM5 convection sections (entu, detu, entd, detd) — the contract enforced by the preprocessor when tm5_convection = true. Used by the TransportBinaryDriver to decide whether to populate ConvectionForcing.tm5_fields on loaded windows.

source

AtmosTransport.MetDrivers.inspect_binary Method

inspect_binary(path; io = stdout) -> NamedTuple

Open the binary at path, print a capability-augmented report to io, and return the binary_capabilities NamedTuple for programmatic consumption (tests, CLI capability-intersection, folder-level validation).

Obsolete format_version < TRANSPORT_BINARY_FORMAT_VERSION files are rejected here just like runtime drivers; inspect the raw JSON header with external tools if a stale file must be audited.

source

AtmosTransport.MetDrivers.load_flux_delta_window! Method

load_flux_delta_window!(reader, win; buffers...) -> NamedTuple | nothing

Load forward endpoint deltas for air mass and the topology's face fluxes. Returns nothing when the binary carries no delta sections.

source

AtmosTransport.MetDrivers.load_qv_pair_window! Method

load_qv_pair_window!(reader, win; qv_start=nothing, qv_end=nothing)

Load the specific-humidity fields at the start and end of window win. Returns (; qv_start, qv_end) or nothing when humidity endpoints are absent. Caller-provided arrays are filled in place.

source

AtmosTransport.MetDrivers.load_surface_window! Method

load_surface_window!(reader, win) -> PBLSurfaceForcing | nothing

Load the raw PBL surface payload for one CS window. This is a convenience wrapper over load_window!; callers that already need the advection fields should use load_window!(reader, win).surface to avoid a second payload read.

source

AtmosTransport.MetDrivers.load_surface_window! Method

load_surface_window!(reader, win; pblh=..., ustar=..., hflux=..., t2m=...) -> PBLSurfaceForcing | nothing

Load raw PBL surface fields for window win. Returns nothing when the binary lacks surface sections. A binary carrying only a subset of pblh, ustar, pbl_hflux, and t2m is rejected because the runtime PBL closure needs the complete raw surface payload. The on-disk heat-flux section is pbl_hflux; callers still receive it as PBLSurfaceForcing.hflux.

source

AtmosTransport.MetDrivers.load_tm5_convection_window! Method

load_tm5_convection_window!(reader, win; entu=..., detu=..., entd=..., detd=...) -> NamedTuple | nothing

Load the four TM5 convection layer-center fields for window win. Returns (; entu, detu, entd, detd) when the binary carries all four sections, or nothing when no TM5 data is present. Allocates only if the caller doesn't provide pre-allocated buffers.

All fields share the same shape as m: (Nx, Ny, Nz) for structured or (ncells, Nz) for face-indexed binaries. Orientation is as written by the preprocessor (AtmosTransport: k=1=TOA, k=Nz=surface); no runtime reorientation happens here — the kernel reads them directly.

Invariant: if ANY of the four sections is present in the header, ALL four must be present. This mirrors the ConvectionForcing.tm5_fields NamedTuple contract — partial payload is not a valid convection forcing.

source

AtmosTransport.MetDrivers.load_transport_window! Method

load_transport_window!(window, driver, win) -> window

Refill an existing host-resident cubed-sphere window (from load_transport_window on the same binary, or on one with the same layout, same_window_layout) with window win, without allocating new field arrays. Equal to load_transport_window(driver, win) provided the halos of window's padded fields still hold the zeros of that first load: only interiors are written.

source

AtmosTransport.MetDrivers.load_transport_window Method

load_transport_window(driver, win)

Load one typed forcing window from the transport binary.

source

AtmosTransport.MetDrivers.load_window! Method

load_window!(reader, win) -> NamedTuple

Load window win from a cubed-sphere transport binary. Returns NTuples of per-panel arrays plus optional cmfmc / dtrain payloads when they are present in the binary.

source

AtmosTransport.MetDrivers.load_window! Method

load_window!(reader, win; buffers...) -> (air_mass, surface_pressure, fluxes)

Load the required transport state for one lat-lon or reduced-Gaussian window. Optional buffer keywords reuse caller-owned storage; omitted buffers are allocated with the reader's output element type.

source

AtmosTransport.MetDrivers.mesh_convention Method

mesh_convention(reader) -> AbstractCubedSpherePanelConvention

Return the panel-numbering convention declared in the binary header.

Returns GnomonicPanelConvention() for ERA5-CS binaries and GEOSNativePanelConvention() for GEOS-FP/IT binaries tagged with panel_convention="geos_native". Callers should pass the result directly to CubedSphereMesh(; convention=mesh_convention(reader)) to guarantee that the halo exchange uses the correct edge-to-edge connectivity table.

source

AtmosTransport.MetDrivers.mesh_definition Method

mesh_definition(reader) -> CubedSphereDefinition

Return the full cubed-sphere geometry definition declared in the binary header. Binaries record cs_coordinate_law, cs_center_law, panel_convention, and longitude_offset_deg explicitly.

source

AtmosTransport.MetDrivers.open_streaming_transport_binary Method

open_streaming_transport_binary(path, grid::AtmosGrid{<:ReducedGaussianMesh},
                                nwindow, sample_window; kwargs...)

Open a transport binary file for streaming (per-window) writes on a reduced-Gaussian grid.

sample_window is a NamedTuple with the same keys as the windows that will be written (e.g. (m=..., hflux=..., cm=..., ps=...)). Its arrays must have the correct sizes but their values are ignored — it is only used to determine payload_sections and to validate dimensions. The typed surface_pressure_basis keyword is required; it is not inferred from the air-mass basis.

Returns a StreamingTransportBinaryWriter.

source

AtmosTransport.MetDrivers.recompute_cm_from_dm_target! Method

recompute_cm_from_dm_target!(cm, am, bm, m, dm_target)

Structured-directional convenience wrapper for the shared explicit-dm continuity closure.

source

AtmosTransport.MetDrivers.recompute_cm_from_dm_target! Method

recompute_cm_from_dm_target!(layout, div_h, cm, m, dm_target, flux_args...;
                             residual_weight = layer_mass_residual_weight)

Shared explicit-dm continuity closure. The topology-specific code only builds div_h; the vertical integration and residual redistribution are common:

$$C_{k+1}=C_k-D_k-\Delta m_k,C_1=0,$$

and the column residual R = C_{N_z+1} is folded back as C_{k+1} ← C_{k+1} − R Σ_{j≤k} w_j / Σ_j w_j with w_k = residual_weight(m_k, k) (the layer mass by default). Preprocessing passes its column-balance weights, so the residual of a hybrid_mass balance reaches only hybrid layers, as in the cubed-sphere diagnose_cs_cm!.

source

AtmosTransport.MetDrivers.recompute_faceindexed_cm_from_dm_target! Method

recompute_faceindexed_cm_from_dm_target!(cm, hflux, face_left, face_right,
                                         div_scratch, m, dm_target)

Face-indexed convenience wrapper for the shared explicit-dm continuity closure.

source

AtmosTransport.MetDrivers.supports_convection Method

Does this driver provide convective mass flux / detrainment for convection?

source

AtmosTransport.MetDrivers.supports_diffusion Method

Does this driver provide diffusivity fields for boundary-layer diffusion?

source

AtmosTransport.MetDrivers.supports_moisture Method

Does this driver provide specific humidity for dry-mass correction?

source

AtmosTransport.MetDrivers.supports_native_vertical_flux Method

Does this driver provide native vertical mass fluxes (vs diagnosing from continuity)?

source

AtmosTransport.MetDrivers.surface_pressure_basis Method

Surface-pressure meaning supplied by a meteorological driver.

The compatibility fallback is total pressure, matching the pre-existing custom-driver contract. A driver that supplies dry pressure must override this method and return DrySurfacePressure().

source

AtmosTransport.MetDrivers.tm5_convection_mass_basis Method

tm5_convection_mass_basis(r::TransportBinaryReader) -> Union{AbstractMassBasis, Nothing}

Typed air-mass basis of the TM5 convection sections (DryBasis() or MoistBasis()) parsed from the header key TM5_CONVECTION_MASS_BASIS_KEY; nothing when the binary has no TM5 sections or does not record the basis (written before the key existed, with moist fluxes).

source

AtmosTransport.MetDrivers.uses_binary_substep_contract Method

Does this driver provide a verified per-window timestep contract?

source

AtmosTransport.MetDrivers.validate_cs_writer_contract! Method

validate_cs_writer_contract!(header::AbstractDict)

Write-time guard: assert every runtime-read cubed-sphere contract key (_CS_WRITER_CONTRACT_KEYS) is present before a binary is finalized — the writer-side mirror of [validate_transport_contract!]. The single choke point open_streaming_cs_transport_binary emits these keys with defaults, so this never fires in normal use; it exists to fail LOUDLY if a future refactor drops the default emission, rather than silently shipping a binary that makes the runtime run convection/chemistry per advection substep (the 2026-05-31 N320 regression: a new source path omitted runtime_substep_contract).

source

AtmosTransport.MetDrivers.validate_transport_contract! Method

validate_transport_contract!(header::AbstractDict)

Assert that header declares the current transport-binary contract and that the timing metadata is self-consistent. format_version is a hard boundary: only TRANSPORT_BINARY_FORMAT_VERSION is accepted. Older files are obsolete and must be regenerated rather than loaded through compatibility defaults.

Shared between TransportBinaryDriver, TransportBinaryReader, and the scripts/diagnostics/inspect_transport_binary.jl tool so there is ONE validator every reader-facing tool calls.

source

AtmosTransport.MetDrivers.verify_window_continuity Method

verify_window_continuity(scratch, m_cur, cm, m_next, steps_per_window)
verify_window_continuity(layout, scratch, m_cur, cm, m_next, steps_per_window, flux_args...)

Replay one window's stored mass fluxes against the stored air-mass endpoints, cell by cell. With n = steps_per_window, each cell's budget residual is

r = m_cur − 2n (div_h + cm[k+1] − cm[k]) − m_next

(div_h the net horizontal outflow of one flux application) and its scale is

s = |m_cur| + |m_next| + 2n (Σ_faces |F_h| + |cm[k]| + |cm[k+1]|),

the summed magnitudes of the budget's terms, which bounds the rounding error of the sum. The result's max_rel_err is the largest |r| / s of any cell, with max_abs_err = |r| and worst_idx at that cell. A non-finite residual counts as Inf, so NaN or Inf in the stored data fails every tolerance. Compare max_rel_err with replay_tolerance(FT).

The first form assumes scratch.div and scratch.mag (a ReplayScratch) are already populated; the second builds them through the topology-specific layout.

This certifies that the stored fluxes carry m_cur to m_next under the runtime's palindrome continuity. It does not test the winds themselves: preprocessing diagnoses cm from the same horizontal fluxes and endpoints just before the check; see What the replay gate certifies.

source

AtmosTransport.MetDrivers.verify_window_continuity_cs Method

verify_window_continuity_cs(m_cur, am, bm, cm, m_next, steps_per_window;
                            scratch = ReplayScratch(size(m_cur[1])))

Cubed-sphere convenience wrapper for the shared replay kernel. The caller must provide panel-local arrays with synchronized boundary mirrors so each panel's structured divergence matches the closed-sphere flux field. Callers that check many windows should allocate one panel-sized scratch and pass it to every call; all panels reuse it.

source

AtmosTransport.MetDrivers.verify_window_continuity_ll Method

verify_window_continuity_ll(m_cur, am, bm, cm, m_next, steps_per_window)

Structured-directional convenience wrapper for the shared replay kernel.

source

AtmosTransport.MetDrivers.verify_window_continuity_rg Method

verify_window_continuity_rg(m_cur, hflux, cm, m_next, face_left, face_right,
                            steps_per_window; scratch = ReplayScratch(size(m_cur)))

Face-indexed convenience wrapper for the shared replay kernel. Pass a reused scratch to avoid allocating per window.

source

AtmosTransport.MetDrivers.write_streaming_window! Method

write_streaming_window!(writer, window)

Pack and write a single window to the streaming transport binary. Windows must be written in order (1, 2, …, nwindow).

source

AtmosTransport.MetDrivers.write_transport_binary Method

write_transport_binary(path, grid, windows; kwargs...) -> path

Write a canonical v4 lat-lon or reduced-Gaussian transport binary from an AtmosGrid and an ordered vector of forcing windows. Window payloads must match the grid topology and declared mass basis. The typed surface_pressure_basis keyword is required and records whether window.ps is total or dry pressure; it is deliberately independent of mass_basis. The file is written through AtomicFiles.atomic_publish: it replaces path only after the header and all payloads succeed, with mode 0o666 & ~umask. A lat-lon mesh must have uniform latitude faces: the header records only the latitude interval, so a mesh built from non-uniform faces (Δφ = NaN) is refused with an ArgumentError.

source

AtmosTransport.MetDrivers.ERA5 Module

ERA5 met driver

ERA5-specific dry flux building from spectral, gridded, and native-GRIB fields.

source

AtmosTransport.MetDrivers.ERA5.ERA5ReducedGaussianGeometry Type

ERA5ReducedGaussianGeometry{FT}

Reduced-Gaussian geometry read from a native ERA5 / IFS GRIB message.

Fields

• latitudes – ring-center latitudes [degrees], ordered south -> north

• nlon_per_ring – number of longitude cells on each ring (pl)

• grid_type – GRIB grid type, expected to be "reduced_gg"

• gaussian_number – reduced-Gaussian resolution parameter N

• longitude_first – longitude of first stored grid point [degrees]

• longitude_last – longitude of last stored grid point [degrees]

• j_scans_positively – raw GRIB scanning-direction flag

• j_points_are_consecutive – raw GRIB storage-order flag

source

AtmosTransport.MetDrivers.ERA5.diagnose_cm_from_continuity! Method

diagnose_cm_from_continuity!(cm, am, bm, Δb, Nx, Ny, Nz)

Diagnose vertical mass flux from horizontal convergence (CPU column loop).

Arguments

• cm :: AbstractArray{FT,3} — output vertical flux, size (Nx, Ny, Nz+1)

• am :: AbstractArray{FT,3} — x-face flux, size (Nx+1, Ny, Nz)

• bm :: AbstractArray{FT,3} — y-face flux, size (Nx, Ny+1, Nz)

• Δb :: AbstractVector{FT} — B-coefficient increments, length Nz

• Nx, Ny, Nz :: Int — grid dimensions

source

AtmosTransport.MetDrivers.ERA5.read_era5_reduced_gaussian_geometry Method

read_era5_reduced_gaussian_geometry(path; FT=Float64, param_id=nothing,
                                    level=nothing, date=nothing, time=nothing)

Read reduced-Gaussian ring geometry from the first matching native GRIB message in path.

This is intended for ERA5 / IFS native fields already archived on the reduced Gaussian grid, for example q, o3, and many cloud/physics variables. Spectral files (gridType = sh) are intentionally rejected.

source

AtmosTransport.MetDrivers.ERA5.read_era5_reduced_gaussian_mesh Method

read_era5_reduced_gaussian_mesh(path; FT=Float64, radius=EARTH_RADIUS, kwargs...)

Convenience wrapper that reads native reduced-Gaussian GRIB geometry and returns a ReducedGaussianMesh ready for src transport geometry.

source