Geometry#

geometry#

Grid:#

class Grid[source]#

Abstract base grid object.

  • mesh(): return a dictionary of type {axis_name : np.meshgrid of coordinate}

  • coords(): return a dictionary of type {axis_name : 1d coordinate values}

abstractmethod mesh(shape)[source]#
Return type:

dict[str, ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]]

Returns:

a dictionary of type {axis_name : np.meshgrid of coordinate}

abstractmethod coords(shape)[source]#
Return type:

dict[str, ndarray[tuple[int, ...], dtype[TypeVar(_ScalarType_co, bound= generic, covariant=True)]]]

Returns:

a dictionary of type {axis_name : 1d coordinate values}

class UniformCartesianGrid(origin, delta)[source]#

Uniform Cartesian Grid. Dimension is infered by length of delta.

Variables:

  • origin – origin of grid

  • delta – step size

class CoordScalar(grid, dimension, amplitude)[source]#

prescribe a scalar field that is a grid coordinate scaled with a constant amplitude

Variables:

  • grid – grid which provides coordinate variables

  • dimension – label of coordinate direction

  • amplitude – factor by which to scale the coordinate

get_grid_spacing_coord(coord, new_dim)[source]#

get a coordinate for the grid spacing

Parameters:

  • coord (DataArray) – dataarray of a coordinate

  • new_dim (str) – name of dimesion associated with grid spacing (would typically shift _face <-> _center)

Return type:

DataArray

Returns:

The coordinate spacing with dimension new_dim

interpolate_to_grid(ds, target_dims=[], coord_map={}, drop_coords=True)[source]#

Spatial interpolation to a target_grid

Parameters:

  • ds (TypeVar(T_Xarray, DataArray, Dataset)) – input data array or dataset. Needs to have dimensions with coordinates that are labelled x*, y*, z* etc. or

  • target_dims (list[str]) – list of dimension names to interpolate to, in the order xdim, ydim, zdim. They must exist in ds as DataArry/coordinates

  • coord_map (dict[str, DataArray]) – dictionary of {existing_dimension_in_ds : target_coordinate_as_DataArray}

  • drop_coords (bool) – flag to exclude spatial coordinates relying on removed dims from output

Return type:

TypeVar(T_Xarray, DataArray, Dataset)

Returns:

the input data interpolated to the target coordinates

compose_vector_components_on_grid(components, target_dims=[], vector_dim='c1', name='', long_name='', drop_coords=True)[source]#

turn a list of arrays into a vector field

Parameters:

  • components (list[DataArray]) – list of vector components

  • target_dims (list[str]) – if target_dims is given, it will interpolate onto it first, otherwise all componets must have the same dimesions and coordinates

  • vector_dim (str) – label of dimension indexing vector components

  • name (str) – name of new array

  • lon_name – long_name of new array

  • drop_coords (bool) – flag picked up by interpolate_to_grid() to exclude spatial coordinates relying on removed dims from output

Return type:

DataArray

diff_lin_on_grid(ds, dim, periodic_field=False)[source]#

differentiate a dataarray on staggered grid assumes that we have coordinate staggering as:

c_face(i) --  +  ------ c_face(i+1) -------- +
|             |                 |            |
+ ------ c_centre(i) ---------- + ----- c_centre(i+1)

where c_{face|center} is any dimension

Parameters:

  • ds (DataArray) – input array to be differentiated

  • dim (str) – dimension along which to differentiate

  • periodic_field (bool) – boundary condition treatment; if False will fill boundary values with NaN. Note that only 1 boundary is undefined: upper boundary for face-coordinates, and lower boundary for centre-coordinates.

Return type:

DataArray

Returns:

the derivative on the grid with offset staggering in the differentiated dimension face -> centre and v.v.

grad_on_cart_grid(ds, space_dims, periodic_field=[False, False, False])[source]#

differentiate a scalar with respect to given space dims on staggered grid

Parameters:

  • ds (DataArray) – input array to be differentiated

  • space_dims (list[str]) – labels for the spatial dimensions (to be differentiated against)

  • periodic_field (list[bool]) – boundary condition treatment; passed to diff_lin_on_grid()

Return type:

Dataset

grad_vec_on_grid(ds, target_dims=['x_centre', 'y_centre', 'z_centre'], new_dim_name=['c1', 'c2'], name=None)[source]#

computes gradient of a vector described onto target dimensions

Parameters:

  • ds (Dataset) – should be a dataset which only contains the components of the vector in sorted order and target coordinates.

  • target_dims (list[str]) – the dimensions to compute the derivative on (must be coordinates in input dataset)

  • new_dim_name (list[str]) – the names of the new dimensions: [vector component, differential component]

  • name (str | None) – name for output dataarray (optional)

Return type:

DataArray

Tensors:#

tensor_self_outer_product(arr, vec_dim='c1', new_dim='c2')[source]#

Tensor product \(a_i a_j\) from vector field arr. Assumes that arr has dimensions vec_dim but not dimension new_dim.

