Open interfaces · Shared meaning · Differentiable coupling

A common language for connected water models

HydroCouple defines how independently developed models describe themselves, exchange data and coordinate execution. Its optional differentiation interfaces also let sensitivities travel through a coupled system—supporting uncertainty assessment, data assimilation, learning and control.

Follow the derivativesAPI reference

Current interface pre-release: 2.0.0-alpha.2 · C++20 · Python bindings · MIT

The standard in one picture

Models keep their physics. Connections share a meaning.

An output from one model becomes an input to another. The connection identifies the quantity, units, geometry and time; an adapted output performs declared transformations where needed. A workflow coordinates the models’ lifecycle and execution. HydroCouple builds on concepts from the OGC OpenMI 2.0 standard and extends them with spatial data, efficient array exchange and optional capabilities.

Model coupling with declared data semanticsA runoff output passes through an adapted output into a receiving-water input. Quantity, units, geometry and time describe the exchange. The models retain their own equations and state.A connection carries more than a numberRunoff componentOwn equations · own stateOUTPUT · dischargeReceiving-water modelOwn equations · own stateINPUT · boundary inflowAdapted outputMap space · align time · convert unitsQuantityunitsGeometrytimeDeclare the exchange. Validate compatibility. Execute a coordinated workflow.
A runoff–receiving-water connection is illustrative. Components declare inputs and outputs; adapters reconcile compatible representations. Adapters must preserve the intended physical meaning. Open figure →

Describe

Expose identity, configuration, inputs, outputs, state and supported capabilities.

Exchange

Move values with their units, dimensions, spatial references and temporal semantics.

Coordinate

Initialize, validate, prepare, update and finish through a common lifecycle.

The interface standard defines the contract. The SDK provides implementations and workflows; models provide their own numerical methods.

The differentiation extension

Carry sensitivities through the whole cascade

A Jacobian collects derivatives of a vector of outputs with respect to a vector of inputs. A gradient describes how one scalar objective changes with its variables. HydroCouple exposes Jacobian products, so components can propagate sensitivities without assembling or storing a full Jacobian.

Jacobian
Local linear response of all selected outputs to the selected inputs, parameters and prior state.J = ∂y / ∂x
JVP · forward mode
A Jacobian–vector product sends an input tangent perturbation forward to an output tangent.δy = J δx
VJP · reverse mode
A vector–Jacobian product sends an objective cotangent backward. In column-vector notation:∇xL = Jᵀ ∇yL
Forward and reverse derivatives across coupled modelsModel A, adapter M and model B form a cascade with composite Jacobian J_B times J_M times J_A. Tangent perturbations travel forward. Cotangents of an objective travel backward through transposed Jacobians. The adapter derivative is part of the chain.The chain rule crosses the connectionModel Aa = f(x)local derivative J_AAdapter Mb = m(a)local derivative J_MModel By = g(b)local derivative J_BFORWARD · values and tangent perturbationsa, δab, δbREVERSE · objective cotangentsJ_Bᵀ λJ_Mᵀ J_Bᵀ λComposite Jacobian: J = J_B J_M J_A · Each link contributes its own derivative.
The adapter belongs to the derivative chain. A unit conversion, spatial mapping or stateful transformation must contribute its own derivative, alongside those of the connected models. Open figure →

The standard specifies the derivative contract, not the differentiation method. Automatic differentiation (AD) applies the chain rule to implemented numerical operations to obtain derivatives. A component can use AD or supply analytical derivatives or a hand-written adjoint through the same JVP/VJP interfaces. Every component and adapter on the requested path must supply valid derivatives. Read the contracts →

Interactive illustration · dimensionless linear example

See uncertainty and sensitivities change together

A toy cascade has two inputs and two outputs. Change an adapter’s mapping gain, input standard deviation or correlation. The composite Jacobian maps input covariance to output covariance.

Enable JavaScript to explore the example. Its calculations use J = BMA and Σy = JΣxJᵀ; all quantities are dimensionless.

Equations and assumptions

