Model Configuration

The model configuration is specified within the PlanktonModel data structure. As documented below, the various parameters of a PlanktonModel can all be specified via keyword arguments. Options and features are documented in more detail afterwards and in the Examples section.

PlanktonIndividuals.Model.PlanktonModel — Type
PlanktonModel(arch::Architecture, grid::AbstractGrid;
              FT = Float32,
              mode = QuotaMode(),
              N_species = 1,
              N_individual = [1024],
              max_individuals = 1024*8,
              bgc_params = nothing, 
              phyt_params = nothing,
              nut_initial = default_nut_init(),
              t = 0.0,
              )

Generate a PlanktonModel data structure.

Keyword Arguments (Required)

  • arch : CPU() or GPU(). Computer architecture being used to run the model.
  • grid : a AbstractGrid structure. Discrete grid for the model (resolution and geometry).

Keyword Arguments (Optional)

  • FT: Floating point data type. Default: Float32.
  • mode : Phytoplankton physiology mode, choose among CarbonMode(), QuotaMode(), or MacroMolecularMode().
  • N_species : Number of species.
  • N_individual : Number of individuals per species, should be a vector with N_species elements.
  • max_individuals : Maximum number of individuals for each species the model can hold, usually take the maximum of all the species and apply a factor to account for the growth of individuals during one simulation.
  • bgc_params : Parameter set for biogeochemical processes modeled in the model, use default if nothing, use Dict to update parameters, the format and names of parameters can be found by running bgc_params_default().
  • phyt_params : Parameter set for physiological processes of individuals modeled in the model, use default if nothing, use Dict to update parameters, the format and names of parameters can be found by running phyt_params_default(N_species, mode).
  • nut_initial : The source of initial conditions of nutrient fields, should be either a NamedTuple or a Dict containing the file paths pointing to the files of nutrient initial conditions.
  • t : Model time, start from 0 by default, in second.
source

Architecture

Passing arch = CPU() or arch = GPU() to the PlanktonModel constructor will determine whether the model is time stepped on a CPU or GPU.

Users do not need to modify the setup or simulation script to change the architecture to run on. The only thing that needs to be changed is arch = CPU() or arch = GPU().

Running on GPUs

Please refer to GPU Support for more detail on running PlanktonIndividuals on GPUs and don't hesitate to open an issue if you have any difficulty.

Grid

Two options are supported for the grid: RectilinearGrid and LatLonGrid with constant grid spacing in horizontal directions; grid spacing can differ between dimensions. Both Periodic and Bounded domain options are supported for the horizontal directions, whereas the domain is always Bounded in the vertical direction (top and bottom).

The RectilinearGrid is constructed by specifying its size (Tuple specifying the number of grid points in each dimension) and x, y, and z (Tuple specifying the start and end points).

PlanktonIndividuals.Grids.RectilinearGrid — Type
RectilinearGrid(;size, x, y, z,
                 FT = Float32,
                 topology = (Periodic, Periodic, Bounded),
                 landmask = nothing,
                 halo = (2, 2, 2))

Creats a RectilinearGrid struct with size = (Nx, Ny, Nz) grid points. x and y directions must be regular spaced, z direction can be vertically stretched or regular spaced.

Keyword Arguments (Required)

  • size : A tuple prescribing the number of grid points. size is a 3-tuple no matter for 3D, 2D, or 1D model.
  • x and y : A 2-tuple that specify the start and end points of the domain.
  • z : is either a (1) 1D array that specifies the locations of cell faces in z direction, or (2) 2-tuples that specify the start and end points of the domain. Vertical indexing starts from surface and use negative numbers for depth.

Keyword Arguments (Optional)

  • FT: Floating point data type. Default: Float32.
  • topology : A 3-tuple specifying the topology of the domain. The topology can be either Periodic or Bounded in each direction.
  • landmask : a 3-dimentional array to indicate where the land is.
  • halo : A tuple of integers that specifies the size of the halo region of cells surrounding the physical interior for each direction. halo is a 3-tuple no matter for 3D, 2D, or 1D model. At least 2 halo points are needed for DST3FL advection scheme.
source

For example, a rectilinear grid with $32 \times 64 \times 128$ grid points and grid spacing of $dx=1$m, $dy=2$m, $dz=4$m is constructed like this:

