Models Module

The nereus.models module provides support for specific atmospheric and ocean models. All mesh loaders return standardized xr.Dataset objects with consistent variable naming.

Universal Mesh Loader

nereus.models.load_mesh(path, *, mesh_type=None, use_dask=None, **kwargs)

Universal mesh loader with auto-detection.

Parameters:

• path (str, Path, or int) – Path to mesh directory/file, or number of points for HEALPix.

• mesh_type (str, optional) – Mesh type: “fesom”, “healpix”, “nemo”, “ifs_tco”, or “auto”. If None or “auto”, attempts to auto-detect.

• use_dask (bool, optional) – Whether to use dask arrays. Auto-detects if None.

• **kwargs – Additional arguments passed to model-specific loader.

Returns:

Standardized mesh dataset.

Return type:

xr.Dataset

Examples

>>> # Auto-detect FESOM mesh
>>> mesh = nr.load_mesh("/path/to/mesh")

>>> # Explicit type
>>> mesh = nr.load_mesh("/path/to/mesh_mask.nc", mesh_type="nemo")

>>> # HEALPix from npoints
>>> mesh = nr.load_mesh(3145728, mesh_type="healpix")

nereus.models.detect_mesh_type(path)

Auto-detect mesh type from path.

Parameters:

path (str or Path) – Path to mesh directory or file.

Returns:

Detected mesh type: “fesom”, “mitgcm”, “mpas”, “nemo”, or “unknown”.

Return type:

str

Notes

HEALPix meshes are generated, not loaded from files, so this function only detects file-based mesh types.

FESOM2

The Finite Element Sea ice-Ocean Model version 2 uses an unstructured triangular mesh.

FESOM2 model support for nereus.

This module provides functionality for working with FESOM2 ocean model data, including mesh loading and data handling.

Examples

>>> import nereus as nr

# Load a FESOM mesh (returns xr.Dataset) >>> mesh = nr.fesom.load_mesh(“/path/to/mesh”) >>> print(f”Mesh has {mesh.sizes[‘npoints’]} nodes”)

# Access mesh data >>> lon = mesh[“lon”] # xr.DataArray >>> lon_np = mesh[“lon”].values # numpy array >>> area = mesh[“area”] >>> triangles = mesh[“triangles”]

# Open data with mesh coordinates >>> ds = nr.fesom.open_dataset(“temp.fesom.2010.nc”, mesh=mesh)

# Use with diagnostics >>> ice_area = nr.ice_area(sic, mesh[“area”], mask=mesh[“lat”] > 0)

# Use with plotting >>> fig, ax, _ = nr.plot(ds.temp[0, 0, :], mesh[“lon”].values, mesh[“lat”].values)

nereus.models.fesom.compute_element_centers(mesh)

Compute element center coordinates.

Adds lon_tri and lat_tri variables to the mesh dataset.

Parameters:

mesh (xr.Dataset) – FESOM mesh dataset with lon, lat, and triangles.

Returns:

Mesh with lon_tri and lat_tri added.

Return type:

xr.Dataset

Examples

>>> mesh = nr.fesom.load_mesh(path)
>>> mesh = nr.fesom.compute_element_centers(mesh)
>>> lon_elem = mesh["lon_tri"]

nereus.models.fesom.element_to_node(data, mesh, method='mean')

Interpolate data from element centers to nodes.

For each node, aggregates values from all connected elements.

Parameters:

• data (xr.DataArray or ndarray) – Element data with shape (…, nelem).

• mesh (xr.Dataset) – FESOM mesh dataset with triangles.

• method ({"mean", "sum"}) – Aggregation method.

Returns:

Node data with shape (…, npoints).

Return type:

xr.DataArray or ndarray

Examples

>>> mesh = nr.fesom.load_mesh(path)
>>> temp_node = nr.fesom.element_to_node(temp_elem, mesh)

nereus.models.fesom.load_mesh(path, *, use_dask=None)

Load FESOM mesh from directory or NetCDF file.

Parameters:

• path (str or Path) – Path to mesh directory (containing nod2d.out, etc.) or to fesom.mesh.diag.nc file.

• use_dask (bool, optional) – Whether to use dask arrays. If None, auto-detects based on mesh size (>1M points triggers dask).

Returns:

Standardized mesh dataset with: - lon, lat: Node coordinates (npoints,) - area: Node cluster area in m^2 (npoints,) - triangles: 0-indexed triangle connectivity (nelem, 3) - lon_tri, lat_tri: Element center coordinates (nelem,) - depth: Layer center depths in meters (nz,) - depth_bounds: Layer interfaces (nz, 2) - layer_thickness: Layer thickness in meters (nz,) Plus original FESOM variables with their native names.

