Getting started with eSCAPE

Earth Landscape (eSCAPE) is a long-term surface evolution model, built to simulate topography dynamic, sediment transport and sedimentary basins formation at various space and time scales.

---

What’s eSCAPE?

eSCAPE is an open-source Python-based code and can be used to simulate:

• hillslope processes (soil creep using linear diffusion),
• fluvial incision (stream power law),
• sediment transport and deposition,
• spatially and temporally varying tectonics (vertical displacements) and
• climatic forces (rainfall) and/or sea-level fluctuations.

---

Installation

We provide two ways to use eSCAPE from:

• the docker image or
• from a local install via setuptools.

---

Docker

If you like the live demo, you can install eSCAPE via Docker!

Docker is a type of lightweight virtualisation, and is the preferred method for eSCAPE usage on personal computers. You will first need to install Docker on your system, and then you may install eSCAPE via Docker.

Note

Docker may be driven from the command line, but new users may wish to use the Docker Kitematic GUI instead for ease.

Simply search for escape-docker within Kitematic, and then click ‘CREATE’ to launch a container. You will eventually wish to modify your container settings (again through Kitematic) to enable local folder volume mapping, which will allow you to access your local drives within your container.

For Linux users, and those who prefer the command line, the following minimal command should be sufficient to access the badlands Jupyter Notebook examples:

docker pull geodels/escape-docker

Once downloaded you will now be able to run eSCAPE locally.

Important

You only need to pull the image once. Once it is installed you will only have to run the following command to start the code.

docker run -it -p 8888:8888 -v "$PWD":/live/share geodels/escape-docker

Navigate to localhost:8888 to see the notebooks.

This command will create a new container using the escape-docker image. Note that it will first check to see if the image exists locally, and otherwise will download a copy from the Docker Hub. This will only happen the first time you run the command; subsequent execution will use the downloaded image.

Once the new instance is created, eSCAPE image is launched within the container. Note that we also pass an option of the form -p host_port:docker_port which tells docker to perform a port mapping from the docker instance to the host. This allows us to use our native web browser to access the active docker notebook instance at http://localhost:8888/.

For interactive processes (like a shell), we must use -i -t together in order to allocate a tty for the container process. -i -t is often written -it as see in the command above.

Finally, the -v command or --volume=[host-src:]container-dest attach a volume or folder from the local computer to the container shared folder (here /live/share). The host-src is an absolute path or a name value and in the command above correspond to the place where the command is run from.

Tip

A step by step guide on how to use the eSCAPE docker image is provided here. 💣

Local installation

Below is a step by step guide to install eSCAPE on Linux system.

Update your system and install default packages

apt-get update -qq
apt-get install -yq --no-install-recommends bash-completion build-essential
apt-get install -yq --no-install-recommends python3-minimal python3-dev python3-pip
apt-get install -yq --no-install-recommends python3-tk python3-dbg cmake
apt-get install -yq --no-install-recommends python3-setuptools wget gfortran

MPI

MPICH_VERSION="3.3"
MPICH_CONFIGURE_OPTIONS="--enable-fast=all,O3 --prefix=/opt/mpich"
MPICH_MAKE_OPTIONS="-j4"

mkdir /tmp/mpich-build
wget http://www.mpich.org/static/downloads/${MPICH_VERSION}/mpich-${MPICH_VERSION}.tar.gz
tar xvzf mpich-${MPICH_VERSION}.tar.gz
cd mpich-${MPICH_VERSION}
./configure ${MPICH_CONFIGURE_OPTIONS}
make ${MPICH_MAKE_OPTIONS}
make install
ldconfig
cd /tmp
rm -fr *

export MPI_DIR=/opt/mpich
export PATH=${MPI_DIR}/bin:$PATH

PIP installation

pip3 install -U setuptools
pip3 install -U wheel
pip3 install --no-cache-dir numpy jupyter ipython plotly
pip3 install --no-cache-dir matplotlib ipython scipy
MPICC=${MPI_DIR}/mpicc MPICXX=${MPI_DIR}/mpicxx MPIFC=${MPI_DIR}/mpifort pip3 install --no-cache-dir mpi4py

PETSC

