Domains, Variables, Fields, and Data arrays.

Model

A biogeochemical model consisting of Domains, created from a YAML configuration file using create_model_from_config.

Domain

A model region containing Variables and Reactions that act on them.

Domain spatial size is defined by grid, which may be nothing to define a scalar Domain, or an AbstractMesh to define a spatially-resolved Domain with multiple cells.

Named data_dims may be set by set_data_dimension! to allow Variables with additional non-spatial dimensions, eg to represent quantities on a wavelength grid.

AbstractMesh

Defines additional geometric and topological information for PB.Domain

Concrete subtypes should implement methods:

PB.internal_size, optionally PB.cartesian_size

PB.Grids.set_subdomain!, PB.Grids.get_subdomain

PB.Grids.create_default_cellrange, PB.Grids.get_region

internal_size(::Type{<:AbstractSpace}, mesh::AbstractMesh; [subdomain=""] [space=:cell]) -> NTuple{ndims, Int}

Array size to use for model Variables.

All AbstractMesh concrete subtypes (UnstructuredVectorGrid, CartesianLinearGrid, ...) should implement this method.

Optional Keyword Arguments

• subdomain::String="": a named subdomain

cartesian_size(mesh::AbstractMesh) -> NTuple{ndims, Int}

Optional (only regular Cartesian grids should implement this method): Array size of Cartesian Domain.

NB: this may be different from internal_size if the mesh implements a mapping eg to a Vector for internal model Variables.

set_subdomain!(grid::PB.AbstractMesh, subdomainname::AbstractString, subdom::PB.AbstractSubdomain, allowcreate::Bool=false)

Set Subdomain

get_subdomain(grid::PB.AbstractMesh, subdomainname::AbstractString) -> PB.AbstractSubdomain

Get Subdomain

UnstructuredVectorGrid <: PB.AbstractMesh

Minimal Grid for a Vector Domain, defines only some named cells for plotting

UnstructuredColumnGrid <: PB.AbstractMesh

Minimal Grid for a Vector Domain composed of columns (not necessarily forming a 2-D array).

Fields

• ncells::Int total number of cells in this Domain
• Icolumns::Vector{Vector{Int}}: Icolumns[n] should be the indices of column n, in order from surface to floor, where n is also the index of

any associated boundary surface.

• z_coords::Vector{FixedCoord}: z coordinates of cell mid point, lower surface, upper surface
• columnnames::Vector{Symbol}: optional column names

CartesianLinearGrid <: PB.AbstractMesh

nD grid with netcdf CF1.0 coordinates, using Vectors for PALEO internal representation of Variables, with a mapping linear indices <–> some subset of grid indices.

The linear indices mapping should be set with set_linear_index. Conversion of Field values between the PALEO internal representation (a Vector with a linear index) and a Cartesian Array with multiple dimensions (for import and export of model output) is then implemented by cartesian_to_internal and internal_to_cartesian.

Fields

• ncells::Int64: number of cells in Domain = length(linear_index) (may be subset of total points in prod(dims))
• dimnames::Vector{String}: names of dimensions (ordered list)
• dims::Vector{Int}: sizes of dimensions (ordered list)
• coords::Vector{Vector{Float64}}: attached cell-centre coordinates for each dimension (ordered list)
• coords_edges::Vector{Vector{Float64}}: attached cell-edge coordinates for each dimension (ordered list)

CartesianArrayGrid <: PB.AbstractMesh

nD grid with netcdf CF1.0 coordinates, using n-dimensional Arrays for PALEO internal representation of Variables

Fields

• ncells::Int64: number of cells in Domain = length(linear_index) (may be subset of total points in prod(dims))
• dimnames::Vector{String}: names of dimensions (ordered list)
• dims::Vector{Int}: sizes of dimensions (ordered list)
• coords::Vector{Vector{Float64}}: attached cell-centre coordinates for each dimension (ordered list)
• coords_edges::Vector{Vector{Float64}}: attached cell-edge coordinates for each dimension (ordered list)

AbstractSubdomain

Defines the relationship between two PB.Domains by mapping indices in one Domain to related indices in the other, eg interior cells adjacent to a boundary.

Concrete subtypes should implement:

subdomain_view

subdomain_indices

BoundarySubdomain <: PB.AbstractSubdomain

A 2D subdomain corresponding to the 2D boundary Domain associated with a 3D interior Domain:

• indices[ibnd] is the index of the 3D interior cell corresponding to a 2D boundary cell ibnd.

InteriorSubdomain <: PB.AbstractSubdomain

A 3D subdomain corresponding to the 3D interior Domain associated with a 2D boundary Domain: indices[iint] is either:

• missing if iint is the index of an interior cell in the 3D Domain, or
• the index of the 2D boundary Domain cell corresponding to the boundary-adjacent 3D interior Domain cell iint

subdomain_view(values, subdomain::BoundarySubdomain) -> view

Create a view on values in an interior Domain to access cells corresponding to indices in a boundary Domain.

subdomain_view(values, subdomain::InteriorSubdomain) -> var

Return unmodified values from a boundary Domain, indices to access from interior supplied by subdomain_indices

subdomain_view(values, subdomain::Nothing) -> values

Fallback when subdomain == nothing

subdomain_indices(subdomain::BoundarySubdomain) -> nothing

No additional indices required to access Variables in an interior Domain from a boundary Domain (view created by subdomain_view is sufficient).

subdomain_indices(subdomain::InteriorSubdomain) -> indices

Return indices to access Variables in a boundary Domain from interior Domain (will have missing entries where interior cells do not correspond to boundary)

subdomain_indices(subdomain::Nothing) -> nothing

fallback when subdomain == nothing

get_region(grid::Union{PB.AbstractMesh, Nothing}, values; selectargs...) -> values_subset, (dim_subset::NamedDimension, ...)

Return the subset of values given by selectargs (Grid-specific keywords eg cell=, column=, ...) and corresponding dimensions (with attached coordinates).

get_region(grid::Nothing, values) -> values[]

Fallback for Domain with no grid, assumed 1 cell

get_region(grid::UnstructuredVectorGrid, values; cell) -> 
    values_subset, (dim_subset::NamedDimension, ...)

Keywords for region selection:

• cell::Union{Int, Symbol}: an Int, or a Symbol to look up in cellnames

get_region(grid::UnstructuredColumnGrid, values; column, [cell=nothing]) -> 
    values_subset, (dim_subset::NamedDimension, ...)

Keywords for region selection:

• column::Union{Int, Symbol}: (may be an Int, or a Symbol to look up in columnames)
• cell::Int: optional cell index within column, highest cell is cell 1

get_region(grid::Union{CartesianLinearGrid{2}, CartesianArrayGrid{2}} , internalvalues; [i=i_idx], [j=j_idx]) ->
    arrayvalues_subset, (dim_subset::NamedDimension, ...)

Keywords for region selection:

• i::Int: optional, slice along first dimension
• j::Int: optional, slice along second dimension

internalvalues are transformed if needed from internal Field representation as a Vector length ncells, to an Array (2D if neither i, j arguments present, 1D if i or j present, 0D ie one cell if both present)

get_region(grid::Union{CartesianLinearGrid{3}, CartesianArrayGrid{3}}, internalvalues; [i=i_idx], [j=j_idx]) ->
    arrayvalues_subset, (dim_subset::NamedDimension, ...)

Keywords for region selection:

• i::Int: optional, slice along first dimension
• j::Int: optional, slice along second dimension
• k::Int: optional, slice along third dimension

internalvalues are transformed if needed from internal Field representation as a Vector length ncells, to an Array (3D if neither i, j, k arguments present, 2D if one of i, j or k present, 1D if two present, 0D ie one cell if i, j, k all specified).

NamedDimension

A named dimension, with optional attached fixed coordinates coords

PALEO convention is that where possible coords contains three elements, for cell midpoints, lower edges, upper edges, in that order.

FixedCoord

A fixed (state independent) coordinate

VariableBase

A Model biogeochemical Variable. Reactions access Variables using derived Types VariableReaction which are links to VariableDomains.

@enum VariableType

Enumeration of VariableBase subtypes. Allowed values:

• VariableReaction: VT_ReactProperty, VT_ReactDependency, VT_ReactContributor, VT_ReactTarget
• VariableDomain : VT_DomPropDep, VT_DomContribTarget

VariableDomain <: VariableBase

Abstract base Type for a (Domain) model variable.

Defines a named Variable and corresponding data Fields that are linked to by VariableReactions.

See VariableDomPropDep, VariableDomContribTarget

VariableDomPropDep <: VariableDomain

Model (Domain) VariableDomain linking a single VariableReaction{VT_ReactProperty} to multiple VariableReaction{VT_ReactDependency}.

VariableDomContribTarget <: VariableDomain

Model (Domain) VariableDomain linking a single VariableReaction{VT_ReactTarget} to multiple VariableReaction{VT_ReactContributor} and VariableReaction{VT_ReactDependency}.

Attribute{T}

Definition for Variable attribute name. Defines a data type T, a default_value, required (true if always present ie added with default_value when Variable is created), units, and an optional description.

Note that Variable attributes are stored as a per-Variable Dict(name => value), these definitions are only used to provide defaults, check types, and provide descriptive metadata.

