Welcome to pyugrid’s documentation!

Currently, this only contains reference docs – auto-generated from the source docstrings.

One of these days, we’ll add more/better docs – contributions welcome!

For some examples of use, see Jupyter notebooks found in notebook_examples in the source.

Contents:

Indices and tables

Reference

pyugrid package

A Python API to utilize data written using the netCDF unstructured grid conventions:

https://github.com/ugrid-conventions/ugrid-conventions.

This package contains code for reading/writing netcdf files (and potentially other formats) as well as code for working with data on unstructured grids

class pyugrid.UGrid(nodes=None, node_lon=None, node_lat=None, faces=None, edges=None, boundaries=None, face_face_connectivity=None, face_edge_connectivity=None, edge_coordinates=None, face_coordinates=None, boundary_coordinates=None, data=None, mesh_name='mesh')

A basic class to hold an unstructured grid (triangular mesh).

The internal structure mirrors the netcdf data standard.

add_data(uvar)

Add a UVar to the data dict

Parameters:uvar (a ugrid.UVar object) – the UVar object to add. Its name will be the key in the data dict.

Some sanity checking is done to make sure array sizes are correct.

boundaries
build_boundaries()

Builds the boundary segments from the cell array.

It is assumed that -1 means no neighbor, which indicates a boundary

This will over-write the existing boundaries array if there is one.

This is a not-very-smart just loop through all the faces method.

build_boundary_coordinates()

Builds the boundary_coordinates array, using the average of the nodes defining each boundary segment.

Note that you may want a different definition of the boundary coordinates than this computes, but this is here to have an easy default.

This will write-over an existing face_coordinates array

Useful if you want this in the output file

build_celltree()

Tries to build the celltree for the current UGrid. Will fail if nodes or faces is not defined.

build_edge_coordinates()

Builds the face_coordinates array, using the average of the nodes defining each edge.

Note that you may want a different definition of the edge coordinates than this computes, but this is here to have an easy default.

This will write-over an existing face_coordinates array

Useful if you want this in the output file

build_edges()

Builds the edges array: all the edges defined by the triangles

This will replace the existing edge array, if there is one.

NOTE: arbitrary order – should the order be preserved?

build_face_coordinates()

Builds the face_coordinates array, using the average of the nodes defining each face.

Note that you may want a different definition of the face coordinates than this computes, but this is here to have an easy default.

This will write-over an existing face_coordinates array.

Useful if you want this in the output file.

build_face_edge_connectivity()

Builds the face-edge connectivity array

Not implemented yet.

build_face_face_connectivity()

Builds the face_face_connectivity array: giving the neighbors of each triangle.

Note: arbitrary order and CW vs CCW may not be consistent.

check_consistent()

Check if the various data is consistent: the edges and faces reference existing nodes, etc.

data

dict of data associated with the data arrays You can’t set this – must use UGrid.add_data().

edges
face_edge_connectivity
face_face_connectivity
faces
find_uvars(standard_name, location=None)

Find all UVar objects that match the specified standard name

Parameters:
  • standard_name (str) – the standard name attribute. Based on the UGRID conventions.
  • location – optional attribute location to narrow the returned UVar objects (one of ‘node’, ‘edge’, ‘face’, or ‘boundary’).
Returns:

set of matching UVar objects
classmethod from_nc_dataset(klass, nc, mesh_name=None, load_data=False)

create a UGrid object from a netcdf file (or opendap url)

Parameters:
  • nc (netCDF4.DataSet) – An already open Dataset object
  • mesh_name=None – the name of the mesh you want. If None, then you’ll get the only mesh in the file. If there is more than one mesh in the file, a ValueError Will be raised
  • load_data=False – flag to indicate whether you want to load the associated data or not. The mesh will be loaded in any case. If False, only the mesh will be loaded. If True, then all the data associated with the mesh will be loaded. This could be huge!
classmethod from_ncfile(klass, nc_url, mesh_name=None, load_data=False)

create a UGrid object from a netcdf file name (or opendap url)

Parameters:
  • nc_url – the filename or OpenDap url you want to load
  • mesh_name=None – the name of the mesh you want. If None, then you’ll get the only mesh in the file. If there is more than one mesh in the file, a ValueError Will be raised
  • load_data=False – flag to indicate whether you want to load the associated data or not. The mesh will be loaded in any case. If False, only the mesh will be loaded. If True, then all the data associated with the mesh will be loaded. This could be huge!
get_lines()
infer_location(data)
Parameters:data –

Returns ‘nodes’ if data will fit to the nodes, ‘faces’ if the data will fit to the faces, and None otherwise.

interpolate_var_to_points(points, variable, indices=None, grid=None, alphas=None, mask=None, slices=None, slice_grid=True, _copy=False, _memo=True, _hash=None)

interpolates teh passed-in variable to the points in points

used linear interpolation from the nodes.

interpolation_alphas(points, indices=None, _copy=False, _memo=True, _hash=None)

Given an array of points, this function will return the bilinear interpolation alphas for each of the three nodes of the face that the point is located in. If the point is not located on the grid, the alphas are set to 0 :param points: Nx2 numpy array of lat/lon coordinates

