Class ReadYaml#

class tools.inputparser.ReadYaml(filename)[source]#

Class for reading simulation input file and initialising model parameters.

Definition of input parameters is provided in the User Documentation

Initialise

__init__(filename)

Parsing YAML file.

Private Methods

`_get_param`(*keys[, default])	Safe traversal into `self.input`.
`_restartUpdate`()	Update some forcing parameters in case of a restart.
`_readDomain`()	Read domain definition, boundary conditions and flow direction parameters.
`_extraDomain`()	Read domain additional information.
`_extraDomain2`()	Read domain additional information.
`_readTime`()	Read simulation time declaration.
`_addTime`(timeDict)	Read additional time parameters.
`_readSPL`()	Read surface processes erosion and deposition laws parameters.
`_readHillslope`()	Read hillslope parameters.
`_extraHillslope`()	Read extra hillslope parameters.
`_readSoilInfo`()	Read soil information parameters.
`_readSealevel`()	Define sealevel evolution.
`_isKeyinFile`(dmap)	Check if a numpy compressed file exists and that the corresponding keys are present in it.
`_storeTectonics`(k, tecStart, hMap, tMap, ...)	Record tectonic conditions.
`_defineTectonics`(k, tecSort, tecdata)	Define tectonics conditions.
`_readTectonics`()	Parse tectonics forcing conditions.
`_defineErofactor`(k, sStart, sMap, sUniform, ...)	Define sediment surface erodibility factor conditions.
`_readErofactor`()	Parse erodibility factor based on surface geology.
`_getTe`(k, tStart, tMap, tUniform, tedata)	Define elastic map.
`_readTeMap`()	Parse elastic map forcing conditions.
`_defineRain`(k, rStart, rMap, rUniform, ...)	Define precipitation conditions.
`_defineEvap`(k, eStart, eMap, eUniform, evapdata)	Define evaporation conditions for one climate event.
`_readRain`()	Parse rain and evaporation forcing conditions.
`_readCompaction`()	Read compaction parameters.
`_extraStrata`()	Parse the optional dual-lithology (coarse/fine) stratigraphy block.
`_extraProvenance`()	Parse the optional in-model sediment-provenance tracer block.
`_readFlex`()	Parse flexural isostasy variables.
`_extraFlex`()	Read flexure additional information.
`_readOrography`()	Parse orographic precipitation variables.
`_extraOrography`(oroDict)	Read domain additional information.
`_readIce`()	Parse ice flow variables.
`_iceGeomField`(val)	Split a glacier-geometry input (`hela`/`hice`/`hterm`) into a scalar fallback and an optional `[file, key]` map spec.
`_buildIceSeries`(glaciers, elaTop, iceTop, ...)	Build the glacier-geometry time series consumed by `_updateIce`.
`_extraIce`(icefile, elaH, iceH, iceT)	Legacy uniform glacier geometry: build the scalar time functions `self.iceT` / `self.elaH` / `self.iceH` from an `evol` CSV or from constant `hterm` / `hela` / `hice`.
`_checkMap`(spec, name)	Validate that a `[file, key]` npz map exists and contains the field, without loading the (potentially large) array.
`_loadIceMap`(spec, name)	Load a per-vertex glacier-geometry map (full-mesh array) from a validated `[file, key]` npz spec — the same convention as the precipitation/tectonic maps.
`_readOut`()	Parse output directory.

Private functions#

ReadYaml._get_param(*keys, default=None)[source]#

Safe traversal into self.input.

Returns default (None by default) if any key in the chain is missing, or if an intermediate node is not a dict. Never raises KeyError.

Examples:

self._get_param("name")                  # self.input.get("name", default)
self._get_param("domain", "flowdir")     # self.input["domain"].get("flowdir", default)
self._get_param("spl", "K", default=1e-12)

Use this for direct access through self.input. For inner keys on a pre-extracted section dict (e.g. splDict = self.input["spl"] bound on an earlier line), prefer the Python builtin splDict.get(key, default) — it makes the data flow more visible and avoids a redundant top-level lookup.