julia> grid = RectilinearGrid(size=(32, 64, 128), x = (0.0,32.0meters), y = (0.0,128.0meters), z = (0.0,-512.0meter))RegularRectilinearGrid{Float32, Periodic, Periodic, Bounded}
domain: x ∈ [0.0, 32.0], y ∈ [0.0, 128.0], z ∈ [0.0, -512.0]
topology (Tx, Ty, Tz):     (Periodic, Periodic, Bounded)
resolution (Nx, Ny, Nz):   (32, 64, 128)
halo size (Hx, Hy, Hz):    (2, 2, 2)
grid spacing (Δx, Δy, Δz): 1.0, 2.0, [min=4.0, max=4.0])

The LatLonGrid is constructed by specifying its size (Tuple specifying the number of grid points in each dimension) and lat, lon, z (Tuple specifying the start and end points).

PlanktonIndividuals.Grids.LatLonGrid — Type
LatLonGrid(;size, lat, lon, z,
            FT = Float32,
            radius = 6370.0e3,
            landmask = nothing,
            halo = (2, 2, 2))

Creats a LatLonGrid struct with size = (Nx, Ny, Nz) grid points.

Keyword Arguments (Required)

  • size : A tuple prescribing the number of grid points. size is a 3-tuple no matter for 3D, 2D, or 1D model.
  • lat : A 2-tuple specifying the startind and ending points in latitudinal direction. Possible values are from -80 (80S) to 80 (80N).
  • lon : A 2-tuple specifying the startind and ending points in longitudinal direction. Possible values are from -180 (180W) to 180 (180E).
  • z : is either a (1) 1D array that specifies the locations of cell faces in z direction, or (2) 2-tuples that specify the start and end points of the domain. Vertical indexing starts from surface and use negative numbers for depth.

Keyword Arguments (Optional)

  • FT: Floating point data type. Default: Float32.
  • radius : Specify the radius of the Earth used in the model, 6370.0e3 meters by default.
  • landmask : a 3-dimentional array to indicate where the land is.
  • halo : A tuple of integers that specifies the size of the halo region of cells surrounding the physical interior for each direction. halo is a 3-tuple no matter for 3D, 2D, or 1D model. At least 2 halo points are needed for DST3FL advection scheme.
source

For example, a global domain from 80S to 80N, 180W to 180E and 200m depth with spacing of 1 degree horizontally and 10m vertically is constructed like this:

julia> grid = LatLonGrid(size=(360,160,20), lat = (-80,80), lon = (-180,180), z = (0,-200))LatLonGrid{Float32, Periodic, Bounded, Bounded}
domain: x ∈ [-180.0, 180.0], y ∈ [-80.0, 80.0], z ∈ [0.0, -200.0]
topology (Tx, Ty, Tz):     (Periodic, Bounded, Bounded)
resolution (Nx, Ny, Nz):   (360, 160, 20)
halo size (Hx, Hy, Hz):    (2, 2, 2)
grid spacing (Δx, Δy, Δz): 1.0, 1.0, [min=10.0, max=10.0])
PlanktonIndividuals.Grids.LoadLatLonGrid — Function
LoadLatLonGrid(;grid_info, size, lat, lon,
                FT = Float32,
                landmask = nothing,
                halo=(2,2,2))

Creats a LatLonGrid struct with size = (Nx, Ny, Nz) grid points.

Keyword Arguments (Required)

  • grid_info : A NamedTuple contains external grid information (e.g. from MITgcm), please refer to documentation for the required format.
  • size : A tuple prescribing the number of grid points. size is a 3-tuple no matter for 3D, 2D, or 1D model.
  • lat : A 2-tuple specifying the startind and ending points in latitudinal direction. Possible values are from -80 (80S) to 80 (80N).
  • lon : A 2-tuple specifying the startind and ending points in longitudinal direction. Possible values are from -180 (180W) to 180 (180E).

Keyword Arguments (Optional)

  • FT: Floating point data type. Default: Float32.
  • landmask : a 3-dimentional array to indicate where the land is.
  • halo : A tuple of integers that specifies the size of the halo region of cells surrounding the physical interior for each direction. halo is a 3-tuple no matter for 3D, 2D, or 1D model. At least 2 halo points are needed for DST3FL advection scheme.
