Counterfactual API
Reference for World, agree, compare, their result types, and the checkpoint and replay machinery. Signatures are the package's own, and usage is on Counterfactuals.
World
A market, an agent trading it, and the macro path they run under, imported from the top level as tradefloor.World.
World(
*,
seed: int,
universe: Sequence[Instrument],
agent: Any,
pins: dict[str, Any] | None = None,
macro: Macro | None = None,
cash: float = 1_000_000.0,
max_leverage: float | None = 2.0,
steps_per_day: int = 6,
ticks_per_step: int = 65,
start: tuple[int, int, int] = (9, 30, 3),
model: str | ModelParams | None = None,
label: str = "",
)
run(days=1)Advance the world. Each day runs steps_per_day decision steps of ticks_per_step ticks. Returns self.
fork(*labels)One World per label, each identical to this one at the fork: engine, agent, portfolio, generator position. The fork step is recorded on each arm.
apply(scenario)Drive this arm from a Scenario document, rebased onto this world's own day numbering. Returns self.
intervene(**fields)Change macro fields in this arm on the current day. Recorded beside the day-zero pins, so scenario stays reconstructible.
checkpoint(label="")A serialisable Checkpoint of the run so far.
manifest(*, strategy=None, label="")A RunManifest for the run, so the counterfactual is citable and replayable.
replay()Re-execute the order log into a fresh Engine and return it.
summary(*, since=None) / net_worthResult summary, optionally from a step onward, and the portfolio's current worth.
day / step / digestThe next day to run, the next decision step counting the whole run, and a digest of the run state.
scenario / firings / order_logThe reconstructed Scenario for this world, the interventions that fired, and every input that reached the engine.
agree and compare
tf.agree(a: World, b: World) -> Agreement
tf.compare(
control: World,
treatment: World,
*,
agreement: Agreement | None = None,
) -> Comparison
agreeVerifies two arms are identical: engine state, books, portfolio, agent state, generator position. Take it at the fork, before the arms run on.
comparePuts two forked worlds side by side and finds the first step at which the macro, the decision, the orders, the prices and the portfolios came apart. Arms with different steps_per_day are refused. Pass agreement= so the published document states the arms started identical.
Agreementidentical: bool, differences: list[str], as_dict(), render(width=22).
ComparisonPer-series Divergences and both arms' summaries. as_dict(), render(width=24).
DivergenceWhere one series came apart: the step, the day and the values on each side. as_dict(), render().
Checkpointing and replay
Checkpoint.of(engine, *, universe: Sequence[Instrument],
seed: int, macro: Macro | None = None,
label: str = "") -> Checkpoint
tf.branch(engine, count: int = 2, *,
universe: Sequence[Instrument] | None = None,
seed: int | None = None,
macro: Macro | None = None) -> list[Engine]
tf.replay(log, *, seed: int,
universe: Sequence[Instrument],
macro: Macro | None = None,
model: str | ModelParams | None = None,
until: int | None = None) -> Engine
Checkpoint.ofCaptures an engine's history. universe and seed are required because an engine is built from them and keeps neither.
Checkpoint.resume / branch(count=2)Re-execute into one engine, or into count independent engines at the saved point.
Checkpoint.to_json / from_jsonThe serialised form. It outlives the process.
Checkpoint.fingerprintsha256 over the canonical serialisation. RunManifest.of(..., derived_from=checkpoint) records it as lineage.
tf.branchCopies a running engine in constant time via Engine.fork: every column, the generator position, the day's endogenous news, the tape and the order log.
tf.replayRe-executes a recorded order log. seed and universe are not in the log and must be supplied.
See also
Counterfactuals shows the usage, checkpoints and forking covers the engine-level mechanics, and citing a run says what a manifest carries.