pyfvcom2.grid module

class pyfvcom2.grid.Grid(mesh_data: MeshData, sigma_data: SigmaData, coordinate_system: str, epsg_code: str | None = None)[source]

Bases: object

A class to represent a triangular mesh.

Attributes:: n_nodes (int): Number of nodes in the mesh. n_elements (int): Number of elements in the mesh. n_sigma_levels (int): Number of sigma levels in the vertical grid. n_sigma_layers (int): Number of sigma layers in the vertical grid. n_open_boundaries (int): Number of open boundaries. epsg_code (str): EPSG code used for coordinate transformations. lon_nodes (np.ndarray): Longitude of nodes. lat_nodes (np.ndarray): Latitude of nodes. lon_elements (np.ndarray): Longitude of element centroids. lat_elements (np.ndarray): Latitude of element centroids. x_nodes (np.ndarray): Cartesian x-coordinates of nodes. y_nodes (np.ndarray): Cartesian y-coordinates of nodes. x_elements (np.ndarray): Cartesian x-coordinates of element centroids. y_elements (np.ndarray): Cartesian y-coordinates of element centroids. bathy_nodes (np.ndarray): Bathymetry at nodes. bathy_elements (np.ndarray): Bathymetry at element centroids. triangles (np.ndarray): Triangle connectivity array of shape (n_elements, 3), 0-indexed. types_bdy (np.ndarray): Boundary node type codes. nodes_bdy (np.ndarray): Boundary node indices. sigma_config (SigmaConfig): Sigma coordinate configuration. sigma_levels (np.ndarray): Sigma level coordinates at nodes, shape (n_nodes, n_levels). sigma_layers (np.ndarray): Sigma layer coordinates at nodes, shape (n_nodes, n_layers). sigmac_levels (np.ndarray): Sigma level coordinates at element centroids, shape (n_elements, n_levels). sigmac_layers (np.ndarray): Sigma layer coordinates at element centroids, shape (n_elements, n_layers). sigma_levels_nodes (np.ndarray): Sigma level coordinates at nodes, shape (n_levels, n_nodes). sigma_layers_nodes (np.ndarray): Sigma layer coordinates at nodes, shape (n_layers, n_nodes). sigma_levels_elements (np.ndarray): Sigma level coordinates at element centroids, shape (n_levels, n_elements). sigma_layers_elements (np.ndarray): Sigma layer coordinates at element centroids, shape (n_layers, n_elements). z_layers_static (np.ndarray): Static z-coordinates at layer centres for nodes, shape (n_nodes, n_layers). zc_layers_static (np.ndarray): Static z-coordinates at layer centres for element centroids, shape (n_elements, n_layers). z_levels_static (np.ndarray): Static z-coordinates at layer interfaces for nodes, shape (n_nodes, n_levels). zc_levels_static (np.ndarray): Static z-coordinates at layer interfaces for element centroids, shape (n_elements, n_levels). open_boundaries (list[OpenBoundary]): List of open boundary objects.

property bathy_elements: Get the bathymetry values at element centroids.

property bathy_nodes: Get the bathymetry values at nodes.

get_interpolation_coordinates(horizontal_position: str, vertical_position: str, horizontal_coordinate_system: str = 'geographic', vertical_coordinate_system: str = 'z', dates: ndarray | None = None) → InterpolationCoordinates[source]

Get interpolation coordinates for a specific grid position.

Args:

horizontal_position: Whether coordinates are at mesh nodes or element centres (‘node’ or ‘element’). vertical_position: Whether depth coordinates are at layer centres or layer interfaces

(‘layer_centre’ or ‘layer_interface’).

horizontal_coordinate_system: The coordinate system (“geographic” or “cartesian”) for the interpolation coordinates. vertical_coordinate_system: The vertical coordinate system (“z” or “sigma”) for the interpolation coordinates. dates: Array of datetime objects for temporal interpolation. If None, returns empty array.

Returns:

InterpolationCoordinates: The interpolation coordinates for the specified grid position.

property lat_elements: Get the latitude values of element centroids.

property lat_nodes: Get the latitude values at nodes.

property lon_elements: Get the longitude values of element centroids.

