Deltares-research · Carsopre · Apr 13, 2022 · Mar 16, 2022 · Mar 16, 2022 · Mar 21, 2022
diff --git a/README.md b/README.md
@@ -1,48 +1,19 @@
-# How to run a Vegetation simulation in NBSDynamics
+[![ci](https://github.com/Deltares/NBSDynamics/actions/workflows/ci.yml/badge.svg)](https://github.com/Deltares/NBSDynamics/actions/workflows/ci.yml)
+[![docs](https://github.com/Deltares/NBSDynamics/actions/workflows/docs.yml/badge.svg)](https://github.com/Deltares/NBSDynamics/actions/workflows/docs.yml)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Deltares_NBSDynamics&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=Deltares_NBSDynamics)
+![Sonar Coverage](https://img.shields.io/sonar/coverage/Deltares_NBSDynamics?logo=SonarCloud&server=https%3A%2F%2Fsonarcloud.io&?style=plastic&logo=appveyor)
 
+![GitHub release (latest by date)](https://img.shields.io/github/v/release/Deltares/NBSDynamics)
+![GitHub tag (latest by date)](https://img.shields.io/github/v/tag/Deltares/NBSDynamics)
 
-## Simulation structure.
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 
-The simulation is started using the [simtest_saltmars_test](../../test/test_data/simtest_saltmarsh_test.py) file. 
-Here the different paths need to be specified. 
-An object of the class [VegFlowFmSimulation](../../src/core/simulation/veg_delft3d_simulation.py) (which inherits from the BaseSimulation) is created. 
-Within the object, the vegetation species (in constants and vegetation) are required as an input. 
-Different species are defined through different constants. 
-In [Constants](../../src/core/common/constants_veg.py) a json file is called which contains the species specific vegetation parameters. 
-Additional time related constants (e.g. start time and ecological time steps) are defined in [Constants](../../src/core/common/constants_veg.py) and can be changed manually there.  
-Further species can be added by defining their specific parameters using [constants_json_create](../../src/core/common/constants_json_create.py).
+# Official Documentation.
+Check our official GitHub pages documentation at [https://deltares.github.io/NBSDynamics/](https://deltares.github.io/NBSDynamics/).
 
-With those parameters assigned to the object, the simulation is started by using the following methods (specified in the [BaseSimulation](../../src/core/simulation/veg_base_simulation.py)):
+# Current supported models.
+Currently we support the Vegetation and Coral models. More details of how to run them can be found at their respective documentation pages.
+In addition, quick links on how to run models in this package:
+* [Basics: How to run 'any' model](https://deltares.github.io/NBSDynamics/guides/run_simulation/)
+* [How to run a Vegetation Model](https://deltares.github.io/NBSDynamics/guides/run_simulation_veg/)
 
-* initiate
-  * configures hydrodynamics and output
-  * validates simulation directories 
-  * initiated vegetation characteristics for all life stages in the class [LifeStages](../../src/core/vegetation/veg_lifestages.py)
-  * initializes the output ([VegOutputWrapper](../../src/core/output/veg_output_wrapper.py))
-
-* run
-  * when calling the run method (sim_run.run()), the duration of the simulation needs to be specified (in years) (e.g. sim_run.run(5))
-  * if duration is not given, the duration specified in the [Constants](../../src/core/common/constants_veg.py) class will be used 
-  * the start date is set to the date specified in [Constants](../../src/core/common/constants_veg.py)
-  * end date = start date + duration 
-  * a loop is started over the duration of the simulation (years)
-  * inside of that loop another loop iterates over the number of ecological time steps per year (coupling times per year) specified in [Constants](../../src/core/common/constants_veg.py)
-  * to get the hydro and morphological variables from Delft-FM, the hydro-morphodynamics are retrieved every day.
-    * the coupling and retrieving of the values is specified in the class [Delft3D](../../src/core/hydrodynamics/delft3d.py)
-  * aggregated values are then created in the class [Hydro_Morphodynamics](../../src/core/bio_process/hydromorphodynamics.py) and retrieved via the method 'get_hydromorph_values'
-  * the vegetation dynamics are initiated: 
-    * [Mortality and Growth](../../src/core/bio_process/veg_mortality.py)
-      * criteria for mortality and mortality fractions are determined based on the species and the morpho- &  hydrodynamics 
-      * vegetation growth is initiated based on the number of growth days within the current ecological time step
-    * [Colonization](../../src/core/bio_process/veg_colonisation.py)
-      * method is only called when colonization is possible during the specific period of the ecological time step 
-      * criteria for colonization are determined based on the species and the morpho- &  hydrodynamics
-      * the vegetation characteristics of the initial lifestage are updated based on the possible colonization
-    * [Update_Lifestages](../../src/core/vegetation/veg_model.py)
-      * the life stages are updates (initial to juvenile and juvenile to mature)
-      * initial to juvenile always occurs when new vegetation colonized 
-      * juvenile to mature only occurs when vegetation in the juvenile stage reached the maximum years in that life stage
-      * if the maximum age of vegetation is reached, the vegetation is removed
-  * The results are exported using the methods defined in [MapOutput](../../src/core/output/veg_output_model.py) and [HisOutput](../../src/core/output/veg_output_model.py)
-
-* finalize (Finalize simulation)
diff --git a/docs/guides/run_simulation.md b/docs/guides/run_simulation.md
@@ -77,9 +77,9 @@ The following simulations are defined, however their status is not yet final and
 #### Coral FlowFm Simulation
 Open issue: [#68 Fix Delft3D - FlowFMModel run.](https://github.com/Deltares/NBSDynamics/issues/68)
 
-A simulation using the [CoralFlowFmSimulation](reference/simulation/simulation/#src.core.simulation.coral_delft3d_simulation.CoralFlowFmSimulation) object. Which will build the simulation around a `FlowFMModel` hydrodynamic model.
+A simulation using the [CoralFlowFmSimulation](reference/simulation/simulation/#src.biota_models.coral.simulation.coral_delft3d_simulation.CoralFlowFmSimulation) object. Which will build the simulation around a `FlowFMModel` hydrodynamic model.
 
 #### Coral Dimr Simulation
 Open issue: [#69 Fix / Implement Delft3D - DIMR run.](https://github.com/Deltares/NBSDynamics/issues/69)
 
-A simulation using the [CoralDimrSimulation](../../reference/simulation/simulation/#src.core.simulation.coral_delft3d_simulation.CoralDimrSimulation) object. Which will build the simulation around a `DimrModel` hydrodynamic model.
+A simulation using the [CoralDimrSimulation](../../reference/simulation/simulation/#src.biota_models.coral.simulation.coral_delft3d_simulation.CoralDimrSimulation) object. Which will build the simulation around a `DimrModel` hydrodynamic model.
diff --git a/docs/guides/run_simulation_veg.md b/docs/guides/run_simulation_veg.md
@@ -5,44 +5,44 @@
 
 The simulation is started using the [simtest_saltmars_test](../../test/test_data/simtest_saltmarsh_test.py) file. 
 Here the different paths need to be specified. 
-An object of the class [VegFlowFmSimulation](../../reference/simulation/vegetation_simulation/#src.core.simulation.veg_delft3d_simulation) (which inherits from the BaseSimulation) is created. 
+An object of the class [VegFlowFmSimulation](../../reference/simulation/vegetation_simulation/#src.biota_models.vegetation.simulation.veg_delft3d_simulation) (which inherits from the BaseSimulation) is created. 
 Within the object, the vegetation species (in constants and vegetation) are required as an input. 
 Different species are defined through different constants. 
-In [Constants](../../reference/common/common/#src.core.common.constants_veg) a json file is called which contains the species specific vegetation parameters. 
-Additional time related constants (e.g. start time and ecological time steps) are defined in [Constants](../../src/core/common/common/#src.core.common.constants_veg) and can be changed manually there.  
-Further species can be added by defining their specific parameters using [constants_json_create](../../src/core/common/common/#src.core.common.constants_json_create).
+In [Constants](../../reference/common/common/#src.biota_models.vegetation.model.veg_constants) a json file is called which contains the species specific vegetation parameters. 
+Additional time related constants (e.g. start time and ecological time steps) are defined in [Constants](../../src/core/common/common/#src.biota_models.vegetation.model.veg_constants) and can be changed manually there.  
+Further species can be added by defining their specific parameters using [constants_json_create](../../src/core/common/common/#src.biota_models.vegetation.model.constants_json_create).
 
-With those parameters assigned to the object, the simulation is started by using the following methods (specified in the [BaseSimulation](../../reference/simulation/vegetation_simulation/#src.core.simulation.veg_base_simulation)):
+With those parameters assigned to the object, the simulation is started by using the following methods (specified in the [BaseSimulation](../../reference/simulation/vegetation_simulation/#src.biota_models.vegetation.simulation.veg_base_simulation)):
 
 * initiate
   * configures hydrodynamics and output
   * validates simulation directories 
-  * initiated vegetation characteristics for all life stages in the class [LifeStages](../../reference/vegetation/vegetation_model/#src.core.vegetation.veg_lifestages)
-  * initializes the output ([VegOutputWrapper](../../reference/output/vegetation_output/#src.core.output.veg_output_wrapper))
+  * initiated vegetation characteristics for all life stages in the class [LifeStages](../../reference/vegetation/vegetation_model/#src.biota_models.vegetation.model.veg_lifestages)
+  * initializes the output ([VegOutputWrapper](../../reference/output/vegetation_output/#src.biota_models.vegetation.output.veg_output_wrapper))
 
 * run
   * when calling the run method (sim_run.run()), the duration of the simulation needs to be specified (in years) (e.g. sim_run.run(5))
-  * if duration is not given, the duration specified in the [Constants](../../reference/common/common/#src.core.common.constants_veg) class will be used 
-  * the start date is set to the date specified in [Constants](../../reference/common/common/#src.core.common.constants_veg)
+  * if duration is not given, the duration specified in the [Constants](../../reference/common/common/#src.biota_models.vegetation.model.veg_constants) class will be used 
+  * the start date is set to the date specified in [Constants](../../reference/common/common/#src.biota_models.vegetation.model.veg_constants)
   * end date = start date + duration 
   * a loop is started over the duration of the simulation (years)
-  * inside of that loop another loop iterates over the number of ecological time steps per year (coupling times per year) specified in [Constants](../../reference/common/common/#src.core.common.constants_veg)
+  * inside of that loop another loop iterates over the number of ecological time steps per year (coupling times per year) specified in [Constants](../../reference/common/common/#src.biota_models.vegetation.model.veg_constants)
   * to get the hydro and morphological variables from Delft-FM, the hydro-morphodynamics are retrieved every day.
     * the coupling and retrieving of the values is specified in the class [Delft3D](.../../reference/hydrodynamics/hydromodels/#delft3d)
-  * aggregated values are then created in the class [Hydro_Morphodynamics](../../reference/bio_process/vegetation_processes/#src.core.bio_process.veg_hydro_morphodynamics) and retrieved via the method 'get_hydromorph_values'
+  * aggregated values are then created in the class [Hydro_Morphodynamics](../../reference/bio_process/vegetation_processes/#src.biota_models.vegetation.bio_process.veg_hydro_morphodynamics) and retrieved via the method 'get_hydromorph_values'
   * the vegetation dynamics are initiated: 
-    * [Mortality and Growth](../../reference/bio_process/vegetation_processes/#src.core.bio_process.veg_mortality)
+    * [Mortality and Growth](../../reference/bio_process/vegetation_processes/#src.biota_models.vegetation.bio_process.veg_mortality)
       * criteria for mortality and mortality fractions are determined based on the species and the morpho- &  hydrodynamics 
       * vegetation growth is initiated based on the number of growth days within the current ecological time step
-    * [Colonisation](../../reference/bio_process/vegetation_processes/#src.core.bio_process.veg_colonisation)
+    * [Colonisation](../../reference/bio_process/vegetation_processes/#src.biota_models.vegetation.bio_process.veg_colonisation)
       * method is only called when colonisation is possible during the specific period of the ecological time step 
       * criteria for colonisation are determined based on the species and the morpho- &  hydrodynamics
       * the vegetation characteristics of the initial lifestage are updated based on the possible colonisation
-    * [Update_Lifestages](../../reference/vegetation/vegetation_model/#src.core.vegetation.veg_model)
+    * [Update_Lifestages](../../reference/vegetation/vegetation_model/#src.biota_models.vegetation.model.veg_model)
       * the life stages are updates (initial to juvenile and juvenile to mature)
       * initial to juvenile always occurs when new vegetation colonized 
       * juvenile to mature only occurs when vegetation in the juvenile stage reached the maximum years in that life stage
       * if the maximum age of vegetation is reached, the vegetation is removed
-  * The results are exported using the methods defined in [MapOutput](../../reference/output/vegetation_output/#src.core.output.veg_output_model) and [HisOutput](../../reference/output/vegetation_output/#src.core.output.veg_output_model)
+  * The results are exported using the methods defined in [MapOutput](../../reference/output/vegetation_output/#src.biota_models.vegetation.output.veg_output_model) and [HisOutput](../../reference/output/vegetation_output/#src.biota_models.vegetation.output.veg_output_model)
 
 * finalize (Finalize simulation)
diff --git a/docs/index.md b/docs/index.md
@@ -9,10 +9,22 @@ The project is currently being structured as follows:
         guides/         # Contains the documentation related to installation, usage and contribution to this project.
         reference/      # Contains references to the modules. Docstrings will be used to generate automatically documentation.        
     src/
+        biota_models/   # Module containing all biota species models that inherit or use the modules from core/
+            coral/      # Module containing the coral model definition.
+                bioprocess/ # Contains all the different bio processes required by the coral model.
+                model/  # Defines the coral model and related (such as constants).
+                output/ # Contains the definition(s) of output parameters to save.
+                simulation/  # The simulation classes for running different coral configurations.
+            vegetation/ # Module containing the different vegetation model definitions.
+                bioprocess/ # Contains all the different bio processes required by the vegetation model.
+                model/  # Defines the vegetation model and related (such as constants).
+                output/ # Contains the definition(s) of output parameters to save.
+                simulation/  # The simulation classes for running different vegetation configurations.
         core/           # Module containing all the classes and methods of NBSDynamics.
-            bio_process/ # The classes describing biophysical processes.
+            biota/      # The base class biota from which sub models can inherit.
             hydrodynamics/ # The different hydrodynamic models ('Transect', 'Delft3D', 'Reef0D', 'Reef1D')
-            output/     # The output models.
+            output/     # The base output models.
+            simulation/ # The base simulation classes.        
         tools/          # Module containing tools used by the coral_model module.
     test/               # Module based on pytest to mirror and test all the classes from src/
 
@@ -36,68 +48,3 @@ A summary of the architecture can be seen in the following 'reduced' class diagr
 
 ### OutputProtocol
 ![`OutputProtocol`](./diagrams/general_class_diagram-OutputProtocol.png)
-
-
-## CoralModel
-A biophysical model framework written in Python to make simulations 
-on coral development based on four environmental factors: 
-(1) light; (2) flow; (3) temperature; and (4) acidity. 
-For the hydrodynamics, the model can be coupled to Delft3D Flexible Mesh; 
-a hydrodynamic model developed at Deltares 
-([more information](https://oss.deltares.nl/web/delft3dfm)). 
-To enable this online coupling, certain configurations of Python are required 
-([more details](#python-code)).
-
-**Note:** This model is still in its beta and further development is still being done. 
-``coral_model_v0`` is used for the study and is rewritten (``coral_model``) to enhance collaboration.
-(The original version has not been written efficiently and is hard to follow for outsiders.)
-More information on this version control [here](#version-control).
-
-### Biophysics <a name="biophsics"></a>
-This biophysical model framework is part of the result of a 
-[master thesis](https://repository.tudelft.nl/islandora/object/uuid%3Ae211380e-3f92-4afe-b371-f1e87b0c3bbd?collection=education) 
-of which the key findings are published in *Environmental Modelling and Software*
-(the paper can be found [here](https://www.sciencedirect.com/science/article/pii/S1364815221001468?via%3Dihub)).
-
-The biophysical relations used in the biophysical model framework are mainly process-based, 
-where for the acidity the proxy of the aragonite saturation state is used. 
-Furthermore, both photo- and thermal-acclimatisation are included, 
-which result in a dynamic behaviour of the corals to their environment. 
-Hence, the corals are modelled such that they can adapt to changing environmental conditions over time.
-
-For more details on the biophysics, reference is made to the 
-[master thesis](https://repository.tudelft.nl/islandora/object/uuid%3Ae211380e-3f92-4afe-b371-f1e87b0c3bbd?collection=education) 
-and the [paper](https://www.sciencedirect.com/science/article/pii/S1364815221001468?via%3Dihub) that substitute this
-repository.
-
-### Python code <a name="python-code"></a>
-The Python code is written in Python 3 and makes use of various packages. 
-Not all of these packages are automatically included in the standard library of Python, 
-such as ``NetCDF4`` ([download](http://www.ldf.uci.edu/~gohlke/pythonlibs/#netcdf4)). 
-In case the biophysical model framework is to be coupled to Delft3d Flexible Mesh, 
-the ``bmi.wrapper`` package is also required  ([download](https://github.com/openearth/bmi-python)).
-
-The settings of Python and other packages for the online coupling to work properly are the following:
-
-* Python version 3.6.5
-* NumPy version 1.14.3
-* SciPy version 1.1.0
-* NetCDF4 version 1.4.2
-* Matplotlib version 2.2.2
-* BMI-Python
-
-**Note:** These requirements are only required in case the biophysical model framework is to be coupled 
-with Delft3D Flexible Mesh.
-
-
-### Version control <a name="version-control"></a>
-There are two versions of the CoralModel: ``coral_model_v0`` and ``coral_model``.
-The first (``coral_model_v0``) is the original code as used in the study (i.e. 
-[master thesis](https://repository.tudelft.nl/islandora/object/uuid%3Ae211380e-3f92-4afe-b371-f1e87b0c3bbd?collection=education) 
-and [paper](https://www.sciencedirect.com/science/article/pii/S1364815221001468?via%3Dihub)).
-The latter (``coral_model``) is an updated version, which is rewritten such that it enhances collaboration.
-This collaboration was one of the goals to further develop this model, 
-and the biophysical modelling of coral development.
-
-``coral_model_v0`` will be depreciated in the future, when ``coral_model`` is fully operational
-and possibly even incorporates more aspects of coral (reef) development.