eSCAPE-demo: A Jupyter Notebook repository from GEOdels

Content

This repository contains a series of 4 examples to run eSCAPE. Along with the jupyter notebooks used to run the input files, there is also a series of notebooks (MeshGen.ipynb) required to create the initial unstructured grids (vtk binary files).

The mesh creation could be a complicated process and relies on a series of libraries:

For a quick start, it is recommended to use the Geodels escape-docker image that is shipped with all the required libraries, the code as well as the examples found here. You will need to set the Docker preferences based on the specific memory and CPUs available in your local machine. Also it is recommended to attached a volume to the Kitematic image to be able to visualise the model outputs locally.

All the examples have been designed to run on a single machine and should be completed in less than an hour. They are here to illustrate the basic capability of eSCAPE.

The code parallelisation relies on petsc4py and scalability tests are still on-going. For now on, we have seen some good performance up to 64 CPUs using a mesh with more than 6 millions vertices. Our goal is to be able to run models with more than 10 millions nodes and over several hundreds of CPUs.

Usage

Either via jupyter notebooks or python files.

python 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()

Input file

Input files for eSCAPE are based on YAML syntax.

A typical file will look like this:

name: Description of the what is going to be done in this 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: 1.e-6
    sedimentK: 5.e6

output:
    dir: 'outputDir'
    makedir: False

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:

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')
time: the simulation time parameters defined by start, end, tout (the output interval) and dt (the internal time-step).

Follows the optional forcing conditions:

sea: the sea-level declaration with the relative sea-level position (m) and the sea-level curve which is a file containing 2 columns (time and sea-level position).
climatic & 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.

Then the parameters for the surface processes to simulate:

sp_br: for the stream power law with a unique parameter Kbr representing the erodibility coefficient which is scale-dependent and its value depend on lithology and mean precipitation rate, channel width, flood frequency, channel hydraulics. It is worth noting that the coefficient m and n are fixed in this version and take the value 0.5 & 1 respectively.
diffusion: hillslope and marine diffusion coefficients. hillslopeK sets the simple creep transport law which states that transport rate depends linearly on topographic gradient. The marine sediment are transported based on a diffusion coefficient sedimentK.

Finally, you will need to specify the output folder:

output: with dir the directory name and the option makedir that gives the possible to delete any existing output folder with the same name (if set to False) or to create a new folder with the give dir name plus a number at the end (e.g. outputDir_1 if set to True)

Perfomance

The diagram below illustrates the performance of eSCAPE on a mesh with 6M+ nodes.

Distribution on deposited sediments in both the marine and land regions is dependent of the main rivers positions and is happening on specific locations (river mouths, depressions). As these locations are irregularly positioned on the simulated domain it creates unbalancing issues that arise and potentially decrease overall scalability of the model with increasing number of CPUs.