property lon_nodes: Get the longitude values at nodes.

property n_elements: Get the number of elements in the mesh.

property n_nodes: Get the number of nodes in the mesh.

property n_open_boundaries: Get the number of open boundaries.

property n_sigma_layers: Get the number of sigma layers in the vertical grid.

property n_sigma_levels: Get the number of sigma levels in the vertical grid.

property nodes_bdy: Get the boundary node indices.

set_bed_roughness(z0b: float | ndarray, cbcmin: float | ndarray | None = None) → None[source]

Set the bed roughness parameters for the grid.

Args:

z0b: Bottom roughness in metres. A scalar is broadcast to all: elements; an array must have length n_elements.
cbcmin: Minimum bottom drag coefficient (dimensionless), optional.: Same broadcast/validation rules as z0b. If not supplied, cbcmin is not written by write_bed_roughness().

Raises:

PyFVCOM2ValueError: If an array argument has the wrong length.

property sigma_config: Get the sigma configuration.

property sigma_layers: Get sigma layer coordinates at nodes (n_nodes, n_layers).

property sigma_layers_elements: Get the sigma layer values at element centroids (n_layers, n_elements).

property sigma_layers_nodes: Get the sigma layer values at nodes (n_layers, n_nodes).

property sigma_levels: Get sigma level coordinates at nodes (n_nodes, n_levels).

property sigma_levels_elements: Get the sigma level values at element centroids (n_levels, n_elements).

property sigma_levels_nodes: Get the sigma level values at nodes (n_levels, n_nodes).

property sigmac_layers: Get sigma layer coordinates at element centroids (n_elements, n_layers).

property sigmac_levels: Get sigma level coordinates at element centroids (n_elements, n_levels).

property triangles: Get the triangle connectivity array (n_elements, 3), 0-indexed.

property types_bdy: Get the boundary node types array.

write_bed_roughness(roughness_file: str) → None[source]

Write the bed roughness to a NetCDF4 file.

Writes the z0b variable (bottom roughness in metres, dimensioned nele) and, if set_bed_roughness() was called with a cbcmin value, a cbcmin variable (minimum drag coefficient, dimensionless).

The output file is consumed by FVCOM via the BEDFRICFILE namelist entry.

Args:

roughness_file: Path to the output NetCDF file.

Raises:

PyFVCOM2ValueError: If set_bed_roughness() has not been: called.

write_coriolis(coriolis_file: str, coordinate_system: str) → None[source]

Write an FVCOM-formatted Coriolis file.

Args:: coriolis_file: Path to the output Coriolis file. coordinate_system: Which horizontal coordinates to write alongside latitude,

either ‘geographic’ (lon/lat) or ‘cartesian’ (x/y).

write_grid(grid_file: str, coordinate_system: str, depth_file: str | None = None) → None[source]

Write the unstructured grid to an FVCOM-formatted ASCII file.

Args:: grid_file: Path to the output grid file. coordinate_system: Which coordinates to write, either ‘geographic’ (lon/lat) or ‘cartesian’ (x/y). depth_file: If given, also write a separate FVCOM depth file.

write_obc(obc_file: str) → None[source]

Write open boundary node IDs and types to an FVCOM-formatted ASCII file.

Args:: obc_file: Path to the output open boundary file.

write_sigma(sigma_file: str) → None[source]

Write the sigma coordinate configuration to an FVCOM-formatted ASCII file.

Args:: sigma_file: Path to the output sigma file.

write_sponge(sponge_file: str) → None[source]

Write sponge layer parameters to an FVCOM-formatted ASCII file.

Collects sponge radius and coefficient values from every open boundary and writes the Sponge Node Number ASCII file consumed by FVCOM’s SPONGE_FILE namelist entry.

Args:

sponge_file: Path to the output sponge file.

Raises:

PyFVCOM2ValueError: If any open boundary has not had: OpenBoundary.set_sponge() called.

property x_elements: Get the Cartesian x-coordinates of element centroids.

property x_nodes: Get the Cartesian x-coordinates at nodes.

property y_elements: Get the Cartesian y-coordinates of element centroids.

property y_nodes: Get the Cartesian y-coordinates at nodes.

