Skip to content

Commit

Permalink
polish documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@SarahAlidoost
SarahAlidoost committed Oct 1, 2024
1 parent 6e4d831 commit 38eb832
Show file tree
Hide file tree
Showing 6 changed files with 180 additions and 148 deletions.
33 changes: 5 additions & 28 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,44 +3,21 @@
Integrated code of SCOPE and STEMMUS.

SCOPE is a radiative transfer and energy balance model, and STEMMUS model is a two-phase mass and heat transfer model. For more information about the coupling between these two models, please check [this reference](https://gmd.copernicus.org/articles/14/1379/2021/). 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).
[PyStemmusScope](https://pystemmusscope.readthedocs.io).

![img](https://raw.githubusercontent.com/EcoExtreML/STEMMUS_SCOPE/main/docs/assets/imgs/coupling_scheme.png)
(by Zeng & Su, 2021)

## Running STEMMUS_SCOPE

```mermaid
flowchart LR
subgraph Platform
direction RL
b[Snellius]
c[CRIB]
d[Your own machine]
end
A(Data)
Platform --> A
B(Config file)
A --> B
C{{Run model}}
B --> C
click b "https://github.com/EcoExtreML/STEMMUS_SCOPE/tree/main/docs/STEMMUS_SCOPE_on_Snellius.md" "Run STEMMUS_SCOPE on Snellius" _blank
click c "https://github.com/EcoExtreML/STEMMUS_SCOPE/tree/main/docs/STEMMUS_SCOPE_on_CRIB.md" "Run STEMMUS_SCOPE on CRIB" _blank
click d "https://github.com/EcoExtreML/STEMMUS_SCOPE/tree/main/docs/STEMMUS_SCOPE_on_local_device.md" "Run STEMMUS_SCOPE on your own machine" _blank
```
About how to run `STEMMUS_SCOPE` on Snellius, check [./docs/STEMMUS_SCOPE_on_Snellius.md](https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/main/docs/STEMMUS_SCOPE_on_Snellius.md).

If you want to run `STEMMUS_SCOPE` on CRIB, check [./docs/STEMMUS_SCOPE_on_CRIB.md](https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/main/docs/STEMMUS_SCOPE_on_CRIB.md).

If you want to run `STEMMUS_SCOPE` on your own machine, check [./docs/STEMMUS_SCOPE_on_local_device.md](https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/main/docs/STEMMUS_SCOPE_on_local_device.md).

`STEMMUS_SCOPE` scope also has a Basic Model Interface (BMI) mode implemented. The full BMI is implemented in Python in [PyStemmusScope](https://github.com/EcoExtreML/STEMMUS_SCOPE_Processing/). For more information, check [./docs/STEMMUS_SCOPE_BMI.md](https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/main/docs/STEMMUS_SCOPE_BMI.md).
## Documentation

The documentation of the STEMMUS_SCOPE model can be found [here](https://ecoextreml.github.io/STEMMUS_SCOPE/).

## Contributing

If you want to contribute to the development of `STEMMUS_SCOPE`,
have a look at the [contribution guidelines](https://github.com/EcoExtreML/STEMMUS_SCOPE/blob/main/CONTRIBUTING.md).

## How to cite us

[![RSD](https://img.shields.io/badge/rsd-ecoextreml-00a3e3.svg)](https://research-software-directory.org/projects/ecoextreml)
<!-- [![DOI](https://zenodo.org/badge/DOI/<replace-with-created-DOI>.svg)](https://doi.org/<replace-with-created-DOI>) -->
141 changes: 70 additions & 71 deletions docs/STEMMUS_SCOPE_on_CRIB.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,72 +4,74 @@

### Dataflow of STEMMUS_SCOPE on CRIB:

1. Data required by the model are in a folder named "input" 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
documentation](https://scope-model.readthedocs.io/en/latest/directories.html):

- directional: the observer’s zenith and azimuth angles.(only used for
multi-angle simulations (if the option ‘directional’ is switched on in
parameters).
- fluspect_parameters: absorption spectra of different leaf components are
provided, according to PROSPECT 3.1, as well as Fluspect input: standard
spectra for PSI and PSII.
- leafangles: example leaf inclination distribution data are provided.
- radiationdata: RTMo.m calculates spectra based on MODTRAN5 outputs (T-18
system).Note that in the input data (files as well as the spreadsheet),
the broadband input radiation may be provided. SCOPE linearly scales the
input spectra of the optical and the thermal domain in such a way that
the spectrally integrated input shortwave and long-wave radiation matches
with the measured values.
- soil_spectra: the soil spectrum is provided. Note that it is also possible
to simulate a soil reflectance spectrum with the BSM model. In that case,
the values for the BSM model parameters are taken from the input data, and
the archived spectra in this folder are not used.
- input_data.xlsx: the input to SCOPE model is provided. It
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
`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).

2. 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:

- 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.
Data required by the model are in a folder named "input" 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
documentation](https://scope-model.readthedocs.io/en/latest/directories.html):

- directional: the observer’s zenith and azimuth angles.(only used for
multi-angle simulations (if the option ‘directional’ is switched on in
parameters).
- fluspect_parameters: absorption spectra of different leaf components are
provided, according to PROSPECT 3.1, as well as Fluspect input: standard
spectra for PSI and PSII.
- leafangles: example leaf inclination distribution data are provided.
- radiationdata: RTMo.m calculates spectra based on MODTRAN5 outputs (T-18
system).Note that in the input data (files as well as the spreadsheet),
the broadband input radiation may be provided. SCOPE linearly scales the
input spectra of the optical and the thermal domain in such a way that
the spectrally integrated input shortwave and long-wave radiation matches
with the measured values.
- soil_spectra: the soil spectrum is provided. Note that it is also possible
to simulate a soil reflectance spectrum with the BSM model. In that case,
the values for the BSM model parameters are taken from the input data, and
the archived spectra in this folder are not used.
- input_data.xlsx: the input to SCOPE model is provided. It
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
`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:

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:

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

As explained above, the "InputPath" directory of the model is considered as
the working/running directory and should include some data required by the
Expand All @@ -89,12 +91,9 @@ working/running directory.
The `.dat` files are stored in the "InputPath" directory. In
addition, the model reads the site information i.e. the location and
vegetation parameters.
1. The model reads the soil parameters from "SoilPropertyPath" using
`soilpropertyread.m`.
2. Some constants are loaded using `Constant.m`.
3. The model runs step by step until the whole simulation period is completed
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.
4. The results are saved as binary files temporarily. Then, the binary files are
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".

Expand Down
94 changes: 48 additions & 46 deletions docs/STEMMUS_SCOPE_on_Snellius.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,52 +5,54 @@ Dutch National supercomputer hosted at SURF.

### Dataflow of STEMMUS_SCOPE on Snellius:

1. 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.
- model_parameters/vegetation_property:
- directional
- fluspect_parameters
- leafangles
- radiationdata
- soil_spectra
- 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).

2. 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:

- 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.
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.
- model_parameters/vegetation_property:
- directional
- fluspect_parameters
- leafangles
- radiationdata
- soil_spectra
- 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).

### 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:

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

As explained above, the "InputPath" directory of the model is considered as
the working/running directory and should include some data required by the
Expand Down
54 changes: 53 additions & 1 deletion docs/getting_started.md
View file
Original file line number Diff line number Diff line change
@@ -1 +1,53 @@
# Installation requirements
# Requiremnets:

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

### Data on CRIB

[CRIB](https://crib.utwente.nl/) is the ITC Geospatial Computing Platform.

{% 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%}

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

### Configuration file on CRIB

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

### 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/)
4 changes: 3 additions & 1 deletion docs/run_model.md
View file
Original file line number Diff line number Diff line change
@@ -1 +1,3 @@
# How to run the model
#

To run the
2 changes: 1 addition & 1 deletion mkdocs.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ repo_name: STEMMUS_SCOPE
nav:
- Introduction: index.md
- Getting started: getting_started.md
- Run the model: run_model.md
- Running the model: run_model.md
- Contributing guide: contributing_guide.md

theme:
Expand Down

0 comments on commit 38eb832

Please sign in to comment.