pyfvcom2.nemo_reader module

Read native NEMO model output.

class pyfvcom2.nemo_reader.NEMOReader(file_paths: str | PathLike | Sequence[str | PathLike] | Mapping[str, str | PathLike | Sequence[str | PathLike]], grid_var_names: Mapping[str, Mapping[str, str]] | None = None, mask_file_paths: str | PathLike | Mapping[str, str | PathLike] | None = None, mask_var_names: Mapping[str, str] | None = None, thickness_var_names: Mapping[str, str] | None = None, zero_profile_mask_var_names: Sequence[str] | None = ('votemper', 'vosaline'), zero_value_mask_var_names: Sequence[str] | None = ('votemper', 'vosaline'))

Bases: object

Read native NEMO files split by computational grid.

Native NEMO outputs are commonly written as separate files for variables defined on T, U, V and W grids. Unlike CMEMS products, these files often use two-dimensional curvilinear longitude and latitude coordinates. This reader keeps those per-grid coordinates intact and builds a time-to-file index for each supplied grid.

Parameters:

  • file_paths – A path/list of paths for T-grid data, or a mapping of grid name ("T", "U", "V", "W") to path/list of paths.

  • grid_var_names – Optional per-grid variable-name overrides. Each grid entry can override time, lon, lat, depth, x or y names.

  • mask_file_paths – Optional path to a NEMO mesh-mask file, or a mapping of grid name to mask file. A single path is applied to every supplied grid.

  • mask_var_names – Optional per-grid mask variable names. Defaults are tmask, umask, vmask and wmask.

  • thickness_var_names – Optional per-grid cell-thickness variable names. Defaults are e3t, e3u, e3v and e3w.

  • zero_profile_mask_var_names – Optional variable names for which all-depth zero profiles should be treated as invalid when no explicit mask is available. Defaults to AMM-style temperature and salinity names.

  • zero_value_mask_var_names – Optional variable names for which exact zero values should be treated as invalid when no explicit mask is available. This handles AMM-style below-bottom padding in temperature and salinity fields.

close() → None

Close metadata and mask datasets held by the reader.

contains_date(date_time, grid: str = 'T') → bool

Return whether a grid contains date_time within its date range.

dates(grid: str = 'T') → ndarray

Return available dates for a NEMO grid.

depth_levels(grid: str = 'T', positive_down: bool = True) → ndarray

Return depth levels for a NEMO grid.

NEMO depth coordinates are conventionally positive down. Set positive_down=False to return pyfvcom2-style z coordinates.

depth_levels_for_variable(var_name: str, grid: str | None = None, positive_down: bool = True) → ndarray

Return depth levels for a NEMO variable.

depth_var_name(grid: str = 'T') → str
get_bracketing_times(target_datetime, grid: str = 'T')

Find the two NEMO time steps bracketing target_datetime.

Returns:

(t0, t1, alpha) where alpha is the fractional weight for t1. Exact matches return (t, t, 0.0).

Return type:

tuple

get_closest_date_index(date_time, grid: str = 'T') → int

Return the index of the closest available date for a grid.

get_mask(var_name: str, target_datetime=None, grid: str | None = None, depth_index: int | None = None, tolerance=None) → ndarray

Return a boolean mask for a NEMO variable selection.

get_var(var_name: str, target_datetime=None, grid: str | None = None, depth_index: int | None = None, tolerance=None, apply_mask: bool = True) → ndarray

Return values for a NEMO variable.

If target_datetime is omitted, the variable is read from the first metadata file without time selection. If depth_index is supplied for a 3D variable, only that vertical level is returned.

get_var_ndims(var_name: str, grid: str | None = None) → int

Return the number of dimensions for a NEMO variable.

get_vertical_coordinates(var_name: str, target_datetime=None, grid: str | None = None, positive_down: bool = False) → ndarray

Return vertical coordinates for a NEMO variable selection.

If the relevant NEMO cell-thickness variable (e.g. e3t) is present, cell-centre depths are reconstructed from cumulative layer thicknesses. This captures time-varying layer thicknesses caused by the free surface. If no thickness variable is available, the static depth coordinate is broadcast over the horizontal grid.

Parameters:

  • var_name – NEMO variable name whose grid/depth convention to use.

  • target_datetime – Optional time at which to evaluate time-varying cell thicknesses.

  • grid – Optional explicit NEMO grid name.

  • positive_down – Return positive-down depths when True, otherwise return z coordinates with negative values below the surface.

grid_angle(grid: str = 'T') → ndarray

Return the local NEMO i-axis angle relative to east in radians.

The angle is estimated from neighbouring longitude/latitude points on the selected grid. It is intended for rotating native NEMO i/j velocity components onto east/north components on regional curvilinear grids.

grid_for_variable(var_name: str, grid: str | None = None) → str

Return the NEMO grid containing var_name.

property grid_names

Return the NEMO grid names supplied to the reader.

lat_var_name(grid: str = 'T') → str
lats(grid: str = 'T') → ndarray

Return native two-dimensional latitudes for a NEMO grid.

lats_for_variable(var_name: str, grid: str | None = None) → ndarray

Return native latitudes for a NEMO variable.

lon_var_name(grid: str = 'T') → str
lons(grid: str = 'T') → ndarray

Return native two-dimensional longitudes for a NEMO grid.

lons_for_variable(var_name: str, grid: str | None = None) → ndarray

Return native longitudes for a NEMO variable.

time_span(grid: str = 'T')

Return start, end and count for a NEMO grid’s available times.

time_var_name(grid: str = 'T') → str