ParseFromString should usually be Nothing: a value of Type T is then required when calling set_attribute!. If ParseFromString is true, then set_attribute! will accept an AbstractString and call Base.parse(T, strvalue) to convert to T. This allows eg an enum-valued Attribute to be defined by Attribute{EnumType, true} and implementing parse(EnumType, rawvalue::AbstractString)

StandardAttributes

List of standard Variable attributes.

Some of these follow netCDF COARDS/CF conventions:

COARDS:https://ferret.pmel.noaa.gov/Ferret/documentation/coards-netcdf-conventions

• units (where possible should follow the Unidata udunits package https://docs.unidata.ucar.edu/udunits/current/)
• long_name

CF conventions: https://cfconventions.org/cf-conventions/cf-conventions.html#_description_of_the_data

• standard_name http://cfconventions.org/Data/cf-standard-names/current/src/cf-standard-name-table.xml

get_attribute(var::VariableBase, name::Symbol, missing_value=missing) -> value

Get Variable attribute.

@enum VariableFunction

Allowed values of :vfunction Variable Attribute, defining the Variable function to the host ODE or DAE solver.

Explicit ODE problems with dS/dt = F(S) consist of pairs of S::VFStateExplicit, F::VFDeriv Variables.

An implicit ODE problem with dU/dt = F(U) where Total variables U are functions U(S) of State variables S will consist of pairs of U::VFTotal and F::VFDeriv Variables, and also the same number of S::VF_StateTotal (in no particular order).

Algebraic constraints C(S) = 0 include variables C::VFConstraint and the same number of S::VFState, with no corresponding VF_Deriv.

Not all solvers support all combinations.

@enum VariablePhase

Allowed values of :vphase Variable Attribute, defining the component phase this Variable belongs to for multiphase cells.

Field{D <: AbstractData, S <: AbstractSpace, V, N, M}

A Field of values::V of data type D defined on function space S over mesh::M and (optionally) with N data_dims::NTuple{N, NamedDimensions}.

get_field(obj, ...) -> Field

Get Field from PALEO object obj

create a new Field, containing supplied existing_values data arrays

AbstractSpace

Defines a function space within a Domain, on a mesh defined by a Grid

ScalarSpace <: AbstractSpace

A Domain position-independent quantity

CellSpace <: AbstractSpace

A per-cell quantity. Use as Variable attribute :space to create a Variable with data array dimensions from Grid cells.

ColumnSpace <: AbstractSpace

A per-column quantity. Use as Variable attribute :space to create a Variable with data array dimensions from Grid columns.

AbstractData

Defines a Data type that can be composed with an AbstractSpace to form a Field

Concrete subtypes should implement:

allocate_values, check_values, zero_values!, dof_values, get_values_output

If the subtype needs to provide values for a numerical solver (eg as a state variable), it also needs to implement:

init_values!, copyfieldto!, copytofield!, add_field!, add_field_vec!

If the subtype has a representation as components, it should implement: num_components, get_components

UndefinedData <: AbstractData

Undefined data type (no methods implemented). Used to indicate that a Variable can link to any data type.

ScalarData <: AbstractData

A Field scalar (eg a biogeochemical concentration)

ArrayScalarData <: AbstractData

An Array of Field scalars (eg a intensity on a wavelength grid).

NB: only implements minimal methods sufficient to allow use as a model internal variable, not as a state variable.

allocate_values(
    field_data::Type{<:AbstractData}, data_dims::Tuple{Vararg{NamedDimension}}, data_type, space::Type{<:AbstractSpace}, spatial_size::Tuple;
    thread_safe::Bool, allocatenans::Bool,
) -> values

allocate Field.values (eg an Array) for field_data with dimensions defined by spatial_size and data_dims

check_values(
    existing_values, 
    field_data::Type{<:AbstractData},
    data_dims::Tuple{Vararg{NamedDimension}}, 
    data_type, 
    space::Type{<:AbstractSpace}, 
    spatial_size::Tuple{Integer, Vararg{Integer}}
)

Check existing_values is of suitable type, size etc for use as Field.values, throw exception if not.

zero_values!(values, field_data::Type{<:AbstractData}, data_dims::Tuple{Vararg{NamedDimension}}, space::Type{<:AbstractSpace}, cellrange)

Set values over spatial region cellrange to zero at start of main loop

dof_values(
    field_data::Type{<:AbstractData}, 
    data_dims::Tuple{Vararg{NamedDimension}}, 
    space::Type{<:AbstractSpace}, 
    mesh, 
    cellrange
) -> dof::Int

Return degrees-of-freedom for field_data over spatial region cellrange.

Optional: sanitize values for storing as model output. Default implementation is usually OK - only implement eg for Atomic types that should be converted to standard types for storage

sanitized version of values, suitable for storing as output

init_values!(
    values, field_data::Type{<:AbstractData}, data_dims::Tuple{Vararg{NamedDimension}}, space::Type{<:AbstractSpace},
    init_value::Symbol, attribv::VariableBase, convertfn, convertvalues, cellrange, info::NTuple{3, String}
)

Initialize values at model start to init_value over region cellrange using information from Variable attribv attributes, scaled by convertfn and convertvalues.

Optional: only required if this field_data type is used for a model (state) Variable that requires initialisation.

Arguments:

• values: data to be zeroed
• init_value::Symbol: one of :initialvalue, :normvalue, requesting type of initial value required
• attribv::VariableBase: Variable with attributes to use for initialisation
• convertfn::Function: apply multiplier convertfn(convertvalues, i) to initialisation value for cell i. Typically this is used to convert units eg concentration to mol.
• convertvalues: parameters (if any) required by convertfn, eg a volume measure.
• cellrange: range of cells to initialise
• info::::NTuple{3, String}: Tuple (varinfo, convertinfo, trsfrinfo) of identifier strings to use for log messages

copyfieldto!(
    dest,
    doff, 
    values, 
    field_data::Type{<:AbstractData}, 
    data_dims::Tuple{Vararg{NamedDimension}}, 
    space::Type{<:AbstractSpace}, 
    cellrange
) -> num_copied::Int

Copy Field.values values from spatial region defined by cellrange, to dest Array starting at index doff.

Number of values over whole Domain should equal degrees-of-freedom returned by dof_values

Required if this field_data type needs to provide values for a numerical solver.

copytofield!(
    values,
    field_data::Type{<:AbstractData},
    data_dims::Tuple{Vararg{NamedDimension}},
    space::Type{<:AbstractSpace},
    cellrange, 
    src, 
    soff
) -> num_copied::Int

Copy from src Array starting at index soff to Field.values values for spatial region defined by cellrange.

Number of values over whole Domain should equal degrees-of-freedom returned by dof_values

Required if this field_data type needs to provide values for a numerical solver.

add_field!(obj, f::Field ...)

Add Field or Field to PALEO object obj

add_field_vec!(
    dest, 
    field_data::Type{<:AbstractData}, 
    data_dims::Tuple{Vararg{NamedDimension}}, 
    space::Type{<:AbstractSpace}, 
    a, 
    cellrange,
    src, 
    soff
) -> num_added::Int

Implement dest += a*src where dest is a Field.values, src is an Array, a is a number, over region defined by cellrange, starting at index soff in src.

Returns number of elements of src used.

See copytofield!, copyfieldto! for the relationship between Array src and Field values dest.

num_components(field_data::Type{<:AbstractData}) -> Int

get number of components (optional - implement if field_data has a representation as components)

get_components(values, field_data::Type{<:AbstractData}) -> Vector

Convert Field values to a Vector of components (optional - implement if field_data has a representation as components)

AbstractIsotopeScalar <: AbstractData

An IsotopeScalar represents a quantity or flux with isotopic composition. Can be added, subtracted, multiplied by a scalar, and decomposed into components with the same (bulk) transport properties.

Implementation

Each IsotopeScalar should be added to IsotopeTypes, and implement:

• get_total(is::IsotopeScalar) -> total
• arithmetic operations +/- (ie IsotopeScalars can be added and subtracted) and *number, /number (IsotopeScalars can be scaled by a real number).
• methods of the AbstractData interface

and optional isotope-specific functions, eg for a single isotope:

• isotope_totaldelta(::Type{<: IsotopeScalar}, total, delta) -> IsotopeScalar()
• get_delta(is::IsotopeScalar) -> delta

IsotopeLinear <: AbstractIsotopeScalar

Linearized representation of isotopic composition, where moldelta = total * delta.

isotope_totaldelta(::Type{IsotopeLinear}, total, delta) -> IsotopeLinear

Create an IsotopeLinear from total and delta

Examples:

julia> a = PB.isotope_totaldelta(PB.IsotopeLinear, 10.0, -2.0)
(v=10.0, v_moldelta=-20.0, ‰=-2.0)

julia> b = a*2
(v=20.0, v_moldelta=-40.0, ‰=-2.0)

julia> c = a + b
(v=30.0, v_moldelta=-60.0, ‰=-2.0)

julia> PB.get_total(c)
30.0

julia> PB.get_delta(c)
-2.0

generic get_total for non-isotope variable

get_total(is::IsotopeLinear)

Get isotope total

get_delta(is::IsotopeLinear)

Get isotope delta (per mil)