mkdir /tmp/petsc-build
export PETSC_VERSION="3.11.2"
wget http://ftp.mcs.anl.gov/pub/petsc/release-snapshots/petsc-lite-${PETSC_VERSION}.tar.gz
tar zxf petsc-lite-${PETSC_VERSION}.tar.gz && cd petsc-${PETSC_VERSION}

Configure:

./configure --with-debugging=0 --prefix=/opt/petsc
        --COPTFLAGS="-g -O3" --CXXOPTFLAGS="-g -O3" --FOPTFLAGS="-g -O3"
        --with-zlib=1
        --download-fblaslapack=1
        --download-ctetgen=1
        --download-triangle=1
        --download-hdf5=1
        --download-mumps=1
        --download-parmetis=1
        --download-metis=1
        --download-hypre=1
        --download-scalapack=1
        --useThreads=1
        --with-shared-libraries
        --with-cxx-dialect=C++11

Install:

make PETSC_DIR=/tmp/petsc-build/petsc-${PETSC_VERSION} PETSC_ARCH=arch-linux-c-opt all
make PETSC_DIR=/tmp/petsc-build/petsc-${PETSC_VERSION} PETSC_ARCH=arch-linux-c-opt install
make PETSC_DIR=/opt/petsc PETSC_ARCH="" test

Clean:

cd /tmp
rm -fr *
export PETSC_DIR=/opt/petsc
export PATH=${PETSC_DIR}/bin:$PATH

Additional dependencies for eSCAPE

First HDF5 and PETSC4PY

export PYTHONPATH=$PYTHONPATH:/usr/lib
CC=h5pcc HDF5_MPI="ON" HDF5_DIR=${PETSC_DIR} python3 -m pip install --no-cache-dir --no-binary=h5py h5py python3 -m pip install --no-cache-dir petsc4py

Fillit

mkdir /workspace/lib
export F90=gfortran
git clone -b python3 https://github.com/Geodels/fillit.git
cd fillit
python3 setup.py install

and using pip:

pip3 install pandas meshio rasterio meshplex ruamel.yaml

Install eSCAPE

cd /workspace/lib
git clone -b petsc3.11.2 https://github.com/Geodels/eSCAPE.git
cd eSCAPE
export F90=gfortran
export PETSC_DIR=/opt/petsc
export PETSC_ARCH=arch-linux-c-opt
python setup.py install
cd ..

Install eSCAPE-demo

cd examples
git clone -b petsc3.11.2 https://github.com/Geodels/eSCAPE-demo.git

Notebook packages

To run eSCAPE-demo and build the triangular meshes required by eSCAPE several packages are needed:

apt-get update -qq
apt-get install -yq --no-install-recommends gmsh python3-gdal gdal-bin
apt-get install -yq --no-install-recommends libgeos++ libgeos-dev libgdal-dev libproj-dev

and

pip3 install setuptools wheel
pip3 install pathlib shapely descartes geopy pygeotools pygmsh stripy

GMT color scale…

git clone https://github.com/j08lue/pycpt.git
cd pycpt
git checkout b45f720d09da79bcd567c5cbba9a554b0a7cc1d9
python3 setup.py install
cd ..
rm -rf pycpt

HPC installation

List of required compilers

The HPC installation has been tested with both GNU fortran compiler (5.4.0) and Intel-mkl ifort (18.0.1) compiler.

Important

major.minor versions of Python - eSCAPE is compatible with Python version (2.7.x, 3.5.x and above). Python version 2.7.15 has been tested on HPC.

Dependencies

Before you begin compiling eSCAPE and its dependencies, make sure you have set up your computer environment to include Python (2.7 and above), MPI implementation and a supported fortran compiler (gfortran and ifort have been tested).

Warning

eSCAPE requires the PETSc library and petsc4py package. On HPC platforms, the PETSc library is often a default module. If this is not the case you can follow the guide provided in the local installation page.

You will then need to have several other dependencies installed as pip packages. You can check which of them will need to be installed by opening a Python kernel and performing the following set of commands:

import numpy
import pandas
import scipy
from mpi4py import MPI
from petsc4py import PETSc
import ruamel.yaml as yaml
import meshio

If some of these packages are not installed you can install them via pip:

pip install XXX [--user]

where XXX is the missing package.

For petsc4py it is necessary to set the environment variables PETSC_DIR and PETSC_ARCH to their appropriate values (which will depend on your HPC installation):

export PETSC_DIR=\path\to\petsc\location
export PETSC_ARCH=petsc-arch-values
pip install [--user] petsc4py

Custom packages

Two additional packages are required prior to eSCAPE installation:

• meshplex
• fillit

The meshplex package could be installed with pip:

pip install [--user] meshplex

In case you encounter some difficulties during installation related to fastfunc dependency, one can used the following forked version:

git clone https://github.com/Geodels/meshplex.git
cd meshplex
python setup.py install [--user]
cd ..

And fillit is installed using the following set of commands:

export F90=fortran-compiler
git clone https://github.com/Geodels/fillit.git
cd fillit
python setup.py install [--user]

where fortran-compiler needs to be replaced with the fortran compiler used to build PETSC (this will depend of the HPC installation but will likely be gfortran or ifort)

eSCAPE

OK, now that all dependencies are installed we can finally proceed with eSCAPE:

git clone https://github.com/Geodels/eSCAPE.git
cd eSCAPE
python setup.py install [--user]

Testing installation

You can then do a simple test to check that all packages have been successfully installed by starting a python kernel and importing each module individually:

import numpy
import pandas
import scipy
from mpi4py import MPI
from petsc4py import PETSc
import ruamel.yaml as yaml
import meshio
import meshplex
import fillit
import eSCAPE

Example of installation on HPC platform

USyD Artemis HPC

module purge
module load python/2.7.15-intel petsc-intel-mpi hdf5
export F90=ifort
git clone https://github.com/Geodels/fillit.git
cd fillit
python setup.py install --user

git clone https://github.com/Geodels/eSCAPE.git
cd eSCAPE
python setup.py install --user

Input description

Important

In eSCAPE, a YAML input file (syntax) is used to set the parameters and conditions that apply to a given simulation. YAML structure is done through indentation (one or more spaces) and sequence items are denoted by a dash. When parsing the input file, the code is searching for some specific keywords defined below. Some parameters are optional and only need to be set when specific forces or physical processes are applied to a particular experiment.

Here we present the complete list of parameters that can be used in the current version of the code.

name: Description of the simulation...

domain:
  filename: ['data/inputfileparameters.vtk','Z']
  flowdir: 5
  bc: 'slope'
  sphere: 0

time:
  start: 0.
  end: 1000000.
  tout: 1000.
  dt: 100.

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

climate:
  - start: 0.
    uniform: 1.0
  - start: 500000.
    map: ['data/inputfileparameters.vtk','R']
  - start: 500000.
    uniform: 2.0

tectonic:
  - start: 0.
    mapZ: ['data/inputfileparameters.vtk','T1']
  - start: 100000.
    uniform: 0.
  - start: 50000.
    mapZ: ['data/inputfileparameters.vtk','T2']

sp_br:
  Kbr: 1.e-5

sp_dep:
  Ff: 0.3

diffusion:
  hillslopeK: 5.e-2
  sedimentK: 300.

output:
  dir: 'outputDir'
  makedir: False

Tip

All the input parameters that are defined in external files like the initial surface, different precipitation or displacement maps are read from VTK files and defined on an irregular triangular grid (TIN).

Examples on how to produce these files are provided in the demo folder. The only exception is the sea-level file which is a two-columns CSV file containing on the first column the time in years and ordered in ascending order and on the second one the relative position of the sea-level in metres.

The YAML structure is shown through indentation (one or more spaces) and sequence items are denoted by a dash. At the moment the following component are available:

Input parameters relative to initial surface, temporal extent and output.

The domain and time keywords are required for any simulation.

Domain

name: Description of the simulation...

domain:
  filename: ['data/inputfileparameters.vtk','Z']
  flowdir: 5
  bc: 'slope'
  sphere: 0

domain : definition of the unstructured grid containing the vtk grid filename and the associated field (here called Z) as well as the flow direction method to be used flowdir that takes an integer value between 1 (for SFD) and 12 (for Dinf) and the boundary conditions (bc: ‘flat’, ‘fixed’ or ‘slope’)

