UXarray Grid

In this tutorial, you’ll learn:

• What is a UXarray Grid?

• How to load a Grid

• How to access Grid attributes

Related Documentation

• UXarray Data Structures Documentation

Prerequisites

Concepts	Importance	Notes
Unstructured Grids	Necessary
Python programming	Necessary
Introduction to Xarray	Helpful

Time to learn: 10 minutes

---

Overview

In the previous section, we briefly introduced the Grid class, which stores unstructured grid variables such as coordinates and connectivity. This class is the foundation of UXarray, which ensures awareness of the unstructured grid topology between operations. Exploring the grid geometry can be helpful throughout analysis and visualization workflows.

Note:

In most cases, checking the Grid object of either UxDataset or UxDataArray is anticipated be the common scenario since majority of the UXarray workflows will rely on a data set and its variable(s) of interest. Such cases will be showcased as part of many of the following notebooks; thus, this tutorial will focus on the latter where we explore a standalone Grid object.

Unstructured Grid Files

In the following sections, we will look into loading a standalone grid-specific file. The coordinates and connectivity variables of an unstructured grid are often stored as a separate unstructured grid file.

grid_path = "../../meshfiles/outCSne30.grid.ug"

Loading a Grid

The suggested way to construct a standalone Grid is by using the uxarray.open_grid() method. When constructing a standalone grid, only topology variables such as coordinates and connectivity are used to construct the grid. This means that any data variables that reside on the unstructured grid, such as temperature, would not be stored in a Grid. Pairing the grid definiton with data variables will be covered in the next notebook.

import uxarray as ux

uxgrid = ux.open_grid(grid_path)
uxgrid

<uxarray.Grid>
Original Grid Type: UGRID
Grid Dimensions:
  * n_node: 5402
  * n_face: 5400
  * n_max_face_nodes: 4
  * n_nodes_per_face: (5400,)
Grid Coordinates (Spherical):
  * node_lon: (5402,)
  * node_lat: (5402,)
Grid Coordinates (Cartesian):
Grid Connectivity Variables:
  * face_node_connectivity: (5400, 4)
Grid Descriptor Variables:
  * n_nodes_per_face: (5400,)

uxarray.Grid

• Dimensions:
  • n_face: 5400
  • n_max_face_nodes: 4
  • n_node: 5402
• Spherical Coordinates: (2)
  • node_lon
    (n_node)
    float64
    -45.0 45.0 135.0 ... 138.0 135.0

    standard_name :

    longitude

    long_name :

    longitude of 2D mesh nodes

    units :

    degrees_east

    array([-45.        ,  45.        , 135.        , ..., 141.09968961,
           138.03317102, 135.        ])

  • node_lat
    (n_node)
    float64
    ...

    standard_name :

    latitude

    long_name :

    latitude of 2D mesh nodes

    units :

    degrees_north

    [5402 values with dtype=float64]

• Cartesian Coordinates: (0)
• Connectivity: (1)
  • face_node_connectivity
    (n_face, n_max_face_nodes)
    int64
    0 8 356 124 8 ... 5401 297 6 298

    cf_role :

    face_node_connectivity

    start_index :

    0

    _FillValue :

    -9223372036854775808

    array([[   0,    8,  356,  124],
           [   8,    9,  357,  356],
           [   9,   10,  358,  357],
           ...,
           [5399, 5400,  299,  300],
           [5400, 5401,  298,  299],
           [5401,  297,    6,  298]])

• Descriptors: (1)
  • n_nodes_per_face
    (n_face)
    int64
    4 4 4 4 4 4 4 4 ... 4 4 4 4 4 4 4 4

    cf_role :

    n_nodes_per_face

    long name :

    Number of nodes per face

    array([4, 4, 4, ..., 4, 4, 4])

• Attributes: (0)

Printing a Grid displays the contents of our newly created grid object. If you are coming from an Xarray background, this output will look very similar to what one might see when constructing an xarray.Dataset.

Coordinates

Different types of coordinates for the geometric elements of a Grid are either constructed upfront during the grid instantiation or generated at the time of use.

Spherical Coordinates

The spherical node coordinates are always instantiated upfront with the grid initialization and can be examined through the grid attributes such as node_lon, node_lat, etc:

uxgrid.node_lon

<xarray.DataArray 'node_lon' (n_node: 5402)> Size: 43kB
array([-45.        ,  45.        , 135.        , ..., 141.09968961,
       138.03317102, 135.        ])
Dimensions without coordinates: n_node
Attributes:
    standard_name:  longitude
    long_name:      longitude of 2D mesh nodes
    units:          degrees_east

xarray.DataArray

'node_lon'

• n_node: 5402

• -45.0 45.0 135.0 -135.0 -45.0 45.0 ... 147.3 144.2 141.1 138.0 135.0

  array([-45.        ,  45.        , 135.        , ..., 141.09968961,
         138.03317102, 135.        ])

• Coordinates: (0)
• Indexes: (0)
• Attributes: (3)

  standard_name :

  longitude

  long_name :

  longitude of 2D mesh nodes

  units :

  degrees_east

However, the spherical face and edge coordinates might not be readily available in the grid definition (see the original Grid object above for reference) and would need to be generated by UXarray when prompted; for instance:

uxgrid.face_lon

/home/runner/miniconda3/envs/unstructured-grid-viz-cookbook-dev/lib/python3.10/site-packages/uxarray/grid/coordinates.py:255: UserWarning: This cannot be guaranteed to work correctly on concave polygons
  warnings.warn("This cannot be guaranteed to work correctly on concave polygons")

<xarray.DataArray 'face_lon' (n_face: 5400)> Size: 43kB
array([-43.51197953, -40.51148089, -37.51089576, ..., 141.03881231,
       138.01110363, 135.        ])
Dimensions without coordinates: n_face
Attributes:
    standard_name:  longitude
    long name:      Longitude of the center of each face
    units:          degrees_east

xarray.DataArray

'face_lon'

• n_face: 5400

• -43.51 -40.51 -37.51 -34.51 -31.51 ... 147.1 144.1 141.0 138.0 135.0

  array([-43.51197953, -40.51148089, -37.51089576, ..., 141.03881231,
         138.01110363, 135.        ])

• Coordinates: (0)
• Indexes: (0)
• Attributes: (3)

  standard_name :

  longitude

  long name :

  Longitude of the center of each face

  units :

  degrees_east

Cartesian coordinates

The original uxgrid object above shows no Cartesian coordinates; however, UXarray is able to generate those as soon as the user tries to access one of them; for instance:

uxgrid.node_x

<xarray.DataArray 'node_x' (n_node: 5402)> Size: 43kB
array([ 0.57735027,  0.57735027, -0.57735027, ..., -0.58878977,
       -0.57332232, -0.55611709])
Dimensions without coordinates: n_node
Attributes:
    standard_name:  x
    long name:      Cartesian x location of the corner nodes of each face
    units:          meters

xarray.DataArray

'node_x'

• n_node: 5402

• 0.5774 0.5774 -0.5774 -0.5774 ... -0.6026 -0.5888 -0.5733 -0.5561

  array([ 0.57735027,  0.57735027, -0.57735027, ..., -0.58878977,
         -0.57332232, -0.55611709])

• Coordinates: (0)
• Indexes: (0)
• Attributes: (3)

  standard_name :

  x

  long name :

  Cartesian x location of the corner nodes of each face

  units :

  meters

Connectivity

In unstructured grid geometry, connectivity information between each type of geometric elements can be defined, e.g. face-node, node-edge, edge-face, etc. UXarray requires only the face-node connectivity, either coming from the grid definition or being constructed by UXarray in special cases, in addition to the node coordinates to represent the topology.

UXarray can also generate all the other connectivity information when prompted.

Let us look at the face-node connectivity, for example:

uxgrid.face_node_connectivity

<xarray.DataArray 'face_node_connectivity' (n_face: 5400, n_max_face_nodes: 4)> Size: 173kB
array([[   0,    8,  356,  124],
       [   8,    9,  357,  356],
       [   9,   10,  358,  357],
       ...,
       [5399, 5400,  299,  300],
       [5400, 5401,  298,  299],
       [5401,  297,    6,  298]])
Dimensions without coordinates: n_face, n_max_face_nodes
Attributes:
    cf_role:      face_node_connectivity
    start_index:  0
    _FillValue:   -9223372036854775808

xarray.DataArray

'face_node_connectivity'

• n_face: 5400
• n_max_face_nodes: 4

• 0 8 356 124 8 9 357 356 9 10 ... 300 5400 5401 298 299 5401 297 6 298

  array([[   0,    8,  356,  124],
         [   8,    9,  357,  356],
         [   9,   10,  358,  357],
         ...,
         [5399, 5400,  299,  300],
         [5400, 5401,  298,  299],
         [5401,  297,    6,  298]])

• Coordinates: (0)
• Indexes: (0)
• Attributes: (3)

  cf_role :

  face_node_connectivity

  start_index :

  0

  _FillValue :

  -9223372036854775808

Descriptors

UXarray provides descriptors for further information about the geometry. For instance, an array that shows the number of nodes for each face can be helpful to determine if the grid is uniformly constructed of a single shape or multiple n-gons, and simplify some of the grid-specific calculations as well.

uxgrid.n_nodes_per_face

<xarray.DataArray 'n_nodes_per_face' (n_face: 5400)> Size: 43kB
array([4, 4, 4, ..., 4, 4, 4])
Dimensions without coordinates: n_face
Attributes:
    cf_role:    n_nodes_per_face
    long name:  Number of nodes per face

xarray.DataArray

'n_nodes_per_face'

• n_face: 5400

• 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 ... 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4 4

  array([4, 4, 4, ..., 4, 4, 4])

• Coordinates: (0)
• Indexes: (0)
• Attributes: (2)

  cf_role :

  n_nodes_per_face

  long name :

  Number of nodes per face

What is next?

The next section will cover the other core data structures of UXarray, UxDataset and UxDataArray classes and how to open unstructured grid datasets for data analysis and visualization purposes.