update input definition

docs/user_guide/index.rst

@@ -7,38 +7,36 @@ User Guide
 This user guide explains the different parameters available in goSPL input file.
 
 .. note::
-    For examples using goSPL, the user is invited to download goSPL-examples `repository <https://github.com/Geodels/gospl-examples>`_ which covers some of the basic functionalities of the code: 
+    For examples using goSPL, the user is invited to download the **goSPL-examples** `repository <https://github.com/Geodels/gospl-examples>`_ which covers some of the basic functionalities of the code: 
 
     - data structure used in the gospl input file,
     - how to generate initial conditions like topography, precipitation and tectonic maps to force a simulation,
     - how to extract some of the output from the your results.
 
-    Those examples cover just a small selection of functions as an illustration of principles. 
+    Those examples highlight just a small selection of functions as an illustration of principles. 
 
     For a full overview of goSPL capabilities, head to the `API reference <https://gospl.readthedocs.io/en/latest/api_ref/index.html>`_. 
 
     For additional examples, you might be interested in the following set of examples available from the `Stellar-SFM project <https://geodels.github.io/stellar-sfm/welcome.html>`_.
 
-.. warning::
+    .. warning::
 
-    `Stellar-SFM project <https://geodels.github.io/stellar-sfm/welcome.html>`_ is based on a previous version of goSPL and some of the new features will not be available. There might also be some of the oldest features that might not be fully functional with the newest version. If you are interested in reproducing the examples from this Stellar-SFM project, you could use the branch `v2023 <https://github.com/Geodels/gospl/tree/v2023>`_ from goSPL. 
+        `Stellar-SFM project <https://geodels.github.io/stellar-sfm/welcome.html>`_ is based on a previous version of goSPL and some of the new features will not be available. There might also be some of the oldest features that might not be fully functional with the newest version. If you are interested in reproducing the examples from this Stellar-SFM project, you could use the branch `v2023 <https://github.com/Geodels/gospl/tree/v2023>`_ from goSPL. 
 
 
 Input file
 ---------------------
 
-.. important::
+The code is primarily a **parallel global scale landscape evolution model**, built to simulate **topography and basins** dynamics. The following processes are considered:
 
-    The code is primarily a **parallel global scale landscape evolution model**, built to simulate **topography and basins** dynamics. The following processes are considered:
-
-    - **river incision** and **deposition** using stream power law,
-    - continental **deposition** in depressions,
-    - **marine deposition** at river mouth,
-    - **hillslope processes** in both marine and inland areas,
-    - **sediment compaction** as stratigraphic layers geometry and properties change, 
-    - spatially and temporally varying **tectonics** (horizontal and vertical displacements).
-    - spatially and temporally varying **precipitation** grids as well as **orographic** rain and sea-level fluctuations, 
-    - possibility to account for **flexural** isostasy driven by changes in surface loading.
+- **river incision** and **deposition** using stream power law,
+- continental **deposition** in depressions,
+- **marine deposition** at river mouth,
+- **hillslope processes** in both marine and inland areas,
+- **sediment compaction** as stratigraphic layers geometry and properties change, 
+- spatially and temporally varying **tectonics** (horizontal and vertical displacements).
+- spatially and temporally varying **precipitation** grids as well as **orographic** rain and sea-level fluctuations, 
+- possibility to account for **flexural** isostasy driven by changes in surface loading.
 
 
 Required parameters
@@ -50,10 +48,10 @@ Required parameters
     .. grid-item-card::  
         :text-align: center
 
-        **Minimal input declaration**
+        **Mesh and temporal definition**
         ^^^
 
-        Imposing initial conditions and specifying at least one physical processes.
+        Imposing initial nesh conditions and simulation duration.
 
         +++
 
@@ -97,7 +95,7 @@ Optional parameters related to climate
     .. grid-item-card::  
         :text-align: center
 
-        **Climate-related parameters**
+        **Climate-related conditions**
         ^^^
 
         Imposing precipitation and sea-level.

docs/user_guide/inputfile.rst

@@ -36,21 +36,25 @@ Initial mesh definition and simulation declaration
 
         The following parameters are **required**:
 
-        a. the initial spherical surface mesh ``npdata`` as well as
+        a. the initial spherical or 2D surface mesh ``npdata`` (**.npz** file). This file contains the following keys: ``v`` the mesh vertices coordinates, ``z`` the vertice elevations, ``c`` the mesh cells.
         b. the flow direction method to be used ``flowdir`` that takes an integer value between 1 (for SFD) and 6 (for MFD)
         c. the exponent (``flowexp``) used in the flow direction approach. Default value is set to 0.42.
-        d. boundary conditions (``bc``) when not running a global model. Each integer corresponds to an edge defined in the following order: south, east, north, and west. The integer is set to 0 for open and 1 closed boundaries.
+        d. boundary conditions (``bc``) when not running a global model. Each integer corresponds to an edge defined in the following order: south, east, north, and west. The integer is set to either 0 for open or to 1 for closed boundaries.
 
-        In addition the following optional parameters can be set:
+        In addition the following optional parameters could be set:
 
