AtmosTransport.jl

Appearance

State API ​

For narrative coverage including the dry-basis contract and the tracer accessor surface, see State & basis.

AtmosTransport.State.AbstractFaceFluxState Type
julia
AbstractFaceFluxState

Root type for all face-centered mass flux representations.

The transport operator contract is written in terms of this abstract type. Concrete subtypes differ in storage layout to match the mesh's natural flux_topology, and carry a Basis <: AbstractMassFluxBasis type parameter to enforce moist/dry safety.

source
AtmosTransport.State.AbstractMassBasis Type
julia
AbstractMassBasis

Supertype for mass-basis tags carried by CellState and FluxState.

source
AtmosTransport.State.AbstractStructuredFaceFluxState Type
julia
AbstractStructuredFaceFluxState <: AbstractFaceFluxState

Face fluxes stored as separate directional arrays on a logically rectangular mesh. Concrete subtypes expose am (x-face), bm (y-face), cm (z-face).

Structured cell-loop kernels access these arrays directly for performance.

source
AtmosTransport.State.AbstractUnstructuredFaceFluxState Type
julia
AbstractUnstructuredFaceFluxState <: AbstractFaceFluxState

Face fluxes stored as a single face-indexed array with explicit connectivity. Natural for reduced Gaussian and other unstructured meshes (Phase 2+).

source
AtmosTransport.State.CellState Type
julia
CellState{Basis, A, Raw, Names}

Cell-centered prognostic state for transport.

Fields

  • air_mass :: A — air mass per cell [kg] on the basis carried by Basis. Layout matches grid: (Nx, Ny, Nz) for structured, (ncells, Nz) for unstructured.

  • tracers_raw :: Raw — packed tracer mass storage. Shape is (size(air_mass)..., Nt): (Nx, Ny, Nz, Nt) on structured grids, (ncells, Nz, Nt) on face-indexed grids. Kernels dispatch directly on this field; non-kernel code uses the accessor API (ntracers, get_tracer, eachtracer).

  • tracer_names :: Names — NTuple{Nt, Symbol} of tracer names in storage order.

Property access

state.tracers returns a lazy TracerAccessor that forwards state.tracers.CO2 to get_tracer(state, :CO2) (a selectdim view into tracers_raw). state.air_dry_mass aliases state.air_mass for dry-basis code that prefers that name.

Invariant

After each transport step, sum(air_mass) and the per-tracer mass sum sum(view(tracers_raw, ..., t)) must each be conserved (within floating-point tolerance).

source
AtmosTransport.State.CellState Method
julia
CellState(m::AbstractArray; tracers...)

Convenience constructor: CellState(m; CO2=rm_co2, SF6=rm_sf6). Defaults to DryBasis. The input 3D/2D arrays are COPIED into the packed tracers_raw buffer at construction — they are not aliased. Use get_tracer(state, :CO2) (or state.tracers.CO2) to read or mutate the stored tracer after construction.

source
AtmosTransport.State.CellState Method
julia
CellState(::Type{B}, air_mass, tracers_raw, tracer_names)

Direct construction from already-packed storage. Used by adaptation and low-level code that has a 4D buffer in hand.

source
AtmosTransport.State.CubedSphereFaceFluxState Type
julia
CubedSphereFaceFluxState{Basis, AX, AY, AZ} <: AbstractStructuredFaceFluxState

Panel-native structured-directional flux storage for cubed-sphere transport. Each field is an NTuple{6} of halo-padded panel arrays matching the strang_split_cs! contract.

source
AtmosTransport.State.CubedSphereState Type
julia
CubedSphereState{Basis, A3, Raw4, Names}

Panel-native prognostic state for cubed-sphere transport.

Fields

  • air_mass :: NTuple{6, A3} — halo-padded panel air mass arrays with shape (Nc + 2Hp, Nc + 2Hp, Nz).

  • tracers_raw :: NTuple{6, Raw4} — packed per-panel tracer storage with shape (Nc + 2Hp, Nc + 2Hp, Nz, Nt).

  • tracer_names :: Names — names of the tracer axis in storage order.

  • halo_width :: Int — halo width Hp needed to recover the physical interior.