Return type:

xr.Dataset

Examples

>>> mesh = nr.fesom.load_mesh("/path/to/mesh")
>>> print(f"Mesh has {mesh.sizes['npoints']} nodes")
>>> area = mesh["area"]
>>> lon = mesh["lon"].values

nereus.models.fesom.mask_by_depth(data, nod_area_nans)

Apply depth mask to data, setting invalid cells to NaN.

This function masks ocean data based on bottom topography using nod_area_nans from the FESOM mesh, which contains NaN for cells below the ocean floor.

Parameters:

• data (xr.DataArray or ndarray) – Data to mask. Can be: - 2D array (nz, npoints) for 3D fields - 1D array (npoints,) for 2D fields at a single level

• nod_area_nans (xr.DataArray or ndarray) – 3D node area array with NaN where cells are below bottom/land. Use mesh.nod_area_nans or a slice of it (e.g., mesh.nod_area_nans[10, :]). Must match data shape.

Returns:

Masked data as numpy array with NaN where nod_area_nans is NaN. Returns float64 to support NaN values.

Return type:

ndarray

Examples

>>> mesh = nr.fesom.load_mesh(path)
>>> # Mask 3D temperature field
>>> temp_masked = nr.fesom.mask_by_depth(temp_3d, mesh.nod_area_nans)
>>>
>>> # Mask single level (e.g., level 10)
>>> temp_lev10_masked = nr.fesom.mask_by_depth(
...     temp_3d[10, :], mesh.nod_area_nans[10, :]
... )

Notes

The function is dimension-name-agnostic - it works purely by array shape. This avoids issues with inconsistent dimension names across different FESOM output files (nod2, npoints, ncells, etc.).

For volume computations, you can use nod_area_nans directly since it already contains the area values with NaN for invalid cells.

nereus.models.fesom.node_to_element(data, mesh, method='mean')

Interpolate data from nodes to element centers.

For each triangle, computes an aggregate of its three vertex values.

Parameters:

• data (xr.DataArray or ndarray) – Node data with shape (…, npoints).

• mesh (xr.Dataset) – FESOM mesh dataset with triangles.

• method ({"mean", "median", "min", "max"}) – Aggregation method.

Returns:

Element data with shape (…, nelem).

Return type:

xr.DataArray or ndarray

Examples

>>> mesh = nr.fesom.load_mesh(path)
>>> temp_elem = nr.fesom.node_to_element(temp_node, mesh)

nereus.models.fesom.open_dataset(data_path, mesh=None, mesh_path=None)

Open a FESOM2 data file with mesh information.

Parameters:

• data_path (str or path-like) – Path to the data file (NetCDF).

• mesh (xr.Dataset, optional) – Pre-loaded mesh dataset. If not provided, mesh_path must be specified.

• mesh_path (str or path-like, optional) – Path to mesh directory. Ignored if mesh is provided.

Returns:

Dataset with mesh coordinates attached.

Return type:

xr.Dataset

Examples

>>> mesh = nr.fesom.load_mesh("/meshes/core2")
>>> ds = nr.fesom.open_dataset("temp.fesom.2010.nc", mesh=mesh)
>>> ds = nr.fesom.open_dataset("temp.fesom.2010.nc", mesh_path="/meshes/core2")

FESOM2 Mesh Loading

nereus.models.fesom.load_mesh(path, *, use_dask=None)

Load FESOM mesh from directory or NetCDF file.

Parameters:

• path (str or Path) – Path to mesh directory (containing nod2d.out, etc.) or to fesom.mesh.diag.nc file.

• use_dask (bool, optional) – Whether to use dask arrays. If None, auto-detects based on mesh size (>1M points triggers dask).

Returns:

Standardized mesh dataset with: - lon, lat: Node coordinates (npoints,) - area: Node cluster area in m^2 (npoints,) - triangles: 0-indexed triangle connectivity (nelem, 3) - lon_tri, lat_tri: Element center coordinates (nelem,) - depth: Layer center depths in meters (nz,) - depth_bounds: Layer interfaces (nz, 2) - layer_thickness: Layer thickness in meters (nz,) Plus original FESOM variables with their native names.

Return type:

xr.Dataset

Examples

>>> mesh = nr.fesom.load_mesh("/path/to/mesh")
>>> print(f"Mesh has {mesh.sizes['npoints']} nodes")
>>> area = mesh["area"]
>>> lon = mesh["lon"].values

The load_mesh function expects a directory containing FESOM2 mesh files:

Required files:

• nod2d.out: ASCII file with 2D node coordinates

  # node_id longitude latitude boundary_flag
  1 -180.0 -80.0 0
  2 -179.5 -80.0 0
  ...
  

• elem2d.out: ASCII file with element connectivity

  # elem_id node1 node2 node3
  1 1 2 100
  2 2 3 101
  ...
  

• mesh.diag.nc or fesom.mesh.diag.nc: NetCDF file with node areas

  Dimensions: nod2, nz
  Variables: nod_area(nz, nod2)
  

Optional files:

• aux3d.out: ASCII file with vertical level information

  # depth levels (one per line)
  0.0
  10.0
  25.0
  ...
  

FESOM2 Functions

nereus.models.fesom.compute_element_centers(mesh)

Compute element center coordinates.

Adds lon_tri and lat_tri variables to the mesh dataset.

Parameters:

mesh (xr.Dataset) – FESOM mesh dataset with lon, lat, and triangles.

Returns:

Mesh with lon_tri and lat_tri added.

Return type:

xr.Dataset

Examples

>>> mesh = nr.fesom.load_mesh(path)
>>> mesh = nr.fesom.compute_element_centers(mesh)
>>> lon_elem = mesh["lon_tri"]

nereus.models.fesom.node_to_element(data, mesh, method='mean')

Interpolate data from nodes to element centers.

For each triangle, computes an aggregate of its three vertex values.

Parameters:

• data (xr.DataArray or ndarray) – Node data with shape (…, npoints).

• mesh (xr.Dataset) – FESOM mesh dataset with triangles.

• method ({"mean", "median", "min", "max"}) – Aggregation method.

Returns:

Element data with shape (…, nelem).

Return type:

xr.DataArray or ndarray

Examples

>>> mesh = nr.fesom.load_mesh(path)
>>> temp_elem = nr.fesom.node_to_element(temp_node, mesh)

nereus.models.fesom.element_to_node(data, mesh, method='mean')

Interpolate data from element centers to nodes.

For each node, aggregates values from all connected elements.

Parameters:

• data (xr.DataArray or ndarray) – Element data with shape (…, nelem).

• mesh (xr.Dataset) – FESOM mesh dataset with triangles.

• method ({"mean", "sum"}) – Aggregation method.

Returns:

Node data with shape (…, npoints).

Return type:

xr.DataArray or ndarray

Examples

>>> mesh = nr.fesom.load_mesh(path)
>>> temp_node = nr.fesom.element_to_node(temp_elem, mesh)

nereus.models.fesom.mask_by_depth(data, nod_area_nans)

Apply depth mask to data, setting invalid cells to NaN.

This function masks ocean data based on bottom topography using nod_area_nans from the FESOM mesh, which contains NaN for cells below the ocean floor.

Parameters:

• data (xr.DataArray or ndarray) – Data to mask. Can be: - 2D array (nz, npoints) for 3D fields - 1D array (npoints,) for 2D fields at a single level

• nod_area_nans (xr.DataArray or ndarray) – 3D node area array with NaN where cells are below bottom/land. Use mesh.nod_area_nans or a slice of it (e.g., mesh.nod_area_nans[10, :]). Must match data shape.

Returns:

Masked data as numpy array with NaN where nod_area_nans is NaN. Returns float64 to support NaN values.

Return type:

ndarray

Examples

>>> mesh = nr.fesom.load_mesh(path)
>>> # Mask 3D temperature field
>>> temp_masked = nr.fesom.mask_by_depth(temp_3d, mesh.nod_area_nans)
>>>
>>> # Mask single level (e.g., level 10)
>>> temp_lev10_masked = nr.fesom.mask_by_depth(
...     temp_3d[10, :], mesh.nod_area_nans[10, :]
... )

Notes

The function is dimension-name-agnostic - it works purely by array shape. This avoids issues with inconsistent dimension names across different FESOM output files (nod2, npoints, ncells, etc.).

For volume computations, you can use nod_area_nans directly since it already contains the area values with NaN for invalid cells.

nereus.models.fesom.open_dataset(data_path, mesh=None, mesh_path=None)

Open a FESOM2 data file with mesh information.

Parameters:

• data_path (str or path-like) – Path to the data file (NetCDF).

• mesh (xr.Dataset, optional) – Pre-loaded mesh dataset. If not provided, mesh_path must be specified.

• mesh_path (str or path-like, optional) – Path to mesh directory. Ignored if mesh is provided.

Returns:

Dataset with mesh coordinates attached.

Return type:

xr.Dataset

Examples

>>> mesh = nr.fesom.load_mesh("/meshes/core2")
>>> ds = nr.fesom.open_dataset("temp.fesom.2010.nc", mesh=mesh)
>>> ds = nr.fesom.open_dataset("temp.fesom.2010.nc", mesh_path="/meshes/core2")

