suxarray package

Subpackages

Submodules

suxarray.util_vtk module

Module contents

Top-level package for suxarray.

class suxarray.Grid(grid_obj: Dataset | Grid, ds_sgrid_info: Dataset | None = None, source_grid_spec: str = 'UGRID', source_dims_dict: dict | None = {}, **kwargs)[source]

Bases: Grid

uxarray Grid class for SCHISM See uxarray Grid documentation for the details of the methods and properties

Examples

TBD

classmethod from_dataset(ds_out2d: Dataset, ds_zcoords: Dataset, **kwargs)[source]

Create a Grid object from a SCHISM output 2D dataset and a z-coordinate dataset

Parameters

ds_out2dxr.Dataset

SCHISM output 2D dataset

ds_sgrid_infoxr.Dataset, optional

Extra SCHISM grid information

Returns

Grid

get_strtree(elements: str | None = 'nodes')[source]
intersect(geometry: shapely.geometry.BaseGeometry, element: str | None = 'faces', **kwargs)[source]

Find intersecting elements with a Shapely geometry

Parameters

geometry: shapely.geometry.Geometry element: str, optional

Returns

int

Indices of intersecting elements

isel(**dim_kwargs)[source]

Indexes an unstructured grid along a given dimension (n_node, n_edge, or n_face) and returns a new grid.

Currently only supports inclusive selection, meaning that for cases where node or edge indices are provided, any face that contains that element is included in the resulting subset. This means that additional elements beyond those that were initially provided in the indices will be included. Support for more methods, such as exclusive and clipped indexing is in the works.

Parameters inverse_indices : Union[List[str], Set[str], bool], default=False

Indicates whether to store the original grids indices. Passing True stores the original face indices, other reverse indices can be stored by passing any or all of the following: ([“face”, “edge”, “node”], True)

**dims_kwargs: kwargs

Dimension to index, one of [‘n_node’, ‘n_edge’, ‘n_face’]