Tip

The ‘flat’ option assumes that all edges elevations are set to the elevations of their closest non-edge vertices, the ‘fixed’ option is used when edges elevations need to remain at their initial positions during the model run and the ‘slope’ option defines a slope based on the closest non-edge node average slope.

Schematic diagram (in a) showing flow paths when considering a triangular irregular network composed of 10 vertices (node IDs are given for each case). Cells (i.e. voronoi area defining the region of influence of each vertex) are coloured by elevation. Two cases are presented considering single flow direction (top sketch – SFD) and multiple flow direction (bottom sketch – MFD/Dinf). White arrows indicate flow direction and their sizes vary in proportion to slope (not at scale). (b) Differences in calculated drainage area for a portion of South America from eSCAPE using the two flow direction methods.

Time

time:
  start: 0.
  end: 1000000.
  tout: 1000.
  dt: 100.

The time structure is also a required element in the YML input and defines the duration of the simulation from start to end time (in years). It is worth noting that these times can be negative, for example start can be equal to -150,000 years and end to -75,000 years.

Caution

The only requirement is that start time needs to be lower than end time… (don’t forget this is a forward model!)

The user also needs to define the time step dt used to compute the model processes (erosion, transport and deposition).

Lastly, the user needs to define the output interval (tout - in years). Depending of the size of your model, decreasing the number of output by increasing tout will make your simulation run quicker.

Input parameters relative to forcing conditions.

Sea

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

By default, the sea-level (sea) position in eSCAPE is set to 0 m. If you wish to set it to another position you can use the position parameter 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).

Important

The sea-level curve is defined as a 2 columns ASCII file containing in the first column the time in years (they don’t need to be regularly temporally spaced) and in the second the sea-level position for the given time (in metres). When the model runs, it will interpolate linearly between the successive times to define the position of the sea-level.

Climate & tectonic

Note

As for the sea-level structure, climate & tectonic are both optional. They may be defined as a sequence of multiple forcing conditions each requiring a starting time (start in years) and either a constant value applied to the entire grid (uniform) or spatially varying values specified in a file (map).

climate & tectonic : have the same structure with a sequence of events defined by a starting time (start) and either a constant value (uniform) or a map.

climate:
  - start: 0.
    uniform: 1.0
  - start: 500000.
    map: ['data/inputfileparameters.vtk','R']
  - start: 500000.
    uniform: 2.0

tectonic:
  - start: 0.
    mapZ: ['data/inputfileparameters.vtk','T1']
  - start: 100000.
    uniform: 0.
  - start: 50000.
    mapZ: ['data/inputfileparameters.vtk','T2']

Surface processes

Input parameters relative to physical processes.

The default law available in eSCAPE is based on the detachment-limited equation (sp_br), where erosion rate \(\dot{\epsilon}\) depends on drainage area \(A\), net precipitation \(P\) and local slope \(S\) and takes the form:

\[\dot{\epsilon}=\kappa_{br} (PA)^m S^n\]

\(\kappa_{br}\) (defined as the Kbr element in the YML) is a dimensional coefficient describing the erodibility of the channel bed as a function of rock strength, bed roughness and climate, \(m\) and \(n\) are dimensionless positive constants.

sp_br:
  Kbr: 1.e-5

Important

It is worth noting that the coefficient \(m\) and \(n\) are fixed in this version and take the value 0.5 and 1 respectively.

sp_dep:
  Ff: 0.3

Once the entrainment rates have been obtained, the sediment flux moving out at every node \(Q_s^{out}\) equals the flux of sediment flowing in plus the local erosion rate. \(Q_s^{out}\) takes the following form:

\[Q_s^{out} = Q_s^{in} +(1-F_f )E \Omega\]

\(\Omega\) is the voronoi area of the considered vertex and \(F_f\) (Ff) is the volumetric fraction of fine sediment small enough to be considered permanently in suspension.

As an example, in case where bedrock breaks only into sand and gravel fractions, \(F_f\) would be zero. As a result, simulated deposits and transported sediment flux in the model only include sediment coarse enough that it does not permanently stay in suspension.

Diffusion

Note

Transport along slope by gravity is simulated using a linear diffusion law referred to as soil creep.