Parameters:indices – If the face indices of the points is already known, it can be passed in to save repeating the effort.
Returns:Nx3 numpy array of interpolation factors

TODO: mask the indices that aren’t on the grid properly.

locate_faces(points, method='celltree', _copy=False, _memo=True, _hash=None)

Returns the face indices, one per point.

Points that are not in the mesh will have an index of -1

If a single point is passed in, a single index will be returned If a sequence of points is passed in an array of indexes will be returned.

Parameters:
  • points – The points that you want to locate – (lon, lat). If the shape of point is 1D, function will return a scalar index. If it is 2D, it will return a 1D array of indices
  • method='celltree' – method to use. Options are ‘celltree’, ‘simple’. for ‘celltree’ the celltree2d pacakge must be installed: https://github.com/NOAA-ORR-ERD/cell_tree2d/ ‘simple’ is very, very slow for large grids.

This version utilizes the CellTree data structure.

locate_nodes(points)

Returns the index of the closest nodes to the input locations.

Parameters:points – the lons/lats of locations you want the nodes closest to.
Returns:the index of the closest node.
node_lat
node_lon
nodes
num_vertices

Number of vertices in a face.

save_as_netcdf(filepath)

Save the ugrid object as a netcdf file.

Parameters:filepath – path to file you want o save to. An existing one will be clobbered if it already exists.

Follows the convention established by the netcdf UGRID working group:

http://publicwiki.deltares.nl/display/NETCDF/Deltares+CF+proposal+for+Unstructured+Grid+data+model

class pyugrid.UVar(name, location, data=None, attributes=None)

A class to hold a variable associated with the UGrid. Data can be on the nodes, edges, etc. – “UGrid Variable”

It holds an array of the data, as well as the attributes associated with that data – this is mapped to a netcdf variable with attributes(attributes get stored in the netcdf file)

data

The data associated with the UVar – a numpy array-like object with the actual data

dtype

data type of the variable

max

maximum value of the variable

min

minimum value of the variable

ndim

number of dimensions of the variable

shape

The shape of the data array associated with the UVar.

class pyugrid.UMVar(name, location='none', data=None, attributes=None)

A class to group multiple UVars (or other data sources) and retrieve common information. All the variables grouped in this class must have the same shape, location, and unique names.

TODO: Add attribues that all grouped variables have in common to the UMVar?

add_var(var)

code to read the netcdf unstructured grid standard:

https://github.com/ugrid-conventions/ugrid-conventions/

This code is called by the UGrid class to load into a UGRID object.

pyugrid.read_netcdf.find_mesh_names(nc)

find all the meshes in an open netcCDF4.DataSet

Parameters:nc – the netCDF4 Dataset object to look for mesh names in

NOTE: checks for 2-d topology_dimension

pyugrid.read_netcdf.is_valid_mesh(nc, varname)

determine if the given variable name is a valid mesh definition

Parameters:
  • nc – a netCDF4 Dataset to check
  • varname – name of the candidate mesh variable
pyugrid.read_netcdf.load_grid_from_nc_dataset(nc, grid, mesh_name=None, load_data=True)

loads UGrid object from a netCDF4.DataSet object, adding the data to the passed-in grid object.

It will load the mesh specified, or look for the first one it finds if none is specified

Parameters:
  • nc (netCDF4 Dataset object) – netcdf Dataset to be loaded up
  • grid (UGrid object.) – the grid object to put the mesh and data into.
  • mesh_name=None – name of the mesh to load
  • load_data=False – flag to indicate whether you want to load the associated data or not. The mesh will be loaded in any case. If False, only the mesh will be loaded. If True, then all the data associated with the mesh will be loaded. This could be huge!

NOTE: passing the UGrid object in to avoid circular references, while keeping the netcdf reading code in its own file.

pyugrid.read_netcdf.load_grid_from_ncfilename(filename, grid, mesh_name=None, load_data=True)

loads UGrid object from a netcdf file, adding the data to the passed-in grid object.

It will load the mesh specified, or look for the first one it finds if none is specified

Parameters:
  • filename – filename or OpenDAP url of dataset.
  • grid (UGrid object.) – the grid object to put the mesh and data into.
  • mesh_name=None – name of the mesh to load
  • load_data=False – flag to indicate whether you want to load the associated data or not. The mesh will be loaded in any case. If False, only the mesh will be loaded. If True, then all the data associated with the mesh will be loaded. This could be huge!

pyugrid.grid_io package

assorted code for doing input/output for pyugrid

pyugrid.grid_io.load_from_varnames(filename, names_mapping, attribute_check=None)

Load a UGrid from a netcdf file where the roles are defined by the names of the variables.

Parameters:
  • filename – names of the file to load (or OPeNDAP URL).
  • names_mapping – dict that maps the variable names to UGrid components
  • attribute_check=None – list of global attributes that are expected

The names_mapping dict has to contain at least: ‘nodes_lon’, ‘nodes_lat’

Optionally (and mostly required), it can contain: face_face_connectivity’, ‘face_coordinates_lon’, ‘face_coordinates_lat’, and ‘faces’