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_pfts optionally replaces each logical plankton component's intrinsic size structure with the same named PFT realization vocabulary used by registered families. 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 declares each prognostic state together with the conserved Element it represents, using nothing for non-elemental states. reference_state identifies the state used as the biological reference basis.

For example, states=(biomass=:carbon, chlorophyll=nothing) declares a carbon inventory named :biomass plus a non-elemental chlorophyll state. Element identity is therefore independent of state spelling and is queried centrally through state_element. Each conserved Element may currently be represented by at most one state.

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. State identity and Element identity are independent: any declared state name may map explicitly to an Element Symbol.

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 with one consumer-level ingestion capacity shared across prey.

switching_exponent=1 allocates grazing proportionally to palatable prey biomass, while larger positive integer exponents increasingly favor abundant palatable prey. palatability is a nonnegative interaction weight, not a probability.

Heterotrophic consumption of substitutable substrates with shared consumer capacity.

maximum_rate is one per-consumer uptake capacity shared across all declared substrates. substrate_preference controls the relative accessibility of each consumer-resource pair.

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.

For PreferentialGrazing, maximum_rate is one consumer-level ingestion capacity shared across all declared prey. For HeterotrophicConsumption, maximum_rate is likewise one consumer-level uptake capacity shared across substitutable substrates. 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 N - 1 named fractions. The omitted product receives the exact conservative remainder 1 - sum(supplied fractions). This removes one redundant routing degree of freedom while preserving exact closure by construction. 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. domain owns the formulation's numeric validity contract. 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.

External driver read required by one scientific factor.

Scalar model-component read required by one scientific factor.

Setup-only read of one prognostic state from the factor's current logical plankton.

reference.plankton must match the logical plankton at the realized :plankton axis position.

Return the ordered semantic inputs read by a factor before its parameter slots.

Return named child factors composed by a factor.

Return whether factor is scientifically applicable to process.

Evaluate a factor from its authoritative semantic operand order.

Compiled factor lowering assembles operands to this contract; direct/compiled parity tests cover every built-in factor formulation.

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. ==, isequal, hash, and content hashing share that scientific identity; named mapping insertion order is ignored. 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. Equality and hashing use this resolved scientific content; 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.

Return the scientific domain constraints declared for one realized parameter.

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. entities_by_pft contains realized SizeClass identities; plankton contains physical plankton tracers.

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, edges, row_axis, and column_axis. edges contains only modeled interactions; the dense matrix may include additional storage cells.