Climate related parameters#

Sea-level (eustatic) forcing#

Note

By default, the sea-level position in goSPL is set to 0 m. If you wish to set it to another position you can use the position key that changes the sea-level to a new value relative to sea-level. Another option consists in defining your own sea-level curve (curve) or using a published one (e.g. Haq curve for example).

Declaration example:

sea:
    position: 0.
    curve: 'sealevel.csv'

The sea-level declaration is defined with 2 optional parameters:

the relative sea-level position in meters (optional), its default value is set to 0.0
a sea-level curve e.g. a file containing 2 columns (time and sea-level position). Not required in case no sea-level fluctuations needs to be specified.

Important

The sea-level curve is defined as a 2 columns csv file containing in the first column the time in years (it doesn’t need to be regularly temporally spaced) and in the second the sea-level position for the given time. When goSPL interprets this file, it will interpolate linearly between the defined times to find the position of the sea-level for every time step.

Climatic (rainfall) forcing conditions#

Declaration example:

climate:
    - start: 1000.
      map: ['rain_map','r']
    - start: 20000.
      uniform: 1.
    - start: 30000.
      zscale: [0.0008, 0.5]

The climatic forcing is defined in a similar fashion as the tectonic one. It is based on a sequence of events with each event starting at a given time (start in years) and corresponding to a given precipitation condition. Each event must specify one of three rainfall sources:

uniform — a single rainfall value (m/yr) applied across the whole mesh.
map — a path-and-key pair pointing at a precipitation grid stored in an .npz file (e.g. ['rain_map', 'r'] where 'r' is the key holding the per-vertex values, in m/yr).
zscale — a two-element list [A, B] that makes the rainfall scale linearly with elevation at every node and every time step: \(\mathrm{P_i = A \cdot \eta_i + B}\) (clamped to non-negative values), where \(\mathrm{\eta_i}\) is the current surface elevation in metres and \(\mathrm{P_i}\) is the resulting precipitation rate in m/yr. A is therefore in (m/yr) per m and B is the sea-level intercept in m/yr.

The precipitation field is re-evaluated at every time step (defined by dt). For zscale this means the rain pattern follows the evolving topography — newly uplifted regions wet, eroded regions dry — without needing pre-baked maps for every snapshot.

Important

When defining a precipitation grid, one needs to use the npz format and needs to specify the key corresponding to the precipitation variable in the file. In the above example this key is 'r'. The precipitation grid needs to define values for all vertices in the mesh.

Note

The zscale option is a cheap proxy for orographic precipitation: it captures the first-order increase in rainfall with elevation but ignores wind direction, atmospheric dynamics, and rain-shadow effects. For the full orographic precipitation model — including airflow, condensation, and downwind drying — see the dedicated Orographic precipitation section below.

Negative values of \(\mathrm{P_i}\) (which can occur for low B and sub-sea-level nodes) are clamped to zero before being routed through the flow accumulation, so coastal depressions do not act as moisture sinks.

Evaporation (optional)#

Each climate event may additionally declare an evaporation rate that is subtracted from runoff before river flow accumulation and from lake-surface inflow before pit overflow. Evaporation is opt-in per event — any row that omits both keys contributes zero evaporation for the corresponding interval, so existing input files are unaffected.

Declaration example:

climate:
    - start: 0.
      uniform: 1.0
      evap_uniform: 0.3
    - start: 50000.
      map: ['rain_map', 'r']
      evap_map: ['evap_map', 'e']
    - start: 100000.
      uniform: 0.5
      # no evap_* key — evaporation is zero for this interval

Two source types are supported:

evap_uniform — a single evaporation rate (m/yr) applied at every land node.
evap_map — a path-and-key pair pointing at a per-vertex evaporation grid stored in an .npz file, matching the same convention as the map rainfall source.

Elevation-banded evaporation (an analogue of zscale) is not yet supported.

Note

Evaporation is applied as a single rate, used identically over channels and over lake surfaces. Cells with evap > rain produce zero runoff (the excess evaporative capacity is dropped — groundwater is out of scope). Lakes whose lake-surface evaporation budget exceeds their inflow simply do not form; waterFill stays at the bare-topography level in those depressions.

The lake-evaporation budget per depression is computed using the maximum-fill surface area (the full extent the lake would occupy at spillover) rather than the actual fill area. This is intentionally conservative: it over-estimates lake evaporation at partial-fill levels, which biases the model towards drier basins — the physically appropriate direction when potential evaporation is the limiting term.

Channels and lakes share the same per-cell rate; users who need a higher lake-surface rate (e.g. to capture open-water evaporation over endorheic basins) should encode the spatial pattern directly in evap_map.

Important

The Evap per-node field is written to the HDF5/XDMF output whenever the YAML declares any evaporation; it can be visualised in Paraview alongside Rain to verify the input pattern. The reduced flow accumulation FA, the reduced lake levels in waterFill, and the lake-erosion proxy fillFA all propagate the evaporation losses automatically.

Orographic precipitation definition#

Warning

The orographic precipitation is only available for 2D grids and will not be working for global models.

goSPL implements the Linear Theory of Orographic Precipitation following Smith & Barstad (2004).

Note

The model includes airflow dynamics, condensed water advection, and downslope evaporation. It consists of two vertically-integrated steady-state advection equations describing:

the cloud water density and
the hydrometeor density.

Solving these equations using Fourier transform techniques, derives a single formula relating terrain and precipitation.

Declaration example:

orography:
    regdx: 200.
    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:

regdx: the resolution of the regular grid used to perform the orographic rain calculation.

Important

If both orographic rain and flexure are turned-on then the regdx values will have to be the same.

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

Warning

In case you missed it above: when flexure and orographic rain capabilities are defined in the same simulation, you will need to have the same grid resolution (regdx) for each definition.