Skip to content

Commit

Permalink
add user guide input definitions
Browse files Browse the repository at this point in the history
tristan-salles committed Jun 24, 2024
1 parent 1acbae9 commit 08bc0cf
Showing 5 changed files with 384 additions and 258 deletions.
146 changes: 135 additions & 11 deletions docs/user_guide/index.rst
Original file line number Diff line number Diff line change
@@ -4,19 +4,45 @@
User Guide
================

This user guide covers essential features of goSPL, mostly in the form of interactive Jupyter notebooks and Python scripts. Reading this guide, you will learn:
This user guide explains the different parameters available in goSPL input file.

- 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 model results to visualise them in Jupyter notebooks,
- how to run a sequence of backward/forward gospl models using Python functions,
- how to set a script for running gospl on HPC.
.. 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:

Notebooks cover 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>`_.
- 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.

Step 1 - The input file
------------------------------
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::

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

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

.. toctree::
:maxdepth: 3
@@ -31,10 +57,10 @@ Step 1 - The input file
.. grid-item-card::
:text-align: center

**Understanding the input file structure**
**Minimal input declaration**
^^^

Imposing initial conditions, specifying physical processes parameters and understanding how the input file is structured...
Imposing initial conditions and specifying at least one physical processes.

+++

@@ -44,3 +70,101 @@ Step 1 - The input file

Learn more.


Parameters related to surface processes
----------------------------------------------

.. toctree::
:maxdepth: 3
:hidden:

surfproc


.. grid:: 1
:padding: 3

.. grid-item-card::
:text-align: center

**Surface processes parameters**
^^^

Definition of the stream power law and hillslope parameters.

+++

.. button-ref:: surfproc
:color: secondary
:click-parent:

Learn more.


Optional parameters related to climate
----------------------------------------------

.. toctree::
:maxdepth: 3
:hidden:

optfile1


.. grid:: 1
:padding: 3

.. grid-item-card::
:text-align: center

**Climate-related parameters**
^^^

Imposing precipitation and sea-level.

+++

.. button-ref:: optfile1
:color: secondary
:click-parent:

Learn more.


Optional parameters related to tectonics
----------------------------------------------

.. toctree::
:maxdepth: 3
:hidden:

optfile2


.. grid:: 1
:padding: 3

.. grid-item-card::
:text-align: center

**Adding tectonic forcing**
^^^

Imposing tectonic conditions on your mesh.

+++

.. button-ref:: optfile2
:color: secondary
:click-parent:

Learn more.

.. toctree::
:maxdepth: 3
:hidden:

inputfile
surfproc
optfile1
optfile2
248 changes: 1 addition & 247 deletions docs/user_guide/inputfile.rst
Original file line number Diff line number Diff line change
@@ -1,21 +1,7 @@
.. _inputfile:


.. important::

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.

==============================
Input file parameters
Required input file parameters
==============================

.. note::
@@ -104,238 +90,6 @@ Setting model temporal evolution

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


Stream Power Law parameters
---------------------------

.. grid:: 1
:padding: 3

.. grid-item-card::

**Declaration example**:

.. code:: python
spl:
K: 3.e-8
d: 0.42
m: 0.4
fDa: 10.
fDm: 40.
mthd = 1
This part of the input file define the parameters for the fluvial surface processes based on the *Stream Power Law* (SPL) and is composed of:

a. ``K`` representing the erodibility coefficient which is scale-dependent and its value depend on lithology and mean precipitation rate, channel width, flood frequency, channel hydraulics. It is used in the SPL law: :math:`E = K (\bar{P}A)^m S^n`

.. warning::
It is worth noting that the coefficient *n* is fixed and take the value *1*.

b. Studies have shown that the physical strength of bedrock which varies with the degree of chemical weathering, increases systematically with local rainfall rate. Following `Murphy et al. (2016) <https://doi.org/10.1038/nature17449>`_, the stream power equation is adapted to explicitly incorporate the effect of local mean annual precipitation rate, P, on erodibility: :math:`E = (K_i P^d) (\bar{P}A)^m S^n`. ``d`` (:math:`d` in the equation) is a positive exponent that has been estimated from field-based relationships to 0.42. Its default value is set to 0.
c. ``m`` is the coefficient from the SPL law: :math:`E = K (\bar{P}A)^m S^n` and takes the default value of 0.5.
d. ``fDa`` vg
e. ``fDm`` vg
f. ``mthd`` chosen approach

