API Documentation

eSCAPE is a long-term surface evolution model built to simulate landscape development, sediment transport and sedimentary basins formation from upstream regions down to marine environments.

Below you will find the nitty-gritty components of the Python code… The following API documentation provides a nearly complete description of the different functions that compose the code… ✌

Warning

It is worth mentioning that a set of fortran functions are also part of eSCAPE code but are not described in this API…

Model class

LandscapeEvolutionModel super class is the main entry point for eSCAPE and contains an inherited class (LandscapeEvolutionModelClass) that defines the following 3 main functions:

Main functions	Summary
LandscapeEvolutionModel()	Instantiates eSCAPE model object and performs surface processes evolution.
runProcesses()	Run eSCAPE Earth surface processes.
destroy()	Destroy PETSc DMPlex objects and associated Petsc local/global Vectors and Matrices.

A typical call to eSCAPE will be like this

import eSCAPE as sim

# Reading input file
model = sim.LandscapeEvolutionModel('input_globe.yml',False,False)

# Running model
model.runProcesses()

# Cleaning model
model.destroy()

eSCAPE.LandscapeEvolutionModel(filename, *args, **kwargs)

Instantiates eSCAPE model object and performs surface processes evolution.

This object contains methods for the following operations:

• initialisation of eSCAPE mesh based on input file options.
• computation of surface processes
• cleaning/destruction of PETSC objects

Args

filename : YAML input file verbose : True/False

Output option for model main functions

showlog : True/False

Output option for PETSC logging file

Returns:object Return type:LandscapeEvolutionModel

Input/Output

Declaration of input/output functions to

• Parse the YAML input file
• Write HDF5 output of computed surface parameters

Input/output classes for initialisation and evaluation of eSCAPE model.

Input functions

class eSCAPE.tools.inputparser.ReadYaml(filename)

Parsing YAML input file

Parameters:filename – input filename (.yml YAML file)

Output functions

class eSCAPE.tools.outmesh.WriteMesh(loclen=None, coords=None, dx=None, dy=None, lcells=None, lcoords=None)

Output model paramters using hdf5 library

create_OutputDir()

Create a directory to store outputs.

Mesher

Set of functions used to build PETSC DMPlex mesh and update forcing conditions such as rain, sealevel, tectonic.

Meshing module for unstructured eSCAPE grid generation.

Unstructured Mesh

class eSCAPE.mesher.unstructuredmesh.UnstMesh(filename, dim=2)

Creating a distributed DMPlex and global vector from it based on triangulated mesh

applyForces()

Find the different values for climatic and tectonic forces that will be applied to the considered time interval

destroy_DMPlex()

Destroy PETSc DMPlex objects and associated Petsc local/global Vectors and Matrices.

updateBoundaries()

Apply boundary forcing for slope and flat conditions.

Landscape evolution

Main functions used to compute surface erosion/deposition. This encompasses both river and hillslope processes.

Surface process module for hillslope and stream erosion/deposition.

Surface processes

class eSCAPE.flow.surfprocplex.SPMesh(*args, **kwargs)

Building the surface processes based on different neighbour conditions

FlowAccumulation(filled=False)

Compute multiple flow accumulation.

HillSlope()

Perform hillslope diffusion.

SedimentDiffusion()

Initialise sediment diffusion from pit and marine deposition.

cptErosion()

Compute erosion using stream power law.

cptSedFlux()

Compute sediment flux.

depositDepressions()

Compute deposition in depressions.

downSediment(Qw=None, type=0)

Transport excesss sediment volume to downstream regions.

marineDeposition()

Deposit sediment in marine environment.

Pit filling

Parallel priority-flood algorithm for unstructured mesh based on Barnes, 2016

Depressions filling module for pits determination based on priority flooding algorithm.

Depression algorithm

class eSCAPE.pit.pitfillunst.UnstPit(*args, **kwargs)

Building the priority flooding algorithm for depression determination

getDepressions()

Perform pit filling based on vertex elevation.