Skip to content

docs: explain replay-to-realtime transition #740

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
russlan23 wants to merge 2 commits into
base: main
Choose a base branch
from
+26 −0
Open

docs: explain replay-to-realtime transition #740

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9b06952
docs: explain replay-to-realtime transition
russlan23 Aug 5, 2026
3a72fef
docs: avoid repeating realtime handoff details
russlan23 Aug 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions docs/wiki/concepts/Execution-Modes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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:
Expand Down