Out of scope: this helper navigates self.input only. For NPZ-archive accesses elsewhere in this file (_isKeyinFile, the rainKey/sedKey blocks inside _readRain/_readErofactor/ _readTeMap), keep the existing try/except KeyError since those exceptions carry user-facing diagnostics about missing fields in the data file.

See AGENTS.md > The _extra* methods are mandatory continuations: the call chain (_readDomain → _extraDomain → _extraDomain2, _readHillslope → _extraHillslope, etc.) is load-bearing. The internal try/except KeyError blocks inside those methods are NOT load-bearing and use this helper.

ReadYaml._restartUpdate()[source]#: Update some forcing parameters in case of a restart.

ReadYaml._readDomain()[source]#: Read domain definition, boundary conditions and flow direction parameters.

ReadYaml._extraDomain()[source]#: Read domain additional information.

ReadYaml._extraDomain2()[source]#: Read domain additional information.

ReadYaml._readTime()[source]#: Read simulation time declaration.

ReadYaml._addTime(timeDict)[source]#: Read additional time parameters.

ReadYaml._readSPL()[source]#: Read surface processes erosion and deposition laws parameters.

ReadYaml._readHillslope()[source]#: Read hillslope parameters.

ReadYaml._extraHillslope()[source]#: Read extra hillslope parameters.

ReadYaml._readSoilInfo()[source]#: Read soil information parameters.

ReadYaml._readSealevel()[source]#: Define sealevel evolution.

ReadYaml._isKeyinFile(dmap)[source]#: Check if a numpy compressed file exists and that the corresponding keys are present in it.

ReadYaml._storeTectonics(k, tecStart, hMap, tMap, zMap, tecEnd, tecdata)[source]#

Record tectonic conditions.

Parameters:

k – tectonic event number
tecStart – tectonic event start time
hMap – horizontal tectonic information
tMap – vertical tectonic displacement information
zMap – elevation information
tEnd – tectonic event end time
tecdata – pandas dataframe storing each tectonic event

Returns:

appended tecdata

ReadYaml._defineTectonics(k, tecSort, tecdata)[source]#

Define tectonics conditions.

Parameters:

k – tectonic event number
tecSort – sorted tectonic event
tecdata – pandas dataframe storing each tectonic event

Returns:

appended tecdata

ReadYaml._readTectonics()[source]#: Parse tectonics forcing conditions.

ReadYaml._defineErofactor(k, sStart, sMap, sUniform, sedfacdata)[source]#

Define sediment surface erodibility factor conditions.

Parameters:

k – erodibility factor map number
sStart – erodibility factor map start time
sMap – erodibility factor map file event
sUniform – erodibility factor uniform value event
sedfacdata – pandas dataframe storing each erodibility factor map

Returns:

appended sedfacdata

ReadYaml._readErofactor()[source]#: Parse erodibility factor based on surface geology.

ReadYaml._getTe(k, tStart, tMap, tUniform, tedata)[source]#

Define elastic map.

Parameters:

k – elastic map event number
teStart – elastic map event start time
teMap – elastic map file event
teUniform – elastic map uniform thickness value event
tedata – pandas dataframe storing each elastic map event

Returns:

appended tedata

ReadYaml._readTeMap()[source]#: Parse elastic map forcing conditions.

ReadYaml._defineRain(k, rStart, rMap, rUniform, rZscale, raindata)[source]#

Define precipitation conditions.

Parameters:

k – precipitation event number
rStart – precipitation event start time
rMap – precipitation map file event
rUniform – precipitation uniform value event
rZscale – precipitation scaled with elevation value event
raindata – pandas dataframe storing each precipitation event

Returns:

appended raindata

ReadYaml._defineEvap(k, eStart, eMap, eUniform, evapdata)[source]#

Define evaporation conditions for one climate event.

Mirrors _defineRain but for evaporation. Evaporation is opt-in per-row: if both eMap and eUniform are None for this event, evapdata is returned unchanged (no row appended).

Parameters:

k – climate event number
eStart – event start time
eMap – evaporation map (tuple of path+key) or None
eUniform – evaporation uniform scalar (m/yr) or None
evapdata – pandas dataframe storing each evaporation event (or None on first call)

