Alpine3D

Running-a-simulation

You are looking at an old revision of the page Running-a-simulation. This revision was created by Robert Spence.

Table of Content

How to prepare and run a simulation

Introduction

Running an Alpine3D simulation requires several steps:

  1. Getting and compiling Alpine3D
  2. Defining the simulation
  3. Preparing the input data
  4. Configuring the simulation
  5. Running the simulation
  6. 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

This is described in Getting-started. Once you have compiled Alpine3D and prepared everything that is needed (including "make deploy"), you are advised to setup your simulation in a specific directory. For example, a directory named "Dischma" that will have the following subdirectories structure:

  • bin; This is a copy of the bin subdirectory of the Alpine3D sources
  • input; There you copy your meteo data in a "meteo" subdirectory (if needed), your domain grids (see below) in a "surface-grids" directory and the sno files (see below) in a "snowfiles" directory
  • output; The simulation outputs will be written there. You can create a "runoff" subdirectory to contain runoff data
  • setup; The configuration files and start scripts should go there. The simulations will be strated from this directory

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

Several categories of data are necessary for the input:

  • Landscape data: Digital Elevation Model, Land Cover model...
  • Snowcover and soil data
  • Meteorological data

We will go through each of these categories. But first, it is usually a good idea to set up a clean structure for the simulation: we will consider that everything goes into a simulation folder, for example my_simulation. Then you could create several subdirectories: input, output, setup and bin. These subdirectories contain the following:

  • in input, all the input data, stored in a surface-grids directory for the landscape data, in a meteo directory for the meteorological data and in a snowfiles directory for the snowcover and soil data.
  • in output, all the outputs will be writen, the snowcover and soil data in a snowfiles subdirectory and the runoff data in a runoff directory.
  • in setup, all the configuration files and start scripts
  • in bin, all the binary files (namely, the alpine3d binary and some associated libraries as well as the parallel objects for the parallel version).

Landscape data

Digital Elevation Model

Once you know the domain that you want to simulate, you have to get a Digital Elevation Model that contains this area. Usually, these are provided within a rectangular area. You will be able to restrict the actual domain within this rectangular area by settings the cells you to ignore as nodata. However, you need to keep in mind the following:

  • The DEM defines the spatial grid that will be used in Alpine3D
  • Therefore, the resolution of the DEM is the spatial resolution of the simulation
  • Each cell whose DEM is nodata will be skipped by all modules of Alpine3D
  • In order to properly compute the shading effects, do not exclude cells that could cast shades on an interesting part of the domain!

These last two points are important for both the definition of the rectangular DEM as well as filling the unecessary cells with nodata. All other grids (either land cover or potential meteorological grids) will have to use the exact same geolocalization as the DEM (same position, same size, same resolution) unless otherwise specified.

Land Cover model

For each DEM cell, a land cover code must be provided. This must be using the exact same geolocalization as the DEM. uch data are usually available in various classifications, depending on the country. Currently, Alpine3D uses the prevah classification (see Meteoio's ARC plugin documentation) and (improperly) calls the Land Cover Model "Land Use", abbreviated as LUS.

Catchments definition

If you intend on computing the runoff, you have to define the individual catchments. This is currently done by creating a grid that contains a code describing which catchments this pixel belongs to, based on sums of powers of two. For example, a pixel belonging to catchments 0 and 3 would receive the code: 2^0+2^3=9. A pixel belonging to catchments 2, 5, 6 would receive the code 2^2+2^5+2^6=100.

Snow cover and soil data

Either each cell or each cell class (based on Land Cover classification) must be assigned an initial soil and snow profile. Usually, to make things easier, the simulation starts at a time when no snow is present in the domain, making the snow profile empty. The same file also contains potential soil layers data. This file is writen in a Snowpack snowfile supported format (see Snowpack documentation). The profile and layers must be dated from before the simulation starts. The file is named {EXPERIMENT_NAME}_{LAND_USE_CLASS}.{ext} and placed along all other similar files in a separate directory (in order to keep the simulation tidy).

Meteorological data

Usually, the meteorological inputs are provided as points measurements time series and spatially interpolated within alpine3d (using meteoio). But it is also possible to provide some (or all) data as gridded data.

Gridded meteorological data

This relies on using meteoio's USER spatial interpolation algorithm. The grids must follow a specific naming scheme so they can be found and be placed in a specific directory and the grids must have the same geolocalization and size as the dem. This is detailed in meteoio's documentation.

Please note that if not all necessary grids are provided, meteoio will revert to point measurements inputs. It is therefore possible to provide only a few specific grids according to the needs (for example, only the precipitation grids when there are some precipitation).

Point measurements

This is mostly centered around the concept of station: a specific point in the landscape where multiple parameters are measured for a given period. The file formats vary greatly depending on which meteo plugin is used. It is nevertheless always possible to use stations that don't cover the whole period or contain data gaps. It is also possible to use stations that are outside the domain (but they should not be too far away, otherwise this does not make sense!). The model will run with an hourly resolution, so the data should be either hourly or could be meaningfuly resampled to an hourly resolution (i.e., daily measurements would not qualify). Please note that in any case, the following must always be provided:

  • at least one of:
    • air temperature (TA)
    • relative humidity (RH)
    • wind speed (VW)
    • precipitation (HNW)
  • at least one point offering simultaneously the following:
    • air temperature (TA)
    • relative humidity (RH)
    • incoming short wave radiation (ISWR)
    • incoming long wave radiation (ILWR)

It is also recommended to provide stations well distributed over the domain and over the elevation range, so the elevation gradients can be properly computed.

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.

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).

Sequential simulation

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).

Parallel simulation

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.