From 08bc0cf85747c60bb1c481d2848ff2159cff469e Mon Sep 17 00:00:00 2001 From: Tristan Salles Date: Mon, 24 Jun 2024 16:32:23 +1000 Subject: [PATCH] add user guide input definitions --- docs/user_guide/index.rst | 146 ++++++++++++++++++-- docs/user_guide/inputfile.rst | 248 +--------------------------------- docs/user_guide/optfile1.rst | 93 +++++++++++++ docs/user_guide/optfile2.rst | 68 ++++++++++ docs/user_guide/surfproc.rst | 87 ++++++++++++ 5 files changed, 384 insertions(+), 258 deletions(-) create mode 100644 docs/user_guide/optfile1.rst create mode 100644 docs/user_guide/optfile2.rst create mode 100644 docs/user_guide/surfproc.rst diff --git a/docs/user_guide/index.rst b/docs/user_guide/index.rst index 14a71da..b63d69e 100644 --- a/docs/user_guide/index.rst +++ b/docs/user_guide/index.rst @@ -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 `_ 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 `_. For additional examples, you might be interested in the following set of examples available from the `Stellar-SFM project `_. + - 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 `_. + + For additional examples, you might be interested in the following set of examples available from the `Stellar-SFM project `_. + +.. warning:: + + `Stellar-SFM project `_ 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 `_ 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 diff --git a/docs/user_guide/inputfile.rst b/docs/user_guide/inputfile.rst index 484d822..6938d39 100644 --- a/docs/user_guide/inputfile.rst +++ b/docs/user_guide/inputfile.rst @@ -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) `_, 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 ------------------------- diff --git a/docs/user_guide/optfile1.rst b/docs/user_guide/optfile1.rst new file mode 100644 index 0000000..d5d70e2 --- /dev/null +++ b/docs/user_guide/optfile1.rst @@ -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 \ No newline at end of file diff --git a/docs/user_guide/optfile2.rst b/docs/user_guide/optfile2.rst new file mode 100644 index 0000000..0a566dd --- /dev/null +++ b/docs/user_guide/optfile2.rst @@ -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. diff --git a/docs/user_guide/surfproc.rst b/docs/user_guide/surfproc.rst new file mode 100644 index 0000000..334d604 --- /dev/null +++ b/docs/user_guide/surfproc.rst @@ -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) `_, 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) +