\[\frac{\partial z}{\partial t}= D \nabla^2 z\]

in which \(D\) is the diffusion coefficient (hillslopeK) set for both marine and land environments.

diffusion:
  hillslopeK: 5.e-2
  sedimentK: 300.

The marine deposition of river transported sediments are simulated with a diffusion law as well and relies on a different diffusion coefficient (sedimentK).

Output

Model’s output are stored in a directory name (dir) and the option (boolean) makedir gives the possibility to delete any existing folder with the same name (if set to False) 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)

output:
  dir: 'outputDir'
  makedir: False

The output element is optional but is highly recommended as it enables you to specify your ouput folder name (dir). If not specified, the default name will be output.

Important

To prevent the deletion of any output folders if you have not changed the folder name, the code automatically creates a new name which add an underscore and a number at the end of the output filename.

As an example, let us consider you have already ran a model with the dir element set to ’myexp’ and you have decided to change the erodibility value in the SPL law but kept the folder name the same and have makedir set to True.

eSCAPE will create a new folder named ’myexp_0’. If you keep changing any parameters omitting to change the folder name, you will have a list of folders like ’myexp_1’, ’myexp_2’, ’myexp_3’…

Examples

There are numerous resources that you might find useful for learning and using eSCAPE.

The following set of notebooks go through the main workflows for constructing and running eSCAPE models. These models demonstrate current best usage practises, and are guaranteed to operate correctly for each eSCAPE release.

They are available as a github repository.

git clone https://github.com/Geodels/eSCAPE-demo.git

Important

The proposed examples require to create input files and the easiest and recommended way for creating them is to use the Jupyter Notebooks available in the (Geodels escape-docker) container.

Required Python Skills

To use eSCAPE successfully, you will need to have an understanding of the following Python constructs:

1. Basic Python, such as importing modules, and syntax structure (indenting, functions, etc).
2. Containers such as dictionaries, lists and tuples.
3. Flow control (loops, if-else conditionals, etc).
4. Python objects, object methods, object attributes, object lifecycles.

Most beginner (or intermediate) Python tutorials should cover these concepts.

eSCAPE uses h5py for all heavy data disk IO. H5py is a Python library which provides a Python interface to writing/reading HDF5 format files. While not strictly required, more advanced users will certainly find having some familiarity with the h5py libary useful, both for directly querying files eSCAPE has generated, and also for writing their own files (in preference to CSV for example).

Jupyter Notebooks

Jupyter Notebooks is the recommended environment for most model development. In badlands we utilise notebooks to provide inline visualisation of your model configurations, allowing you to quickly see your results, modify as required, and then regenerate and repeat.

If you are new to Jupyter Notebooks, you should familiarise yourself with the notebook environment first. Also, remember the Help menu bar option provides useful references and keyboard shortcuts.

How to get help

If you encounter issues or suspect a bug, please create a ticket using the issue tracker on github.

Testing models

A series of examples are available with the source code. These examples illustrate the different capabilities of the code and are an ideal starting point to learn how to use eSCAPE. Each folder is composed of

1. an input YML file where the different options for the considered experiment are set,
2. a data folder containing the initial surface and potentially some forcing files (e.g. sea-level, rainfall or tectonic grids) and
3. a series of IPython notebooks used to run the experiment and perform some pre or post-processing tasks.

Tip

The range of simulations varies both in term of spatial and temporal resolutions. You can browse the list of examples directly from the IPython notebooks.

Examples on the Docker container

Six examples are available from the notebooks folder in the docker container. These examples illustrate how to setup input files and run the code either in serial or in parallel.

Note

Even if you are planning to run eSCAPE on HPC you should install the container on your local machine to generate the inputs required by the code to run.

Running eSCAPE

Either via jupyter notebooks or Python files.

python3 run_eSCAPE.py -i input.yml -v

where the run_eSCAPE.py script takes one required argument the input filename and an optional verbose command (-v). To run the script in parallel simply use the mpirun command. As an example with N processors it will look like:

mpirun -np N python run_eSCAPE.py -i input.yml

run_eSCAPE.py consists of a limited number of calls to eSCAPE

