E2S-07: Data assimilation model contract¶
Purpose¶
Define independent and stateful data assimilation interfaces.
Contract¶
AssimilationModel:__call__,input_coords,output_coords,default_sources,to,stochastic,set_rng(seed, reset=True).StatefulAssimilationModelextends it:forcing_coords,initialize(*inputs, *forcing) -> (y, state),step(*outputs, *forcing, state) -> (y, state),create_iterator(*inputs, *forcing).- Concrete signatures use named slots: backgrounds before forcing; step state last, positional-or-keyword.
- Slots: DataArray/CoordinateSystem or DataFrame/FrameSchema; optional observations accept
None; multiple slots preserve tuple order. - Initialization computes the first analysis; iteration yields it first, then receives dynamic forcing via
send. Required forcing is never reused implicitly. - Outputs plus serializable state fully determine continuation. Steps replay exactly without mutating inputs/state; execution hooks are iterator-only.
- RNG: calls/new trajectories advance a local stream; reset restarts it,
reset=Falseinitializes only if absent. Seeded execution preserves global RNG; reseeding leaves live trajectories unaffected. Deterministic models use a no-op. - Independent models declare all arguments in
input_coords; stateful models additionally declare forcing. Sources follow slot order; callers fetch and align data. Models document observation times/windows. - Stateful gridded outputs carry
lead_time; the step cadence is the output's last lead time minus the later of the first input slot's last lead time and zero (see the model contract's Lead Time section). Drivers request DataFrame forcing at the analysis valid time, the end of the output being produced, and passNonewhen the source returns no rows. - Independent: HealDA, interpolation (deterministic), CorrDiff (stochastic). Stateful: StormCast and StormCast-CONUS (stochastic).
- Migration: remove
create_generator; use independent calls or forecast-firstcreate_iterator. Replace CorrDiff.seedwithset_rng.