source

Individuals

The number of species can be specified via N_species. The number of individuals per species can be specified via N_individual. The maximum number of individuals per species that the model can hold is specified via max_individuals.

Parameters

Default parameters are generated by two functions called bgc_params_default and phyt_params_default via dictionnaries (Dict). bgc_params contains the parameters for biogeochemical cycls. phyt_params contains the parameters for phytoplankton individuals. The default parameter values are listed here.

Values of the parameters can be changed using update_bgc_params and update_phyt_params.

In the example shown below, we change the value of kDOC, which is the remineralization rate for DOC:

julia> new_params = Dict("kDOC" => 0.01) # no need to include all parametersDict{String, Float64} with 1 entry:
  "kDOC" => 0.01
julia> update_bgc_params(new_params)ERROR: MethodError: no method matching update_bgc_params(::Dict{String, Float64})
The function `update_bgc_params` exists, but no method is defined for this combination of argument types.

Closest candidates are:
  update_bgc_params(::Dict, ::DataType)
   @ PlanktonIndividuals ~/work/PlanktonIndividuals.jl/PlanktonIndividuals.jl/src/Parameters/param_update.jl:10

phyt_params can be changed in the same way.

Nutrient fields

Nutrient fields included in the model are listed below. The initial conditions of the nutrient fields are generated by generate_nutrients either from a NamedTuple or a Dict. The NamedTuple contains two elements. First element is a 10-element NamedTuple, each element is a Float64 number filled uniformly across the domain as initial condition of a tracer. Second element is a 10-element NamedTuple, each element is a Float64 number indicating the random noise of each tracer. The Dict contains the file paths pointing to the files of existing nutrient initial conditions.

NameUnitDescription
DIC$mmol~C/m^3$concentration of dissolved inorganic carbon
NH4$mmol~N/m^3$concentration of ammonia
NO3$mmol~N/m^3$concentration of nitrate
PO4$mmol~P/m^3$concentration of phosphate
DOC$mmol~C/m^3$concentration of dissolved organic carbon
DON$mmol~N/m^3$concentration of dissolved organic nitrogen
DOP$mmol~P/m^3$concentration of dissolved organic phosphorus
POC$mmol~C/m^3$concentration of particulate organic carbon
PON$mmol~N/m^3$concentration of particulate organic nitrogen
POP$mmol~P/m^3$concentration of particulate organic phosphorus
Noisy Initial Conditions

A random noise can be included only if the initial conditions are generated by NamedTuple.

Nutrient Fields

The initial conditions of all the nutrient fields should be non-negative.

An example of the NamedTuple is listed below:

julia> initial_condition = (DIC=20.0, NH4=0.2, NO3=0.5, PO4=0.03, DOC=1.0, DON=0.1, DOP=0.05, POC=0.0, PON=0.0,POP=0.0);
julia> rand_noise = (DIC=0.0, NH4=0.0, NO3=0.0, PO4=0.0, DOC=0.0, DON=0.0, DOP=0.0, POC=0.0, PON=0.0,POP=0.0);
julia> nut_initial = (initial_condition = initial_condition, rand_noise = rand_noise)(initial_condition = (DIC = 20.0, NH4 = 0.2, NO3 = 0.5, PO4 = 0.03, DOC = 1.0, DON = 0.1, DOP = 0.05, POC = 0.0, PON = 0.0, POP = 0.0), rand_noise = (DIC = 0.0, NH4 = 0.0, NO3 = 0.0, PO4 = 0.0, DOC = 0.0, DON = 0.0, DOP = 0.0, POC = 0.0, PON = 0.0, POP = 0.0))

And example of the Dict is listed below:

julia> nut_init = Dict(
           "DIC" => "path/to/DIC.bin",
           "NH4" => "path/to/NH4.bin",
           "NO3" => "path/to/NO3.bin",
           "PO4" => "path/to/PO4.bin",
           "DOC" => "path/to/DOC.bin",
           "DON" => "path/to/DON.bin",
           "DOP" => "path/to/DOP.bin",
           "POC" => "path/to/POC.bin",
           "PON" => "path/to/PON.bin",
           "POP" => "path/to/POP.bin");