HEALPix

HEALPix (Hierarchical Equal Area isoLatitude Pixelization) grids are used by ICON and other models.

HEALPix grid support for nereus.

This module provides functionality for working with HEALPix grids, commonly used in climate models like ICON and IFS.

Examples

>>> import nereus as nr

# Create HEALPix mesh from number of points >>> mesh = nr.healpix.load_mesh(3145728) # nside=512

# Or use nside directly >>> npoints = nr.healpix.nside_to_npoints(512) >>> mesh = nr.healpix.load_mesh(npoints)

# Access mesh data >>> lon = mesh[“lon”].values >>> area = mesh[“area”] # Uniform for all pixels

nereus.models.healpix.load_mesh(npoints, *, nest=True, use_dask=None)

Create HEALPix mesh from number of points.

Infers nside from npoints (npoints = 12 * nside^2).

Parameters:

• npoints (int) – Number of HEALPix pixels. Must be 12 * nside^2 for valid nside.

• nest (bool) – Use NESTED ordering (True) or RING ordering (False). Default is NESTED (True).

• use_dask (bool, optional) – Whether to use dask arrays. Auto-detects if None.

Returns:

Mesh dataset with: - lon: Pixel center longitudes (npoints,) - lat: Pixel center latitudes (npoints,) - area: Pixel area in m^2 (uniform for HEALPix) (npoints,)

Return type:

xr.Dataset

Examples

>>> # Create HEALPix mesh with ~3 million pixels (nside=512)
>>> mesh = nr.healpix.load_mesh(3145728)
>>> print(f"Pixel area: {mesh['area'].values[0] / 1e6:.1f} km^2")

>>> # Create smaller mesh for testing
>>> mesh = nr.healpix.load_mesh(12 * 64**2)  # nside=64

nereus.models.healpix.npoints_to_nside(npoints)

Convert number of points to HEALPix nside parameter.

Parameters:

npoints (int) – Number of HEALPix pixels.

Returns:

HEALPix nside parameter.

Return type:

int

Raises:

ValueError – If npoints is not a valid HEALPix pixel count.

Examples

>>> nr.healpix.npoints_to_nside(3145728)
512

nereus.models.healpix.nside_to_npoints(nside)

Convert HEALPix nside parameter to number of points.

Parameters:

nside (int) – HEALPix nside parameter (must be power of 2).

Returns:

Number of pixels (12 * nside^2).

Return type:

int

Examples

>>> nr.healpix.nside_to_npoints(512)
3145728

nereus.models.healpix.resolution_to_nside(resolution_deg)

Get approximate nside for desired angular resolution.

Parameters:

resolution_deg (float) – Desired angular resolution in degrees.

Returns:

Recommended nside (power of 2).

Return type:

int

Examples

>>> # Get nside for ~1 degree resolution
>>> nside = nr.healpix.resolution_to_nside(1.0)
>>> print(nside)
64

HEALPix Mesh Loading

nereus.models.healpix.load_mesh(npoints, *, nest=True, use_dask=None)

Create HEALPix mesh from number of points.

Infers nside from npoints (npoints = 12 * nside^2).

Parameters:

• npoints (int) – Number of HEALPix pixels. Must be 12 * nside^2 for valid nside.

• nest (bool) – Use NESTED ordering (True) or RING ordering (False). Default is NESTED (True).

• use_dask (bool, optional) – Whether to use dask arrays. Auto-detects if None.

Returns:

Mesh dataset with: - lon: Pixel center longitudes (npoints,) - lat: Pixel center latitudes (npoints,) - area: Pixel area in m^2 (uniform for HEALPix) (npoints,)

Return type:

xr.Dataset

Examples

>>> # Create HEALPix mesh with ~3 million pixels (nside=512)
>>> mesh = nr.healpix.load_mesh(3145728)
>>> print(f"Pixel area: {mesh['area'].values[0] / 1e6:.1f} km^2")

>>> # Create smaller mesh for testing
>>> mesh = nr.healpix.load_mesh(12 * 64**2)  # nside=64

HEALPix Utilities

nereus.models.healpix.nside_to_npoints(nside)

Convert HEALPix nside parameter to number of points.

Parameters:

nside (int) – HEALPix nside parameter (must be power of 2).

Returns:

Number of pixels (12 * nside^2).

Return type:

int

Examples

>>> nr.healpix.nside_to_npoints(512)
3145728

nereus.models.healpix.npoints_to_nside(npoints)

Convert number of points to HEALPix nside parameter.

Parameters:

npoints (int) – Number of HEALPix pixels.

