How to prepare and run a simulation
Running an Alpine3D simulation requires several steps:
- Getting and compiling Alpine3D
- Defining the simulation
- Preparing the input data
- Configuring the simulation
- Running the simulation
- Extracting the data of interest from the outputs
Please note that usually, you would do several iterations on the steps 2-6. The goal of this document is to describe these steps.
Getting and compiling Alpine3D
Please see Getting-started.
Defining the simulation
Here, you have to define the very basic parameters of the simulation:
- The domain
- which geographic area
- which features of the landscape you want to include
- the contours of the area within the rectangular Digital Elevation Model
- The time interval
- what is the starting date (usually, you want to start without snow in the domain)
- if some spin up would be necessary, this gives you the actual simulation starting date
- what is the end date (do you need to wait until all snow is melted in the domain?)
- The overall goal of the simulation
- is about hydrology?
- is about snow transport?
- is about snow cover distribution?
- The meteorological input data
- will you provide points measurements or gridded data?
- in case of climate scenario, which scenario do you want to use?
Once you have answered these very basic questions, you can move forward and start preparing the simulation.
Preparing the input data and files structure
Please keep in mind that Alpine3D simulations MUST run with soil (the SNP_SOIL key will be forced to "true") and with canopy (the CANOPY key will be forced to "true").
Configuring the simulation
This is done by two means: by the io.ini configuration file and by some command line options.
The io.ini configuration file
This file is structured by sections, focused on several aspects:
- General, for a few gerenal options
- Input, for the configuration of the inputs
- Output, for the configuration of the outputs
- Snowpack, for the specific snowpack model configuration
- SnowpackAdvanced, for some advanced Snowpack options, including the necessary ALPINE3D = true key
- Interpolations1D, for the temporal interpolations configuration
- Interpolations2D, for the spatial interpolations configuration
These sections are described in the meteoio and snowpack documentation.
It is also possible (and recommended) to use inishell to generate a proper io.ini for alpine3d.
Unfortunately, the current configuration of inishell for Alpine3D does not cover all the possibilities. You can generate the Snowpack section by using the Snowpack inishell configuration and then copy it into your ini files generated with inishell for Alpine3D.
Command line options
You can get the list of supported options by running alpine3d --help. These options focus on which modules should be enabled (for example, snowdrift), the number of workers for the modules that have been parallelized (for example, 4 workers for ebalance) and the start and end date of the simulation.
Configuring the gridded outputs
The exact outputs must currently be configured by editing the source code. Open the file "snowpackinterface/SnowpackInterface.cc" and look for the writeOutput method. This is where you can comment some of the outputs, or create new one. It is also possible to edit "snowpackinterface/SnowpackInterfaceWorkers.cc" and write in the custom grid any snowpack parameter (or any other computation), then to write it out from "snowpackinterface/SnowpackInterface.cc".
Running the simulation
Several "standard" simulations are available to test that a given installation is properly working. These range from very small (like the Stillberg or Dorfberg simulations) to huge (Graubunden simulation). Both sequential and parallel runs can be done (keeping in mind that a large simulation might not have enough memory to run sequentially).
First, once Alpine3D has been properly compiled and "deployed", copy content of the Alpine3D "bin" subdirectory into the simulation's "bin" subdirectory. Then, go into the "setup" directory and edit the "run.sh": this is the script that controls the simulation. You can configure a parallel (or not parallel) simulation as well as the number of workers (that would run in parallel for a parallel simulation, thus reducing the total computing time or one after another in a sequential simulation). To start a simulation, simply run this script: "./run.sh". Since most simulations last for quite a while, it is usually a good idea to detach the simulation process by using nohup, thus modifying the command line to become "nohup ./run.sh &". Very often, the simulation will be managed by a batch system (please ask your system administrator for how to submit jobs to your batch system).
It will come soon!
Extracting output data
The gridded outputs should all be in the output subdirectory, while the runoff outputs would be in output/runoff.