NOTE: The instructions below are meant for users who want to run the model. If you want to add changes to the model, see the documentation on "Contributing guide".
Workflow of STEMMUS_SCOPE
- The model reads the forcing file associated with the specified site/location,
e.g.,
FI-Hyy_1996-2014_FLUXNET2015_Met.ncfrom "ForcingPath" and extracts forcing variables in.datformat. The.datfiles are stored in theInputPathdirectory. In addition, the model reads the site information i.e. the location and vegetation parameters. - The model runs step by step until the whole simulation period is completed i.e till the last time step of the forcing data.
- The results are saved as binary files temporarily. Then, the binary files are
converted to
.csvfiles and stored in asitename_timestampedoutput directory underOutputPath.
Run the model with MATLAB
If you have MATLAB installed on
your device, you can run the model by passing config file path to the
variable CFG in the main script STEMMUS_SCOPE.m.
As an alternative, you can run the main script using MATLAB command line in a terminal:
To open MATLAB desktop on CRIB, click on the Remote Desktop in the
Launcher. Click on the Applications. You will find the 'MATLAB' software
under the Research. After clicking on 'MATLAB', it asks for your account
information that is connected to a MATLAB license. Then, you can run the
model by passing config file path to the variable CFG in the main script
STEMMUS_SCOPE.m
In order to use MATLAB, you need to send a request to add you to the user pool
on Snellius. Then, pass config file path to the variable CFG in the main script
STEMMUS_SCOPE.m. To run the main script STEMMUS_SCOPE.m using MATLAB command line in a terminal on
a compute node:
module load 2023
module load MATLAB/2023a-upd4
cd src/
matlab -nodisplay -nosplash -nodesktop -r "run('STEMMUS_SCOPE.m');exit;"
To submit a job to a compute node, see instructions here.
Run the model with MATLAB Runtime
If you want to run the model as a standalone application, you need MATLAB
Runtime
version 2023a. You don't need a license for MATLAB Runtime. Note that the
version of the MATLAB Runtime is tied to the version of MATLAB. The
executable file works on the operating system on which the file is created.
The file STEMMUS_SCOPE under exe directory is an executable file of
STEMMUS_SCOPE that is created using MATLAB version 2023a in a Linux
system.
Make sure LD_LIBRARY_PATH is set correctly, in a terminal:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/MATLAB/MATLAB_Runtime/v2023a/runtime/glnxa64:/usr/local/MATLAB/MATLAB_Runtime/v2023a/bin/glnxa64:/usr/local/MATLAB/MATLAB_Runtime/v2023a/sys/os/glnxa64:/usr/local/MATLAB/MATLAB_Runtime/v2023a/sys/opengl/lib/glnxa64
Change /usr/local/MATLAB/MATLAB_Runtime/v2023a to the path where MATLAB Runtime is installed.
Then, you can run the model in a terminal:
On CRIB, MATLAB Runtime is not available. Contact the system administrator for more information.
MATLAB Runtime is available on Snellius. You can run the model by passing the path of the config file in a terminal on a compute node:
module load 2023
module load MATLAB/2023a-upd4
./STEMMUS_SCOPE/exe/STEMMUS_SCOPE config_file_snellius.txt
Note that you don't need to set LD_LIBRARY_PATH on Snellius. To submit a job to a compute node, see instructions here.
You can run the model using the BMI
interface. The BMI interface is available in the script
STEMMUS_SCOPE_exe.m. For that, you need MATLAB
Runtime
version 2023a. You don't need a license for MATLAB Runtime. Note that the
version of the MATLAB Runtime is tied to the version of MATLAB. The
executable file works on the operating system on which the file is created.
The file STEMMUS_SCOPE under exe directory is an executable file of
STEMMUS_SCOPE that is created using MATLAB version 2023a in a Linux
system.
Make sure LD_LIBRARY_PATH is set correctly, in a terminal:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/MATLAB/MATLAB_Runtime/v2023a/runtime/glnxa64:/usr/local/MATLAB/MATLAB_Runtime/v2023a/bin/glnxa64:/usr/local/MATLAB/MATLAB_Runtime/v2023a/sys/os/glnxa64:/usr/local/MATLAB/MATLAB_Runtime/v2023a/sys/opengl/lib/glnxa64
Change /usr/local/MATLAB/MATLAB_Runtime/v2023a to the path where MATLAB Runtime is installed.
To enter the BMI mode:
Now, BMI asks you to select one of the steps "initialize", "update" or "finalize". To initialize the model using a config file, type:
Change path/to/config_file_template.txt to the actual path of the config file.
Run the model with Octave
If you want to run the model for a small time period or tests purpose, you can use Octave. Allmost all funcationalities of STEMMUS_SCOPE are compatible with Octave, but the execution time is longer than MATLAB. After Octave installation, launch octave and install the following Octave packages:
pkg install "https://downloads.sourceforge.net/project/octave/Octave%20Forge%20Packages/Individual%20Package%20Releases/io-2.6.4.tar.gz"
pkg install "https://downloads.sourceforge.net/project/octave/Octave%20Forge%20Packages/Individual%20Package%20Releases/statistics-1.4.3.tar.gz"
Then, pass config file path to the variable CFG in the main script
STEMMUS_SCOPE.m. Run the model in a terminal:
On a Unix system, use octave instead of octave.bat.
Octave from source
Note that Octave on many Linux distributions might be too old so we need to compile it ourselves. See https://wiki.octave.org/Building. Here are build instructions for Ubuntu 22.04:
sudo apt update
# install minimal deps, see https://wiki.octave.org/Octave_for_Debian_systems#The_right_way for all dependencies
sudo apt install -yq wget build-essential gfortran liblapack-dev libblas-dev libpcre3-dev libreadline-dev libnetcdf-dev
wget https://mirror.serverion.com/gnu/octave/octave-7.2.0.tar.gz # or download from local mirror at https://ftpmirror.gnu.org/octave
tar -zxf octave-7.2.0.tar.gz
cd octave-7.2.0
./configure --prefix=/opt/octave
make -j 6
sudo make install
Add /opt/octave/bin to PATH environment variable.
Launch Octave and install Octave dependencies with:
On CRIB, you can use Octave. Allmost all funcationalities of STEMMUS_SCOPE are compatible with Octave, but the execution time is longer than MATLAB. After Octave installation, launch octave and install the following Octave packages:
pkg install "https://downloads.sourceforge.net/project/octave/Octave%20Forge%20Packages/Individual%20Package%20Releases/io-2.6.4.tar.gz"
pkg install "https://downloads.sourceforge.net/project/octave/Octave%20Forge%20Packages/Individual%20Package%20Releases/statistics-1.4.3.tar.gz"
Then, pass config file path to the variable CFG in the main script
STEMMUS_SCOPE.m. Run the model in a terminal:
Since Octave is very slow, it is not recommended to run the model on Snellius using Octave. Use MATLAB Runtime instead.
Run the model with Docker
If you have Docker installed on your device, you
can run the model using the docker image ecoextreml/stemmus_scope and
BMI interface. The docker image is available
on
EcoExtreML.
You can pull the latest image using the following command:
Then, mount the directories and run the model in a terminal:
docker run -u $(id -u):$(id -g) -v /path_to_input_folder:/path_to_input_folder -v /path_to_output_folder:/path_to_output_folder -it ghcr.io/ecoextreml/stemmus_scope:latest
With -it option, you can enter the docker interactive mode.
Now, BMI asks you to select one of the steps "initialize", "update" or "finalize".
To initialize the model using a config file, type:
Make sure that the input and output directories are mounted correctly
and config_file_template.txt is available in the input directory.
Also, remove the container after running the model:
If Docker is installed on CRIB, follow the same
instructions as for the Local device.
Example workflow of running the model
- Download the latest version of the model.
- Download the example dataset from Zenodo here that includes the configuration file.
- Choose one of the options above to run the model.