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.

Variables:

  • 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.

Parameters:

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

Parameters:

  • 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.

Parameters:

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.

Parameters:

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.

Parameters:

  • 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, extra_node_vars: list[str] | None = None, extra_var_attributes: dict | None = None, format='NETCDF4', **kwargs) → None

Write the nest forcing data to a NetCDF file

Parameters:

  • 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.

  • extra_node_vars – Optional list of additional node-based, 3D (time, siglay, node) forcing variables to write, e.g. biogeochemistry/ERSEM tracers. Each name must already have been registered via add_forcing_data.

  • extra_var_attributes – Optional mapping of variable name to a dict of NetCDF attributes for the variables named in extra_node_vars. Any variable without an entry falls back to generic attributes derived from its name.

  • 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.

Parameters:

  • 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.

Parameters:

  • 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:

The interpolation coordinates for the specified grid position.

Return type:

InterpolationCoordinates

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.

Parameters:

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

Parameters:

  • 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

Parameters:

dates – List of datetime objects.