Example ——-` >> grid = ux.open_grid(grid_path) >> grid.isel(n_face = [1,2,3,4])

property sgrid_info: Dataset
sgrid_isel(**kwargs)[source]
subset

alias of GridSubsetAccessor

class suxarray.SxDataArray(*args, sxgrid: Grid = None, **kwargs)[source]

Bases: UxDataArray

depth_average() → SxDataArray[source]

Calculate depth-average of a variable

This may need to be moved to a separate file. TODO: Currently this assumes nodal values. Need to support other element. TODO: Maybe this can be moved to another file.

Parameters

None

Returns

daSxDataArray

Depth averaged variable

integrate(quadrature_rule: str | None = 'triangular', order: int | None = 2) → SxDataArray[source]

Computes the integral of a data variable.

Parameters

quadrature_rulestr, optional

Quadrature rule to use. Defaults to “triangular”.

orderint, optional

Order of quadrature rule. Defaults to 4.

Returns

uxdaUxDataArray

UxDataArray containing the integrated data variable

Examples

Open a Uxarray dataset and compute the integral

>>> import uxarray as ux
>>> uxds = ux.open_dataset("grid.ug", "centroid_pressure_data_ug")
>>> integral = uxds["psi"].integrate()
isel(ignore_grid=False, *args, **kwargs)[source]

Grid-aware index selection.

Performs xarray-style integer-location indexing along specified dimensions. If a single grid dimension (‘n_node’, ‘n_edge’, or ‘n_face’) is provided and ignore_grid=False, the underlying grid is sliced accordingly, and remaining indexers are applied to the resulting DataArray.

Parameters

indexersMapping[Any, Any], optional

A mapping of dimension names to indexers. Each indexer may be an integer, slice, array-like, or DataArray. Mutually exclusive with indexing via kwargs.

dropbool, default=False

If True, drop any coordinate variables indexed by integers instead of retaining them as length-1 dimensions.

missing_dims{‘raise’, ‘warn’, ‘ignore’}, default=’raise’

Behavior when indexers reference dimensions not present in the array. - ‘raise’: raise an error - ‘warn’: emit a warning and ignore missing dimensions - ‘ignore’: ignore missing dimensions silently

ignore_gridbool, default=False

If False (default), allow slicing on one grid dimension to automatically update the associated UXarray grid. If True, fall back to pure xarray behavior.

inverse_indicesbool, default=False

For grid-based slicing, pass this flag to Grid.isel to invert indices when selecting (useful for staggering or reversing order).

**indexers_kwargsdimension=indexer pairs, optional

Alternative syntax for specifying indexers via keyword arguments.

Returns

UxDataArray

A new UxDataArray indexed according to indexers and updated grid if applicable.

Raises

TypeError

If indexers is provided and is not a Mapping.

ValueError

If more than one grid dimension is selected and ignore_grid=False.

item(*args)

Copy an element of an array to a standard Python scalar and return it.

Parameters

*args : Arguments (variable number and type)

  • none: in this case, the method only works for arrays with one element (a.size == 1), which element is copied into a standard Python scalar object and returned.

  • int_type: this argument is interpreted as a flat index into the array, specifying which element to copy and return.

  • tuple of int_types: functions as does a single int_type argument, except that the argument is interpreted as an nd-index into the array.

Returns

zStandard Python scalar object

A copy of the specified element of the array as a suitable Python scalar

Notes

When the data type of a is longdouble or clongdouble, item() returns a scalar array object because there is no available Python scalar that would not lose information. Void arrays return a buffer object for item(), unless fields are defined, in which case a tuple is returned.

item is very similar to a[args], except, instead of an array scalar, a standard Python scalar is returned. This can be useful for speeding up access to elements of the array and doing arithmetic on elements of the array using Python’s optimized math.

Examples

>>> import numpy as np
>>> np.random.seed(123)
>>> x = np.random.randint(9, size=(3, 3))
>>> x
array([[2, 2, 6],
       [1, 3, 6],
       [1, 0, 1]])
>>> x.item(3)
1
>>> x.item(7)
0
>>> x.item((0, 1))
2
>>> x.item((2, 2))
1

For an array with object dtype, elements are returned as-is.

>>> a = np.array([np.int64(1)], dtype=object)
>>> a.item() #return np.int64
np.int64(1)
searchsorted(v, side='left', sorter=None)

Find indices where elements of v should be inserted in a to maintain order.

For full documentation, see numpy.searchsorted

See Also

numpy.searchsorted : equivalent function

subset

alias of DataArraySubsetAccessor

property sxgrid: Grid
class suxarray.SxDataset(*args, sxgrid: Grid = None, source_datasets: str | None = None, **kwargs)[source]

Bases: UxDataset

property sxgrid
suxarray.open_grid(files_out2d: str | PathLike | list | tuple, files_zcoords: str | PathLike | list | tuple | None = None, chunks: Dict[str, int] | None = None) → Dataset[source]

Open SCHISM out2d and zCoordinates files and return a grid object

Parameters

files_out2dstr, os.PathLike, list, tuple

SCHISM out2d files

files_zcoordsstr, os.PathLike, list, tuple

SCHISM zCoordinates files

chunksdict, optional

Chunks for dask

Returns

suxarray.Grid

suxarray.open_hgrid_gr3(path_hgrid: str | PathLike) → Grid[source]

Read SCHISM hgrid.gr3 file and return a suxarray grid

Parameters

suxarray.read_grid(ds_out2d: Dataset, ds_zcoords: Dataset | None = None) → Grid[source]

Read grid information from xarray datasets and return a suxarray grid

Parameters

ds_out2dxr.Dataset

Dataset containing SCHISM out2d-like information

ds_zcoordsxr.Dataset, optional

Dataset containing SCHISM z-coordinate like information

Returns

suxarray.Grid

suxarray.read_schism_nc(grid: Grid, ds_data: Dataset) → SxDataset[source]
suxarray.write_gr3(sxda: SxDataArray, file_gr3: str | PathLike, fill_value: float | None = -9999.0) → None[source]

Write a SCHISM grid to a gr3 file

Parameters

sxdaSxDataArray

SCHISM data array to write out

file_gr3str or Path

Path to the output gr3 file

fill_valuefloat, optional

Fill value to use for missing values

suxarray.write_schism_grid(grid: Grid, file_gridout: str | PathLike, da: DataArray | None = None) → None[source]

Write a SCHISM grid to a NetCDF file

The goal of this function is to write a SCHISM grid information to a NetCDF file that can be understood by SCHISM VisIt plugin.

Parameters

file_gridoutstr or Path

Path to the output NetCDF file

gridGrid

SCHISM grid object

suxarray.write_schism_nc(sxda: SxDataArray, file_dataout: str | PathLike | None = None) → None[source]

Write a SCHISM data array to NetCDF files

NOTE: WIP. The API is not finalized.

Parameters

sxdaSxDataset

SCHISM data array

file_dataoutstr or Path, optional

Path to the output NetCDF file