Mesh

class ESMF.api.mesh.Mesh(*args, **kwargs)

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.

For more information about the ESMF Mesh class, please see the ESMF Mesh documentation.

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:

• filename (str) – the name of NetCDF file containing the Mesh.
• filetype (FileFormat) – the input FileFormat of the Mesh.

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 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.

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.

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.

coord_sys

Return type:CoordSys Returns:The coordinate system of the Mesh.

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.

rank

Return type:int Returns:The rank of the Mesh, (i.e. always 1).

size

Return type:A two element list of integers. Returns:The number of nodes and elements in the Mesh on the current processor.

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)

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.

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 :attr:`~ESMF.api.constants.MeshLoc.NODE`s at this time). The returned array is NOT a copy, it is directly aliased to the underlying memory allocated by ESMF.

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.