Metos3D BGC API¶

Application programming interface (API) for biogeochemical (BGC) models

Definition, realization in Fortran

metos3dbgcinit(...)
metos3dbgcbegin(...)
metos3dbgc(...)
metos3dbgcend(...)
metos3dbgcfinal(...)

Description¶

The interface decouples biogeochemical models and driver routines (ocean circulation, forcing, geometry) programmatically.

It gives the modeler the possibility to provide a free number of tracers, parameters, boundary and domain conditions. It suits well an optimization as well as an Automatic Differentiation (AD) context.

The interface changed (more or less) since it was introduced for the first time. The initial version can be found at \citep[][]{PiwSla16}.

What is it?¶

Ther Metos3D BGC API is a convention how biogeochemical models can be coupled to ocean circulation.

What for?¶

modelers that want to their marine ecosystem or biogeochemical models, coupled to a global ocean circulation,

Why?¶

climate research, ocean simulation, bgc models, uncertainties, parameters, processes, require assessment, at global-basin scale, sophisticated general circulation model,

How?¶

C model template¶

Fortran model template¶

Example 1¶

in the simplest case, assuming you have a model written in Fortran,

File: simple_bgc_model.f90

subroutine metos3dbgc(ny, nx, nu, nb, nd, ndg, dt, q, t, y, u, b, d, dg, ctx)

    integer :: ny           ! tracer count
    integer :: nx           ! layer count
    integer :: nu           ! parameter count
    integer :: nb           ! boundary condition count
    integer :: nd           ! domain condition count
    integer :: ndg          ! diagnostic variable count
    real(8) :: dt           ! ocean time step
    real(8) :: q(nx, ny)    ! bgc model output
    real(8) :: t            ! point in time
    real(8) :: y(nx, ny)    ! bgc model input
    real(8) :: u(nu)        ! parameters
    real(8) :: b(nb)        ! boundary conditions
    real(8) :: d(nx, nd)    ! domain conditions
    real(8) :: dg(nx, ndg)  ! diagnostic variables
    integer :: ctx          ! unsed variable, place holder for bgc context
    
    ! your code here ...
    
end subroutine

Example 2¶

File: bgctype.h90

type bgcctx
    sequence
    real(8) :: a
    real(8) :: b
    logical(4) :: yesOrNo
    real(8), pointer :: ptr(:)
end type

File: more_sophisticated_bgc_model.f90

subroutine metos3dbgc(ny, nx, nu, nb, nd, ndg, dt, q, t, y, u, b, d, dg, ctx)

#include "bgctype.h90"

    integer         :: ny           ! tracer count
    integer         :: nx           ! layer count
    integer         :: nu           ! parameter count
    integer         :: nb           ! boundary condition count
    integer         :: nd           ! domain condition count
    integer         :: ndg          ! diagnostic variable count
    real(8)         :: dt           ! ocean time step
    real(8)         :: q(nx, ny)    ! bgc model output
    real(8)         :: t            ! point in time
    real(8)         :: y(nx, ny)    ! bgc model input
    real(8)         :: u(nu)        ! parameters
    real(8)         :: b(nb)        ! boundary conditions
    real(8)         :: d(nx, nd)    ! domain conditions
    real(8)         :: dg(nx, ndg)  ! diagnostic variables
    type(bgcctx)    :: ctx          ! own bgc context

    ! your code here ...

end subroutine

Example 3¶

Good practice,

store constants in a module,
store pointers for own memory allocation, (usually not needed at all), in data type
- use metos3dbgcinit to allocate memory
- use metos3dbgcfinal to free memory

was what wie how warum why wofuer what for