Make STEMMUS_SCOPE BMI-able

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Unreleased
 
+**Changed:**
+- The STEMMUS_SCOPE Matlab Runtime executable now needs version `R2023a`.
+
+**Added:**
+- STEMMUS_SCOPE BMI preparation:
+  - The executable can be run in an "interactive" mode. 
+    In this mode the model's initialization, time update, and finalization can be called upon separately.
+  - The model now will write away BMI-required variables to a state file, which can be used for the Python BMI.
+
 **Fixed:**
 
 - use `any()` function in `solveTridiagonalMatrixEquations.m` in

README.md

@@ -34,6 +34,8 @@ If you want to run `STEMMUS_SCOPE` on CRIB, check [this document](./docs/STEMMUS
 
 If you want to run `STEMMUS_SCOPE` on your own machine, check [this document](./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 [this document](./docs/STEMMUS_SCOPE_BMI.md).
+
 ## Contributing
 
 If you want to contribute to the development of `STEMMUS_SCOPE`,

docs/STEMMUS_SCOPE_BMI.md

@@ -0,0 +1,42 @@
+## STEMMUS_SCOPE BMI
+
+`STEMMUS_SCOPE` has a BMI-like interface. This is available when running the Matlab Runtime version of the model.
+The full BMI is implemented in Python in [PyStemmusScope](https://github.com/EcoExtreML/STEMMUS_SCOPE_Processing/).
+
+A Docker image will also be available, which allows you to run the model on any system without installing Matlab Runtime.
+
+### BMI mode
+
+When starting the executable, a run-mode can be specified. The following command will run the model using the config file:
+
+```sh
+./STEMMUS_SCOPE "/home/path/to/config/file.txt" full
+```
+
+(Where `./STEMMUS_SCOPE` is the path to the executable. For more info see [documentation](../run_model_on_snellius/exe/README.md))
+
+To start BMI mode, pass anything (e.g. an empty string "") as config file, and use `bmi` to start the model in BMI-mode:
+
+```sh
+./STEMMUS_SCOPE "" bmi
+```
+
+The model will respond with `Finished command. Select run mode: `. Now you can initialize the model:
+
+```
+Finished command. Select run mode: initialize "/home/path/to/config/file.txt"
+```
+
+The model will respond with:
+```
+Reading config from /home/path/to/config/file.txt
+Finished model initialization
+```
+
+Now you can use the commands `update` to advance the model by one timestep, and `finalize` to finalize the model.
+
+### Exposing variables to BMI interface
+
+The variables which are exposed to the Python BMI are defined in `STEMMUS_SCOPE_exe.m`.
+To add more variables, update the `bmiVarNames` variable.
+After this, you will need to change the BMI codes in [PyStemmusScope](https://github.com/EcoExtreML/STEMMUS_SCOPE_Processing/) so it can make use of these exposed variables.

docs/STEMMUS_SCOPE_on_Snellius.md

@@ -120,7 +120,7 @@ matlab -nodisplay -nosplash -nodesktop -r "STEMMUS_SCOPE_exe('config_file_snelli
 #### 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 `2021a`. This is available on Snellius. You can run the
+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**:
 

docs/STEMMUS_SCOPE_on_local_device.md

@@ -19,7 +19,7 @@ You can run STEMMUS_SCOPE locally. Follow the steps below and use `config_file_c
 #### 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 `2021a`. To download and install the MATLAB Runtime, follow
+Runtime version `2023a`. To download and install the MATLAB Runtime, follow
 this
 [instruction](https://nl.mathworks.com/products/compiler/matlab-runtime.html).
 The "STEMMUS_SCOPE" executable file is in `STEMMUS_SCOPE/exe` directory

run_model_on_snellius/exe/README.md

@@ -4,7 +4,7 @@ If you want to run the STEMMUS_SCOPE model, you need to run it using MATLAB or
 [MATLAB Runtime](https://nl.mathworks.com/products/compiler/matlab-runtime.html). You don't need a license for MATLAB Runtime. 
 
 The file `STEMMUS_SCOPE` under `exe` directory is an executable file of
-STEMMUS_SCOPE that is created using MATLAB version `2021a` in a Linux system.
+STEMMUS_SCOPE that is created using MATLAB version `2023a` in a Linux system.
 Note that the version of the MATLAB Runtime is tied to the version of MATLAB.
 For more information, see [How to run STEMMUS_SCOPE on
 CRIB](../README.md#how-to-run-stemmus_scope-on-crib) or [How to run

run_model_on_snellius/exe/build_stemmus_scope_exe.sh

@@ -7,20 +7,20 @@
 #SBATCH -t 00:05:00
 #SBATCH -N 1
 #SBATCH --ntasks=1
-#SBATCH --cpus-per-task=32
-#SBATCH -p thin
+#SBATCH --cpus-per-task=16
+#SBATCH -p genoa
 #SBATCH --output=./slurm_%j.out
 #SBATCH --error=./slurm_%j.out
 
 # Some security: stop script on error and undefined variables
 set -euo pipefail
 
-############ Use module MATLAB/2021a-upd3 to either run the source code or build the executable file ############
+############ Use module MATLAB/2023a-upd4 to either run the source code or build the executable file ############
 ############ This needs a matlab license, make sure yuor account is added to the license pool ############
 # Load matlab module
 # On Snellius Try: "module spider MATLAB" to see how to load the module(s).
-module load 2021
-module load MATLAB/2021a-upd3
+module load 2023
+module load MATLAB/2023a-upd4
 
 # Create executable file
 mcc -m ./src/STEMMUS_SCOPE_exe.m -a ./src -d ./run_model_on_snellius/exe -o STEMMUS_SCOPE -R nodisplay -R singleCompThread