API reference

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

Construct a 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, process parameter overrides, and family-level setting 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 model 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 recipe using the explicitly selected model provider and family.

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. composition binds implicitly represented Elements to nonnegative model parameters, measured per unit of the elemental reference state. These parameters are indexed by plankton entity (and therefore by size class when applicable).

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.

Implicit elemental ratios, keyed by Element.

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.

Saturating-exponential light limitation, $1 - exp(-I / K_I)$.

Monod saturation formulation, $x / (K + x)$.

Monod resource limitation multiplied by exponential inhibition.

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.

Q10() has one scalar q10 coefficient, which may be shared across different processes. Q10(:plankton) or Q10(:consumer) instead indexes q10 by the corresponding process participant. reference_temperature is scalar in both cases.

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.

Linear grazing with prey consumption proportional to prey and consumer biomass.

The rate parameter is consumer-indexed and has inverse-concentration inverse-time units. palatability scales individual consumer-resource links.

Heterotrophic consumption of substitutable substrates with shared consumer capacity.

maximum_rate is one per-consumer uptake capacity shared across all declared substrates. half_saturation and substrate_preference are consumer-resource properties, allowing consumers to differ in affinity and relative accessibility for the same substrate.

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.

Plankton growth with elemental resources and optional multiplicative factors.

additional_resources supplies implicitly represented Elements declared by participating Plankton.composition mappings. Each plankton consumes only its own implicit Elements; the reference Element is supplied by reference_resource. Explicit prognostic elemental states are updated by independent processes such as NutrientUptake. Products route gross uptake before biomass retention.

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.

By default temperature is read from an external driver named :temperature. Pass component instead to read a scalar model component such as an Oceananigans temperature tracer.

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. LinearGrazing instead applies an independent linear grazing rate to each consumer-resource link. 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, its destinations cover the union of their represented Elements.

Plankton mortality process with optional products.

When one mortality process routes multi-element products from multiple plankton, its destinations cover the union of their represented Elements.

Conservative allocation of one process flux among named destinations.

An element-to-pool mapping routes each represented Element from a plankton component. For N products, declare N - 1 fractions; the last receives the balance.

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 size traits, with optional prey protection.

Broadcast one consumer-indexed value across every resource for that consumer.

The single declared dependency must be a vector over realized plankton SizeClasses. The result is a consumer-by-resource matrix whose rows repeat the corresponding consumer value.

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.

A configurable scientific property of a model family.

ModelSetting stores a default value and validation domain for model-level properties that affect the realized model but are not parameters of an individual biological process, such as carbon-to-nitrogen or chlorophyll-to-nitrogen ratios.

Return configurable scientific properties defined by a model family.

Canonical construction inputs for an explicitly selected model family.

ModelRecipe records the family label and canonical construction configuration. The selected provider and Julia environment determine the implementation on replay. Named mapping order is canonicalized for recipe equality and content hashing.

Resolved deterministic scientific state produced by model construction.

ModelManifest records the fully materialized process parameters and model settings, 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 recipe with an explicit family 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).

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

model_settings(bgc) -> NamedTuple

Return resolved model-level settings. For an NPDPlankton adapter, return the settings used by the adapter, including explicitly supplied standalone-runtime ratios.

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

Encode model configuration with a deterministic content hash.

The hash identifies the recorded family label and construction inputs. Reproducible execution uses the selected model provider and its resolved Julia environment.

Decode recipe data and verify its configuration content hash.

Select a model provider explicitly when constructing from the decoded recipe.

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.

LOBSTER3-like defaults expressed through Agate size-trait machinery.

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 Onyx.

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 Onyx.

OceanBioME NPD plankton component backed by one compiled Agate runtime.

NPDPlankton is an integration boundary, not a biological model. The compiled Agate runtime owns the ecological equations; this wrapper maps their signed tracer tendencies onto OceanBioME's existing NPD plankton hooks. Its settings field holds the resolved Agate model settings used by the coupling.

Construct an Agate model family directly as an OceanBioME NPD plankton component.

Replay an Agate recipe as an OceanBioME NPD component using an explicit family.

Construct an NPD plankton component and capture the canonical Agate family recipe.

Return family-specific NPDPlankton keyword overrides for a realized runtime.

Ownership, phytoplankton identity, external dependencies, standard exchange channels, and resolved model settings are inferred from Agate metadata. External families only need to declare choices that cannot be inferred safely, such as nutrient uptake tracers, consumed detritus, or physical-driver dependencies. Configured dependencies are appended to the inferred tracer dependencies.

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.