Skip to content

Commit

Permalink
add documentation for Running the model, polish existing documentatio…
Browse files Browse the repository at this point in the history 
…n, add docker instructions
  • Loading branch information
@SarahAlidoost
SarahAlidoost committed Oct 7, 2024
1 parent be6a72e commit 6bde871
Show file tree
Hide file tree
Showing 6 changed files with 330 additions and 213 deletions.
55 changes: 3 additions & 52 deletions docs/Octave_instructions.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -10,17 +10,6 @@
- [Mount extra directory](#mount-extra-directory)
- [Linux from source](#linux-from-source)

The downloads can be found here
https://octave.org/download

TODO: installation of octave on linux
After installation, launch octave and install the following Octave package:
`pkg install -forge statistics`

For off-line installation, first, download the package [io](https://octave.sourceforge.io/io/index.html) and [statistics](https://octave.sourceforge.io/statistics/index.html). Then, launch octave and run:

`pkg install io-2.6.4.tar.gz`
`pkg install statistics-1.4.3.tar.gz`

## VS Code setup
Add Octave to path, e.g. for (64-bit) Windows add the following folders:
Expand All @@ -35,23 +24,18 @@ The debugger configurations are included in `/.vscode/launch.json`
`Octave Hacking` by Andrew Janke https://marketplace.visualstudio.com/items?itemName=apjanke.octave-hacking
This adds syntax highlighting and formatting.

## Running STEMMUS-SCOPE in Octave
It is possible to run STEMMUS-SCOPE from the command line with the following setup:
`octave.bat --no-gui --interactive --silent --eval "STEMMUS_SCOPE_exe('path_to_config_file')"`

On a Unix system, use `octave` instead of `octave.bat`.
## Developing STEMMUS-SCOPE in Octave
Open the `run_Octave.m` file, either in VS Code or the Octave GUI.
Open the `debug_Octave.m` file, either in VS Code or the Octave GUI.

### Octave GUI
Set the workspace to the `STEMMUS_SCOPE/src` folder, and open the `run_Octave.m` file.
Set the workspace to the `STEMMUS_SCOPE/src` folder, and open the `debug_Octave.m` file.
Here you can set the config file that should be used, and then run the file.

### VS Code
While having the `STEMMUS_SCOPE` folder as the workspace, open the debugger and select `Octave: Debug STEMMUS-SCOPE`.
Start the debugger to run (and debug) the model.

In the `run_Octave.m` file you can set the config file that should be used.
In the `debug_Octave.m` file you can set the config file that should be used.

## VS Code + Dev container

Expand All @@ -78,36 +62,3 @@ After editing file you can restart the editor to get the extra directory inside
See [dev container docs](https://code.visualstudio.com/remote/advancedcontainers/add-local-file-mount) for more info.

To mount Windows directory inside the dev container you have to start the container in WSL2 (aka run Docker service inside WSL2) and use unix paths like `/mnt/c/...`.

## Linux from source

Octave on many Linux distributions is too old so we need to compile it ourselves.
See [https://wiki.octave.org/Building](https://wiki.octave.org/Building).

<details>
<summary>Here are build instructions for Ubuntu 22.04</summary>

```shell
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.

```shell
export PATH=$PATH:/opt/octave/bin
```

Install Octave dependencies with

```shell
octave --eval 'pkg install -forge statistics'
```
</details>
50 changes: 0 additions & 50 deletions docs/STEMMUS_SCOPE_on_CRIB.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -82,53 +82,3 @@ different working/running directory and set the "InputPath" to it. Then,
you should copy the required data i.e. `directional`, `fluspect_parameters`,
`leafangles`, `radiationdata`, `soil_spectra`, and `input_data.xlsx` to the
working/running directory.

### Workflow of STEMMUS_SCOPE on CRIB:

1. The model reads the forcing file associated with the specified location,
e.g., `FI-Hyy_1996-2014_FLUXNET2015_Met.nc` from "ForcingPath" and
extracts forcing variables in `.dat` format using `filesread.m`.
The `.dat` files are stored in the "InputPath" directory. In
addition, the model reads the site information i.e. the location and
vegetation parameters.
2. The model runs step by step until the whole simulation period is completed
i.e till the last time step of the forcing data.
3. The results are saved as binary files temporarily. Then, the binary files are
converted to `.csv` files and stored in a `sitename_timestamped` output
directory under "OutputPath".

### How to run STEMMUS_SCOPE on CRIB:

1. Log in CRIB with your username and password and select a proper compute unit.
2. Download the source code from this repository or get it using `git clone` in
a terminal:

` git clone https://github.com/EcoExtreML/STEMMUS_SCOPE.git `

All the codes can be found in the folder `src` whereas the executable file in
the folder `exe`.

3. Check `config_file_crib.txt` and change the paths if needed, specifically
"InputPath" and "OutputPath".
4. Follow the instructions below:

#### Run using MATLAB that requires a license

If you want to use MATLAB desktop,

1. click on the `Remote Desktop` in the
Launcher. Click on the `Applications`. You will find the 'MATLAB' software under
the `Research`.
2. After clicking on 'MATLAB', it asks for your account information that is
connected to a MATLAB license.
3. Open the file `filesread.m` and set the
variable `CFG` to the path of the config file e.g. `CFG =
'/data/shared/EcoExtreML/STEMMUS_SCOPEv1.0.0/STEMMUS_SCOPE/config_file_crib.txt';`.
4. Then, run the main script `STEMMUS_SCOPE.m`.

As an alternative, you can run the
main script using MATLAB command line in a terminal:

```bash
matlab -nodisplay -nosplash -nodesktop -r "run('STEMMUS_SCOPE.m');exit;"
```
88 changes: 0 additions & 88 deletions docs/STEMMUS_SCOPE_on_Snellius.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,91 +66,3 @@ input_data.xlsx` to the working/running directory. For example:
` cp -r
/projects/0/einf2480/model_parameters/vegetation_property/*
/scratch-shared/EcoExtreML/STEMMUS_SCOPE/input/<your_work_dir> `

### Workflow of STEMMUS_SCOPE on Snellius:

This is the same as the workflow of STEMMUS_SCOPE on crib, see section
[Workflow of STEMMUS_SCOPE on CRIB](./STEMMUS_SCOPE_on_CRIB.md#workflow-of-stemmus_scope-on-crib).

### How to run STEMMUS_SCOPE on Snellius:

1. Log in to Snellius.
2. Download the source code from this repository or get it using `git clone` in
a terminal:

` git clone https://github.com/EcoExtreML/STEMMUS_SCOPE.git `

All the codes can be found in the folder `src` whereas the executable file in
the folder `exe`.

3. Check `config_file_snellius.txt` and change the paths if needed,
specifically "InputPath" and "OutputPath".
4. Follow one of the instructions below:

#### Run using MATLAB that requires a license

In order to use MATLAB, you need to send a request to add you to the user pool
on Snellius. Then, open the file
[config_file_snellius.txt](../config_file_snellius.txt) and set the paths. Then,
run the main script `STEMMUS_SCOPE_exe.m` using MATLAB command line in a terminal on
a **compute node**:

```bash
module load 2021
module load MATLAB/2021a-upd3
matlab -nodisplay -nosplash -nodesktop -r "STEMMUS_SCOPE_exe('config_file_snellius.txt');exit;"
```

> To run the codes above on a compute node, you can create a bash script as:
```bash
#!/bin/bash
# SLURM settings
#SBATCH -J stemmus_scope
#SBATCH -t 01:00:00
#SBATCH -N 1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=32
#SBATCH -p thin
#SBATCH --output=./slurm_%j.out
#SBATCH --error=./slurm_%j.out

module load 2021
module load MATLAB/2021a-upd3
matlab -nodisplay -nosplash -nodesktop -r "STEMMUS_SCOPE_exe('config_file_snellius.txt');exit;"
```

#### Run using MATLAB Compiler that does not require a license

If you want to run the model as a standalone application, you need MATLAB
Runtime version `2023a`. This is available on Snellius. You can run the
model by passing the path of the config file in a terminal on a **compute
node**:

```bash
module load 2021
module load MCR/R2021a.3
./STEMMUS_SCOPE/exe/STEMMUS_SCOPE config_file_snellius.txt
```

The bash script `run_stemmus_scope_snellius.sh` in this repository, runs the
model at 170 sites (default) on a **compute node**. The scripts loops over
forcing files in the "ForcingPath", creates `sitename_timestamped` working
directories under "InputPath" directory and copies required data to those
working dirs. To change the number of sites, open the script and on the last
line change the parameter `{1..170}`. For example `env_parallel -n1 -j32
--joblog $log_file loop_func ::: {1..170}` will run the model at 32 sites
simultaneously. For testing purposes, the time of the bash script is set to
`00:10:00`. Note that the model run can take long for some of the sites. As the
maxium time wall is 5 days on a partition thin, time can be set to`5-00:00:00`
for a complete run of the model.

You can run the script in a terminal:

```shell
cd STEMMUS_SCOPE
mkdir -p slurm
sbatch run_stemmus_scope_snellius.sh
```

This creates a log file per each forcing file in the folder `slurm`.
91 changes: 69 additions & 22 deletions docs/getting_started.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,48 @@
# Requiremnets:

## Infrastructure (computig resources)

To run the STEMMUS-SCOPE model, you can use one of the following computing resources:

- [CRIB](https://crib.utwente.nl/) is the ITC Geospatial Computing Platform.
- [Snellius](https://servicedesk.surfsara.nl/wiki/display/WIKI/Snellius) is the
Dutch National supercomputer hosted at SURF.

Otherwise, you can run the model on your local device if you have the correct
set of software and data.

## Software

To run the STEMMUS-SCOPE model, you need **one** of the following:

- [MATLAB](https://nl.mathworks.com/products/matlab.html)
- [MATLAB Runtime](https://nl.mathworks.com/products/compiler/matlab-runtime.html) on a Unix-like system
- [Octave](https://octave.org/)
- [Docker](https://www.docker.com/)

## Model source code

Download the [latest version of the
model](https://github.com/EcoExtreML/STEMMUS_SCOPE/releases) from the repository
https://github.com/EcoExtreML/STEMMUS_SCOPE or get it using `git clone` in a
terminal:

` git clone https://github.com/EcoExtreML/STEMMUS_SCOPE.git `

All the codes can be found in the folder `src`.

## Data

To run the STEMMUS-SCOPE model, you need to have input data either from in-situ
measurements or from remote sensing. Before running the model, you need to
prepare input data and a configuration file. This can be done using the python
package [PyStemmusScope](https://pystemmusscope.readthedocs.io).
prepare input data and a configuration file for **one site/location**. This can be done using
[setup()](https://pystemmusscope.readthedocs.io/en/v0.2.0/reference/#PyStemmusScope.stemmus_scope.StemmusScope.setup) function
in the python package [PyStemmusScope](https://pystemmusscope.readthedocs.io).

### Example dataset on Zenodo

A pre-processed example dataset for one site can be found on Zenodo
[here](https://zenodo.org/records/10566827).

### Data on CRIB

Expand All @@ -20,16 +57,39 @@ Dutch National supercomputer hosted at SURF.

{% include-markdown "./STEMMUS_SCOPE_on_Snellius.md" start="### Dataflow of STEMMUS_SCOPE on Snellius:" end="### Configuration file:" heading-offset=2%}

### Example dataset on Zenodo

A pre-processed example dataset can be found on Zenodo
[here](https://zenodo.org/records/10566827).

## Configuration file

The configuration file is a text file that sets the paths required by the model.
For example, see
[config_file_template.txt](https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/main/config_file_template.txt).
The configuration file should contain the following information:

```text
WorkDir=/path_to_working_directory/
SoilPropertyPath=/path_to_soil_property_data/
ForcingPath=/path_to_forcing_data/
Location=AU-DaS
directional=/path_to_directional_data/
fluspect_parameters=/path_to_fluspect_parameters_data/
leafangles=/path_to_leafangles_data/
radiationdata=/path_to_radiation_data/
soil_spectrum=/path_to_soil_spectra_data/
InitialConditionPath=/path_to_soil_initial_condition_data/
input_data=/path_to_input_data.xlsx_file/
StartTime=2001-01-01T00:00
EndTime=2001-01-02T00:00
InputPath=/path_to_model_input_folder/
OutputPath=/path_to_model_output_folder/
```

### Example configuration file

An example configuration file can be found [here](https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/main/config_file_template.txt).

> NOTE: If
[setup()](https://pystemmusscope.readthedocs.io/en/v0.2.0/reference/#PyStemmusScope.stemmus_scope.StemmusScope.setup)
function in the python package
[PyStemmusScope](https://pystemmusscope.readthedocs.io) is used to prepare data,
the model configuration file including `InputPath` and `OutputPath` and the data
of **one site/location** will be generated automatically.

### Configuration file on CRIB

Expand All @@ -38,16 +98,3 @@ For example, see
### Configuration file on Snellius

{% include-markdown "./STEMMUS_SCOPE_on_Snellius.md" start="### Configuration file:" end="### Workflow of STEMMUS_SCOPE on Snellius:" heading-offset=2%}

### Example configuration file

An example configuration file can be found [here]((https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/main/config_file_template.txt)).

## Software

To run the STEMMUS-SCOPE model, you need **one** of the following:

- [MATLAB](https://nl.mathworks.com/products/matlab.html)
- [MATLAB Runtime](https://nl.mathworks.com/products/compiler/matlab-runtime.html) on a Unix-like system
- [Octave](https://octave.org/)
- [Docker](https://www.docker.com/)
Loading

0 comments on commit 6bde871

Please sign in to comment.