Returns:

HEALPix nside parameter.

Return type:

int

Raises:

ValueError – If npoints is not a valid HEALPix pixel count.

Examples

>>> nr.healpix.npoints_to_nside(3145728)
512

nereus.models.healpix.resolution_to_nside(resolution_deg)

Get approximate nside for desired angular resolution.

Parameters:

resolution_deg (float) – Desired angular resolution in degrees.

Returns:

Recommended nside (power of 2).

Return type:

int

Examples

>>> # Get nside for ~1 degree resolution
>>> nside = nr.healpix.resolution_to_nside(1.0)
>>> print(nside)
64

NEMO

NEMO (Nucleus for European Modelling of the Ocean) uses structured grids.

NEMO ocean model support for nereus.

This module provides functionality for working with NEMO ocean model meshes, loading from mesh_mask.nc files.

Examples

>>> import nereus as nr

# Load NEMO mesh >>> mesh = nr.nemo.load_mesh(“/path/to/mesh_mask.nc”)

# Access flattened coordinates >>> lon = mesh[“lon”].values # 1D array >>> lat = mesh[“lat”].values >>> area = mesh[“area”]

# The mesh includes original 2D shape for reshaping >>> shape_2d = (mesh.attrs[“nlat”], mesh.attrs[“nlon”])

nereus.models.nemo.flatten_structured(lon_2d, lat_2d, mask=None)

Flatten 2D structured coordinates to 1D.

Parameters:

• lon_2d (ndarray) – 2D longitude array (nlat, nlon).

• lat_2d (ndarray) – 2D latitude array (nlat, nlon).

• mask (ndarray, optional) – Boolean mask (True = include). If None, includes all points.

Returns:

• lon (ndarray) – Flattened longitude (npoints,).

• lat (ndarray) – Flattened latitude (npoints,).

• indices (ndarray) – Flat indices for reconstructing 2D arrays.

Return type:

tuple[ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[floating]], ndarray[tuple[Any, …], dtype[int64]]]

Examples

>>> lon, lat, indices = nr.nemo.flatten_structured(lon_2d, lat_2d, mask=ocean_mask)
>>> # To reshape data back to 2D:
>>> data_2d = np.full(lon_2d.shape, np.nan)
>>> data_2d.flat[indices] = data_1d

nereus.models.nemo.load_mesh(path, *, use_dask=None, mask_var='tmask', lon_var=None, lat_var=None, area_var=None)

Load NEMO mesh from mesh_mask.nc or coordinates file.

Flattens 2D coordinates to 1D for compatibility with nereus functions. Ocean points are identified using the mask variable.

Parameters:

• path (str or Path) – Path to mesh_mask.nc or coordinates file.

• use_dask (bool, optional) – Whether to use dask arrays. Auto-detects if None.

• mask_var (str) – Variable name for ocean mask (default: “tmask”). Set to None to include all points.

• lon_var (str, optional) – Longitude variable name. Auto-detects if None.

• lat_var (str, optional) – Latitude variable name. Auto-detects if None.

• area_var (str, optional) – Cell area variable name. Auto-detects if None.

Returns:

Mesh dataset with: - lon, lat: Flattened coordinates (npoints,) - area: Cell area in m^2 (npoints,) - mask: Ocean mask (npoints,) Attributes include original 2D shape for reshaping.

Return type:

xr.Dataset

Examples

>>> mesh = nr.nemo.load_mesh("/path/to/mesh_mask.nc")
>>> print(f"Ocean points: {mesh.sizes['npoints']}")

>>> # Include all points (land + ocean)
>>> mesh = nr.nemo.load_mesh(path, mask_var=None)

NEMO Mesh Loading

nereus.models.nemo.load_mesh(path, *, use_dask=None, mask_var='tmask', lon_var=None, lat_var=None, area_var=None)

Load NEMO mesh from mesh_mask.nc or coordinates file.

Flattens 2D coordinates to 1D for compatibility with nereus functions. Ocean points are identified using the mask variable.

Parameters:

• path (str or Path) – Path to mesh_mask.nc or coordinates file.

• use_dask (bool, optional) – Whether to use dask arrays. Auto-detects if None.

• mask_var (str) – Variable name for ocean mask (default: “tmask”). Set to None to include all points.

• lon_var (str, optional) – Longitude variable name. Auto-detects if None.

• lat_var (str, optional) – Latitude variable name. Auto-detects if None.

• area_var (str, optional) – Cell area variable name. Auto-detects if None.

Returns:

Mesh dataset with: - lon, lat: Flattened coordinates (npoints,) - area: Cell area in m^2 (npoints,) - mask: Ocean mask (npoints,) Attributes include original 2D shape for reshaping.