source
AtmosTransport.State.DryBasis Type
julia
DryBasis <: AbstractMassBasis

Tag for dry-air mass.

source
AtmosTransport.State.FaceIndexedFluxState Type
julia
FaceIndexedFluxState{Basis, A, AZ} <: AbstractUnstructuredFaceFluxState

Face-centered mass fluxes for unstructured meshes (Phase 2+), tagged with Basis for moist/dry safety.

Type parameters

  • Basis <: AbstractMassFluxBasis — MoistMassFluxBasis or DryMassFluxBasis

Fields

  • horizontal_flux :: A — prepared substep mass transport per horizontal face [kg for the active transport substep]. Layout: (nfaces, Nz). Positive = flow in face-normal direction.

  • cm :: AZ — vertical flux, same convention as structured.

Vertical storage convention

The cm field assumes vertical fluxes are columnar (one column per horizontal cell, same for all mesh types). This is a convenience that holds for every atmospheric grid we currently target (ERA5, GEOS-FP, GEOS-IT, reduced Gaussian). If a future mesh requires non-columnar vertical connectivity, define a new concrete subtype of AbstractUnstructuredFaceFluxState with different storage — the abstract hierarchy supports this without breaking existing code.

source
AtmosTransport.State.MetState Type
julia
MetState{A <: AbstractArray, M}

Container for meteorological fields upstream of the transport core.

Fields

  • ps :: A — surface pressure [Pa]. Layout: (Nx, Ny) or (ncells,).

  • q :: A — specific humidity [kg/kg]. Layout matches grid 3D shape.

  • metvars :: M — additional met-specific fields (winds, omega, diffusivities, etc.) as a NamedTuple. Content depends on the met driver.

Transport operators never receive MetState directly. It is consumed by build_dry_fluxes! to produce AbstractFaceFluxState and CellState.air_dry_mass.

source
AtmosTransport.State.MoistBasis Type
julia
MoistBasis <: AbstractMassBasis

Tag for total-air / moist mass.

source
AtmosTransport.State.StructuredFaceFluxState Type
julia
StructuredFaceFluxState{Basis, AX, AY, AZ} <: AbstractStructuredFaceFluxState

Face-centered mass fluxes for structured grids, tagged with Basis to indicate whether the stored values are moist or dry.

Type parameters

  • Basis <: AbstractMassFluxBasis — MoistMassFluxBasis or DryMassFluxBasis

Fields

  • am :: AX — x-face (longitude) prepared substep mass transport [kg for the active transport substep]. Layout: (Nx+1, Ny, Nz) for LatLon, (Nc+1, Nc, Nz) per panel for CS.

  • bm :: AY — y-face (latitude) prepared substep mass transport [kg for the active transport substep]. Layout: (Nx, Ny+1, Nz) for LatLon, (Nc, Nc+1, Nz) per panel for CS.

  • cm :: AZ — z-face (vertical) prepared substep mass transport [kg for the active transport substep]. Layout: (Nx, Ny, Nz+1) for LatLon.

Convention

  • Positive am = eastward mass transport

  • Positive bm = northward mass transport

  • Positive cm = downward (increasing k / pressure) mass transport

Examples

julia
julia> using AtmosTransport.State: StructuredFaceFluxState, DryMassFluxBasis,
       MoistMassFluxBasis, flux_basis

julia> am = zeros(11, 8, 4); bm = zeros(10, 9, 4); cm = zeros(10, 8, 5);

julia> dry = StructuredFaceFluxState{DryMassFluxBasis}(am, bm, cm);

julia> flux_basis(dry)
DryBasis()

julia> moist = StructuredFaceFluxState{MoistMassFluxBasis}(am, bm, cm);

julia> flux_basis(moist)
MoistBasis()
source
AtmosTransport.State.TracerAccessor Type
julia
TracerAccessor{S}

Lazy, allocation-free wrapper that forwards property-style tracer access (state.tracers.CO2) to get_tracer(state, :CO2). Returned by getproperty(::CellState, :tracers). Reading a tracer that does not exist throws KeyError.

state.tracers[:CO2] is also supported and forwards to get_tracer(state, :CO2) for code that prefers index syntax.

