Skip to content

Getting started

This document will now explain you how to download Alpine3D, how to compile it according to your needs and how to find your way in its code and documentation.

Getting Alpine3D

In order to reduce the maintenance burden and to make Alpine3D easier to tailor to specific needs, it has been decomposed into several tools:

  • Inishell for graphical configuration of the simulations
  • MeteoIO for data retrieval and preprocessing
  • libsnowpack for doing the 1D soil/snow/canopy modeling
  • Alpine3D itself that combines MeteoIO and Snowpack, distributes it over a DEM and adds a radiation model and a snow drift model.

So, you need to get these packages (either as binary or source form) and then, get Alpine3D (In the future, there will be Alpine3D packages containing all you need in one package). There are several ways to get Alpine3D itself:

  • as source package, to recompile for your platform;
  • as git clone.

Please follow the instructions as given for MeteoIO, simply replacing "meteoio" by "alpine3d".

Compiling Alpine3D

You need to download and install (or download/compile and install) the previously listed packages so they can be automatically found. If you don't want to install either MeteoIO or Snowpack on your system, you have to keep the following directory structure:

                💻
                ┣━━╾ 📂 snowpack trunk
                ┣━━╾ 📂 meteoio trunk
                ┗━━╾ 📂 alpine3d trunk
and then Alpine3D would still find MeteoIO and snowpack automatically. Please review the compiling instructions for MeteoIO, since here only what differs will be listed. The generation of the documentation also follows the instructions given for MeteoIO in the previous link (the generated documentation being in doc/Alpine3D_doc.html). Otherwise, you can download a documentation only package (in the Downloads).

Please note that for Alpine3D-3.0.0, at least MeteoIO-2.5.1 is needed (there is a source-only package specially for this reason on MeteoIO's page).

Compiling on Linux/Unix

  • open a terminal and change into the trunk folder of alpine3d
  • "ccmake ."
  • Press [c] to configure, it will then populate the screen with configurable options
  • choose the relevant options (toggle ON/OFF by pressing Enter)
  • Press [c] to configure
  • Switch "Openmp" to ON if you want to run Alpine3D in parallel using openmp
  • Switch "MPI" to ON if you want to run Alpine3D in parallel using MPI (note that you must install MPI before)
  • Press [g] to generate and exit the interface (you might have to press [c] a few times for it to have everything finally setup)
  • "make" to compile the code
  • then, you have two options:
    • pack all the necessary files in a bin directory in the simulation folder:
      • make deploy to copy all the necessary files for a run in the "bin" subdirectory
      • you currently have to manually copy the "bin" subdirectory to your simulation folder (see Running-a-simulation)
    • install all the necessary files on your system:
      • make install to copy all the necessary files on the installation folder that has been configured in cmake (see Snowpack's Getting Started for how to install in a user directory).

On MacOS, follow the same instructions but openmp is currently not supported.

Running a simulation

It is highly recommended 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 (or a link) of the bin subdirectory of the Alpine3D sources
  • input; There you copy your meteo data in a "meteo" subdirectory (if needed), your domain grids in a "surface-grids" directory and the sno files in a "snowfiles" directory
  • output; The simulation outputs will be written there. You can create a "runoff" subdirectory to contain runoff data
  • output/grids; The gridded outputs could go there.
  • setup; The configuration files and start scripts should go there. The simulations will be started from this directory, using the run.sh launch script.

In order to prepare your simulation's data (forcing, grids, snow files), it is highly recommended to have a look at the Alpine3D's online documentation.

You can also have a look at the Running a simulation page in Alpine3D's documentation.

Running in parallel

For an openmp parallel run, you must run on an SMP system. For MPI, you must have the proper MPI libraries installed. Your queuing system (if any) must also support openmp/mpi and you must define how many threads you want to use for each run. This is handled by the run.sh launch script, but you must edit this script according to your needs.

If submitting the job to a cluster using the Sun Grid Engine queuing system, you must edit the header of your run.sh script to define your job name, queue name, number of nodes requested, etc