Hillslope and marine deposition parameters
-------------------------------------------

.. grid:: 1
:padding: 3

.. grid-item-card::

**Declaration example**:

.. code:: python
diffusion:
hillslopeKa: 0.02
hillslopeKm: 0.2
smthDep: 20.0
clinSlp: 5.e-5
Hillslope processes in goSPL is defined using a classical *diffusion law* in which sediment deposition and erosion depend on slopes (*simple creep*). The following parameters can be tuned based on your model resolution:

a. ``hillslopeKa`` is the diffusion coefficient for the aerial domain,
b. ``hillslopeKm`` is the diffusion coefficient for the marine domain,
c. ``smthDep`` is the transport coefficient of freshly deposited sediments entering the ocean from rivers,
d. ``clinSlp`` is the maximum slope of clinoforms (needs to be positive), this slope is then used to estimate the top of the marine deposition based on distance to shore.

Sea-level (eustatic) forcing
-----------------------------

.. grid:: 1
:padding: 3

.. grid-item-card::

**Declaration example**:

.. code:: python
sea:
position: 0.
curve: 'data/sealevel.csv'
The sea-level declaration is defined with 2 optional parameters:

a. the relative sea-level ``position`` in meters (optional),
b. a sea-level ``curve`` *e.g.* a file containing 2 columns (time and sea-level position).


Tectonic forcing parameters
----------------------------

.. grid:: 1
:padding: 3

.. grid-item-card::

**Declaration example**:

.. code:: python
tectonic:
- start: -20000000.
end: -19000000.
mapH: 'input8/disp20Ma'
- start: -19000000.
end: -18000000.
mapH: 'input8/disp19Ma'
- start: -18000000.
end: -17000000.
mapH: 'input8/disp18Ma'
- start: -17000000.
end: -16000000.
mapH: 'input8/disp17Ma'
mapV: 'input8/dispv17Ma'
- start: -16000000.
end: -15000000.
mapV: 'input8/dispv16Ma'
Follows the tectonic forcing conditions with a sequence of events defined by a starting time (``start``) and either a vertical only forcing (*e.g.* uplift and/or subsidence defined with ``mapV``) or a fully 3D displacement mesh ``mapH``. These displacements are set in metres per year.


.. important::

As mentioned above and for the next key parameter as well, these forcing files are defined as numpy zip array (**.npz**).


Compaction & porosity variables defintion
------------------------------------------

.. grid:: 1
:padding: 3

.. grid-item-card::

**Declaration example**:

.. code:: python
compaction:
phis: 0.49
z0s: 3700.0
We assume a depth-porosity relationship for the sediment compaction based on the following parameters:

a. porosity at the surface ``phis``,
b. e-folding depth ``z0s`` (in metres)


Climatic (rainfall) forcing conditions
----------------------------------------

.. grid:: 1
:padding: 3

.. grid-item-card::

**Declaration example**:

.. code:: python
climate:
- start: -20000000.
map: ['input8/rain20Ma','r']
- start: -15000000.
uniform: 1.
The climatic forcing is defined in a similar fashion as the tectonic one with again a sequence of events by a starting time (``start``) and either an uniform rainfall over the entire mesh (``uniform``) or with a precipitation mesh ``map``. The rainfall values have to be in metres per year.

Orographic rain definition
---------------------------

.. grid:: 1
:padding: 3

.. grid-item-card::

**Declaration example**:

.. code:: python
orography:
latitude: 40.0
wind_speed: 10.0
wind_dir: 0
nm: 0.005
env_lapse_rate: -4
moist_lapse_rate: -7
ref_density: 7.4e-3
hw: 5000
conv_time: 1000.
fall_time: 1000.
oro_precip_base: 7.0
oro_precip_min: 0.01
rainfall_frequency: 1
This part of the input file define the parameters for the orographic rain:

a. ``latitude``: average latitude used to compute the Coriolis factors [degrees btw -90 and 90]; default 0
b. ``wind_speed``: wind speed in m/s; default 10
c. ``wind_dir``: wind direction [0: north, 270: west]; default 0
d. ``nm``: moist stability frequency [1/s]; default 0.01
e. ``env_lapse_rate``: environmental lapse rate [degrees Celsius/km]; default -4.0
f. ``moist_lapse_rate``: moist adiabatic lapse rate [degrees Celsius/km]; default -7.0
g. ``ref_density``: reference saturation water vapor density [kg/m^3]; default 7.4e-3
h. ``hw``: water vapor scale height [m]; default 3400
i. ``conv_time``: cloud water to hydrometeor conversion time [s]; default 1000
j. ``fall_time``: hydrometeor fallout time [s]; default 1000
k. ``oro_precip_base``: non-orographic, uniform precipitation rate [mm/h]; default 7.
l. ``oro_precip_min``: minimum precipitation [mm/h] when precipitation rate <= 0; default 0.01
m. ``rainfall_frequency``: number of storm of 1 hour duration per day; default 1


