API reference

construct(family::AbstractModelFamily;
          plankton_pfts, parameter_overrides=(;),
          sinking_tracers=nothing, open_bottom=true, grid=nothing,
          arch=nothing, scalar_type=nothing) -> bgc

Construct a registered model family from its resolved family realization. This is the supported construction seam for external family packages after their own user-facing constructor syntax has been translated into the nested plankton_pfts mapping and parameter overrides. Runtime grid, architecture, and scalar precision remain execution choices.

construct(definition::ModelDefinition; kwargs...) -> bgc

Construct a model directly from authored components, named processes, and parameter definitions. Plankton size structures are realized from the definition, process participation determines interaction axes and required auxiliary drivers, and runtime tracer equations are compiled during setup.

parameter_overrides supplies concrete parameter values over the defaults declared in definition.parameters, including explicit axis-sized interaction matrices. Runtime grid, architecture, and scalar precision remain execution choices rather than part of the scientific definition.

Replay a versioned family recipe in the supplied execution environment.

Author-facing scientific model definition.

Plankton state described by intrinsic component properties.

Ecological function is supplied by process participation. states names every prognostic state carried by the plankton, while reference_state identifies the state used as its biological reference basis. Elemental bookkeeping is inferred centrally by state_element; non-elemental states such as :chlorophyll return nothing.

Scalar material-pool state described by its conserved Element.

Return the conserved-material element represented by a material Pool.

Return all prognostic state identities for a plankton.

Return the plankton state used as its biological reference basis.

Return all prognostic plankton states other than the reference state.

Return the conserved Element represented by state, or nothing for a non-elemental state.

Element identity is the additive elemental inventory represented by the state's numerical value, not the chemical composition of the represented material. Canonical elemental state names map to themselves; other states remain non-elemental until an explicit mapping API is introduced.

Return the intrinsic size-structure specification for component.

Return realized entity identities for one logical component.

Return the state-to-tracer mapping for a plankton, or nothing for a pool.

Return flattened concrete tracer identities realized by one logical component.

Return SizeClass diameter metadata for one component.

Every PFT contributes at least one SizeClass. Implicit singleton SizeClasses have no diameter metadata; returns nothing when all classes are implicit.

Return concrete tracers for one plankton state.

Return one concrete tracer for a plankton state and local realized-entity index.

Abstract supertype for concrete scientific formulations.

Smith light-limitation formulation.

Geider light-response formulation.

This factor regulates Growth rate using chlorophyll-to-carbon information; it does not itself synthesize a prognostic non-elemental state such as :chlorophyll.

Monod single-resource limitation formulation.

Normalized Droop cellular-quota growth-limitation formulation.

Monod nutrient-uptake formulation regulated by cellular quota capacity.

Liebig minimum response-combination formulation.

Differentiable Frank t-norm nutrient-combination formulation.

Q10 temperature-response formulation.

Living-prey grazing formulation with pairwise consumer-resource capacity.

maximum_rate is a per-consumer rate applied independently to each declared prey edge, so each edge receives the full per-consumer rate.

Heterotrophic resource-consumption formulation with pairwise consumer-resource capacity.

maximum_rate is a per-consumer rate applied independently to each declared resource edge, so each edge receives the full per-consumer rate.

Linear plankton-mortality formulation.

Quadratic plankton-mortality formulation.

Linear source-to-destination remineralization formulation.

Abstract supertype for scientific process objects.

Abstract supertype for named multiplicative process-rate factors.

Abstract supertype for process stoichiometry mappings.

Plankton growth process with explicit material inputs and optional multiplicative factors.

bindings.maximum_rate names the model parameter that sets the growth-rate scale. reference_resource supplies the Element represented by the plankton reference_state. additional_resources maps additional Elements to external Pools consumed according to FixedStoichiometry. Factors modify growth rate only; independently prognostic elemental states are supplied through NutrientUptake.

Light-dependent multiplicative Growth factor using the Growth rate scale.

Single-resource multiplicative nutrient-rate factor.

The factor reads an environmental Pool but does not define process material transfer.

Cellular-quota response used by quota-limited growth.

variable_state identifies the internal inventory whose quota varies relative to the Growth plankton's intrinsic reference state.

Multi-response nutrient factor with formulation-owned response composition.

External NutrientResponse subfactors read environmental resource Pools, while internal QuotaResponse subfactors read prognostic cellular states. Each responses key is the Element identity represented by that response (for example, nitrogen=...). Both modify process rate only; material transfer is owned by the process itself, so external and internal responses may be combined within one NutrientLimitation factor.