Returns:

appended evapdata (or unchanged if this row has no evap)

ReadYaml._readRain()[source]#

Parse rain and evaporation forcing conditions.

Both share the same [climate] YAML block. Each climate event row may declare rainfall (uniform/map/zscale) and, optionally, evaporation (evap_uniform/evap_map). Evaporation is opt-in: if no row has an evap field, self.evapdata ends up as None and the downstream solver bypasses both evap hooks.

ReadYaml._readCompaction()[source]#: Read compaction parameters.

ReadYaml._extraStrata()[source]#

Parse the optional dual-lithology (coarse/fine) stratigraphy block.

Continuation of _readCompaction (the coarse porosity curve defaults to the single-fraction compaction values, so a model with strata: dual: False — or no strata block at all — runs the existing single-fraction path bitwise-unchanged).

Sets self.stratLith (master opt-in flag) plus the per-lithology parameters consumed by later phases (porosity-depth curves, bedrock composition, marine fine transport efficiency, per-fraction lake inlet bias, and subaerial/subaqueous diffusivities). All of these are inert while self.stratLith is False.

Dual lithology is only meaningful when stratigraphy recording is on; if requested with stratigraphy disabled (self.stratNb == 0) the flag is forced back to False with a rank-0 warning.

See docs/DESIGN_DUAL_LITHOLOGY.md and AGENTS.md > The _extra* methods are mandatory continuations.

ReadYaml._extraProvenance()[source]#

Parse the optional in-model sediment-provenance tracer block. N source-rock classes are carried (as a passive label — no physics feedback) through erosion, transport, deposition and the stratigraphic record, giving conservation-exact, recycling-aware provenance per layer. See docs/DESIGN_PROVENANCE.md §6.

Sets self.provOn (master opt-in), self.provNb (class count), the per-vertex source-class source (uniform scalar or source [file, key] map, resolved post-mesh in readStratLayers), and an optional cu_weight. All inert while provOn is False; like dual lithology it requires stratigraphy (stratNb > 0).

ReadYaml._readFlex()[source]#: Parse flexural isostasy variables.

ReadYaml._extraFlex()[source]#: Read flexure additional information.

ReadYaml._readOrography()[source]#: Parse orographic precipitation variables.

ReadYaml._extraOrography(oroDict)[source]#: Read domain additional information.

ReadYaml._readIce()[source]#: Parse ice flow variables.

ReadYaml._iceGeomField(val)[source]#

Split a glacier-geometry input (hela/hice/hterm) into a scalar fallback and an optional [file, key] map spec. A list/tuple value is a per-vertex npz map; anything else is a uniform scalar.

Returns:: (scalar_or_None, map_spec_or_None)

ReadYaml._buildIceSeries(glaciers, elaTop, iceTop, termTop)[source]#

Build the glacier-geometry time series consumed by _updateIce.

glaciers (when given) is a list of {start, hela, hice, hterm} events (each altitude uniform-or-map); otherwise the top-level hela/hice/hterm define a single interval starting at tStart. Each interval stores, per field, a (scalar, map_spec) pair (exactly one is non-None). Map files/keys are validated here; the arrays are loaded lazily on interval change in _updateIce.

Returns:: list of intervals sorted by start time.

ReadYaml._extraIce(icefile, elaH, iceH, iceT)[source]#: Legacy uniform glacier geometry: build the scalar time functions self.iceT / self.elaH / self.iceH from an evol CSV or from constant hterm / hela / hice. The per-vertex / time-series map path is handled separately by _buildIceSeries + _updateIce.

ReadYaml._checkMap(spec, name)[source]#: Validate that a [file, key] npz map exists and contains the field, without loading the (potentially large) array. Used at parse time for the glacier-geometry maps; the array is loaded lazily by _loadIceMap on interval change.

ReadYaml._loadIceMap(spec, name)[source]#: Load a per-vertex glacier-geometry map (full-mesh array) from a validated [file, key] npz spec — the same convention as the precipitation/tectonic maps.

ReadYaml._readOut()[source]#: Parse output directory.