construct(; kw...) -> bgc

Construct a size-structured NiPiZD ecosystem model.

The NiPiZD model contains phytoplankton and zooplankton roles. size_structure defines the PFTs within each role; the defaults are P and Z.

In addition to plankton, the NiPiZD definition includes idealized nutrient (N) and detritus (D) cycling. The returned biogeochemistry instance includes a photosynthetically active radiation (PAR) auxiliary field.

During construction, plankton size (diameter) is used to resolve trait-based parameter vectors and interaction matrices (e.g. palatability and assimilation efficiency). You may override interaction matrices explicitly with palatability_matrix and/or assimilation_matrix.

Each PFT size structure may be a NamedTuple range, for example (n=3, min_esd=1, max_esd=10, spacing=:log), or an explicit diameter vector such as [1.0, 3.2, 10.0]; explicit vectors are canonicalized by ascending diameter before SizeClass identities are assigned. At this high-level constructor boundary, (n=0,) means that the PFT realizes one implicit SizeClass, named by the PFT, without diameter metadata; n=1 still means one explicit SizeClass with a defined diameter. PFTs are supplied as size_structure=(phytoplankton=(...), zooplankton=(...)); PFT mapping order is canonicalized by identity rather than authored key order. Explicit SizeClasses use <pft>_<index> identities, such as P_1 or diat_1.

Keywords

• size_structure: phytoplankton and zooplankton PFTs, supplied as a NamedTuple with phytoplankton and zooplankton fields. Defaults to P and Z PFTs with two SizeClasses each.
• parameters=(;): parameter overrides (validated against the NiPiZD parameter set). Vector parameters may be supplied positionally, as partial NamedTuple overrides keyed by realized plankton SizeClass identity (for example P_1, diat_1, or microzoo_1), or as allometric definitions for diameter-indexed plankton vectors.
• palatability_matrix=nothing: optional palatability matrix override. Must be an explicit rectangular matrix with rows ordered by realized zooplankton SizeClasses and columns ordered by realized phytoplankton SizeClasses.
• assimilation_matrix=nothing: optional assimilation matrix override with the same consumer-by-prey SizeClass ordering as palatability_matrix.
• grid=BoxModelGrid(): grid used for architecture inference and default scalar-type selection
• scalar_type=nothing: explicit runtime scalar type. When omitted, construction uses eltype(grid) or Float64 if no grid is supplied
• arch=nothing: override the architecture (usually inferred from grid)
• sinking_tracers=nothing: sinking speed overrides, e.g. (D = 2/day, P_1 = 0.1/day, ...)
• open_bottom=true: whether sinking tracers leave the domain

Returns

An Oceananigans.Biogeochemistry.AbstractContinuousFormBiogeochemistry instance.

Example

using Agate.Models: NiPiZD

bgc = NiPiZD.construct()

Trait-style allometric parameter overrides may be supplied during construction:

using Oceananigans.Units: day
using Agate.Library.Allometry: AllometricParam, PowerLaw

bgc = NiPiZD.construct(;
    parameters=(;
        maximum_growth_rate=AllometricParam(
            PowerLaw(); prefactor=2 / day, exponent=-0.15
        ),
    ),
)

construct_plus_recipe(; kw...) -> bgc, recipe

Construct NiPiZD and return the model together with its versioned family recipe. The recipe records the registered family version, PFT size realization, authored parameter overrides, sinking configuration, and open-bottom state. Runtime grid, architecture, scalar precision, components, processes, and compiled equations are supplied when the recipe is realized.

construct_from_recipe(recipe; grid=BoxModelGrid(), arch=nothing, scalar_type=nothing) -> bgc

Replay a NiPiZD recipe in the supplied runtime environment.