Mesh

class esmpy.api.mesh.Mesh(parametric_dim=None, spatial_dim=None, coord_sys=None, filename=None, filetype=None, convert_to_dual=None, add_user_area=None, meshname='', mask_flag=None, varname='')

The Mesh class is a Python wrapper object for the ESMF Mesh. The individual values of all coordinate and mask arrays are referenced to those of the underlying Fortran ESMF object.

The ESMF library provides a class for representing unstructured grids called the Mesh. Fields can be created on a Mesh to hold data. Fields created on a Mesh can also be used as either the source or destination or both of a regrididng operation which allows data to be moved between unstructured grids. A Mesh is constructed of nodes and elements. A node, also known as a vertex or corner, is a part of a Mesh which represents a single point. Coordinate information is set in a node. An element, also known as a cell, is a part of a mesh which represents a small region of space. Elements are described in terms of a connected set of nodes which represent locations along their boundaries. Field data may be located on either the nodes or elements of a Mesh.

Refer to the Mesh Class of the ESMF Reference Manual for more information.

An unstructured Mesh can be created in two different ways, as a Mesh in memory, or from a SCRIP formatted or CF compliant UGRID file. The arguments for each type of Mesh creation are outlined below.

Created in-memory:

The in-memory Mesh can be created manually in 3 steps:

  1. create the Mesh (specifying parametric_dim and spatial_dim),

  2. add nodes,

  3. add elements.

REQUIRED:

Parameters:

  • parametric_dim (int) – the dimension of the topology of the Mesh (e.g. a Mesh composed of squares would have a parametric dimension of 2 and a Mesh composed of cubes would have a parametric dimension of 3).

  • spatial_dim (int) – the number of coordinate dimensions needed to describe the locations of the nodes making up the Mesh. For a manifold the spatial dimension can be larger than the parametric dimension (e.g. the 2D surface of a sphere in 3D space), but it cannot be smaller.

OPTIONAL:

Parameters:

coord_sys (CoordSys) – Coordinate system for the Mesh. If None, defaults to SPH_DEG.

Created from file:

Note that Meshes created from file do not use the parametric_dim and spatial_dim parameters.

REQUIRED:

Parameters:

OPTIONAL:

Parameters:

  • convert_to_dual (bool) – a boolean value to specify if the dual Mesh should be calculated. Defaults to False. This argument is only supported with SCRIP.

  • add_user_area (bool) – a boolean value to specify if an area property should be added to the mesh. This argument is only supported for SCRIP or ESMFMESH. If None, defaults to False.

  • meshname (str) – the name of the Mesh metadata variable in a UGRID file. This argument is only supported with UGRID. If None, defaults to the empty string.

  • mask_flag (MeshLoc) – an enumerated integer that, if specified, tells whether a mask in a UGRID file should be defined on the Mesh. This argument is only supported with UGRID. If None, defaults to no masking.

  • varname (str) – a variable name for the mask in a UGRID file if mask_flag is specified. This argument is only supported for UGRID. If None, defaults to the empty string.

property area
Return type:

A two element list of numpy arrays to hold values for the nodes and elements of the Mesh.

Returns:

The Mesh area represented as a numpy array of floats of the same number of entries as Mesh elements.

property coords
Return type:

A two element list of numpy arrays to hold values for the nodes and elements of the Mesh.

Returns:

The coordinates represented as a numpy array of floats with a value for each node and/or element of the Mesh Mesh.

property coord_sys
Return type:

CoordSys

Returns:

The coordinate system of the Mesh.

property mask
Return type:

A two element list of numpy arrays to hold values for the nodes and elements of the Mesh.

Returns:

The masked values on the nodes and elements of the Mesh.

property rank
Return type:

int

Returns:

The rank of the Mesh, (i.e. always 1).

property size
Return type:

A two element list of integers.

Returns:

The number of nodes and elements in the Mesh on the current processor.

property size_owned
Return type:

A two element list of integers.

Returns:

The number of owned nodes and elements in the Mesh on the current processor.

add_elements(element_count, element_ids, element_types, element_conn, element_mask=None, element_area=None, element_coords=None)

Add elements to a Mesh, this must be done after adding nodes.

REQUIRED:

Parameters:

  • element_count (int) – the number of elements to add to the Mesh.

  • element_ids (ndarray) – a numpy array of of shape (element_count, 1) to specify the element ids.

  • element_types (ndarray) – a numpy array of MeshElemType`s of shape ``(element_count, 1)` to specify the element types.

  • element_conn (ndarray) – a numpy array of shape sum(element_types[:], 1) to specify the connectivity of the Mesh. The connectivity array is constructed by concatenating the tuples that correspond to the element_ids. The connectivity tuples are constructed by listing the node_ids of each element in COUNTERCLOCKWISE order.

OPTIONAL:

Parameters:

  • element_mask (ndarray) – a numpy array of shape (element_count, 1) containing integer values to specify masked elements. The specific values that are masked are specified in the Regrid constructor.

  • element_area (ndarray) – a numpy array of shape (element_count, 1) to specify the areas of the elements.

  • element_coords (ndarray) – a numpy array of shape (element_count, 1) to specify the coordinates of the elements.

add_nodes(node_count, node_ids, node_coords, node_owners, node_mask=None)

Add nodes to a Mesh, this must be done before adding elements.

Parameters:

  • node_count (int) – the number of nodes to add to the Mesh.

  • node_ids (ndarray) – a numpy array of shape (node_count, 1) to specify the node_ids.

  • node_coords (ndarray) – a numpy array of shape (spatial_dim*node_count, 1) to specify the coordinates of the Mesh. The array should be constructed by concatenating the coordinate tuples into a numpy array that correspond to node_ids.

  • node_owners (ndarray) – a numpy array of shape (node_count, 1) to specify the rank of the processor that owns each node.

OPTIONAL:

Parameters:

node_mask (ndarray) – a numpy array of shape (node_count, 1) containing integer values to specify masked nodes. The specific values that are masked are specified in the Regrid constructor.

copy()

Copy a Mesh in an ESMF-safe manner.

Returns:

A Mesh shallow copy.

destroy()

Release the memory associated with a Mesh.

free_memory()

Free memory associated with the creation of a Mesh which is no longer needed for ongoing operations.

get_coords(coord_dim, meshloc=<MeshLoc.NODE: 0>)

Return a numpy array of coordinates at a specified Mesh location (coordinates can only be returned for the Mesh NODE at this time). The returned array is NOT a copy, it is directly aliased to the underlying memory allocated by esmpy.

REQUIRED:

Parameters:

coord_dim (int) – the dimension number of the coordinates to return: e.g. [x, y, z] = (0, 1, 2), or [lat, lon] = (0, 1)

OPTIONAL:

Parameters:

meshloc (MeshLoc) – the MeshLoc of the coordinates. If None, defaults to NODE.

Returns:

A numpy array of coordinate values at the specified MeshLoc.