Required input file parameters#

Note

Input files for goSPL are based on YAML syntax. The YAML structure is shown through indentation (one or more spaces) and sequence items are denoted by a dash.

Initial mesh definition and simulation declaration#

Declaration example:

name: Description of your simulation run

domain:
    npdata: ['input/mesh','v','c','z']
    flowdir: 5
    bc:'ofof'
    fast: False
    seadepo: True
    nperodep: 'input/erodep20Ma'
    npstrata: 'input/sed20Ma'
    advect: 'iioe2'

The following parameters are required:

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

  2. the flow direction method to be used flowdir that takes an integer value between 1 (for SFD) and 6 (for MFD)

The planet geometry defaults to Earth but can be overridden to model another body (both optional): radius is the planet radius in metres (default 6378137.0) used for the spherical-mesh geometry, and gravity is the surface gravity in m/s2 (default 9.81) used by the flexural-isostasy solver. For example a Mars run would set radius: 3389500.0 and gravity: 3.71.

In addition the following optional parameters could be set:

  1. boundary conditions (bc) when not running a global model: a 4-character string, one per edge in the order north, east, south, west (N at y = ymax, E at x = xmax, S at y = ymin, W at x = xmin). Each character is:

    • o — open: a deep base-level outlet (the edge is held below sea level); water and the sediment it carries drain out across it.

    • f — fixed: a base-level outlet at the natural edge elevation; flow and sediment still leave the domain there (this is not a no-flux wall).

    • w — wall: a true no-flux wall; flow is contained and sediment deposits against the edge instead of draining out.

    Legacy digits are accepted: 0 is read as o (open) and 1 as f (fixed). The default is 'oooo'. For example 'ofof' opens north/south with fixed east/west; 'wfwf' walls north/south with fixed east/west.

    Note

    The w (wall) boundary contains flow, and deposits the sediment that reaches the closed edge. A domain that is fully enclosed by walls (no o/f/marine exit anywhere) conserves sediment over a single step, but not indefinitely once its basins fill: goSPL’s spill-based sediment cascade cannot aggrade a fully-closed basin (it assumes excess always spills toward an outlet). Combine walls with at least one o/f edge (or a marine area) for a fully mass-conserving long run.

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

  3. seadepo performing marine deposition or not. By default it is set to True.

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

  5. 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. An optional stratK key (same (mesh_points, init_layers) shape) may be provided to impose a per-layer erodibility multiplier. When the layer is exposed at the surface, the effective SPL erodibility becomes K * stratK where K is the value declared in the spl block. Values < 1 model softer-than-default bedrock; values > 1 model more resistant lithologies; the default (key absent, or value 1.0) keeps the SPL behaviour unchanged. Sediment eroded from such a layer and re-deposited downstream loses the multiplier and reverts to 1.0 (i.e. the YAML-default K).

  6. when dual lithology is enabled (strata: dual: True), two further optional keys (same (mesh_points, init_layers) shape) let each initial layer carry its own per-vertex coarse/fine composition: strataHf is the fine-fraction bulk thickness of each layer (so the coarse thickness is strataH - strataHf, and the per-layer fine fraction is strataHf / strataH), and phiF is the per-layer fine porosity. Because both arrays are indexed by vertex and by layer, the initial sand/mud distribution can vary freely across the mesh and with depth (see the per-vertex recipe in the note below). strataHf is clamped to [0, strataH] on load; if it is absent the initial column is all-coarse (a rank-0 warning is printed under dual lithology), and if phiF is absent it defaults to the fine surface porosity phi0f. These keys are ignored (with a warning) when dual lithology is off. The required fields (strataH/strataZ/phiS) and the shape consistency of every layer array are validated on load, so a missing field or a mismatched shape stops the run with a clear error rather than failing cryptically later. Running with -v prints a one-line summary of the stratigraphy setup (mode, compaction curves, layer count, whether a per-vertex composition was supplied, and the bedrock-floor model).

  7. advect define the advection scheme used when applying horizontal displacements. Choices are upwind, iioe1, iioe2 and interp (go to the technical information in the documentation for more information).

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.

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, and ed the erosion deposition node values and call it for both the npdata and nperodep parameters.

Note

Setting a per-vertex initial coarse/fine distribution (dual lithology). To prescribe how sand (coarse) and mud (fine) are distributed across the mesh at the start of a dual-lithology run, build the npstrata file with the optional strataHf (and phiF) arrays alongside the mandatory strataH/strataZ/phiS. Every array is shaped (mesh_points, init_layers) — one row per global mesh vertex, one column per initial layer (deepest layer first). The per-vertex, per-layer fine fraction is simply strataHf / strataH:

import numpy as np

mpoints, nlayers = mesh_vertices, 3
strataH = np.full((mpoints, nlayers), 50.0)          # 50 m thick layers
strataZ = np.zeros((mpoints, nlayers))               # deposition elevation
phiS    = np.full((mpoints, nlayers), 0.49)          # coarse porosity

# Per-vertex fine fraction (e.g. muddier basin centre, sandier margins):
fine_frac = my_spatial_fine_fraction(mpoints, nlayers)   # in [0, 1]
strataHf  = fine_frac * strataH                          # fine bulk thickness
phiF      = np.full((mpoints, nlayers), 0.63)            # fine porosity

np.savez("input/init_strata",
         strataH=strataH, strataZ=strataZ, phiS=phiS,
         strataHf=strataHf, phiF=phiF)

Reference it with npstrata: 'input/init_strata' and enable strata: dual: True. Add strata: bedrock_sentinel: True to place a dedicated, infinite bedrock reservoir (composition bedrock_coarse_frac) beneath these finite layers, so erosion that exhumes the whole initial pile then taps bedrock rather than the deepest supplied layer.

Setting model temporal evolution#

Declaration example:

time:
    start: -20000000.
    end: 0.
    dt: 250000.
    tout: 1000000.
    rstep: 25
    strat: 500000.

time is also a required component of every input file. The following parameters are needed:

  1. start is the model start time in years,

  2. end is the model end time in years,

  3. dt is the model internal time step (the approach in goSPL uses an implicit time step).

  4. tout is the output interval used to create model outputs.

The following parameters are optional:

  1. to restart a simulation use the rstep key and specify the time step number.

  2. strat is the stratigraphic timestep interval used to update the stratigraphic record.

Important

In cases where the specify dt and strat parameters are greater than tout, they will automatically be rescaled to match with the output interval. 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#

Declaration example:

output:
    dir: 'forward'
    makedir: False

Finally, you will need to specify the output folder, with 2 possible parameters:

  1. dir gives the output directory name.

The following parameter is optional:

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