Metadata-Version: 2.4
Name: vercor
Version: 0.4.4
Summary: Versatile Earth-system coupler for atmosphere, ocean, sea-ice, and land components
Author: Roman Nuterman
Maintainer-email: Roman Nuterman <nuterman@nbi.ku.dk>
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX
Classifier: Operating System :: Unix
Classifier: Operating System :: MacOS
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Oceanography
Classifier: Topic :: Scientific/Engineering :: Physics
License-File: LICENSE
Requires-Dist: numpy>=2.2.6
Requires-Dist: scipy>=1.9.3
Requires-Dist: h5py>=3.11.0
Requires-Dist: h5netcdf>=1.4.1
Requires-Dist: xarray>=2025.1.2
Requires-Dist: matplotlib>=3.8.1
Requires-Dist: jax
Requires-Dist: jax-datetime
Requires-Dist: tree-math
Requires-Dist: click>=8.1
Requires-Dist: black ; extra == "dev"
Requires-Dist: build ; extra == "dev"
Requires-Dist: flake8 ; extra == "dev"
Requires-Dist: mypy ; extra == "dev"
Requires-Dist: PyYAML ; extra == "dev"
Requires-Dist: pytest>=7.4.0 ; extra == "dev"
Requires-Dist: pytest-cov ; extra == "dev"
Requires-Dist: pytest-xdist>=3.7 ; extra == "dev"
Requires-Dist: types-PyYAML ; extra == "dev"
Requires-Dist: dinosaur==1.3.5 ; extra == "jcm"
Requires-Dist: jcm==1.1.1 ; extra == "jcm"
Requires-Dist: PyYAML ; extra == "test"
Requires-Dist: pytest>=7.4.0 ; extra == "test"
Requires-Dist: pytest-cov ; extra == "test"
Requires-Dist: pytest-xdist>=3.7 ; extra == "test"
Requires-Dist: veros>=1.6.2,<1.7 ; extra == "veros"
Provides-Extra: dev
Provides-Extra: jcm
Provides-Extra: test
Provides-Extra: veros

# VerCOR

<p align="center">
  <a href="http://vercor.readthedocs.io/?badge=latest">
    <img src="https://readthedocs.org/projects/vercor/badge/?version=latest" alt="Documentation status">
  </a>
  <a href="https://github.com/nutrik/vercor/actions/workflows/python-package.yml">
    <img src="https://github.com/nutrik/vercor/actions/workflows/python-package.yml/badge.svg" alt="Test status">
  </a>
  <a href="https://codecov.io/github/nutrik/vercor" > 
    <img src="https://codecov.io/github/nutrik/vercor/graph/badge.svg"/> 
  </a>
</p>

Versatile Earth system COupleR (VerCOR) connects atmosphere, ocean, sea-ice,
land, and forcing-data components on a shared clock. It helps Earth-system
researchers compose models, exchange fields between grids, and collect
diagnostics and output.

VerCOR is built on [JAX](https://github.com/jax-ml/jax). Output-free JAX
workflows remain differentiable end to end, supporting sensitivity analysis,
automatic differentiation, and gradient-based experiments.

> **Stable release:** Version `0.4.4` is the current release. VerCOR 0.3
> applications should follow the
> [Migration guide](https://vercor.readthedocs.io/en/latest/migration-0.3-to-0.4.html).

## Key capabilities

- Combine JAX-native and host-side models in one coupled simulation.
- Exchange scalar and vector fields between rectilinear grids.
- Use bilinear or conservative regridding.
- Run Gregorian, no-leap, or 360-day calendars.
- Use bundled slab atmosphere, ocean, land, and sea-ice components.
- Connect optional JCM, Veros, and CAMulator models.
- Supply static or time-dependent forcing data.
- Preserve immutable state across JAX transformations.
- Enable period averages, final fields, and snapshots when requested.

## Requirements and installation

VerCOR supports Python 3.12 and 3.13 and requires a JAX installation supported
by your platform.

Install the core package:

```bash
python -m pip install "vercor==0.4.4"
```

Install an optional extra before using a bundled JCM or Veros setup:

```bash
python -m pip install "vercor[jcm]"
python -m pip install "vercor[veros]"
```

CAMulator additionally requires NCAR's
[MILES-CREDIT](https://github.com/NCAR/miles-credit). A compatible CREDIT
release has not yet been confirmed or pinned.

Version `0.4.4` is the current release. Upgrade an older installation for the
published stable API:

```bash
python -m pip install --upgrade "vercor==0.4.4"
```

## Quick start

This dependency-light example runs a slab ocean for two one-hour steps:

```python
from datetime import datetime

import jax.numpy as jnp

from vercor import Clock, Coupler, RectilinearGrid
from vercor.setups import make_slab_ocean


grid = RectilinearGrid.uniform(
    "quickstart",
    nlon=2,
    nlat=2,
    longitude=(0.0, 360.0),
    latitude=(-90.0, 90.0),
)
clock = Clock(datetime(2000, 1, 1), dt_seconds=3600.0, steps=2)
ocean = make_slab_ocean(grid)
coupler = Coupler(clock, components=(ocean,), run_order=(ocean.name,))

final_state = coupler.run()
sea_surface_temperature = final_state.component(ocean.name).field(
    "sea_surface_temperature"
)

assert sea_surface_temperature.shape == grid.shape
assert bool(jnp.all(jnp.isfinite(sea_surface_temperature)))
```

## Setup gallery

VerCOR packages runnable setup scripts with its distribution.
List the available templates, copy one into a user-editable directory, then run
that local copy:

```console
vercor show-setups
vercor copy-setup run_jcm_with_veros \
  --to ~/vercor-setups/run_jcm_with_veros
vercor run \
  --loglevel info \
  --float-type float64 \
  ~/vercor-setups/run_jcm_with_veros/run_jcm_with_veros.py
```

`vercor --version` reports the installed distribution version. `VERCOR_SETUP_DIR`
may add external templates as an `os.pathsep`-separated list of direct
directories. Every template name must be unique across the packaged gallery and
those directories; duplicates are errors. `copy-setup --to` creates missing
parent directories or reuses an existing directory, but never overwrites an
existing setup file.

An external template must define exactly
`run_setup(*, loglevel, float_type)`. `vercor run` passes lowercase-only
`loglevel` choices (`trace`, `debug`, `info`, `warning`, or `error`) and
`float_type` choices (`float64` or `float32`); their defaults are `info` and
`float64`. The function returns `None` for success or an integer process status.

## Documentation

Read the canonical documentation at
[https://vercor.readthedocs.io/](https://vercor.readthedocs.io/):

- [Researcher guide](https://vercor.readthedocs.io/en/latest/researchers/)
- [Developer guide](https://vercor.readthedocs.io/en/latest/developers/)
- [Python API](https://vercor.readthedocs.io/en/latest/api/)
- [Migration guide](https://vercor.readthedocs.io/en/latest/migration-0.3-to-0.4.html)
- [Plugin authoring](https://vercor.readthedocs.io/en/latest/plugin-authoring.html)

Repository resources:

- [Changelog](CHANGELOG.md)
- [License](LICENSE)

