pyfvcom2.nest module

class pyfvcom2.nest.GridBand(nodes: ndarray, elements: ndarray, node_weights: ndarray = None, element_weights: ndarray = None)

Bases: object

Grid band with adjoining nodes and elements and vertical sigma structure.

To be used when constructing an FVCOM nest.

property element_weights: ndarray

Get element weights.

Returns:

Array of element weights.

property elements: ndarray

Get element connectivity.

Returns:

Array of element connectivity.

property node_weights: ndarray

Get node weights.

Returns:

Array of node weights.

property nodes: ndarray

Get node coordinates.

Returns:

Array of node coordinates.

class pyfvcom2.nest.Nest(open_boundary: OpenBoundary)

Bases: object

Representation of an FVCOM nest

A nest consists of an open boundary and one or more grid bands which extend away from the open boundary into the interior of the domain.

Attributes:

open_boundary: OpenBoundary instance defining the nest’s open boundary. open_boundary_weights: Weights for the open boundary nodes. grid_bands: List of GridBand instances defining the nest’s grid bands.

add_grid_band(grid_band: GridBand)

Add a GridBand to the nest.

Args:

grid_band: GridBand instance to add.

get_grid_bands() → list

Get the list of GridBands in the nest.

Returns:

List of GridBand instances.

class pyfvcom2.nest.NestManager(grid: Grid, num_grid_bands=1, weights_calculation_method: str = 'linear')

Bases: object

Manager for FVCOM nests

add_forcing_data(interpolator: Interpolator, fvcom_var_name: str, horizontal_position: str) → None

Add forcing data for the nests

Args:

interpolator: Interpolator instance to use for interpolation. fvcom_var_name: FVCOM name for the forcing variable. horizontal_position: Whether coordinates are at mesh nodes or element centres (‘node’ or ‘element’).

add_nest(nest: Nest)

Add a Nest to the manager.

Args:

nest: Nest instance to add.

add_tidal_data(tide_manager: TideManager) → None

Add tidal forcing data using a TideManager.

Computes tidal predictions for zeta at nodes, and u, v at element centres, for all nest positions at the dates set via set_dates. The barotropic tidal velocities are also stored as ua and va.

Args:

tide_manager: TideManager with interpolators registered for

the required variables (zeta, u, v).

apply_ramp(ramp_length: float, initial_ts: list | None = None, ramp_type: str = 'cosine') → None

Apply a ramp to forcing (and optionally tidal) data.

Blends each variable smoothly from an initial value at t=0 to the full forcing values, preventing a shock at model start-up.

Velocities (u, v, ua, va) and sea surface elevation (zeta) are always ramped from zero. Temperature and salinity are only ramped when initial_ts is provided.

Must be called after add_forcing_data (and add_tidal_data if tidal data is present) and before create_forcing_file.

Args:

ramp_length: Spin-up duration or timescale in seconds.

For ‘cosine’ and ‘linear’, the ramp reaches full amplitude at exactly t = ramp_length. For ‘tanh’, it is a timescale: the ramp reaches ~76 % at t = ramp_length and ~99.5 % at t = 3 * ramp_length (asymptotic, never strictly reaches 1).

initial_ts: [temp_initial, salinity_initial] scalar values to ramp

from for temperature and salinity. If None those variables are not ramped.

ramp_type: Shape of the ramp function. One of:

• ‘cosine’ (default): half-cosine, C¹ continuous at both t=0 and t=ramp_length. Reaches full amplitude at t=ramp_length.

• ‘tanh’: hyperbolic tangent, C∞ everywhere but asymptotic.

• ‘linear’: linear rise, C⁰ (kinked at t=0 and t=ramp_length).

clear_nests() → None

Clear all nests from the manager

create_forcing_file(output_path: str, nest_type: int, adjust_tides: list[str] | None = None, format='NETCDF4', **kwargs) → None

Write the nest forcing data to a NetCDF file

Args:

output_path: Path to the output NetCDF file. nest_type: Type of model nesting. adjust_tides: List of variable names to adjust by adding tidal

predictions (e.g. [‘zeta’, ‘u’, ‘v’, ‘ua’, ‘va’]). Requires that add_tidal_data has been called first.

format: NetCDF format to use. Defaults to ‘NETCDF4’. **kwargs: Additional keyword arguments for writing the forcing file.

get_all_element_weights() → ndarray

Get all element weights for all nests.

Returns:

Array of element weights.

get_all_nest_elements() → ndarray

Get all unique element indices used in all nests.

Returns:

Array of unique element indices.

get_all_nest_nodes() → ndarray

Get all unique node indices used in all nests.

Returns:

Array of unique node indices.

get_all_node_weights() → ndarray

Get all node weights for all nests.

Returns:

Array of node weights.

get_forcing_data(variable: str | None = None, adjust_tides: bool = False) → dict | ndarray

Get forcing data, optionally with tidal adjustment applied.

Args:

variable: If given, return the array for that variable only.

If None, return a dict of all forcing variables.

adjust_tides: If True, add tidal predictions to the applicable

forcing variables (those for which tidal data exists). Requires that add_tidal_data has been called first.

Returns:

Dictionary of variable name to array, or a single array when variable is specified.

Raises:

PyFVCOM2ValueError: If no forcing data has been added, or the

requested variable is not available.

get_interpolation_coordinates(horizontal_position: str, vertical_position: str, horizontal_coordinate_system: str | None = 'geographic', vertical_coordinate_system: str | None = 'z') → InterpolationCoordinates

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.

Returns:

InterpolationCoordinates: The interpolation coordinates for the specified grid position.

get_nests() → list

Get the list of Nests managed by the manager.

Returns:

List of Nest instances.

get_tidal_data(variable: str | None = None) → dict | ndarray

Get tidal prediction data.

Args:

variable: If given, return the array for that variable only.

If None, return the full dict of all tidal variables.

Returns:

Dictionary of variable name to array, or a single array when variable is specified.

Raises:

PyFVCOM2ValueError: If no tidal data has been added, or the

requested variable is not available.

make_nests(num_grid_bands: int) → None

Make nests for each open boundary in the grid

Args:

grid: Grid instance containing open boundaries. num_grid_bands: Number of grid bands to create for each nest.

set_dates(dates: list[datetime]) → None

Set the dates for the forcing data

Args:

dates: List of datetime objects.