Mesh

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

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

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