Forcing paleo-topography definition
-----------------------------------

.. grid:: 1
:padding: 3

.. grid-item-card::

**Declaration example**:

.. code:: python
forcepaleo:
dir: 'output-backward'
steps: [5,10,5]
For simulations that require to be forced with paleo-topography maps obtained from backward models, you will also have to set this key composed of 2 parameters:

a. ``dir`` the directory containing the outputs of the backward model,
b. ``steps`` the steps from the model outputs that will be used to force the forward model topography.

.. important::

The ``steps`` often correspond to the time where you have a paleotopography dataset that you want to match for example from a Scotese paleotopography map.

Output folder definition
-------------------------

93 changes: 93 additions & 0 deletions docs/user_guide/optfile1.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
.. _optfile1:


=================================
Climate related parameters
=================================

Sea-level (eustatic) forcing
-----------------------------

.. grid:: 1
:padding: 3

.. grid-item-card::

**Declaration example**:

.. code:: python
sea:
position: 0.
curve: 'data/sealevel.csv'
The sea-level declaration is defined with 2 optional parameters:

a. the relative sea-level ``position`` in meters (optional),
b. a sea-level ``curve`` *e.g.* a file containing 2 columns (time and sea-level position).


Climatic (rainfall) forcing conditions
----------------------------------------

.. grid:: 1
:padding: 3

.. grid-item-card::

**Declaration example**:

.. code:: python
climate:
- start: -20000000.
map: ['input8/rain20Ma','r']
- start: -15000000.
uniform: 1.
The climatic forcing is defined in a similar fashion as the tectonic one with again a sequence of events by a starting time (``start``) and either an uniform rainfall over the entire mesh (``uniform``) or with a precipitation mesh ``map``. The rainfall values have to be in metres per year.

Orographic rain definition
---------------------------

.. grid:: 1
:padding: 3

.. grid-item-card::

**Declaration example**:

.. code:: python
orography:
latitude: 40.0
wind_speed: 10.0
wind_dir: 0
nm: 0.005
env_lapse_rate: -4
moist_lapse_rate: -7
ref_density: 7.4e-3
hw: 5000
conv_time: 1000.
fall_time: 1000.
oro_precip_base: 7.0
oro_precip_min: 0.01
rainfall_frequency: 1
This part of the input file define the parameters for the orographic rain:

a. ``latitude``: average latitude used to compute the Coriolis factors [degrees btw -90 and 90]; default 0
b. ``wind_speed``: wind speed in m/s; default 10
c. ``wind_dir``: wind direction [0: north, 270: west]; default 0
d. ``nm``: moist stability frequency [1/s]; default 0.01
e. ``env_lapse_rate``: environmental lapse rate [degrees Celsius/km]; default -4.0
f. ``moist_lapse_rate``: moist adiabatic lapse rate [degrees Celsius/km]; default -7.0
g. ``ref_density``: reference saturation water vapor density [kg/m^3]; default 7.4e-3
h. ``hw``: water vapor scale height [m]; default 3400
i. ``conv_time``: cloud water to hydrometeor conversion time [s]; default 1000
j. ``fall_time``: hydrometeor fallout time [s]; default 1000
k. ``oro_precip_base``: non-orographic, uniform precipitation rate [mm/h]; default 7.
l. ``oro_precip_min``: minimum precipitation [mm/h] when precipitation rate <= 0; default 0.01
m. ``rainfall_frequency``: number of storm of 1 hour duration per day; default 1
68 changes: 68 additions & 0 deletions docs/user_guide/optfile2.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
.. _optfile2:


==============================
Tectonic related parameters
==============================

Tectonic forcing parameters
----------------------------

.. grid:: 1
:padding: 3

.. grid-item-card::

**Declaration example**:

.. code:: python
tectonic:
- start: -20000000.
end: -19000000.
mapH: 'input8/disp20Ma'
- start: -19000000.
end: -18000000.
mapH: 'input8/disp19Ma'
- start: -18000000.
end: -17000000.
mapH: 'input8/disp18Ma'
- start: -17000000.
end: -16000000.
mapH: 'input8/disp17Ma'
mapV: 'input8/dispv17Ma'
- start: -16000000.
end: -15000000.
mapV: 'input8/dispv16Ma'
Follows the tectonic forcing conditions with a sequence of events defined by a starting time (``start``) and either a vertical only forcing (*e.g.* uplift and/or subsidence defined with ``mapV``) or a fully 3D displacement mesh ``mapH``. These displacements are set in metres per year.


.. important::

As mentioned above and for the next key parameter as well, these forcing files are defined as numpy zip array (**.npz**).

Forcing paleo-topography definition
-----------------------------------

.. grid:: 1
:padding: 3

.. grid-item-card::

**Declaration example**:

.. code:: python
forcepaleo:
dir: 'output-backward'
steps: [5,10,5]
For simulations that require to be forced with paleo-topography maps obtained from backward models, you will also have to set this key composed of 2 parameters:

a. ``dir`` the directory containing the outputs of the backward model,
b. ``steps`` the steps from the model outputs that will be used to force the forward model topography.

.. important::

The ``steps`` often correspond to the time where you have a paleotopography dataset that you want to match for example from a Scotese paleotopography map.
87 changes: 87 additions & 0 deletions docs/user_guide/surfproc.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,87 @@
.. _surfproc:

=================================
Surface processes parameters
=================================

Stream Power Law parameters
---------------------------

.. grid:: 1
:padding: 3

.. grid-item-card::

**Declaration example**:

.. code:: python
spl:
K: 3.e-8
d: 0.42
m: 0.4
fDa: 10.
fDm: 40.
mthd = 1
This part of the input file define the parameters for the fluvial surface processes based on the *Stream Power Law* (SPL) and is composed of:

a. ``K`` representing the erodibility coefficient which is scale-dependent and its value depend on lithology and mean precipitation rate, channel width, flood frequency, channel hydraulics. It is used in the SPL law: :math:`E = K (\bar{P}A)^m S^n`

.. warning::
It is worth noting that the coefficient *n* is fixed and take the value *1*.

b. Studies have shown that the physical strength of bedrock which varies with the degree of chemical weathering, increases systematically with local rainfall rate. Following `Murphy et al. (2016) <https://doi.org/10.1038/nature17449>`_, the stream power equation is adapted to explicitly incorporate the effect of local mean annual precipitation rate, P, on erodibility: :math:`E = (K_i P^d) (\bar{P}A)^m S^n`. ``d`` (:math:`d` in the equation) is a positive exponent that has been estimated from field-based relationships to 0.42. Its default value is set to 0.
c. ``m`` is the coefficient from the SPL law: :math:`E = K (\bar{P}A)^m S^n` and takes the default value of 0.5.
d. ``fDa`` dimensionless deposition coefficient for continental domain
e. ``fDm`` dimensionless deposition coefficient for marine domain
f. ``mthd`` chosen approach to account for sediment deposition (should be either 1 or 2)

Hillslope and marine deposition parameters
-------------------------------------------

.. grid:: 1
:padding: 3

.. grid-item-card::

**Declaration example**:

.. code:: python
diffusion:
hillslopeKa: 0.02
hillslopeKm: 0.2
smthDep: 20.0
clinSlp: 5.e-5
Hillslope processes in goSPL is defined using a classical *diffusion law* in which sediment deposition and erosion depend on slopes (*simple creep*). The following parameters can be tuned based on your model resolution:

a. ``hillslopeKa`` is the diffusion coefficient for the aerial domain,
b. ``hillslopeKm`` is the diffusion coefficient for the marine domain,
c. ``smthDep`` is the transport coefficient of freshly deposited sediments entering the ocean from rivers,
d. ``clinSlp`` is the maximum slope of clinoforms (needs to be positive), this slope is then used to estimate the top of the marine deposition based on distance to shore.



Compaction & porosity variables definition
------------------------------------------

.. grid:: 1
:padding: 3

.. grid-item-card::

**Declaration example**:

.. code:: python
compaction:
phis: 0.49
z0s: 3700.0
We assume a depth-porosity relationship for the sediment compaction based on the following parameters:

a. porosity at the surface ``phis``,
b. e-folding depth ``z0s`` (in metres)

0 comments on commit 08bc0cf

Please sign in to comment.