Return type:

xr.Dataset

Examples

>>> mesh = nr.nemo.load_mesh("/path/to/mesh_mask.nc")
>>> print(f"Ocean points: {mesh.sizes['npoints']}")

>>> # Include all points (land + ocean)
>>> mesh = nr.nemo.load_mesh(path, mask_var=None)

The NEMO mesh loader expects a mesh_mask.nc file and flattens 2D coordinates to 1D for compatibility with nereus functions. Original 2D shape information is preserved in mesh attributes.

MITgcm

MITgcm (MIT General Circulation Model) reads native MDS binary files (.meta + .data).

MITgcm ocean model support for nereus.

This module provides functionality for working with MITgcm model output, reading from the native MDS binary format (.meta + .data file pairs).

Examples

>>> import nereus as nr

# Load MITgcm mesh >>> mesh = nr.mitgcm.load_mesh(“/path/to/run/”)

# Load diagnostic data >>> ds = nr.mitgcm.open_dataset(“/path/to/run/”, prefix=”diags2D”, … delta_t=3600, ref_date=”1710-1-1”, mesh=mesh)

nereus.models.mitgcm.load_mesh(path, *, grid_type='C', use_dask=None, mask_land=False)

Load MITgcm mesh from a directory of MDS grid files.

Parameters:

• path (str or Path) – Directory containing MITgcm grid files (XC.data, YC.data, etc.).

• grid_type ({"C", "G"}) – Which grid point to use: - "C": Cell centers (reads XC/YC). - "G": Cell corners (reads XG/YG).

• use_dask (bool, optional) – Whether to use dask arrays. Auto-detects if None.

• mask_land (bool) – If True, derive land/ocean masks from hFacC.data (3D, per-level) or fall back to Depth.data > 0 (2D surface only). The masks are stored as land_mask (2D boolean, npoints) and hFacC (3D float, depth_level × npoints) if available. Default is False to preserve raw data access.

Returns:

Mesh dataset with lon, lat, area on npoints dimension. Optionally includes depth, layer_thickness, bathymetry. When mask_land=True, also includes land_mask and hFacC. Attributes include nx, ny, original_shape.

Return type:

xr.Dataset

Examples

>>> mesh = nr.mitgcm.load_mesh("/path/to/run/")
>>> mesh_masked = nr.mitgcm.load_mesh("/path/to/run/", mask_land=True)
>>> # Use mask to filter data: ds["THETA"].where(~mesh["land_mask"])

nereus.models.mitgcm.open_dataset(path, prefix, iters='all', *, delta_t=1.0, ref_date=None, mesh=None, mask_land=False)

Load MITgcm diagnostic output as an xarray Dataset.

Parameters:

• path (str or Path) – Directory containing MDS diagnostic files.

• prefix (str or list of str) – Diagnostic file prefix(es) (e.g., "diags2D" or ["diags2D", "diags3D"]).

• iters ("all" or list of int) – Iteration numbers to load. "all" discovers all available.

• delta_t (float) – Model timestep in seconds (used to compute time coordinate).

• ref_date (str, optional) – Reference date string (e.g., "1710-1-1"). If given, time coordinate is datetime64; otherwise seconds from start.

• mesh (xr.Dataset, optional) – Nereus mesh dataset. If provided, attaches lon, lat (and depth if available) as coordinates.

• mask_land (bool) – If True, replace land-point values with NaN. Uses hFacC from mesh (3D per-level masking) or land_mask (2D surface masking). Requires mesh loaded with mask_land=True. If mesh has no mask variables, this option is silently ignored.

Returns:

Dataset with dimensions (time, npoints) for 2D fields and (time, depth_level, npoints) for 3D fields.

Return type:

xr.Dataset

Examples

>>> ds = nr.mitgcm.open_dataset(
...     "/path/to/run/", prefix="diags2D",
...     delta_t=3600, ref_date="1710-1-1",
... )

MITgcm Mesh Loading

nereus.models.mitgcm.load_mesh(path, *, grid_type='C', use_dask=None, mask_land=False)

Load MITgcm mesh from a directory of MDS grid files.

Parameters:

• path (str or Path) – Directory containing MITgcm grid files (XC.data, YC.data, etc.).

• grid_type ({"C", "G"}) – Which grid point to use: - "C": Cell centers (reads XC/YC). - "G": Cell corners (reads XG/YG).

• use_dask (bool, optional) – Whether to use dask arrays. Auto-detects if None.

