diff --git a/docs/wiki/concepts/Execution-Modes.md b/docs/wiki/concepts/Execution-Modes.md index 8a95f7d40..bf2fd2078 100644 --- a/docs/wiki/concepts/Execution-Modes.md +++ b/docs/wiki/concepts/Execution-Modes.md @@ -13,6 +13,7 @@ Since engines can run in both simulated and realtime mode, users should **always - [Table of Contents](#table-of-contents) - [Simulation Mode](#simulation-mode) - [Realtime Mode](#realtime-mode) + - [Replay Before Going Realtime](#replay-before-going-realtime) - [csp.PushMode](#csppushmode) - [Handling Duplicate Timestamps](#handling-duplicate-timestamps) - [Realtime Group Event Synchronization](#realtime-group-event-synchronization) @@ -38,6 +39,31 @@ All time based inputs such as `csp.timer` and alarms will switch to executing in As always, `csp.now()` should still be used in `csp.node` code, even when running in realtime mode. `csp.now()` will be the time assigned to the current engine cycle. +### Replay Before Going Realtime + +To include a historical replay before the handoff described above, set `starttime` +to a time in the past while using `realtime=True`: + +```python +from datetime import datetime, timedelta, timezone + +now = datetime.now(timezone.utc) + +csp.run( + my_graph, + starttime=now - timedelta(hours=1), + endtime=now + timedelta(minutes=5), + realtime=True, +) +``` + +Here, `my_graph` replays one hour of history and then runs live for approximately +five minutes. Use an absolute future `endtime` when the run must remain active +after the handoff; if it has already passed when replay finishes, no live interval +remains. + +The graph's historical input adapters must provide data for the replay interval. Realtime adapters begin supplying external events after the engine reaches realtime. Nodes do not need separate replay and live implementations: use `csp.now()` for engine time and `csp.in_realtime()` when behavior must explicitly depend on the current phase. + ## csp.PushMode When consuming data from input adapters there are three choices on how one can consume the data: