The aim of the VSoil modelling software platform is to create and use computer models with proper software. These models are built by assembling elementary blocks called modules. These modules describe processes (physical, chemical or biological phenomena) taking place in the soil or at its interfaces, such as the atmosphere or the plant. The processes use input variables that can influence the evolution of different variables of interest, which are output variables.

This document describes the most common uses of the VSoil modelling platform. More detailed descriptions can be found in more specific documents available with the platform: tutorials, user manuals, etc. We will refer to these when appropriate.

We are going to describe various use cases frequently encountered in a scientific research context. The VSoil modelling platform can also be used in other more specific contexts: design offices, industry, etc.

What are the possible uses of VSoil?

To illustrate a frequently encountered context, let's imagine a person working in a scientific environment. This person is interested in physical, chemical or biological phenomena in the soil or at its interfaces. This person wants to answer a scientific question using a computer representation. In practical terms, this means using a numerical model capable of calculating quantities of interest.

Using an existing VSoil model

The VSoil modelling platform is delivered with models, already assembled and ready to run, with complete example configuration files. The VSoil user can adapt these initial situations provided, or create new ones. The VSoil platform guides the user in the different needed steps. Its graphical interface includes a multitude of descriptions and guides to help configure the initial situations of the models. All model components, called modules in VSoil, are accompanied by additional documentation and links to reference publications.

Prerequisites: this scenario requires knowledge in the use of scientific models. Skills are required to parameterise the models. This includes, in particular, defining the coordinates of the points on the calculation grid and the soil layers. It is also necessary to describe the initial situations of the modules: parameter values, initial conditions and boundary conditions.

To find out which models are available in VSoil, there is a dedicated web page with a search engine.

Within the VSoil platform, manipulation of an existing model requires the use of the vsoil-player software. See What you can do with vsoil-player software for more information.

Creating a new VSoil model from existing modules

A model is a set of computer representations of phenomena designed to answer a scientific question. It is therefore often necessary to create new models, either from scratch or from an existing one, close to the needs. The VSoil modelling platform is designed for this purpose and guides you through the creation of a new model. It allows you to integrate, step by step, the different building blocks, called modules in VSoil, available in the platform. The VSoil graphical interface guides the user through the assembly of the available modules.

Prerequisites: this scenario requires confirmed knowledge as a model user, as described in the previous scenario. Scientific competence in the processes concerned by the model to be built is required. You need to have an informed view when choosing the processes and, above all, the associated computer representations (the modules).

Within the VSoil platform, the creation of a model from existing modules requires the use of the vsoil-models software. See What you can do with vsoil-models software for more information.

Creating a VSoil module describing an existing process

Over 130 modules are supplied with the VSoil modelling platform. They are the computer representation of physical, chemical or biological phenomena. If there is no computer representation corresponding to the need, the user can create a new one, ex nihilo, or from an existing one. The VSoil platform guides the user step by step through this creation phase. The computer coding part is facilitated by a dedicated source code editor. This includes a number of aids and a context-sensitive automatic code generator. In this way, users can concentrate primarily on the calculation code needed to produce their numerical results. The VSoil platform takes charge of most other aspects automatically: reading the initial state, exchanging input and output variables with other modules, writing output variables to files, etc.

Prerequisites: this scenario requires, first of all, a mastery of the mathematical formalism that must represent the desired process. It may also be necessary to choose a numerical resolution method and be able to transform it into a calculation algorithm. Finally, user needs a grounding in computer programming and scientific calculation, to produce the corresponding source code.

Within the VSoil platform, the creation of a module from a process already described requires the use of the vsoil-modules software. See What you can do with vsoil-modules software for more information.

Defining processes and variables

More than 50 processes are currently defined and supplied with the VSoil modelling platform. They can be used to represent most physical, chemical or biological phenomena in the soil or at its interfaces. In addition, nearly 700 variables are already present in the VSoil platform. As input or output variables of processes, they represent the possible interactions between phenomena. It is possible to enrich this by creating new processes and new variables. These can be created from scratch or from existing data.

The VSoil platform guides you through the creation of processes and variables. The graphical interface helps users to name variables. It also makes it easy to associate them with process as input or output variables. Moreover, the graphical interface automatically displays the possible linkages between processes, in the form of directed graphs called skeletons in VSoil.

Prerequisites: this scenario requires scientific knowledge on the concerned process and its interactions with other processes.

Within the VSoil platform, the creation of a new process or new variables requires the use of the vsoil-processes software. See What you can do with vsoil-processes software for more information.