diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 0ca2d975..8d12f105 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -7,7 +7,7 @@ read and follow our contributing guidelines.
## Contributing via GitHub
-If you want to work with the `STEMMUS_SCOPE` repository for the first time, or on a new computer,
+If you want to work with the `STEMMUS_SCOPE` repository for the first time, or on a new computer,
you need to configure a few things following steps 1 through 5 below.
@@ -28,7 +28,7 @@ SSH](https://docs.github.com/en/authentication/connecting-to-github-with-ssh)
#### 2.1. Checking for existing SSH keys
-Open a terminal and run the command below:
+Open a terminal and run the command below:
```bash
ls -la ~/.ssh
@@ -70,7 +70,7 @@ Then, run the command below:
ssh-add ~/.ssh/id_ed25519
```
-This asks for your "passphrase" that was provided in the previous step.
+This asks for your "passphrase" that was provided in the previous step.
#### 2.4. Adding a new SSH key to your GitHub account
@@ -124,7 +124,7 @@ Git](https://swcarpentry.github.io/git-novice/02-setup/index.html).
Open a terminal and run the command below:
```bash
-cd
+cd
```
Now you are in your `HOME` directory. Run the command below:
@@ -144,65 +144,191 @@ To know about the most common Git commands, follow the guides
[here](https://hackmd.io/B4v6KwsBRzG-akLDF8e5pg).
-## Development of the MATLAB source of STEMMUS_SCOPE model
+## Adding changes to the model source code
+
+To setup the required software and configurations, see the documentation on
+`Getting started`.
+
+It would be ideal to introduce changes incrementally over time. This way, you
+can track the changes and understand the impact of each change. Here are the
+steps to follow:
+
+- Submit [an issue](https://github.com/EcoExtreML/STEMMUS_SCOPE/issues) to the
+ repository. This issue should describe the problem or the feature you want to
+ introduce.
+- Create a new branch from the `main` branch. This branch should have a
+ descriptive name that relates to the issue you are working on.
+- Make the changes in the new branch, for example, you can add new features, fix
+ bugs, or improve the documentation. Follow [MATLAB Guidelines 2.0, Richard
+ Johnson](http://cnl.sogang.ac.kr/cnlab/lectures/programming/matlab/Richard_Johnson-MatlabStyle2_book.pdf)
+ when introducing new changes to the codes.
+- Commit the changes to the new branch. Write a descriptive commit message that
+ explains the changes you are introducing.
+- Push the changes to the repository.
+- Create a **draft** [pull
+ request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)
+ to the `main` branch. This pull request should reference the issue you are
+ working on.
+- When you are done with the changes, run [the tests](#testing-new-changes) and
+ [MISS_HIT commands](#miss_hit-checks), make sure they pass.
+- Make the pull request ready for review. Ask for a review from the repository
+ maintainers.
+- The maintainers will review the changes and provide feedback. You may need to
+ make additional changes based on the feedback.
+- When the changes are approved, the maintainers will merge the pull request.
+
+## Reviewing a pull request
+
+When you are reviewing a pull request, you should follow the steps below:
-To contribute to the STEMMUS_SCOPE model, you need access to the model source code that is stored in the repository [STEMMUS_SCOPE](https://github.com/EcoExtreML/STEMMUS_SCOPE). You also need a MATLAB license. MATLAB `2021a` is installed on
-[Snellius]((https://servicedesk.surfsara.nl/wiki/display/WIKI/Snellius)) and [CRIB](https://crib.utwente.nl/), see [this instruction](https://pystemmusscope.readthedocs.io/en/latest/contributing_link.html#development-of-stemmus-scope-model).
+- Check the changes introduced in the pull request. Make sure the changes are
+ consistent with the issue description. Also, check for example variable names,
+ function names, documentation, global variables, ..., to see if the changes
+ are consistent with the [MATLAB Style Guidelines
+ 2.0](http://cnl.sogang.ac.kr/cnlab/lectures/programming/matlab/Richard_Johnson-MatlabStyle2_book.pdf).
+- Run [the tests](#testing-new-changes) and [MISS_HIT commands](#miss_hit-checks) to make sure they pass.
+- Provide feedback on the changes. You can ask questions, suggest improvements,
+ or point out issues.
+- When you are satisfied with the changes, approve the pull request. Ask a
+ maintainer to [re-generate the executable
+ file](#creating-an-executable-file-of-stemmus_scope) and merge the pull
+ request.
+- If the changes are related to BMI, you have to ask the maintainer to make a
+ new release of the model. This way a new docker image will be created and the
+ model will be available for the users.
+- If the changes are related to the documentation, make sure that documentation
+ page can be built successfully, see [Building the documentation
+ locally](#building-the-documentation-locally).
+
+## Merging a pull request
+
+When you are merging a pull request, you should follow the steps below:
+
+- Make sure the pull request is approved by at least one reviewer.
+- Make sure all the items in the pull requests list are checked.
+
+## Creating an executable file of STEMMUS_SCOPE
+
+See the disumentation on [executable
+file](https://github.com/EcoExtreML/STEMMUS_SCOPE/tree/main/run_model_on_snellius/exe).
+
+## MISS_HIT Checks
+
+When you submit a pull request, the code is also [checked](https://github.com/EcoExtreML/STEMMUS_SCOPE/actions/workflows/lint.yml) by the [MISS_HIT](misshit.org/) linter and style checker.
+The status of `MISS_HIT` checks is shown below the pull request. The checks should be successful (green) before merging the pull request. To work with `MISS_HIT`, follow the instructions below:
-## Create an executable file of STEMMUS_SCOPE
+- Installing MISS_HIT: To install MISS_HIT, follow their [installation instructions](https://github.com/florianschanda/miss_hit#installation-via-pip).
+
+- Running MISS_HIT: To run the style checker or linter, navigate to the `src/` folder in STEMMUS_SCOPE, and run the following commands:
-See the [exe readme](./exe/README.md).
+ ```bash
+ mh_style
+ mh_lint
+ mh_metric
+ ```
+
+ Follow the errors and information in the output to fix any issues.
-## Follow MATLAB style guidelines
+- Configuring MISS_HIT: `MISS_HIT` is configured in [`miss_hit.cfg`](./miss_hit.cfg). This file contains
+the configuration for the linter and style checker. Please do not change this
+file unless you are familiar with the configuration options.
-When you are introducing new changes to the codes, please follow the style introduced in [MATLAB Guidelines 2.0, Richard Johnson](http://cnl.sogang.ac.kr/cnlab/lectures/programming/matlab/Richard_Johnson-MatlabStyle2_book.pdf).
+## Testing new changes
-When you submit a pull request, the code is also [checked](https://github.com/EcoExtreML/STEMMUS_SCOPE/actions/workflows/lint.yml) by the [MISS_HIT](misshit.org/) linter and style checker.
-The status of `MISS_HIT` checks is shown below the pull request. The checks should be successful (green) before merging the pull request.
-MISS_HIT is configured in [`miss_hit.cfg`](./miss_hit.cfg).
+To test the new changes, we can only check if the new changes do not break the
+model. To do this, follow the steps below:
-### Installing MISS_HIT
-It is best practice to install packages in environments. See the dropdown menu for instructions.
-However, you can also continue below to install MISS_HIT without these steps.
+- Run the notebook `compare_git_branch_results.ipynb` in the `test` folder. This
+ notebook will compare the results of the model between the `main` branch and
+ the new branch with the changes. If the results are similar, the changes do
+ not break the model.
+- [Create the executable file](#creating-an-executable-file-of-stemmus_scope) of
+ the model and run the model with the new changes. Check if the model runs
+ without any errors.
+- [Run the model with Octave](#octave-compatibility) to check if the new changes
+ are compatible with Octave.
+
+## Building the documentation locally
+
+Documentation is created using several markdown files and the [`mkdocs`
+tool](https://www.mkdocs.org/). The markdown files are located in the `docs`
+folder. The configuration file for `mkdocs` is `mkdocs.yml` located in the root
+directory. To build the documentation locally, follow the steps below:
+
+- Install the required dependencies as:
+
+ ```bash
+ cd STEMMUS_SCOPE
+ pip install -r docs/requirements.txt
+ ```
-Python environment / conda instructions
+- Build the documentation as:
-You need to have a valid python installation on your system.
+ ```bash
+ mkdocs build
+ ```
-Create an enviroment with `venv` or conda:
+- Preview the documentation as:
-### **Venv**
-```bash
-python3 -m venv misshit # python on windows.
-```
-Activate this environment
-```bash
-source misshit/bin/activate
-```
+ ```bash
+ mkdocs serve
+ ```
-Or on Windows:
-```pwsh
-./misshit/Scripts/Activate.ps1
-```
+Click on the link provided in the terminal to view the documentation in your
+browser.
-### **conda**
-```bash
-conda env create --name misshit
-conda activate misshit
-```
+## Making a release
-
+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](https://wiki.octave.org/Building). Here are build instructions for Ubuntu 22.04:
+
+```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
+```
+
+Launch Octave and install Octave dependencies with:
+
+```bash
+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"
+```
+
## VS Code setup
Add Octave to path, e.g. for (64-bit) Windows add the following folders:
diff --git a/docs/STEMMUS_SCOPE_on_CRIB.md b/docs/STEMMUS_SCOPE_on_CRIB.md
index b75eb29c..eb3d5c43 100644
--- a/docs/STEMMUS_SCOPE_on_CRIB.md
+++ b/docs/STEMMUS_SCOPE_on_CRIB.md
@@ -2,15 +2,20 @@
[CRIB](https://crib.utwente.nl/) is the ITC Geospatial Computing Platform.
-### Dataflow of STEMMUS_SCOPE on CRIB:
+### Dataflow of STEMMUS_SCOPE on CRIB
-Data required by the model are in a folder named "input" under project directory
-on CRIB. This folder includes:
+To run the STEMMUS-SCOPE model, you need to have input data either from in-situ
+measurements or from remote sensing. Plumber2 site data are avialable under
+project directory on CRIB. This folder includes:
- Plumber2_data: the forcing/driving data provided by PLUMBER2.
- SoilProperty: the soil texture data and soil hydraulic parameters.
-Below the directory explanations are from [SCOPE
+In addition to site data, the remote sensing data are available on CRIB in
+`global_data` folder.
+
+Data required by the model are in a folder named "input". Below the directory
+explanations are from [SCOPE
documentation](https://scope-model.readthedocs.io/en/latest/directories.html):
- directional: the observer’s zenith and azimuth angles.(only used for
@@ -34,44 +39,48 @@ documentation](https://scope-model.readthedocs.io/en/latest/directories.html):
provides parameter inputs for PROSPECT, leaf_biochemical, fluorescence,
soil, canopy, aerodynamic, angles, photosynthetic temperature dependence
functional parameters, etc.
-- input_soilLayThick.csv (optional): A file to change the discretization of
- the soil layers of the STEMMUS model. An example of this file is in
- [example_data folder](../example_data). This file (if needed) should be copied into the
+- input_soilLayThick.csv (optional): A file to change the discretization of the
+ soil layers of the STEMMUS model. An example of this file is in [example_data
+ folder](https://github.com/EcoExtreML/STEMMUS_SCOPE/tree/main/example_data).
+ This file (if needed) should be copied into the
`InputPath` folder. If this file is used, it will override the default settings of
the soil layers. The file has three columns: 1) layer number, 2) layer thickness,
and 3) maximum root depth. The user is free to change the values of the three columns.
Also, the number of rows determines the number of the soil layers and the total
thickness of the soil column (sum of soil layer thickness).
-### Configuration file:
+### Configuration file
-Config file: it is a text file that sets the paths **required** by the
- model. For example, see [config_file_crib.txt](../config_file_crib.txt) in this
- repository. This file includes:
+Config file: it is a text file that sets the paths **required** by the model.
+For example, see
+[config_file_crib.txt](https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/main/config_file_crib.txt)
+or
+[config_file_crib_global.txt](https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/main/config_file_crib_global.txt)
+in this repository. This file includes:
- - SoilPropertyPath: a path to soil texture data and soil hydraulic
- parameters.
- - InputPath: this is the working/running directory of the model and should
- include the data of `directional`, `fluspect_parameters`, `leafangles`,
- `radiationdata`, `soil_spectra`, and `input_data.xlsx`.
- - OutputPath: this is the base path to store outputs of the model. When the
- model runs, it creates `sitename_timestamped` directories under this
- path.
- - ForcingPath: a path to the forcing/driving data. I.e. the Plumber2 dataset.
- - Location: Location where the model should be run. Currently,
- the model runs at the site scale. For example, if we put `FI-Hyy` here, the model
- runs at the `FI-Hyy` site.
- - StartTime: The start time of the model, in the ISO 8601 format. For example:
- `2001-01-01T00:00`. Note that the time can only be defined in half hour increments.
- If you want the start time to be the first available data point of the forcing data,
- you can set StartTime to `NA`.
- - EndTime: The end time of the model. Formatted the same way as the StartTime.
- For example: `2001-12-31T23:30`. If you want the end time to be the last available
- data point of the forcing data, you can set EndTime to `NA`.
+- SoilPropertyPath: a path to soil texture data and soil hydraulic
+ parameters.
+- InputPath: this is the working/running directory of the model and should
+ include the data of `directional`, `fluspect_parameters`, `leafangles`,
+ `radiationdata`, `soil_spectra`, and `input_data.xlsx`.
+- OutputPath: this is the base path to store outputs of the model. When the
+model runs, it creates `sitename_timestamped` directories under this
+path.
+- ForcingPath: a path to the forcing/driving data. I.e. the Plumber2 dataset.
+- Location: Location where the model should be run. Currently,
+the model runs at the site scale. For example, if we put `FI-Hyy` here, the model
+runs at the `FI-Hyy` site.
+- StartTime: The start time of the model, in the ISO 8601 format. For example:
+`2001-01-01T00:00`. Note that the time can only be defined in half hour increments.
+If you want the start time to be the first available data point of the forcing data,
+you can set StartTime to `NA`.
+- EndTime: The end time of the model. Formatted the same way as the StartTime.
+For example: `2001-12-31T23:30`. If you want the end time to be the last available
+data point of the forcing data, you can set EndTime to `NA`.
- To edit the config file, open the file with a text editor and change the
- paths. The variable names e.g. `SoilPropertyPath` should not be changed.
- Also, note a `/` is required at the end of each line.
+To edit the config file, open the file with a text editor and change the
+paths. The variable names e.g. `SoilPropertyPath` should not be changed.
+Also, note a `/` is required at the end of each line.
As explained above, the "InputPath" directory of the model is considered as
the working/running directory and should include some data required by the
diff --git a/docs/STEMMUS_SCOPE_on_Snellius.md b/docs/STEMMUS_SCOPE_on_Snellius.md
index 5d245d34..295e3074 100644
--- a/docs/STEMMUS_SCOPE_on_Snellius.md
+++ b/docs/STEMMUS_SCOPE_on_Snellius.md
@@ -3,10 +3,12 @@
[Snellius](https://servicedesk.surfsara.nl/wiki/display/WIKI/Snellius) is the
Dutch National supercomputer hosted at SURF.
-### Dataflow of STEMMUS_SCOPE on Snellius:
+### Dataflow of STEMMUS_SCOPE on Snellius
-Data required by the model are in a folder named "data" in the project
- directory `einf2480` on Snellius. This directory includes:
+To run the STEMMUS-SCOPE model, you need to have input data either from in-situ
+measurements or from remote sensing. Data required by the model are in a folder
+named "data" in the project directory `einf2480` on Snellius. This directory
+includes:
- forcing/plumber2_data: the forcing/driving data provided by PLUMBER2.
- model_parameters/soil_property: the soil texture data and soil hydraulic parameters.
@@ -19,40 +21,43 @@ Data required by the model are in a folder named "data" in the project
- input_data.xlsx
- input_soilThick.csv (optional)
-For the explanation of the directories see
-[Dataflow of STEMMUS_SCOPE on CRIB](./STEMMUS_SCOPE_on_CRIB.md#dataflow-of-stemmus_scope-on-crib).
+In addition to site data, the remote sensing data are available on Snellius in
+`global_data` folder.
-### Configuration file:
+### Configuration file
Config file: it is a text file that sets the paths **required** by the model.
- For example, see [config_file_snellius.txt](../config_file_snellius.txt) in
- this repository. This file includes:
+For example, see
+[config_file_snellius.txt](https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/main/run_model_on_snellius/config_file_snellius.txt)
+or
+[config_file_snellius_global.txt](https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/main/run_model_on_snellius/config_file_snellius_global.txt)
+in this repository. This file includes:
- - SoilPropertyPath: a path to soil texture data and soil hydraulic
- parameters.
- - InputPath: this is the working/running directory of the model and should
- include the data of `directional`, `fluspect_parameters`, `leafangles`,
- `radiationdata`, `soil_spectra`, and `input_data.xlsx`.
- - OutputPath: this is the base path to store outputs of the model. When the
- model runs, it creates `sitename_timestamped` directories under this
- path.
- - ForcingPath: a path to the forcing/driving data. I.e. the Plumber2 dataset.
- - Location: Location where the model should be run. Currently,
- the model runs at the site scale. For example, if we put `FI-Hyy` here, the model
- runs at the `FI-Hyy` site.
- - StartTime: The start time of the model, in the ISO 8601 format. For example:
- `2001-01-01T00:00`. Note that the time can only be defined in half hour increments.
- If you want the start time to be the first available data point of the forcing data,
- you can set StartTime to `NA`.
- - EndTime: The end time of the model. Formatted the same way as the StartTime.
- For example: `2001-12-31T23:30`. If you want the end time to be the last available
- data point of the forcing data, you can set EndTime to `NA`.
+- SoilPropertyPath: a path to soil texture data and soil hydraulic
+ parameters.
+- InputPath: this is the working/running directory of the model and should
+ include the data of `directional`, `fluspect_parameters`, `leafangles`,
+ `radiationdata`, `soil_spectra`, and `input_data.xlsx`.
+- OutputPath: this is the base path to store outputs of the model. When the
+model runs, it creates `sitename_timestamped` directories under this
+path.
+- ForcingPath: a path to the forcing/driving data. I.e. the Plumber2 dataset.
+- Location: Location where the model should be run. Currently,
+the model runs at the site scale. For example, if we put `FI-Hyy` here, the model
+runs at the `FI-Hyy` site.
+- StartTime: The start time of the model, in the ISO 8601 format. For example:
+`2001-01-01T00:00`. Note that the time can only be defined in half hour increments.
+If you want the start time to be the first available data point of the forcing data,
+you can set StartTime to `NA`.
+- EndTime: The end time of the model. Formatted the same way as the StartTime.
+For example: `2001-12-31T23:30`. If you want the end time to be the last available
+data point of the forcing data, you can set EndTime to `NA`.
- To edit the config file, open the file with a text editor and change the
- paths. The `InputPath` and `OutputPath` are user-defined directories, make
- sure they exist and you have right permissions. The variable name e.g.
- `SoilPropertyPath` should not be changed. Also, note a `/` is required at
- the end of each line.
+To edit the config file, open the file with a text editor and change the
+paths. The `InputPath` and `OutputPath` are user-defined directories, make
+sure they exist and you have right permissions. The variable name e.g.
+`SoilPropertyPath` should not be changed. Also, note a `/` is required at
+the end of each line.
As explained above, the "InputPath" directory of the model is considered as
the working/running directory and should include some data required by the
diff --git a/docs/contributing_guide.md b/docs/contributing_guide.md
index a6b802c4..7b734730 100644
--- a/docs/contributing_guide.md
+++ b/docs/contributing_guide.md
@@ -1 +1,7 @@
+#
+
+> NOTE: The instructions below are meant for users who want to add changes to
+the model source code. If you want to run the model, see the documentation on
+`Running the model`.
+
{% include-markdown "../CONTRIBUTING.md" start="# Contributing guidelines" heading-offset=2%}
\ No newline at end of file
diff --git a/docs/getting_started.md b/docs/getting_started.md
index 1f614a5c..ac14bd09 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -1,6 +1,6 @@
-# Requiremnets:
+# Requiremnets
-## Infrastructure (computig resources)
+## Computig resource
To run the STEMMUS-SCOPE model, you can use one of the following computing resources:
@@ -22,40 +22,37 @@ To run the STEMMUS-SCOPE model, you need **one** of the following:
## Model source code
-Download the [latest version of the
+The source code of STEMMUS_SCOPE can be found in the GitHub repository
+[https://github.com/EcoExtreML/STEMMUS_SCOPE](https://github.com/EcoExtreML/STEMMUS_SCOPE)
+under the folder `src`. 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:
+or get it using `git clone` in a terminal:
- ` git clone https://github.com/EcoExtreML/STEMMUS_SCOPE.git `
+` 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 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).
+[setup()](https://pystemmusscope.readthedocs.io/en/latest/reference/#PyStemmusScope.stemmus_scope.StemmusScope.setup) function
+in the python package [PyStemmusScope](https://pystemmusscope.readthedocs.io/en/latest/). See example datasets below:
-### Example dataset on Zenodo
+=== "Example dataset on Zenodo"
+ A pre-processed example dataset for one site can be found on Zenodo
+ [here](https://zenodo.org/records/10566827).
-A pre-processed example dataset for one site can be found on Zenodo
-[here](https://zenodo.org/records/10566827).
+=== "Data on CRIB"
+ [CRIB](https://crib.utwente.nl/) is the ITC Geospatial Computing Platform.
-### Data on CRIB
+ {% include-markdown "./STEMMUS_SCOPE_on_CRIB.md" start="### Dataflow of STEMMUS_SCOPE on CRIB" end="### Configuration file" heading-offset=2%}
-[CRIB](https://crib.utwente.nl/) is the ITC Geospatial Computing Platform.
+=== "Data on Snellius"
+ [Snellius](https://servicedesk.surfsara.nl/wiki/display/WIKI/Snellius) is the
+ Dutch National supercomputer hosted at SURF.
-{% include-markdown "./STEMMUS_SCOPE_on_CRIB.md" start="### Dataflow of STEMMUS_SCOPE on CRIB:" end="### Configuration file:" heading-offset=2%}
-
-### Data on Snellius
-
-[Snellius](https://servicedesk.surfsara.nl/wiki/display/WIKI/Snellius) is the
-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%}
+ {% include-markdown "./STEMMUS_SCOPE_on_Snellius.md" start="### Dataflow of STEMMUS_SCOPE on Snellius" end="### Configuration file" heading-offset=2%}
## Configuration file
@@ -80,21 +77,20 @@ 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
+See example configuration files below:
-{% include-markdown "./STEMMUS_SCOPE_on_CRIB.md" start="### Configuration file:" end="### Workflow of STEMMUS_SCOPE on CRIB:" 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). If
+ [setup()](https://pystemmusscope.readthedocs.io/en/latest/reference/#PyStemmusScope.stemmus_scope.StemmusScope.setup)
+ function in the python package
+ [PyStemmusScope](https://pystemmusscope.readthedocs.io/en/latest/) 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 Snellius
+=== "Example configuration file on CRIB"
+ {% include-markdown "./STEMMUS_SCOPE_on_CRIB.md" start="### Configuration file" heading-offset=2%}
-{% include-markdown "./STEMMUS_SCOPE_on_Snellius.md" start="### Configuration file:" end="### Workflow of STEMMUS_SCOPE on Snellius:" heading-offset=2%}
+=== "Example configuration file on Snellius"
+ {% include-markdown "./STEMMUS_SCOPE_on_Snellius.md" start="### Configuration file" heading-offset=2%}
diff --git a/docs/run_model.md b/docs/run_model.md
index a6c074aa..05ab07e5 100644
--- a/docs/run_model.md
+++ b/docs/run_model.md
@@ -1,11 +1,12 @@
#
-> NOTE: The instructions below is meant for users who want to run the model. If
-you want to develop the model, see the documentation on `Contributing guide`.
+> 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
-1. The model reads the forcing file associated with the specified location,
+1. The model reads the forcing file associated with the specified site/location,
e.g., `FI-Hyy_1996-2014_FLUXNET2015_Met.nc` from "ForcingPath" and extracts
forcing variables in `.dat` format. The `.dat` files are stored in the
`InputPath` directory. In addition, the model reads the site information i.e.
@@ -16,6 +17,7 @@ you want to develop the model, see the documentation on `Contributing guide`.
converted to `.csv` files and stored in a `sitename_timestamped` output
directory under `OutputPath`.
+
## Run the model with MATLAB
=== "Local device"
@@ -98,7 +100,7 @@ you want to develop the model, see the documentation on `Contributing guide`.
Note that you don't need to set `LD_LIBRARY_PATH` on Snellius. To submit a job to a compute node, see instructions [here](https://servicedesk.surf.nl/wiki/display/WIKI/Example+job+scripts).
-=== BMI interface
+=== "BMI interface"
You can run the model using the [BMI](https://bmi.readthedocs.io/en/stable/)
interface. The BMI interface is available in the script
`STEMMUS_SCOPE_exe.m`. For that, you need [MATLAB
@@ -136,57 +138,7 @@ you want to develop the model, see the documentation on `Contributing guide`.
## Run the model with Octave
=== "Local device"
- If you want to run the model for a small time period or tests purpose, you
- can use [Octave](https://octave.org/). 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:
-
- ```bash
- 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:
-
- ```bash
- cd src/
- octave.bat --no-gui --interactive --silent --eval "STEMMUS_SCOPE"
- ```
-
- 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](https://wiki.octave.org/Building). Here are build instructions for Ubuntu 22.04:
-
- ```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
- ```
-
- Launch Octave and install Octave dependencies with:
-
- ```bash
- 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"
- ```
-
+ {% include-markdown "./Octave_instructions.md" start="# Running STEMMUS-SCOPE in Octave" end="## VS Code setup" heading-offset=2%}
=== "CRIB"
On CRIB, you can use [Octave](https://octave.org/). Allmost all
@@ -256,3 +208,12 @@ you want to develop the model, see the documentation on `Contributing guide`.
[Apptainer](https://apptainer.org/docs/user/main/introduction.html), see
instructions
[here](https://servicedesk.surf.nl/wiki/pages/viewpage.action?pageId=30660251).
+
+## Example workflow of running the model
+
+1. Download the [latest version of the
+ model](https://github.com/EcoExtreML/STEMMUS_SCOPE/releases).
+2. Download the example dataset from Zenodo
+ [here](https://zenodo.org/records/10566827) that includes the configuration
+ file.
+3. Choose one of the options above to run the model.
diff --git a/run_model_on_snellius/README.md b/run_model_on_snellius/README.md
index 92cc0bd6..bd12273b 100644
--- a/run_model_on_snellius/README.md
+++ b/run_model_on_snellius/README.md
@@ -7,3 +7,25 @@ This folder contains files that are needed for running `STEMMUS_SCOPE` on Snelli
- `config_file_snellius.txt` is the model config file
Before submitting the job via `sbatch run_stemmus_scope_snellius.sh`, make sure that conda environment `pystemmusscope` is created, see the [environment file](https://github.com/EcoExtreML/STEMMUS_SCOPE_Processing/blob/main/environment.yml). Also, set the `WorkDir` and `NumberOfTimeSteps` in the model config file e.g. `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`.