Reading In Grid Data

UXarray offers support for loading and representing unstructured grids by utilizing existing Xarray functionality paired with new routines that are specifically written for operating on unstructured grids.

Overview

When working with unstructured grids, the grid definition and data variables are often stored as separate files (most of the time as netCDF). This means that there are multiple separate files that need to be read in at once.

For example, the NOAA Geoflow project consists of 4 files (1 grid file and 3 data files). This project follows the UGRID conventions. Special thanks to John Clyne, Shilpi Gupta, and the VAPOR team for providing these data!

geoflow-small
│   grid.nc
│   v1.nc
│   v2.nc
│   v3.nc

Opening The Grid and Data Files with Xarray

First, read in the grid definition and data variable netCCDF files by using xarray.open_dataset. In addition, xr.open_mf_dataset can be used for combining multiple data variables into a single xarray.Dataset.

import xarray as xr

# Base data path
base_path = "../../test/meshfiles/ugrid/geoflow-small/"

# Path to Grid file
grid_path = base_path + "grid.nc"

# Paths to Data Variable files
var_names = ['v1.nc', 'v2.nc', 'v3.nc']
data_paths = [base_path + name for name in var_names]

# Open the Grid file
grid_ds = xr.open_dataset(grid_path)

# Open a single file or multiple files
v1_ds = xr.open_dataset(data_paths[0])
multi_data_ds = xr.open_mfdataset(data_paths)

grid_ds

<xarray.Dataset>
Dimensions:          (nMeshFaces: 3840, nFaceNodes: 4, nMeshNodes: 6000,
                      meshLayers: 20)
Coordinates:
    mesh_node_x      (nMeshNodes) float64 ...
    mesh_node_y      (nMeshNodes) float64 ...
Dimensions without coordinates: nMeshFaces, nFaceNodes, nMeshNodes, meshLayers
Data variables:
    mesh             int32 ...
    mesh_face_nodes  (nMeshFaces, nFaceNodes) float64 ...
    mesh_depth       (meshLayers, nMeshNodes) float64 ...

xarray.Dataset

• Dimensions:
  • nMeshFaces: 3840
  • nFaceNodes: 4
  • nMeshNodes: 6000
  • meshLayers: 20
• Coordinates: (2)
  • mesh_node_x
    (nMeshNodes)
    float64
    ...

    standard_name :

    longitude

    long_name :

    Longitude of 2D mesh nodes.

    units :

    degrees_east

    [6000 values with dtype=float64]

  • mesh_node_y
    (nMeshNodes)
    float64
    ...

    standard_name :

    latitude

    long_name :

    Latitude of 2D mesh nodes.

    units :

    degrees_north

    [6000 values with dtype=float64]

• Data variables: (3)
  • mesh
    ()
    int32
    ...

    cf_role :

    mesh_topology

    long_name :

    Topology data of 2D unstructured mesh.

    topology_dimension :

    2

    node_coordinates :

    mesh_node_x mesh_node_y

    face_node_connectivity :

    mesh_face_nodes

    face_dimension :

    nMeshFaces

    [1 values with dtype=int32]

  • mesh_face_nodes
    (nMeshFaces, nFaceNodes)
    float64
    ...

    cf_role :

    face_node_connectivity

    long_name :

    Maps every face to its corner nodes.

    start_index :

    0

    [15360 values with dtype=float64]

  • mesh_depth
    (meshLayers, nMeshNodes)
    float64
    ...

    units :

    meters

    positive :

    up

    standard_name :

    elevation

    mesh :

    mesh

    location :

    node

    [120000 values with dtype=float64]

• Indexes: (0)
• Attributes: (0)

multi_data_ds

<xarray.Dataset>
Dimensions:  (time: 1, meshLayers: 20, nMeshNodes: 6000)
Coordinates:
  * time     (time) float64 13.0
Dimensions without coordinates: meshLayers, nMeshNodes
Data variables:
    v1       (time, meshLayers, nMeshNodes) float64 dask.array<chunksize=(1, 20, 6000), meta=np.ndarray>
    v2       (time, meshLayers, nMeshNodes) float64 dask.array<chunksize=(1, 20, 6000), meta=np.ndarray>
    v3       (time, meshLayers, nMeshNodes) float64 dask.array<chunksize=(1, 20, 6000), meta=np.ndarray>

xarray.Dataset

• Dimensions:
  • time: 1
  • meshLayers: 20
  • nMeshNodes: 6000
• Coordinates: (1)
  • time
    (time)
    float64
    13.0

    long_name :

    time

    units :

    second

    calendar :

    axis :

    T

    array([13.])

