Merge pull request #232 from GEB-model/main

Update DYNAMO branch

Author: ltierolf

README.md

@@ -1,4 +1,3 @@
-## Overview
 GEB (Geographical Environmental and Behavioural model) simulates the environment (e.g., hydrology, floods), the individual people, households and orginizations as well as their interactions at both small and large scale. The model does so through a "deep" coupling of an agent-based model a hydrological model, a vegetation model and a hydrodynamic model. You can find full documentation [here](https://geb-model.github.io/GEB/).
 
 The figure below shows a schematic overview of the model agent-based and hydrological model.
@@ -20,11 +19,13 @@ or with [uv](https://docs.astral.sh/uv/):
 uv pip install geb --prerelease=allow
 ```
 
+To run SFINCS (the hydrodynamic model), you also need to install Docker (on Windows) or Singularity (on Linux and Mac OS X). To install Docker you need to obtain and install Docker from their website (https://www.docker.com/get-started) and make sure Docker or Singularity is running.
+
 ## Development installation and setup
 
 To contribute to GEB, we recommend first cloning the repository from this repo using `git clone`, and then use uv to install the dependencies. Therefore, first install [uv](https://docs.astral.sh/uv/#installation) and [git](https://git-scm.com/).
 
-Also create a folder where you would like to store the code and model, we call this the *working directory*. In this *working directory*, create a folder called *model*, and place the model input files in this folder. The directory structure should look like this:
+Also create a folder where you would like to store the code and model, we call this the *working directory*. Note that this folder should *NOT* be placed into a cloud synchonized folder (e.g., OneDrive). In this *working directory*, create a folder called *model*, and place the model input files in this folder. The directory structure should look like this:
 
 ```
 working directory

docs/conf.py

@@ -52,13 +52,14 @@
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.coverage",
-    "sphinx.ext.napoleon",
+    "sphinx.ext.napoleon",  # Napoleon is a Sphinx extension that enables Sphinx to parse both NumPy and Google style docstrings
     "sphinx.ext.viewcode",
     "sphinx_rtd_theme",
     "sphinx_autodoc_typehints",
     "sphinxcontrib.autoprogram",
     "sphinxcontrib.autoyaml",
     "sphinxcontrib.bibtex",
+    "myst_parser",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/contribution_guide.rst

@@ -0,0 +1,59 @@
+Contribution Guide
+===================
+
+General Recommendations
+----------------------------
+
+- It is RECOMMENDED to turn on notifications of GitHub issues to remain aware of current issues and suggested solutions. You can do so using the "watch" feature on the GEB GitHub page.
+- You MUST use descriptive commit messages for every commit (e.g., no "some fixes", "progress", etc.).
+- It is RECOMMENDED to keep up-to-date with the main branch by frequently (at least once a week) pulling updates from the main. This will reduce the number of merge conflicts and avoid work duplication.
+- You MUST use descriptive branch names, and include your name or your sub-project if multiple people work on the same topic.
+
+Feature Development
+----------------------------
+
+The main version of GEB is always on the ``main`` branch. This branch SHOULD be stable, and we aim for it to be free of bugs 
+(acknowledging that this is an almost impossible aim). New features are developed in other branches.
+
+- It is RECOMMENDED to create a GitHub issue with the features that you are working on and to communicate this to other developers
+  working on similar topics, so that everyone is aware of ongoing work.
+- It is RECOMMENDED to limit the number of features in a single branch. If possible, break your feature into several sub-features.
+- When the (sub-)features are complete, the branch MUST be merged into ``main`` using a pull request on GitHub.
+- It is RECOMMENDED to get feedback on the code from one of the main developers. You can use the reviewer mechanism on the pull request page.
+
+Bugs
+----------------------------
+
+We use GitHub issues for tracking bugs.
+
+- When you find a bug that affects ``main``, you MUST create a new issue describing the bug.
+- When fixing the bug:
+  - The fix MUST be reported on the issue.
+  - The issue MUST link to the fix.
+- It is RECOMMENDED to create the fix in a dedicated bug-fix branch created from ``main`` (i.e., not from your working branch).
+- Merge the bug-fix branch into your own branch as needed, and separately request a merge of the bug-fix branch back into ``main``.
+- It is also RECOMMENDED to communicate the bug to developers who may be affected.
+
+Testing
+----------------------------
+
+We use ``pytest`` for automated testing of the GEB model.
+
+- It is RECOMMENDED to write tests for your code.
+- Tests are automatically run on GitHub when any branch is pushed.
+
+Coding Practices
+----------------------------
+
+- All variable names MUST be clear. Prefer long and descriptive names over short, unclear ones.
+- Code comments are RECOMMENDED, focusing on *why* something is done, rather than *what* is done. The *what* should ideally be
+  evident from the variable naming and structure.
+- Units MUST be in SI units, or have the unit appended to the variable name. If SI units cannot be used (e.g., when coupling
+  with other models), units should be converted immediately on import or export.
+- Monetary units MUST be nominal USD (face value) for the respective years.
+- It is RECOMMENDED to use ``assert`` statements in the model to ensure correct behaviour.
+- When there is an error, the model SHOULD fail. Do not catch exceptions and replace with dummy data.
+- All code MUST be formatted using ``ruff format`` and ``ruff check``. Imports MUST be ordered using ``isort`` (included in ``ruff``).
+- It is RECOMMENDED to install the ruff plugin and set ruff as the default formatter in Visual Studio Code.
+  Also turn on “format on paste” and “format on save”.
+- ``ruff format`` and ``ruff check`` are automatically executed when pushing to GitHub.

docs/index.rst

@@ -31,7 +31,7 @@ The figure below shows a schematic overview of some parts of the model, showing
   :maxdepth: 1
   :caption: Getting Started
 
-  Installation <installation>
+  Overview and installation <overview_and_installation>
   Configuration <configuration>
   Preprocessing <preprocessing>
   Running the model <running>
@@ -63,4 +63,5 @@ The figure below shows a schematic overview of some parts of the model, showing
   :caption: About
 
   Authors <authors_page>
+  Contribution guide <contribution_guide>
   Updates <updates>

docs/installation.rst

@@ -0,0 +1,5 @@
+Overview and installation
+========================
+
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_

docs/overview_and_installation.rst

@@ -1,65 +1,31 @@
-1) DOWNLOAD PACKAGES
+Download Packages
+===============
 
-So PlantFATE runs with the use of 2 other packages and with the coupling package you need to checkout 4 different github repositories. 
+```bash
 
-The packages are:
+git clone [email protected]:jaideep777/Plant-FATE.git
+git switch feature_python_pckg  # switch to the feature branch
+cd Plant-FATE
 
-1) Coupling package: https://github.com/jensdebruijn/couple-plantFATE-CWatM (branch: develop)
-2) PlantFATE package: https://github.com/jaideep777/Plant-FATE (branch: feature_stepByStepSim)
-3) libpspm package: https://github.com/jaideep777/libpspm (branch: develop)
-4) Phydro package: https://github.com/jaideep777/phydro (branch: master)
+```
 
-For ease of running and set up put these in one big project root folder (not necessary for the coupling package):
+Install optional packages from plantfate extras in GEB:
 
-  root
-  |---- phydro
-  |     |--- inst/include
-  |
-  |---- libpspm
-  |     |--- include
-  |     |--- lib
-  |
-  |---- Plant-FATE
-  |     |--- inst/include
+```bash
 
-2) INSTALL PLANTFATE and PYBIND
+uv sync --extra plantfate
 
-- module load cm-eigen3/3.3.7
-- module load shared
-- module load 2022
-- module load GSL/2.7-GCC-11.3.0
+```
 
-As per instructions in PlantFATE readme, install natively in C++.
 
-You may need to install additional libraries, specifically pybind: 
+Compiling PlantFATE
+=====================
 
-* pip
+```bash
 
-  * pip install pybind11
+module load shared 2024 Eigen/3.4.0-GCCcore-12.3.0 GSL/2.7-GCC-12.3.0
+cd Plant-FATE
+make all
+uv pip install ../Plant-FATE/
 
-  * pip install cppimport
-* libpspm
-
-  * cd libpspm
-
-  * make clean testclean
-
-  * make
-
-  * make check
-
-* Phydro
-
-  * cd phydro
-
-  * make clean testclean
-
-  * make check
-
-* PlantFATE
-
-  * cd Plant-FATE
-
-  * make clean testclean
-  
-  * make python
+```

docs/plantFATE.rst

@@ -38,7 +38,7 @@ For example, to export the total bare soil evaporation, gridded daily discharge,
                 function: weightednansum
         hydrology.routing:
             discharge_daily:
-                varname: grid.var.discharge
+                varname: grid.var.discharge_m3_s
                 type: grid
                 function: null
         agents.crop_farmers:
@@ -53,7 +53,7 @@ The following options are supported.
 * **filename**: The name of the file to be created. This can be a .csv or .zarr file. If the file already exists, it will be overwritten. The filename will be created in the output directory specified in the model configuration file, and placed inside the subdirectory with the name of the module.
 * **varname**: The name of the variable to be reported. NumPy-style fancy indexing is supported. For example `varname[:,0]` selects the first column of a 2D array. There are two options:
 
-  + **module attribute**: The variable name in the module. Any variable that can be reached from "self" in the module can be used. For example, `[self.]varname` or `[self.]grid.var.discharge`. Note that `self.` is ommited.
+  + **module attribute**: The variable name in the module. Any variable that can be reached from "self" in the module can be used. For example, `[self.]varname` or `[self.]grid.var.discharge_m3_s`. Note that `self.` is ommited.
   + **local variable**: Any variable that exists within the `step` function of the module. This is useful for reporting variables that are not stored between timesteps. Local variables are prefixed with ".", for exampe `.actual_bare_soil_evaporation` in the example above.
 * **type**: The type of the variable. This can be one of the following:
 

docs/report.rst

@@ -2,7 +2,7 @@ setup_region:
   subgrid_factor: 20
 
 set_time_range:
-  start_date: 1970-01-01
+  start_date: 2000-01-01
   end_date: 2024-12-31
 
 setup_hydrography:
@@ -14,10 +14,10 @@ setup_regions_and_land_use:
   ISO3_column: GID_0
 
 setup_cell_area:
-  
-setup_economic_data:
 
 setup_mannings:
+  
+setup_economic_data:
 
 setup_soil_parameters:
 
@@ -340,5 +340,5 @@ setup_forcing_era5:
 
 setup_SPEI:
   window: 12
-  calibration_period_start: 2000-01-01
-  calibration_period_end: 2020-12-31
+  calibration_period_start: 2011-01-01
+  calibration_period_end: 2021-12-31

examples/geul/build.yml

@@ -14,7 +14,7 @@ general:
   # start of the spinup time (YYYY-MM-DD).
   # spinup_time: 1999-01-01
   # spinup_time: 1980-01-01
-  spinup_time: 2001-01-01
+  spinup_time: 2011-01-01
   # spinup_time: 2020-01-01
   ###
   # base folder where to report output data to
@@ -24,7 +24,7 @@ hazards:
   floods:
     simulate: true
     resolution: 100
-    nr_subgrid_pixels: 5
+    nr_subgrid_pixels: 4
     flood_risk: false
     gpu: false
     force_overwrite: true
@@ -38,6 +38,6 @@ hazards:
 report:
   hydrology.routing:
     discharge_daily:
-      varname: grid.var.discharge
+      varname: grid.var.discharge_m3_s
       type: grid
       function: null