nereus 0.4.0

Python module for working with geophysical data from atmospheric and ocean models

Nereus, fast visualization and diagnostics for unstructured climate model data

Nereus is a Python library for quick data exploration of unstructured atmospheric and ocean model output in Jupyter notebooks. Plot global maps, compute diagnostics, and visualize transects from models like FESOM, ICON, and others — all with minimal code.

✨ Features

• One-line plotting — Visualize unstructured mesh data on publication-quality maps
• Fast regridding — KD-tree based interpolation with automatic caching
• Multiple projections — Robinson, Mollweide, stereographic, orthographic, and more
• Ocean & sea ice diagnostics — Ice area/volume/extent, heat content, volume-weighted means
• Vertical transects — Cross-section plots along great circle paths
• Hovmöller diagrams — Time-depth and time-latitude visualizations
• Region masking — Built-in support for ocean basins, NINO regions, MOC basins

Installation

pip install nereus

Quick Start

import nereus as nr
import xarray as xr

# Load your unstructured model output
ds = xr.open_dataset("model_output.nc")
mesh = xr.open_dataset('model_grid.nc')

# Plot sea surface temperature in one line
fig, ax, interp = nr.plot(
    ds.temp.isel(time=0, nz1=0),
    mesh.lon, mesh.lat,
    projection="rob",
    cmap="RdBu_r",
    vmin=-2, vmax=30
)

# Reuse interpolator for another variable
fig, ax, _ = nr.plot(ds.salt.isel(time=0, nz1=0), ds.lon, ds.lat, interpolator=interp)

Regridding

# Regrid to a regular 0.5° grid
regridded, interp = nr.regrid(data, lon, lat, resolution=0.5)

# Reuse interpolator for efficiency
regridded_salt, _ = nr.regrid(salinity, lon, lat, interpolator=interp)

Working with FESOM

# Load mesh once, reuse for multiple operations
mesh = nr.fesom.load_mesh("/path/to/mesh/")

# Compute sea ice extent
extent = nr.ice_extent(ds.a_ice, mesh.area, threshold=0.15)

# Ocean heat content (total in Joules)
ohc = nr.heat_content(ds.temp, mesh.area, mesh.layer_thickness)

# Ocean heat content map (J/m² at each point)
ohc_map = nr.heat_content(ds.temp, mesh.area, mesh.layer_thickness, output="map")

# Volume-weighted mean temperature
mean_temp = nr.volume_mean(ds.temp, mesh.area, mesh.layer_thickness)

Vertical Transects

# Plot a transect from point A to point B
nr.transect(
    ds.temp,
    mesh.lon, mesh.lat, mesh.depth,
    start=(-30, -60),  # (lon, lat)
    end=(30, 60),
    cmap="thermal"
)

Supported Models

Model/mesh	Status
FESOM2	✅ Full support
IFS TCO	✅ Full support
HEALPix	✅ Full support
MITgcm	✅ Full support
NEMO	✅ Full support
ICON-O	📋 Planned
ICON-A	📋 Planned

Documentation

📖 Full documentation: nereus.readthedocs.io

• Installation Guide
• Quick Start Tutorial
• API Reference

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

# Clone and install in development mode
git clone https://github.com/koldunovn/nereus.git
cd nereus
pip install -e ".[dev]"

# Run tests
pytest tests/

License

MIT License — see LICENSE for details.

---

Named after the Greek god of the sea, the "Old Man of the Sea."