Metadata-Version: 2.4
Name: dcoupler
Version: 0.2.0
Summary: Differentiable Earth System Coupler
Author-email: Darri Eythorsson <darri.eythorsson@ucalgary.ca>
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/DarriEy/dcoupler
Project-URL: Homepage, https://github.com/DarriEy/dcoupler
Project-URL: Issues, https://github.com/DarriEy/dcoupler/issues
Keywords: hydrology,differentiable,coupling,earth-system,pytorch
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: xarray
Provides-Extra: jax
Requires-Dist: jax>=0.4; extra == "jax"
Requires-Dist: jaxlib; extra == "jax"
Provides-Extra: models
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Provides-Extra: all
Requires-Dist: dcoupler[dev,jax]; extra == "all"
Dynamic: license-file

# dCoupler

Differentiable Earth System Coupler — a PyTorch-based framework for building
differentiable coupling graphs between hydrological and earth system model
components.

## Quickstart

```bash
pip install dcoupler
```

```python
import torch
import dcoupler as dc

# Define two components
class Bucket(dc.DifferentiableComponent):
    ...

class Router(dc.DifferentiableComponent):
    ...

# Build coupling graph
graph = dc.CouplingGraph()
graph.add_component(bucket)
graph.add_component(router)
graph.connect("bucket", "runoff", "router", "lateral_inflow")

# Run forward
outputs = graph.forward(external_inputs, n_timesteps=365, dt=86400)

# Optimize via backprop
loss = loss_fn(outputs, observations)
loss.backward()
optimizer.step()
```

## Component Types

| Type | Gradient | Use Case |
|------|----------|----------|
| `DifferentiableComponent` | PyTorch autograd | Pure PyTorch models |
| `JAXComponent` | JAX vjp via bridge | JAX models (XAJ, SAC-SMA, Snow-17) |
| `ProcessComponent` | None / finite diff | External executables (SUMMA, MESH) |
| `EnzymeComponent` | Enzyme AD | C++ models with Enzyme |

All component types implement the `BMIMixin` protocol for standardized
lifecycle management (initialize/update/finalize).

## Optional Dependencies

```bash
pip install dcoupler[jax]     # JAX bridge support
pip install dcoupler[models]  # cfuse + droute components
pip install dcoupler[all]     # Everything
```

## License

Apache 2.0 — see [LICENSE](LICENSE) for details.