• Data variables: (3)
  • v1
    (time, meshLayers, nMeshNodes)
    float64
    dask.array<chunksize=(1, 20, 6000), meta=np.ndarray>

    units :

    standard_name :

    mesh :

    mesh

    location :

    node

    coordinates :

    mesh_node_x mesh_node_y mesh_depth

    Array Chunk Bytes 0.92 MiB 0.92 MiB Shape (1, 20, 6000) (1, 20, 6000) Dask graph 1 chunks in 2 graph layers Data type float64 numpy.ndarray

  • v2
    (time, meshLayers, nMeshNodes)
    float64
    dask.array<chunksize=(1, 20, 6000), meta=np.ndarray>

    units :

    standard_name :

    mesh :

    mesh

    location :

    node

    coordinates :

    mesh_node_x mesh_node_y mesh_depth

    Array Chunk Bytes 0.92 MiB 0.92 MiB Shape (1, 20, 6000) (1, 20, 6000) Dask graph 1 chunks in 2 graph layers Data type float64 numpy.ndarray

  • v3
    (time, meshLayers, nMeshNodes)
    float64
    dask.array<chunksize=(1, 20, 6000), meta=np.ndarray>

    units :

    standard_name :

    mesh :

    mesh

    location :

    node

    coordinates :

    mesh_node_x mesh_node_y mesh_depth

    Array Chunk Bytes 0.92 MiB 0.92 MiB Shape (1, 20, 6000) (1, 20, 6000) Dask graph 1 chunks in 2 graph layers Data type float64 numpy.ndarray

• Indexes: (1)
  • time
    PandasIndex

    PandasIndex(Float64Index([13.0], dtype='float64', name='time'))

• Attributes: (0)

Representing The Unstructured Grid with UXarray

import uxarray as ux

# Construct a UXarray Grid object from `grid_ds`
grid = ux.Grid(grid_ds)

grid.ds

<xarray.Dataset>
Dimensions:          (nMeshFaces: 3840, nFaceNodes: 4, nMeshNodes: 6000,
                      meshLayers: 20)
Coordinates:
    mesh_node_x      (nMeshNodes) float64 ...
    mesh_node_y      (nMeshNodes) float64 ...
Dimensions without coordinates: nMeshFaces, nFaceNodes, nMeshNodes, meshLayers
Data variables:
    mesh             int32 ...
    mesh_face_nodes  (nMeshFaces, nFaceNodes) uint64 0 1 6 5 ... 5994 5999 5998
    mesh_depth       (meshLayers, nMeshNodes) float64 ...

xarray.Dataset

• Dimensions:
  • nMeshFaces: 3840
  • nFaceNodes: 4
  • nMeshNodes: 6000
  • meshLayers: 20
• Coordinates: (2)
  • mesh_node_x
    (nMeshNodes)
    float64
    ...

    standard_name :

    longitude

    long_name :

    Longitude of 2D mesh nodes.

    units :

    degrees_east

    [6000 values with dtype=float64]

  • mesh_node_y
    (nMeshNodes)
    float64
    ...

    standard_name :

    latitude

    long_name :

    Latitude of 2D mesh nodes.

    units :

    degrees_north

    [6000 values with dtype=float64]

• Data variables: (3)
  • mesh
    ()
    int32
    ...

    cf_role :

    mesh_topology

    long_name :

    Topology data of 2D unstructured mesh.

    topology_dimension :

    2

    node_coordinates :

    mesh_node_x mesh_node_y

    face_node_connectivity :

    mesh_face_nodes

    face_dimension :

    nMeshFaces

    [1 values with dtype=int32]

  • mesh_face_nodes
    (nMeshFaces, nFaceNodes)
    uint64
    0 1 6 5 1 ... 5993 5994 5999 5998

    cf_role :

    face_node_connectivity

    long_name :

    Maps every face to its corner nodes.

    start_index :

    0

    _FillValue :

    18446744073709551615

    array([[   0,    1,    6,    5],
           [   1,    2,    7,    6],
           [   2,    3,    8,    7],
           ...,
           [5991, 5992, 5997, 5996],
           [5992, 5993, 5998, 5997],
           [5993, 5994, 5999, 5998]], dtype=uint64)

  • mesh_depth
    (meshLayers, nMeshNodes)
    float64
    ...

    units :

    meters

    positive :

    up

    standard_name :

    elevation

    mesh :

    mesh

    location :

    node

    [120000 values with dtype=float64]

• Indexes: (0)
• Attributes: (0)

As can be seen, the Grid object has its own grid.ds of type xarray.Dataset to define the grid topology. However, the Grid object has further attributes, variables, and functions to specify the unstructured grid and be executed on it, which can be explored in the next notebooks.