-        e. the ``fast`` key allows you to run a model without applying any surface processes on top. This is used to run backward model in a quick way, but can also potential be set to *True* if you want to check your input files prior to running a forward model with all options.
-        f. ``seadepo`` performing marine deposition or not
-        g. to start a simulation using a previous erosion/deposition map use the ``nperodep`` key and specify a file containing for each vertex of the mesh the cumulative erosion deposition values in metres.
-        h. to start a simulation using an initial stratigraphic layer use the ``npstrata`` key and specify a file containing for each vertex of the mesh the stratigraphic layer thickness and the porosities of the sediments.
+        e. the ``fast`` key allows you to run a model without applying any surface processes on top. This is used to check your input files prior to run your simulation with all options. By default it is set to *False*.
+        f. ``seadepo`` performing marine deposition or not. By default it is set to *False*.
+        g. to start a simulation using a previous erosion/deposition map use the ``nperodep`` key and specify a file (**.npz** format with the erosion deposition defined with the key ``ed``) containing for each vertex of the mesh the cumulative erosion deposition values in metres. 
+        h. to start a simulation using an initial stratigraphic layer use the ``npstrata`` key (**.npz** file) and specify a file containing for each vertex of the mesh the stratigraphic layer thickness ``strataH``, the elevation at time of deposition ``strataZ``, and the porosities of the sediment ``phiS``. 
 
 .. warning::
 
-  It is worth noting that all the input files require to run a goSPL simulation must be defined as numpy zip array (**.npz**). This allows to directly and efficiently load the dataset during initialisation. This is specially efficient when running large models.
+  It is worth noting that all the input files require to run a goSPL simulation must be defined as numpy zip array (**.npz**). This allows to directly and efficiently load the dataset during initialisation. This is specially efficient when running large models. 
+
+.. note::
+
+  It is also possible to have only one **.npz** file containing the required keys. For example you could set an input file containing the following keys: ``v`` the mesh vertices coordinates, ``z`` the vertice elevations, ``c`` the mesh cells, ``ed`` erosion deposition and call it for both the ``npdata`` and ``nperodep`` parameters.
 
 
 Setting model temporal evolution
@@ -78,17 +82,20 @@ Setting model temporal evolution
         ``time`` is also a required component of every input file. The following parameters are needed:
 
         a. ``start`` is the model start time in years,
-        b. ``end``` is the model end time in years,
+        b. ``end`` is the model end time in years,
         c. ``dt`` is the model internal time step (the approach in goSPL uses an implicit time step).
-        d. ``tout`` is the output interval used to create model outputs,
+        d. ``tout`` is the output interval used to create model outputs.
+
+        The following parameters are **optional**:
+
         e. to restart a simulation use the ``rstep`` key and specify the time step number.
-        f. ``tec`` is the tectonic timestep interval used to update the tectonic meshes and perform the required horizontal displacements (vertical displacements are done every ``dt``).
+        f. ``tec`` is only relevant for specific cases when using a plates reconstruction model. This tectonic timestep interval is used to update the tectonic meshes and to perform the required horizontal displacements. For standard tectonic conditions (vertical movements), the calculation is performed every ``dt``.
         g. ``strat`` is the stratigraphic timestep interval used to update the stratigraphic record.
 
 
 .. important::
 
-  In cases where the specify ``dt``, ``strat`` and ``tec`` parameters are greater than ``tout``, they will automatically be rescaled to match with the output interval. The ``tec`` parameter should be set to similar to the temporal time step used in your reconstruction (usually around 1Ma). This time step is used to perform the horizontal displacements. The vertical displacements are updated for each time step. When turn-on the stratal records will be output at the same time as the output ones, but the file will potentially contain multiple stratigraphic layers per output if ``strat`` is lower than ``tout``.
+  In cases where the specify ``dt``, ``strat`` and ``tec`` parameters are greater than ``tout``, they will automatically be rescaled to match with the output interval. The ``tec`` parameter should be set to the temporal time step used in your reconstruction (usually 1 Ma). This time step is used to perform the horizontal displacements. The vertical displacements are updated for each time step. When turned-on the stratal records will be output at the same time as the output ones, but the file will potentially contain multiple stratigraphic layers per output if ``tout`` is a multiple of ``strat``.
 
 Output folder definition
 -------------------------
@@ -108,8 +115,10 @@ Output folder definition
 
         Finally, you will need to specify the output folder, with 2 possible parameters:
 
-        a. ``dir`` gives the output directory name and
-        b. the option ``makedir`` gives the ability to delete any existing output folder with the same name (if set to False) or to create a new folder with the given `dir` name plus a number at the end (*e.g.* outputDir_XX if set to True with XX the run number). It allows you to avoid overwriting on top of previous runs.
+        a. ``dir`` gives the output directory name.
+
+        The following parameter is **optional**:
+
+        b. the option ``makedir`` gives the ability to delete any existing output folder with the same name (if set to *False* - default value) or to create a new folder with the given `dir` name plus a number at the end (*e.g.* outputDir_XX if set to *True* with XX the run number). It allows you to avoid overwriting on top of previous runs.
 
-.. _`Paraview`: https://www.paraview.org/download/
 .. _`YAML`: https://circleci.com/blog/what-is-yaml-a-beginner-s-guide/