• mask_land (bool) – If True, derive land/ocean masks from hFacC.data (3D, per-level) or fall back to Depth.data > 0 (2D surface only). The masks are stored as land_mask (2D boolean, npoints) and hFacC (3D float, depth_level × npoints) if available. Default is False to preserve raw data access.

Returns:

Mesh dataset with lon, lat, area on npoints dimension. Optionally includes depth, layer_thickness, bathymetry. When mask_land=True, also includes land_mask and hFacC. Attributes include nx, ny, original_shape.

Return type:

xr.Dataset

Examples

>>> mesh = nr.mitgcm.load_mesh("/path/to/run/")
>>> mesh_masked = nr.mitgcm.load_mesh("/path/to/run/", mask_land=True)
>>> # Use mask to filter data: ds["THETA"].where(~mesh["land_mask"])

The MITgcm mesh loader expects a directory containing grid files (XC.data, YC.data, optionally RAC.data, RC.data, DRF.data, Depth.data). 2D coordinates are flattened to 1D for compatibility with nereus functions.

Use mask_land=True to load land/ocean masks from hFacC.data (3D per-level) or Depth.data (2D fallback). The mesh will then contain land_mask (boolean) and hFacC (float with partial cell fractions).

MITgcm Data Loading

nereus.models.mitgcm.open_dataset(path, prefix, iters='all', *, delta_t=1.0, ref_date=None, mesh=None, mask_land=False)

Load MITgcm diagnostic output as an xarray Dataset.

Parameters:

• path (str or Path) – Directory containing MDS diagnostic files.

• prefix (str or list of str) – Diagnostic file prefix(es) (e.g., "diags2D" or ["diags2D", "diags3D"]).

• iters ("all" or list of int) – Iteration numbers to load. "all" discovers all available.

• delta_t (float) – Model timestep in seconds (used to compute time coordinate).

• ref_date (str, optional) – Reference date string (e.g., "1710-1-1"). If given, time coordinate is datetime64; otherwise seconds from start.

• mesh (xr.Dataset, optional) – Nereus mesh dataset. If provided, attaches lon, lat (and depth if available) as coordinates.

• mask_land (bool) – If True, replace land-point values with NaN. Uses hFacC from mesh (3D per-level masking) or land_mask (2D surface masking). Requires mesh loaded with mask_land=True. If mesh has no mask variables, this option is silently ignored.

Returns:

Dataset with dimensions (time, npoints) for 2D fields and (time, depth_level, npoints) for 3D fields.

Return type:

xr.Dataset

Examples

>>> ds = nr.mitgcm.open_dataset(
...     "/path/to/run/", prefix="diags2D",
...     delta_t=3600, ref_date="1710-1-1",
... )

Reads MDS diagnostic output and produces xr.Dataset with proper variable names, time coordinates, and spatial dimensions matching the nereus mesh convention.

MPAS-Ocean

MPAS-Ocean (Model for Prediction Across Scales) uses an unstructured Voronoi mesh stored in standard NetCDF files.

MPAS ocean model support for nereus.

This module provides functionality for working with MPAS-Ocean model output. MPAS uses an unstructured Voronoi mesh stored in standard NetCDF files, with mesh information embedded alongside the data.

Examples

>>> import nereus as nr

# Load MPAS mesh from any MPAS-Ocean NetCDF file >>> mesh = nr.mpas.load_mesh(“/path/to/mpas_output.nc”)

# Open data file with mesh coordinates attached >>> ds = nr.mpas.open_dataset(“/path/to/mpas_output.nc”, mesh=mesh)

nereus.models.mpas.load_mesh(path, *, use_dask=None)

Load MPAS-Ocean mesh from a NetCDF file.

Any MPAS-Ocean NetCDF file can be used because mesh variables (lonCell, latCell, areaCell, etc.) are embedded in every output file.

Parameters:

• path (str or Path) – Path to an MPAS-Ocean NetCDF file.

• use_dask (bool, optional) – Whether to use dask arrays. Auto-detects if None.

Returns:

Mesh dataset with lon, lat, area on npoints dimension. Also includes depth, layer_thickness, bathymetry, maxLevelCell when available in the source file.

Return type:

xr.Dataset

Examples

>>> mesh = nr.mpas.load_mesh("/path/to/mpas_output.nc")

nereus.models.mpas.open_dataset(data_path, mesh=None, mesh_path=None)

Open an MPAS-Ocean data file with mesh coordinates attached.

Parameters:

• data_path (str or path-like) – Path to the data file (NetCDF).

• mesh (xr.Dataset, optional) – Pre-loaded mesh dataset. If not provided, mesh_path must be specified, or mesh will be loaded from the data file itself.

• mesh_path (str or path-like, optional) – Path to a file to load mesh from. Ignored if mesh is provided.

