Class UnstMesh#

class mesher.unstructuredmesh.UnstMesh[source]#

This class defines the spherical mesh characteristics and builds a PETSc DMPlex that encapsulates this unstructured mesh, with interfaces for both topology and geometry. The PETSc DMPlex is used for parallel redistribution for load balancing.

Note

goSPL is built around a Finite-Volume method (FVM) for representing and evaluating partial differential equations. It requires the definition of several mesh variables such as:

the number of neighbours surrounding every node,

the cell area defined using Voronoi area,

the length of the edge connecting every nodes, and

the length of the Voronoi faces shared by each node with his neighbours.

In addition to mesh defintions, the class declares several functions related to forcing conditions (e.g. paleo-precipitation maps, tectonic (vertical and horizontal) displacements, stratigraphic layers…). These functions are defined within the UnstMesh class as they rely heavely on the mesh structure.

Important

The grid (2D or spherical) requires locally-orthogonal Voronoi/Delaunay staggering, or an unstructured C-grid type numerical formulation as described in Engwirda 2017

Finally a function to clean all PETSc variables is defined and called at the end of a simulation.

Methods

`applyForces`()	Finds the different values for climatic, tectonic and sea-level forcing that will be applied at any given time interval during the simulation.
`applyTectonics`()	Finds the different values for tectonic forces that will be applied at any given time interval during the simulation.
`destroy_DMPlex`()	Destroys PETSc DMPlex objects and associated PETSc local/global Vectors and Matrices at the end of the simulation.

Initialise

__init__()

The initialisation of UnstMesh class calls the private function _buildMesh.

Public Methods

`applyForces`()	Finds the different values for climatic, tectonic and sea-level forcing that will be applied at any given time interval during the simulation.
`applyTectonics`()	Finds the different values for tectonic forces that will be applied at any given time interval during the simulation.
`destroy_DMPlex`()	Destroys PETSc DMPlex objects and associated PETSc local/global Vectors and Matrices at the end of the simulation.

Private Methods

`_buildMesh`()	This function is at the core of the UnstMesh class.
`_generateVTKmesh`(points, cells)	A global VTK mesh is generated to compute the distance between mesh vertices and coastlines position.
`_get_boundary`([label])	In case of a flat mesh (non global), this function finds the nodes on the boundary from the DM.
`_meshfrom_cell_list`(dim, cells, coords)	Creates a DMPlex from a list of cells and coordinates.
`_meshStructure`()	Defines the mesh structure and the associated voronoi parameter used in the Finite Volume method.
`_readErosionDeposition`()	Reads existing cumulative erosion depostion from a previous experiment if any as defined in the YAML input file following the nperodep key.
`_set_DMPlex_boundary_points`(label)	In case of a flat mesh (non global), this function finds the points that join the edges that have been marked as "boundary" faces in the DAG then sets them as boundaries.
`_updateRain`()	Finds current rain values for the considered time interval and computes the volume of water available for runoff on each vertex.
`_updateEroFactor`()	Finds current erodibility factor values for the considered time interval.
`_xyz2lonlat`()	Converts local x,y,z representation of cartesian coordinates from the spherical triangulation to latitude, longitude in degrees.

Public functions#

UnstMesh.applyForces()[source]#: Finds the different values for climatic, tectonic and sea-level forcing that will be applied at any given time interval during the simulation.

UnstMesh.applyTectonics()[source]#: Finds the different values for tectonic forces that will be applied at any given time interval during the simulation.

UnstMesh.destroy_DMPlex()[source]#: Destroys PETSc DMPlex objects and associated PETSc local/global Vectors and Matrices at the end of the simulation.

Private functions#

UnstMesh._buildMesh()[source]#

This function is at the core of the UnstMesh class. It encapsulates both spherical mesh construction (triangulation and voronoi representation for the Finite Volume discretisation), PETSc DMPlex distribution and several PETSc vectors allocation.

The function relies on several private functions from the class:

_generateVTKmesh
_meshfrom_cell_list
_meshStructure
_readErosionDeposition
_xyz2lonlat
readStratLayers

Note

It is worth mentionning that partitioning and field distribution from global to local PETSc DMPlex takes a lot of time for large mesh and there might be some quicker way in PETSc to perform this step that I am unaware of…

UnstMesh._generateVTKmesh(points, cells)[source]#

A global VTK mesh is generated to compute the distance between mesh vertices and coastlines position.

The distance to the coastline for every marine vertices is used to define a maximum shelf slope during deposition. The coastline contours are efficiently obtained from VTK contouring function. This function is performed on a VTK mesh which is built in this function.

UnstMesh._get_boundary(label='boundary')[source]#: In case of a flat mesh (non global), this function finds the nodes on the boundary from the DM.

UnstMesh._meshfrom_cell_list(dim, cells, coords)[source]#

Creates a DMPlex from a list of cells and coordinates.

Note

As far as I am aware, PETSc DMPlex requires to be initialised on one processor before load balancing.

Parameters:

dim – topological dimension of the mesh
cells – vertices of each cell
coords – coordinates of each vertex

UnstMesh._meshStructure()[source]#

Defines the mesh structure and the associated voronoi parameter used in the Finite Volume method.

Important

The mesh structure is built locally on a single partition of the global mesh.

Once the voronoi definitions have been obtained a call to the fortran subroutine definetin is performed to order each node and the dual mesh components, it records:

all cells surrounding a given vertice,
all edges connected to a given vertice,
the triangulation edge lengths,
the voronoi edge lengths.

UnstMesh._readErosionDeposition()[source]#

Reads existing cumulative erosion depostion from a previous experiment if any as defined in the YAML input file following the nperodep key.

This functionality can be used when restarting from a previous simulation in which the spherical mesh has been modified either to account for horizontal advection or to refine/coarsen a specific region during a given time period.

UnstMesh._set_DMPlex_boundary_points(label)[source]#: In case of a flat mesh (non global), this function finds the points that join the edges that have been marked as “boundary” faces in the DAG then sets them as boundaries.

UnstMesh._updateRain()[source]#: Finds current rain values for the considered time interval and computes the volume of water available for runoff on each vertex.

Note

It is worth noting that the precipitation maps are considered as runoff water. If one wants to account for evaporation and infiltration you will need to modify the precipitation maps accordingly as a pre-processing step.

UnstMesh._updateEroFactor()[source]#: Finds current erodibility factor values for the considered time interval.

Note

It is worth noting that the erodibility factor is an indice representing different lithological classes (see Moosdorf et al., 2018).

UnstMesh._xyz2lonlat()[source]#

Converts local x,y,z representation of cartesian coordinates from the spherical triangulation to latitude, longitude in degrees.

The latitudinal and longitudinal extend are between [0,180] and [0,360] respectively. Lon/lat coordinates are used when forcing the simulation with paleo-topoography maps.