Parameters:

  • arr (DataArray) – xarray Dataset with dimension vec_dim which will be used for the tensor product

  • vec_dim – the dimension of the vector field to be used to form the tensor product

  • new_dim – the name of the new dimension to be created for the tensor product

  • returns – xarray DataArray with the vec_dim and new_dim dimensions sorted to the front.

Return type:

DataArray

trace(tensor, dims=('c1', 'c2'), name=None)[source]#

trace along 2 dimesions.

Parameters:

  • tensor (TypeVar(T_Xarray, DataArray, Dataset)) – tensor input

  • dims (Sequence[str]) – dimensions with respect to which to take the trace. The tensor must be square with respect to them. All coordinates of dims must match.

  • name – name of the new array. If None, the name of the input tensor is used.

Return type:

TypeVar(T_Xarray, DataArray, Dataset)

traceless(tensor, dims=('c1', 'c2'))[source]#

returns a traceless version of tensor.

NB : bug/unexpected behaviour when nan in trace

Parameters:

  • tensor (DataArray) – tensor input

  • dims (Sequence[str]) – dimensions with respect to which to take the trace.

Return type:

DataArray

Frobenius_norm(tensor, tens_dims=['c1', 'c2'])[source]#

Frobenius norm of a tensor: \(|A| = \sqrt{A_{ij} A_{ij}}\)

Parameters:

  • tensor (TypeVar(T_Xarray, DataArray, Dataset)) – tensor input

  • dims – dimensions with respect to which to take the norm.

Return type:

TypeVar(T_Xarray, DataArray, Dataset)

symmetrise(tensor, dims=['c1', 'c2'], name=None)[source]#

\(0.5 (a + a^T)\).

Parameters:

  • tensor (TypeVar(T_Xarray, DataArray, Dataset)) – tensor input

  • dims (Sequence[str]) – dimensions with respect to which to take the transpose. Can be any length and the transpose means that the order is reversed. so [c1, c2, c3] will transpose to [c3, c2, c1]. All coordinates of dims must match. Note that no checks are performed whether dims are dimensions of tensor or whether tensor is square with respect to the transposed dimensions.

  • name – name of symmetrized tensor.

Return type:

TypeVar(T_Xarray, DataArray, Dataset)

antisymmetrise(tensor, dims=['c1', 'c2'], name=None)[source]#

\(0.5 (a - a^T)\).

Parameters:

  • tensor (DataArray) – tensor input

  • dims (Sequence[str]) – dimensions with respect to which to take the transpose. Can be any length and the transpose means that the order is reversed. so [c1, c2, c3] will transpose to [c3, c2, c1]. All coordinates of dims must match. Note that no checks are performed whether dims are dimensions of tensor or whether tensor is square with respect to the transposed dimensions.

  • name – name of anti-symmetrized tensor.

Return type:

DataArray

anisotropy_renorm(tensor, tensor_dims=('c1', 'c2'))[source]#

Compute the anisotropy renormalisation of a 2-rank 3x3 tensor i.e. tensor/trace(tensor) - 1/3 Identity. Must have trace(tensor) != 0 for sensible results

Parameters:

  • tensor (TypeVar(T_Xarray, DataArray, Dataset)) – tensor input

  • tensor_dims (Sequence[str]) – tensor dimensions

Return type:

TypeVar(T_Xarray, DataArray, Dataset)

grad_scalar(sca, space_dims, new_dim_name='c1', name=None)[source]#

gradient vector of a scalar using centred 2nd order difference, reduced to 1st order at boundaries

Parameters:

  • sca (DataArray) – input scalar, with spatial coordinates space_dims

  • space_dims (list[str]) – labels for the spatial dimensions (to be differentiated against)

  • new_dim_name (str) – the name of the new dimension (of the differential direction)

  • name – name for output dataarray. If None, the name of the input scalar is used.

Return type:

DataArray

Returns:

gradient (assuming cartesian geometry)

grad_vector(vec, space_dims, new_dim_name='c2', name=None)[source]#

gradient tensor of a vector using centred 2nd order difference, reduced to 1st order at boundaries

Parameters:

  • vec (DataArray) – input vector, with spatial coordinates space_dims

  • space_dims (list[str]) – labels for the spatial dimensions (to be differentiated against)

  • new_dim_name (str) – the name of the new dimension (of the differential direction)

  • name – name for output dataarray. If None, the name of the input vector is used.

Return type:

DataArray

Returns:

gradient (assuming cartesian geometry)

grad_vector_lin(vec, space_dims, new_dim_name='c2', name=None)[source]#

gradient tensor of a vector – 1st order backward finite-difference

Parameters:

  • vec (DataArray) – input vector, with spatial coordinates space_dims

  • space_dims (list[str]) – labels for the spatial dimensions (to be differentiated against)

  • new_dim_name (str) – the name of the new dimension (of the differential direction)

  • name – name for output dataarray. If None, the name of the input vector is used.

Return type:

DataArray

Returns:

gradient (assuming cartesian geometry)