What you can do with vsoil-modules

We present on this page what you can do with vsoil-modules software. It allows to create modules from processes.

The program "vsoil-modules" is dedicated to handling the modules

 The modules are used to create models using dedicated software.
 To obtain process, use dedicated software.

The objective of the module creator is to represent a physical, chemical or biological phenomenon using computer source code. This code must calculate output variables and their evolution over time. To do this, the module can have input variables at its disposal, coming from the output variables of other upstream modules, its own parameters, etc. Many characteristics of the module influence the code to be produced and its complexity. In a first part, we will describe the main characteristics of the modules. They are encountered when using the vsoil-modules software. In a second part, we will detail the specificities of the modules according to their typology.

Characteristics of a VSoil module

A VSoil module is associated with a process. The input and output variables of the module come from those of its process. A VSoil module must calculate its output variables at the time steps of the simulation. In general, the output variables are functions of the module input variables. But, in some cases, the module may not have any input variables. This situation occurs (i) if the process associated with the module describes a boundary condition of the system, or (ii) if the designer wants the module to be a boundary condition of the model to be represented. In all these cases, no input is selectable for the module.

A module operates in a spatial context which can be dimension 1, 3 or dimensionless. Note: For the VSoil platform, a spatial domain of dimension 2 is a simple special case of dimension 3. In dimension 1, we consider a vertical soil profile. The points in the calculation grid therefore only have one depth, from the surface to the bottom of the profile. Dimension 3 adds two components to this depth. A dimensionless module, called 0D in VSoil, considers the points of the calculation grid as independent. In this case, unlike the two previous ones, the module output variables do not depend on adjacent points.

You can define parameters and data files specific to the module. These will be available in the calculation code and will thus be able to participate in the calculation of its output variables. The values of these parameters and files must be provided when the module is used in a model.

A module may depend on time. It is (i) either the current time, in absolute value since a reference date; is (ii) the time elapsed since the previous current time. In this second case, VSoil also makes the input variables at the previous time available to the calculation code. They can thus be used to calculate the module output variables.

During a simulation, it is possible for the soil profile to change. This is the case, for example, when erosion or deposition phenomena occur on the ground surface. The points on the calculation grid can then change, both in position and in number. When a module is compatible with this functionality of VSoil, its output variables must be able to be recalculated accordingly on demand.

The module is both a numerical solution method and a computer source code. This consists of choosing a mathematical and computational strategy to approximate the resolution of equations. The choice of numerical methods depends above all on the desired precision and the acceptable calculation time. The most common numerical methods are iterative (e.g. fixed point, Jacobi, Gauss-Seidel); numerical integration (e.g.: trapezoids, Simpson, Romberg) or to solve differential equations (e.g.: Euler, Runge-Kutta). The software development then consists of translating the chosen numerical method into an algorithm, then into source code in a language, Fortran or C++ in VSoil.

Ultimately, the source code makes it possible to calculate the module output variables (i) at the initial time and (ii) at each time of a simulation. The VSoil-modules graphical interface allows the module creator to concentrate on coding these two parts. VSoil takes charge of calling these calculation codes at the appropriate times and provides them with the necessary input data.

Typical modules

Certain characteristics, seen above, can strongly influence the computer source code of a module. In the following sections, we will describe some cases frequently encountered in VSoil, of generally increasing complexity.

Modules without input variables

As written at the beginning of the previous section, a module which represents a boundary condition of the system to be modeled has no input variables. Examples in VSoil: climate, plant, phenomena at the surface or bottom of the soil profile. Such a module, called “no input” in VSoil, has no feedback with other modules. Therefore, it can calculate its output variables only with parameters, file contents, stochastic values, etc.

There will be a tutorial on this particular case soon: Create a “no input” module to produce climate data.

Modules and time dependence

Generally speaking, a module calculates its output variables using its input variables, plus possibly parameters. When the module is declared as not time dependent, its input variables are only available at the current time step of the simulation. There is a tutorial on this: Module creation tutorial with VSoil: root water uptake.

When a module is time dependent, it can also use its input variables at the previous time. In addition, it has access to several variables concerning time during the simulation: current time (i.e. elapsed since the reference date), time elapsed since the previous time, changes in day, month or year, etc.

When several modules, integrated into a model, depend on time, they must be in phase. That is to say, they must calculate their output variables at identical simulation times. We must therefore find a common time step between everyone. VSoil uses the lowest proposed value. It is a mechanism where, at each simulation time, a module can refuse the time step proposed by VSoil and possibly propose another, necessarily shorter. The mechanism put in place to show how variable time steps are managed in a module are given in the tutorial: Module creation tutorial with VSoil: mulch decomposition.

We saw, in the previous paragraph, that a module which depends on time may have to re-calculate its output variables, with a shorter time step. This requires particular attention if the module calculates cumulative quantities over time or uses internal variables. A tutorial addresses this subject: organic matter first order.

Dimension 1 modules

The ground is represented by a mesh. It is a grid of points, in layers of soil. For a module of dimension 1, this mesh is vertical, from the surface to the bottom of the profile. The input and output variables of the module represented in the soil profile are therefore variables whose values are ordered in vectors, with a neighborhood of ad-hoc points. Computerwise, these are arrays of dimension 1. There is a tutorial on this subject: Module creation tutorial with VSoil: simple denitrification.

Dimension 3 modules

In dimension 3, the mesh is still a set of points, between the surface and the bottom of the soil profile. These points are not necessarily organised in a homogeneous manner. The neighbors of each point are given by a matrix.

There will be a tutorial on this particular case soon: Create a 3D module.

Modules with mesh change

When running a model, a module can request to change the simulation mesh. Example: to densify the mesh at certain locations of interest. This may involve (i) adding or removing points from the grid; (ii) changing the position of points; (iii) changing the depths of soil layers. When requested, all modules of the model must be able to recalculate all their output variables with the new soil profile. For certain variables, the calculation must be done by carrying out an interpolation from the old to the new grid. VSoil offers functions to facilitate this sometimes delicate step. There are two official modules in the VSoil platform that demonstrate this functionality: swf_dynamic_grid_example_cpp and swf_dynamic_grid_example_fortran. The first is written in C++ language and the second in Fortran.