construct(; kw...) -> bgc

Construct a size-structured Onyx ecosystem model.

The Onyx 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 Onyx 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). Interaction matrices may be overridden explicitly through parameters.

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 Onyx 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. Interaction matrices such as palatability_matrix and assimilation_matrix are supplied here as explicit consumer-by-prey matrices when overriding their derived defaults.
• 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 Onyx

bgc = Onyx.construct()

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

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

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

construct(recipe::Construction.ModelRecipe; grid=BoxModelGrid(), arch=nothing, scalar_type=nothing) -> bgc

Replay a Onyx recipe in the supplied runtime environment.

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

Construct Onyx and return the model together with its construction recipe. The recipe records PFT size realization, authored parameter overrides, sinking configuration, and open-bottom state. The selected family and Julia environment supply the model implementation on replay.