Temperature-dependent multiplicative process-rate factor.

Independent external nutrient uptake into one plankton inventory state.

The plankton reference state scales uptake capacity but is not itself transferred. Parameter bindings are explicit because quota bounds are commonly shared with QuotaResponse.

Consumer-resource process with optional factors and unassimilated products.

The formulation maximum_rate is pairwise capacity: one consumer's rate is applied independently to each declared consumer-resource edge. When one living-prey consumption process routes multi-element unassimilated products from multiple resources, those resources currently must expose the same prognostic Element set.

Plankton mortality process with optional products.

When one mortality process routes multi-element products from multiple plankton, those plankton currently must expose the same prognostic Element set.

Conservative allocation of one process product flux among named destinations.

Each product destination may be either one component Symbol or a named element-to-component mapping. A multi-element mapping without FixedStoichiometry routes prognostic elemental states directly. FixedStoichiometry derives multi-element products from a one-element source; every product then declares the same elements and includes the stoichiometric reference element.

For N products, specify either N - 1 named fractions or all N fractions. When one fraction is omitted, that product receives the exact conservative remainder 1 - sum(supplied fractions). When all fractions are supplied, every authored value is used directly and setup requires their sum to equal one within floating-point tolerance. A single product requires no fractions.

Fixed conversion from one reference element to process target elements.

Each bound ratio is the amount of its target element per unit reference element.

Source-to-destination remineralization process.

Return the scientific formulation carried by a process or factor.

Return the named multiplicative factors attached to a process.

Return canonical participant roles for an authored scientific process.

Return setup-only authored model-parameter bindings for one slot-owning node.

A runtime model parameter whose storage is determined by scientific process slots.

The stable parameter name is the key in the enclosing parameters NamedTuple. Scalar, vector, and matrix storage are inferred from the slots that bind the parameter and their realized process applicability; process slots therefore determine the storage axes.

A construction-only parameter used to derive one or more runtime parameters.

ConstructionParameter values are materialized during setup but are not stored in the runtime biogeochemistry. Shaped construction parameters use axes=:plankton; omitting axes defines a scalar construction parameter.

Abstract supertype for construction-time default providers.

Default providers are evaluated on the host during model construction. They must produce concrete numeric values (scalars, vectors, matrices) that can later be moved to a GPU architecture via Adapt.

Derive a parameter default from other resolved parameters during construction.

deriver is a setup-time strategy object. Custom derivers implement derive_default; built-in context-sensitive providers may also use realized parameter metadata. deps names ordinary runtime parameters and/or construction-only ConstructionParameter values available to the derivation. Derived defaults are evaluated once after direct defaults and explicit overrides are materialized.

Compute a value for a DerivedDefault provider.

Concrete derivers receive the owning model source, construction context, and a NamedTuple containing exactly the dependencies declared by deps. The owner is a registered model family for named models and the authored ModelDefinition for direct construction. Derivation runs on the host during model construction.

Indicates that a parameter has no default value.

The parameter must be supplied by an override before construction can complete.

Default provider for a diameter-indexed vector parameter.

The provider materializes value over the parameter's realized storage labels. For slot-bound Parameter values those labels come from process applicability; for a ConstructionParameter they come from its explicit construction axis.

Derive consumer-by-prey palatability from allometric trait vectors.

Derive consumer-by-prey assimilation from consumer-specific efficiency traits.

Validated process instance in canonical model state.

semantic_facts contains setup-only scientific decisions that compilation may trust. binding_refs contains dense references into the canonical model's ordered parameter-binding tuple, arranged alongside the process/factor/product structure so lowering never reconstructs scientific paths.

Return the stable identity of a canonical process.

Formulation-local declaration of one semantic parameter slot.

Dimensionality is structural: zero, one, or two declared axes imply scalar, vector, or matrix values respectively. qualify identifies repeated semantic instances without changing storage dimensionality. For a scalar slot, a qualifier that is also a process participant role provides ecological applicability without becoming a storage axis.

Return semantic parameter slots declared by a slot-owning scientific node.

Attach setup-validated semantic facts to a process before compilation.

Custom process implementations may extend this hook when lowering needs setup-resolved facts beyond the authored process object.

Setup-time context shared by process lowering and static tendency compilation.

Lower one canonical process to generic fluxes.

Custom process implementations may extend this hook through CanonicalProcess{Process} for a concrete process type.

Derive biomass-gain and resource-loss fluxes for factorized growth.

Return compiled operands for the unqualified process-owned parameter slots of a custom process.