Returns:

Dataset with mesh coordinates attached.

Return type:

xr.Dataset

Examples

>>> mesh = nr.mpas.load_mesh("/path/to/mpas_output.nc")
>>> ds = nr.mpas.open_dataset("/path/to/another_output.nc", mesh=mesh)

>>> # Or load mesh from the data file itself
>>> ds = nr.mpas.open_dataset("/path/to/mpas_output.nc")

MPAS-Ocean Mesh Loading

nereus.models.mpas.load_mesh(path, *, use_dask=None)

Load MPAS-Ocean mesh from a NetCDF file.

Any MPAS-Ocean NetCDF file can be used because mesh variables (lonCell, latCell, areaCell, etc.) are embedded in every output file.

Parameters:

• path (str or Path) – Path to an MPAS-Ocean NetCDF file.

• use_dask (bool, optional) – Whether to use dask arrays. Auto-detects if None.

Returns:

Mesh dataset with lon, lat, area on npoints dimension. Also includes depth, layer_thickness, bathymetry, maxLevelCell when available in the source file.

Return type:

xr.Dataset

Examples

>>> mesh = nr.mpas.load_mesh("/path/to/mpas_output.nc")

The MPAS-Ocean mesh loader reads any MPAS-Ocean NetCDF file, since mesh variables (lonCell, latCell, areaCell, etc.) are embedded in every output file. Coordinates are converted from radians to degrees and normalized to [-180, 180].

MPAS-Ocean Data Loading

nereus.models.mpas.open_dataset(data_path, mesh=None, mesh_path=None)

Open an MPAS-Ocean data file with mesh coordinates attached.

Parameters:

• data_path (str or path-like) – Path to the data file (NetCDF).

• mesh (xr.Dataset, optional) – Pre-loaded mesh dataset. If not provided, mesh_path must be specified, or mesh will be loaded from the data file itself.

• mesh_path (str or path-like, optional) – Path to a file to load mesh from. Ignored if mesh is provided.

Returns:

Dataset with mesh coordinates attached.

Return type:

xr.Dataset

Examples

>>> mesh = nr.mpas.load_mesh("/path/to/mpas_output.nc")
>>> ds = nr.mpas.open_dataset("/path/to/another_output.nc", mesh=mesh)

>>> # Or load mesh from the data file itself
>>> ds = nr.mpas.open_dataset("/path/to/mpas_output.nc")

Opens an MPAS-Ocean NetCDF file and attaches mesh coordinates (lon, lat, depth) from the mesh dataset. If no mesh is provided, it is loaded from the data file itself.

IFS TCO

IFS TCO model support for nereus.

This module provides functionality for loading IFS TCO meshes as xr.Dataset objects with standardized variable names.

Examples

>>> import nereus as nr
>>> mesh = nr.ifs_tco.load_mesh("/path/to/grid.nc", "/path/to/areas.nc")
>>> mesh["lon"]

nereus.models.ifs_tco.load_mesh(grid_file, area_file, *, use_dask=None)

Load IFS TCO mesh from grid and area files.

Parameters:

• grid_file (str or Path) – Path to the grid NetCDF file containing A*.lon and A*.lat.

• area_file (str or Path) – Path to the area NetCDF file containing A*.srf.

• use_dask (bool, optional) – Whether to use dask arrays. Auto-detects if None.

Returns:

Standardized mesh dataset with: - lon, lat: Coordinates (npoints,) - area: Cell area in m^2 (npoints,) Plus original variables with their native names.

Return type:

xr.Dataset

IFS TCO Mesh Loading

nereus.models.ifs_tco.load_mesh(grid_file, area_file, *, use_dask=None)

Load IFS TCO mesh from grid and area files.

Parameters:

• grid_file (str or Path) – Path to the grid NetCDF file containing A*.lon and A*.lat.

• area_file (str or Path) – Path to the area NetCDF file containing A*.srf.

• use_dask (bool, optional) – Whether to use dask arrays. Auto-detects if None.

Returns:

Standardized mesh dataset with: - lon, lat: Coordinates (npoints,) - area: Cell area in m^2 (npoints,) Plus original variables with their native names.

Return type:

xr.Dataset

The IFS TCO mesh loader expects separate grid and area NetCDF files. It selects the A* prefix for lon/lat and A*.srf for area, then flattens the coordinates to a 1D mesh compatible with nereus utilities.

ICON-Ocean (Planned)

Note

ICON-Ocean support is planned for a future release.

ICON-Atmosphere (Planned)

Note

ICON-Atmosphere support is planned for a future release.

IFS (Planned)

Note

IFS/ECMWF support is planned for a future release.