import eSCAPE
model = eSCAPE.LandscapeEvolutionModel(***)
model.runProcesses()
model.destroy()

as shown below:

import argparse
import eSCAPE as sim

# Parsing command line arguments
parser = argparse.ArgumentParser(description='This is a simple entry to run eSCAPE model.',add_help=True)
parser.add_argument('-i','--input', help='Input file name (YAML file)',required=True)
parser.add_argument('-v','--verbose',help='True/false option for verbose', required=False,action="store_true",default=False)
parser.add_argument('-l','--log',help='True/false option for PETSC log', required=False,action="store_true",default=False)

args = parser.parse_args()
if args.verbose:
  print("Input file: {}".format(args.input))
  print(" Verbose is on? {}".format(args.verbose))
  print(" PETSC log is on? {}".format(args.log))

# Reading input file
model = sim.LandscapeEvolutionModel(args.input,args.verbose,args.log)

# Running model
model.runProcesses()

# Cleaning model
model.destroy()

Example running scripts used on specific HPC platforms

Here is an example of PBS job for Artemis HPC Platform (USyD):

#!/bin/bash

# Project
#PBS -P BGH

# 64 CPUs
#PBS -l select=8:ncpus=8:mpiprocs=8:mem=8GB

# Time limit
#PBS -l walltime=10:00:00
#PBS -q alloc-dm

# Set up environment
module load python/2.7.15-intel petsc-intel-mpi hdf5

cd $PBS_O_WORKDIR
cd earth

# Launching the job!
mpirun -np 64 python run_escape.py

with run_escape.py a python script calling eSCAPE function:

import eSCAPE as sim

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

# Running model
model.runProcesses()

# Cleaning model
model.destroy()

Use qsub command to launch.

Workshop

A set of workshop documents and models are also provided and aims to introduce those interested in landscape evolution and source to sink problems to eSCAPE.

The set of problems is quite broad and should be of interest to a wide community. The workshop has been designed to run over a couple of days but can be shorten if needed!

Note

You do not have to be a seasoned modeller to participate. Geomorphologists, tectonicists and sedimentologists interested in testing conceptual models based on field observations are welcome!

We welcome all kinds of contributions! Please get in touch if you would like to help out.

Important

Everything from code to notebooks to examples and documentation are all equally valuable so please don’t feel you can’t contribute.

To contribute please fork the project make your changes and submit a pull request. We will do our best to work through any issues with you and get your code merged into the main branch.

If you found a bug, have questions, or are just having trouble with eSCAPE, you can:

• join the eSCAPE User Group on Slack by sending an email request to: tristan.salles@sydney.edu.au
• open an issue in our issue-tracker and we’ll try to help resolve the concern.

Publications

Note

Open-source and free software is a critical part of modern research and if you have been using eSCAPE it is important to properly acknowledge and cite our work.

Papers on the algorithms

When using eSCAPE, we would really appreciate if you cite at least one of the following papers 💣

Salles, T.: eSCAPE: parallel global-scale landscape evolution model, Journal of Open Source Software, 3(30), 964, doi:10.21105/joss.00964, 2018.

Salles, T.: eSCAPE: Regional to Global Scale Landscape Evolution Model v2.0, Geosci. Model Dev., doi:10.5194/gmd-2019-126, 2019.

Collaborations

How to contribute

We welcome all kinds of contributions! Please get in touch if you would like to help out.

Important

Everything from code to notebooks to examples and documentation are all equally valuable so please don’t feel you can’t contribute.

To contribute please fork the project make your changes and submit a pull request. We will do our best to work through any issues with you and get your code merged into the main branch.

If you found a bug, have questions, or are just having trouble with eSCAPE, you can:

• join the eSCAPE User Group on Slack by sending an email request to: tristan.salles@sydney.edu.au
• open an issue in our issue-tracker and we’ll try to help resolve the concern.

Where to find support

Running models

eSCAPE User Group on Slack is the best place to ask questions regarding how to use the code and run new experiments…

Technical Q&A

Please feel free to submit new code issues to the issue-log to request new features, document new bugs, or ask coding questions.

License

This program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

See also

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this program. If not, see http://www.gnu.org/licenses/lgpl-3.0.en.html.

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.