property z_layers_static: Get static z-coordinates at layer centres for nodes (n_nodes, n_layers).

property z_levels_static: Get static z-coordinates at layer interfaces for nodes (n_nodes, n_levels).

property zc_layers_static: Get static z-coordinates at layer centres for element centroids (n_elements, n_layers).

property zc_levels_static: Get static z-coordinates at layer interfaces for element centroids (n_elements, n_levels).

class pyfvcom2.grid.OpenBoundary(bdy_id: int, node_indices: ndarray, sigma_levels: ndarray, sigma_layers: ndarray)[source]

Bases: object

Represents an open boundary in the mesh.

Args:: bdy_id: Unique identifier for the boundary. node_indices: Array of node indices that form this boundary. sigma_levels: Sigma level coordinates for boundary nodes. sigma_layers: Sigma layer coordinates for boundary nodes.

property bdy_id: int

Get the boundary ID.

Returns:: Unique identifier for this boundary.

property nnodes: int

Get the number of nodes in this boundary.

Returns:: Number of nodes that form this boundary.

property node_indices: ndarray

Get the node indices for this boundary.

Returns:: Array of node indices that form this boundary.

set_sponge(radius: float | ndarray, coefficient: float | ndarray) → None[source]

Set the sponge layer parameters for all nodes on this boundary.

A scalar radius or coefficient is broadcast to every node on the boundary. Per-node arrays must have length equal to nnodes.

Args:

radius: Sponge layer radius in metres. A single float applies the: same value to every node; an array must match nnodes.
coefficient: Sponge layer coefficient (dimensionless relaxation: strength). Same broadcasting rules as radius.

Raises:

PyFVCOM2ValueError: If an array argument does not match nnodes.

property sigma_layers: ndarray

Get sigma layers for boundary nodes.

Returns:: Sigma layer coordinates for boundary nodes.

property sigma_levels: ndarray

Get sigma levels for boundary nodes.

Returns:: Sigma level coordinates for boundary nodes.

property sponge_coefficient: ndarray | None: Sponge layer coefficient at each boundary node, or None if not set.

property sponge_radius: ndarray | None: Sponge layer radius at each boundary node (m), or None if not set.

pyfvcom2.grid.connectivity(p, t)[source]

Assemble connectivity data for a triangular mesh.

The edge based connectivity is built for a triangular mesh and the boundary nodes identified. This data should be useful when implementing FE/FV methods using triangular meshes.

Args: p : np.ndarray

Nx2 array of nodes coordinates, [[x1, y1], [x2, y2], etc.]

tnp.ndarray: Mx3 array of triangles as indices, [[n11, n12, n13], [n21, n22, n23], etc.]

Returns: e : np.ndarray

Kx2 array of unique mesh edges - [[n11, n12], [n21, n22], etc.]

tenp.ndarray: Mx3 array of triangles as indices into e, [[e11, e12, e13], [e21, e22, e23], etc.]
e2tnp.ndarray: Kx2 array of triangle neighbours for unique mesh edges - [[t11, t12], [t21, t22], etc]. Each row has two entries corresponding to the triangle numbers associated with each edge in e. Boundary edges have e2t[i, 1] = -1.
bndnp.ndarray, bool: Nx1 logical array identifying boundary nodes. p[i, :] is a boundary node if bnd[i] = True.

Notes: Python translation of the MATLAB MESH2D connectivity function by Darren Engwirda. See: https://github.com/dengwirda/MESH2D. Code translated by Pierre Cazenave, PML.

References: .. [1] Darren Engwirda, Locally-optimal Delaunay-refinement and optimisation-based mesh generation, Ph.D. Thesis, School of Mathematics and Statistics, The University of Sydney, September 2014.

pyfvcom2.grid.find_connected_elements(n, triangles)[source]

Return the IDs of the elements connected to node number `n’.

Parameters:

n (int or iterable) – Node ID(s) around which to find the connected elements. If more than one node is given, the unique elements for all nodes are returned. Order of results is not maintained.
triangles (np.ndarray) – Triangulation matrix to find the connected elements. Shape is [nele, 3].

Returns:

surroundingidx – Indices of the surrounding elements.

Return type:

np.ndarray