source
AtmosTransport.State.allocate_face_fluxes Method
julia
allocate_face_fluxes(::FaceIndexedFluxTopology, nfaces, ncells, Nz;
                     FT=Float64, ArrayType=Array,
                     basis::Type{<:AbstractMassBasis}=DryMassFluxBasis)

Allocate zeroed face-indexed flux arrays for a connected-face mesh.

source
AtmosTransport.State.allocate_face_fluxes Method
julia
allocate_face_fluxes(::StructuredFluxTopology, Nx, Ny, Nz;
                     FT=Float64, ArrayType=Array,
                     basis::Type{<:AbstractMassFluxBasis}=DryMassFluxBasis)

Allocate zeroed face flux arrays for a structured mesh. The returned StructuredFaceFluxState is tagged with the specified basis.

source
AtmosTransport.State.allocate_face_fluxes Method
julia
allocate_face_fluxes(mesh::AbstractHorizontalMesh, Nz; kwargs...)

Allocate a flux container using the mesh's natural face-connected topology.

source
AtmosTransport.State.allocate_face_fluxes Method
julia
allocate_face_fluxes(mesh::AbstractStructuredMesh, Nz; kwargs...)

Allocate a flux container using the mesh's natural structured topology.

source
AtmosTransport.State.allocate_tracers Method
julia
allocate_tracers(names::NTuple{N, Symbol}, Nx, Ny, Nz;
                 FT=Float64, ArrayType=Array, fill_value=zero(FT))

Allocate a NamedTuple of 3D tracer mass arrays. Still useful for test fixtures that want to pre-build per-tracer 3D arrays for a CellState(m; tracers...) keyword-form constructor call.

source
AtmosTransport.State.eachtracer Method
julia
eachtracer(state::CellState)

Iterate name => tracer_slice pairs for every tracer in state, in storage order. The yielded shape matches the previous pairs(::NamedTuple) contract so callers that destructure for (name, rm) in eachtracer(state) continue to work.

source
AtmosTransport.State.flux_basis Method
julia
flux_basis(state) → AbstractMassFluxBasis

Return the mass flux basis tag for the given flux state.

source
AtmosTransport.State.get_tracer Method
julia
get_tracer(state::CellState, name::Symbol)
get_tracer(state::CellState, idx::Integer)

Return a view of the tracer mass slice. For a structured grid with state.tracers_raw :: Array{FT, 4}, this is selectdim(state.tracers_raw, 4, idx), a contiguous SubArray{FT, 3} (because Julia is column-major and the tracer axis is the slowest-varying). Mutations through the returned view are reflected in state.tracers_raw.

Throws KeyError(name) if name is not a tracer in state.

source
AtmosTransport.State.mixing_ratio Method
julia
mixing_ratio(state::CellState, name::Symbol)

Compute mixing ratio q = tracer_mass / air_dry_mass for the named tracer.

source
AtmosTransport.State.ntracers Method
julia
ntracers(state::CellState) -> Int

Number of tracers carried by state.

source
AtmosTransport.State.set_uniform_mixing_ratio! Method
julia
set_uniform_mixing_ratio!(state::CellState, name::Symbol, χ)

Set tracer name to uniform mixing ratio χ: tracer_mass = χ × air_dry_mass.

source
AtmosTransport.State.total_air_mass Method
julia
total_air_mass(state::CellState) -> scalar

Sum of air mass across all cells and levels.

source
AtmosTransport.State.total_mass Method
julia
total_mass(state::CellState, name::Symbol) -> scalar

Sum of tracer mass across all cells and levels.

source
AtmosTransport.State.tracer_index Method
julia
tracer_index(state::CellState, name::Symbol) -> Union{Int, Nothing}

Index of the tracer named name in state.tracer_names, or nothing if absent.

source
AtmosTransport.State.tracer_name Method
julia
tracer_name(state::CellState, idx::Integer) -> Symbol

Name of the tracer at index idx. Throws BoundsError if out of range.

source
AtmosTransport.State.tracer_names Method
julia
tracer_names(state::CellState) -> NTuple{Nt, Symbol}

Names of all tracers in state, in stored order.

source