A = [[1, 0.2], [0.1, 0.8]], M = diag(gain, 1), B = [[1.2, 0.4], [0.3, 0.9]]. J = BMA. The input covariance has variances σ₁² and σ₂² and covariance ρσ₁σ₂. This is an exact linear example, not a calibrated water model. For nonlinear models, Σy ≈ JΣxJᵀ is a local first-order approximation.

Beyond a single exchange

Follow state through time

A time step maps previous state, inputs and parameters to new state and outputs. Both components and adapters can carry memory. Their differentiation interfaces distinguish state before from state after; checkpointing lets a workflow restore and replay earlier steps at the correct linearization point.

Checkpointing and derivative propagation through timeA sequence of three steps carries both component and adapter state. A checkpoint is saved before each step. Reverse differentiation restores and replays the relevant earlier step before evaluating its vector-Jacobian product and propagating the state cotangent to the preceding step.Memory is part of the derivativeStep 1(state 0, input) → state 1component + adapter stateCheckpoint before step 1Step 2(state 1, input) → state 2component + adapter stateCheckpoint before step 2Step 3(state 2, input) → state 3component + adapter stateCheckpoint before step 3Restore → replay the earlier step → evaluate its VJP → carry the state cotangent backward
A relaxation adapter is one example of a connection with memory. Its state must be restored together with the models’ state when differentiating an earlier step. Open figure →

The current SDK reverse workflow supports time-stepped acyclic compositions, including differentiable, checkpointable relaxation adapters. It rejects unsupported paths rather than inventing a derivative. Feedback-loop differentiation and general multi-rate differentiation require further workflow support. Workflow scope →

What the extension enables

From system response to system decisions

Uncertainty assessment

Trace sensitivity to forcing, parameters and initial conditions across models. Propagate correlated input covariance with a local linear approximation, then use ensembles for nonlinear behavior. Sensitivity alone is not an uncertainty estimate.

JCGM uncertainty guidance, §5

Physics-informed machine learning

Train a learned relation inside a physical model, or use model sensitivities in an inverse problem. Physics-informed neural networks (PINNs) additionally use space/time derivatives to construct governing-equation residuals—a different derivative from a coupled model’s parameter sensitivity.

Raissi, Perdikaris & Karniadakis

Calibration and control

Differentiate a scalar objective with respect to parameters or control actions. This can support gradient-based calibration and model predictive control (MPC). Constraints, observation quality and nonsmooth events such as valve switching still belong in the application.

Differentiable hybrid physics and machine learningA learned relation supplies a physical model whose outputs feed an objective using observations and constraints. Reverse sensitivities reach trainable parameters or control actions. This is a conceptual hybrid physics–machine-learning workflow, rather than a claim that a solver implements a physics-informed neural network.A physics–learning composition with a shared objectiveLearned relationparameters θPhysical modelstate + governing equationsObjectiveobservations + constraintsL(θ, u)u: control actionsReverse sensitivities connect the objective to parameters and control actions.Conceptual workflow · derivatives, physical constraints and optimizer are supplied by the application.
Hybrid physics–machine-learning models can connect a learned relation, a physical solver and an objective. PINNs are a specific approach within physics-informed machine learning; differentiable coupling is a broader capability. Open figure →
Example · a drainage-system digital twin

Connect observations to forecasts—and decisions

A water-system digital twin can connect a physical catchment, storage network and receiving water to a model that is continually updated from observations. Data assimilation combines these observations with a prior forecast (the background), accounting for their uncertainties, to estimate an updated state (the analysis) for the next forecast. NIST: digital twin elements · ECMWF: assimilation terminology