This is the narrow parameterized-process extension seam: custom lowering receives semantic slot names mapped directly to static operands without depending on canonical binding references.

Versioned registered-family recipe captured before runtime realization.

ModelRecipe stores only the registered family identity, its exact scientific definition_version, and canonical construction inputs. Named mapping insertion order is not part of recipe identity. Components, processes, parameter definitions, runtime precision, host fields, and compiled equations are supplied by the loaded family implementation on replay.

Resolved deterministic scientific state produced by model construction.

ModelManifest records the fully materialized parameters, realized PFT entities and tracer ordering, interaction sources, sinking configuration, and scalar type. It is an in-memory record of the constructed model state; durable replay is defined by the corresponding recipe representation.

Replay a versioned family recipe and return its resolved manifest.

Capture canonical family construction inputs for durable replay.

Return the durable model-recipe schema identifier supported by this Agate version.

Normalize named-family (n=0,) shorthand to one implicit SizeClass (nothing).

Return the registered model family used to replay recipe after identity/version checks.

Resolve the scalar type from an explicit choice, the grid, or Float64.

Return the stable recipe-family identifier for a model family.

Return the registered model-family token identified by family.

Encode a versioned family recipe with a scientific content hash and package provenance.

Decode a recipe document, verifying its hash, family registration, and definition version.

Write a recipe document to path as pretty-printed JSON.

Read and decode a recipe document from path.

Identity token for a named biogeochemical model family.

Scientific definition version for a named model family.

Bump this version whenever family science, defaults, derivation algorithms, or canonical definition structure changes in a way that should invalidate durable recipe replay.

Return the keyed parameter definitions owned by a model family or direct source.

Canonical logical components for a named model family.

Returns a named collection whose keys are stable model component identities and whose values describe intrinsic component structure.

Canonical logical components for NiPiZD.

Canonical named scientific processes for a named model family.

The keys are stable process-instance identities. Process declarations describe scientific topology and are canonicalized before runtime realization.

Canonical named scientific processes for NiPiZD.

model_summary(bgc) -> NamedTuple

Return a compact summary of a constructed biogeochemistry instance.

The returned NamedTuple contains:

• tracers::Vector{Symbol}
• auxiliary_fields::Vector{Symbol}
• parameters::Vector{Symbol}
• has_sinking_velocities::Bool

describe([io], bgc; verbose=false)

Print a human-readable summary of bgc.

Set verbose=true to print full tracer / parameter lists.

tracer_names(bgc) -> Vector{Symbol}

Return the ordered tracer symbols required by bgc.

This helper is intended for interactive inspection, so it materializes the underlying tracer-name tuple as a Vector{Symbol}.

The ordering matches Oceananigans / OceanBioME state-vector conventions.

auxiliary_field_names(bgc) -> Vector{Symbol}

Return the ordered auxiliary field symbols required by bgc.

Auxiliary fields are non-tracer state fields (for example, light or temperature) that appear in tracer tendencies.

parameter_names(bgc) -> Vector{Symbol}

Return the parameter keys available on bgc.parameters.

This list describes the resolved parameter fields available on the constructed biogeochemistry instance.

pfts(bgc) -> NamedTuple

Return a NamedTuple mapping plankton PFT symbols to realized SizeClass symbols. Every PFT has at least one SizeClass: without explicit size structure it has one implicit class named by the PFT; explicit structures use <pft>_<index>. Each class appears once independent of prognostic-state multiplicity. PFT order follows the realized model layout.

plankton_tracers(bgc) -> Vector{Symbol}

Return all plankton tracer symbols as a flat vector in runtime PFT/SizeClass order.

plankton_diameters(bgc) -> Vector

Return diameter metadata for realized plankton SizeClasses. The ordering follows the flattened values of pfts(bgc), with one entry per SizeClass even when it carries multiple prognostic state tracers. Explicit SizeClasses return their equivalent spherical diameter; implicit singleton SizeClasses return nothing. Models without plankton return an empty vector.

nonplankton_tracers(bgc) -> Vector{Symbol}

Return the tracer symbols that are not part of a plankton PFT.

tracer_groups(bgc) -> NamedTuple

Return a structural grouping summary of the constructed tracer layout.

interaction_matrix(bgc, parameter::Symbol) -> NamedTuple

Return a consumer-by-resource parameter matrix with realized entity labels.

parameter is the canonical model parameter identity, for example :palatability_matrix or :assimilation_matrix. Each matrix uses the axes and labels of that parameter rather than one model-global interaction topology. The returned NamedTuple contains parameter, matrix, rows, columns, row_axis, and column_axis.