Class UnstMesh

class mesher.unstructuredmesh.UnstMesh

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.

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

Initialise

__init__()

The initialisation of UnstMesh class calls the private function _buildMesh.

Public Methods

applyForces()	Finds the different values for climatic 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.
initExtForce()	Initialises the forcing conditions: sea level condition, rainfall maps and tectonics.
reInitialiseElev()	This functions reinitialises gospl elevation if one wants to restart a simulation that does not necessitate to rebuild the mesh structure.
updatePaleomap()	Forces model to match provided paleomaps at specific time interval during 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.
_meshAdvector(tectonic, timer)	Advects the mesh horizontally and interpolates mesh information.
_meshUpliftSubsidence(tectonic)	Applies vertical displacements based on tectonic rates.
_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.
_updateTectonics()	Finds the current tectonic regimes (horizontal and vertical) 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()

Finds the different values for climatic and sea-level forcing that will be applied at any given time interval during the simulation.

UnstMesh.applyTectonics()

Finds the different values for tectonic forces that will be applied at any given time interval during the simulation.

UnstMesh.destroy_DMPlex()

Destroys PETSc DMPlex objects and associated PETSc local/global Vectors and Matrices at the end of the simulation.

UnstMesh.initExtForce()

Initialises the forcing conditions: sea level condition, rainfall maps and tectonics.

UnstMesh.reInitialiseElev()

This functions reinitialises gospl elevation if one wants to restart a simulation that does not necessitate to rebuild the mesh structure. It can be used when running a simulation from the Jupyter environment.

UnstMesh.updatePaleomap()

Forces model to match provided paleomaps at specific time interval during the simulation.

This function is only used when the paleomap key is defined in the YAML input file. It will read the paleotopography map and assign the paleo elevation on the spherical mesh.

Private functions

UnstMesh._buildMesh()

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)

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')

In case of a flat mesh (non global), this function finds the nodes on the boundary from the DM.

UnstMesh._meshAdvector(tectonic, timer)

Advects the mesh horizontally and interpolates mesh information.

The advection proceeds in each partition seprately in the following way:

1. based on the horizontal displacement velocities, the mesh coordinates and associated variables (cumulative erosion deposition and stratigraphic layers composition) are moved.

2. a kdtree is built with the advected coordinates and used to interpolate the mesh variables on the initial local mesh position. The interpolation is based on a weighting distance function accounting for the 3 closest advected vertices.

3. interpolated variables on the initial mesh coordinates are then stored in PETSc vectors and class parameters are updated accordingly.

Parameters

• tectonic – local tectonic rates in 3D

• timer – tectonic time step in years

UnstMesh._meshUpliftSubsidence(tectonic)

Applies vertical displacements based on tectonic rates.

Parameters

tectonic – local tectonic rates

UnstMesh._meshfrom_cell_list(dim, cells, coords)

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

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.

This function uses the meshplex library to compute from the list of coordinates and cells the volume of each voronoi and their respective characteristics.

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

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 sperical 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)

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

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._updateTectonics()

Finds the current tectonic regimes (horizontal and vertical) for the considered time interval.

For horizontal displacements, the mesh variables will have to be first advected over the grid and then reinterpolated on the initial mesh coordinates. The approach here does not allow for mesh refinement in zones of convergence and thus can be limiting but using a fixed mesh has one main advantage: the mesh and Finite Volume discretisation do not have to be rebuilt each time the mesh is advected.

This function calls the following 2 private functions:

• _meshAdvector

• _meshUpliftSubsidence

UnstMesh._xyz2lonlat()

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.

previous

Class Model

next

Class PITFill