Variational data assimilation for a water-system digital twinRainfall drives a coupled model trajectory. An observation operator maps model states to measured water levels and flows at sensor locations and times. The objective combines a background-state prior and observation misfit, weighted by their error covariances. Reverse derivative products pass through the observation operator, adapters, models and previous time steps to an optimizer that updates initial state and optionally parameters. Reintegrating produces the analysis state for a new forecast and control-scenario evaluation. The cycle repeats as observations arrive. This is a conceptual application, not an implemented operational assimilation service.Data assimilation keeps a digital twin connected to the water systemPhysical systemCatchment · storage · receiving waterRainfall forcing + level / flow observationsTimestamped measurements with observation-error estimatesrainfallobservationsCoupled trajectoryObservation operatorAssimilation objectivex₀ → x₁ → … → xₜrunoff → storage → rivermodels + adapters + memoryŷₜ = Hₜ(xₜ)level / flow at sensor locationsmatch quantity, place and timeL = prior + misfitbackground and observationsweighted by error covariances∇ŷ LVJP of HₜVJPs continue through adapters and earlier time stepsAssimilate → produce the analysisOptimize initial state x₀ (and optional parameters θ)Reintegrate to obtain the updated current stateForecast → support decisionsFlood risk · storage availability · outflowEvaluate gate / pump control scenariosanalysisRepeat with each observation window · conceptual variational assimilation workflow
Illustrative application: assimilate water levels and flows across a runoff–storage–river cascade, then forecast flood risk and evaluate control scenarios. The observation operator contributes its derivative alongside the physical models and adapters. Open figure →

Observe in model space

An observation operator maps model state to the quantity, location and time of a measurement. Level and flow observations can inform unobserved storage and upstream states through their modeled connections.

Differentiate the mismatch

Four-dimensional variational data assimilation (4D-Var) adjusts initial conditions over an observation window. AD can supply the objective gradient through the model trajectory and observation operators; HydroCouple’s VJPs carry it across component boundaries.

Update, forecast, control

Reintegrate from the optimized initial state to obtain the current analysis. Start the next forecast from that state and evaluate control actions against downstream risk and available storage. Repeat as new observations arrive.

Variational assimilation minimizes a background penalty plus observation misfit, weighted by their error covariances. ECMWF: gradients and adjoints in 4D-Var

This illustrates an application the interfaces can support when all participating paths provide derivatives and replay. Assimilation, sensor quality checks, error covariances and the optimizer are application responsibilities. Ensemble Kalman filters offer another assimilation approach and do not require explicit model derivatives.

The rest of the contract

Shared data, flexible execution

Spatial and temporal meaning

Geometries, meshes, networks, rasters and layered domains describe where values apply. Time-series and time-marching interfaces describe when they apply.

Efficient array exchange

Typed buffers declare shape, strides and memory space for efficient C++, Python and accelerator exchange. Quantities declare units and how values behave when mapped or aggregated.

Parallel and distributed workflows

Cloning supports independent ensemble members. Distributed interfaces describe transports, remote components and partitioned data. Implementations choose the runtime and execution backend.

Geometry follows OGC Simple Feature Access concepts. SDK and engine I/O can use OGC GeoPackage, NetCDF or HDF5; these file formats are distinct from the runtime coupling interface.

Explore the main interface contracts
ConcernInterfaceResponsibility
Model executionIModelComponentLifecycle, inputs, outputs, arguments, state, capabilities and diagnostics.
Data and adaptationIComponentDataItem, IInput, IOutput, IAdaptedOutputTyped data, connections and declared transformations.
DifferentiationIDifferentiableModelComponent, IDifferentiableAdaptedOutputJVPs and VJPs of the most recent update or refresh.
ReplayICheckpointableModelComponent, ICheckpointableAdaptedOutputSave, restore and release state for earlier-step replay.
CompositionIWorkflowComponent, ICloneableModelComponentCoordinate components and create independent component instances.
Distributed dataITransport, IPartitionedComponentDataItemTransport-neutral messaging and partitioned fields.
Primary sources

Read the standard. Explore its implementations.

HydroCouple API referenceThe model, data, spatial, temporal and workflow contracts.HydroCouple interface sourceC++20 declarations, Python bindings and 2.0 release notes.HydroCouple SDKConcrete components, adapters and differentiation workflows.OGC OpenMI 2.0The runtime model-exchange concepts underlying the lineage.

AI tools assisted with the writing and illustrative figure code. Terminology and capability descriptions were checked against the HydroCouple 2.0.0-alpha.2 contracts. The interactive example is dimensionless and synthetic; it reports no operational model results.