Extending the model

Overall organisation of the model code

The model source code is structured to be as modular as possible. This means for example that generic model infrastructure such as the numerical schemes, grid definitions and input/output-routines are as detached from the actual physical formulation of the model as reasonably possible within the limitations of Fortran. Further, the different physical models are all self-contained and can be run independently from each other; add-ons to physical models such as the atmospheric tracer module are formulated such that they will work without adaptation with each of the available atmospheric models.

Some specific consequences of this modular approach are:

• Model components need to register themselves which variables are to be included in the netCDF output.

• Model components need to register the variables required for the exchange with other model components.

• Fortran modules need to define their own routines for initialisation and termination, called init_<module_name> and term_<module_name> as far as relevant.

• All relevant API to run the model is contained in the runctrl module. This module coordinates the overall initialisation and termination of a model simulation. The runctrl module is used in both the Fortran executable and the python runscripts.

• Preprocessors share the model numerics and grid definitions and all other generic infrastructure in src_base and src_numerics.

• Different model components can be swiched on/off both at compile time and (as far as available in the executable) for each model simulation. Each model component thus needs to be guarded by a compile-time switch to include/exclude the model from the compilation.

The following table gives a brief overview over the functions and content of each Fortran module in an order in which all interdependencies between modules have been resolved (i.e. modules depend on only on other modules that appear earlier in the list). The first list of modules contains the basic infrastruture and numerics used for all physical models and the preprocessors.

Fortran module	Folder	Description
kind	src_base	Defines the numerical precision used throughout.
ptr	src_base	Fortran boilerplate necessary to define and use procedure pointers.
consts	src_base	Defines physical constants and model parameters.
logfile	src_base	Defines the report and status files and functions for error reporting.
surflib	src_base	Defines parameterised 2d-functions, e.g. Gaussian ridges and hills.
ncin	src_base	Reads netCDF files for initialisation/restart.
config_base	src_base	Defines and parses the grid, topo and metio namelists.
grid	src_base	Defines various grids (main, staggered, multigrid for the QG-inversion).
interpolate	src_numerics	Defines interpolation functions between grids of different resolutions.
boundaries	src_numerics	Defines different boundary conditions and makes them available in a common interface.
ellipse	src_numerics	Defines routines to solve elliptical PDEs, for example to do a Laplace-inversion.
derivatives	src_numerics	Defines derivatives on the grid at different numerical precision.
timeint	src_numerics	Defines abstract time integration routines.
coupler	src_base	Defines the interfaces used to exchange information between model components.
ncout	src_base	Writes results from the simulation as netCDF output.

With all these basics established, we can proceed to define the different physical model components. The model compomnents each typically contain several Fortran modules. Typically each model component contains

• a configuration module defining the model-specific namelists,

• a module containing functions to calculate diagnostic variables, and

• a module containing the prognostic equations and a function advancing the model by a time step.

Currently, the following physical models are available:

Model component	Folder	Description
bedymo	src_atmos	Physical core of the namegiving QG/PE model.
bedymoPE	src_atmos	An optimised PE model (currently defunct).
trace	src_atmos	An atmospheric passive tracer module.
slab	src_ocean	A slab-ocean with different parameterisation for prescribed and wind-induced currents.

With all physical models defined, the src_core folder contains first and foremost the runctrl module which orchestrates all of the above and provides functions to initialise, run and terminate the model. These functions are used in the Bedymo standalone executable defined in bedymo_main and the python runscripts.

Fortran module	Folder	Description
config_run	src_core	Defines and parses the models, numerics and timectrl namelists.
runctrl	src_core	Provides the API to run the model for the Fortran executable and the python run scripts.
bedymo_main	src_core	Defines the Fortran executable and its command line options.

Finally, preprocessors are defined in the src_pre folder. Currently there is only one preprocessor available which can be used to define custom idealised initial conditions for Bedymo.

Preprocessor	Folder	Description
init	src_pre	Defines an executable to create custom idealised initial conditions for Bedymo.

Adding parameterisations and model components

Given the modular approach and the comprehesive basic infrastructure it is relatively straightforward to add new model components to Bedymo. The existing physical models provide a template on how to best structure the new code to fit into the modelling framework.

The only place where existing code must be touched to include a new model component is the runctrl module. Here, the new model component must be included in the model initialitsaion and termination choreography as well as in the function that advances all model components by a time step. With that in place, remember to document the new model component

1. in the top section of the compile script, listing the models that can be included in the compilation.

2. this documentation page defined in the doc/source-directory of the model code repository.

Note that parameterisations beyond a certain complexity are best included as new model components similar to the tracer module. This allows to enable/disable/configure the parameterisations independently from, for example, the atmospheric model which they hook onto.

Happy coding!