Reproducibility
Run a market twice with the same inputs on the same release and you get the same market, bit for bit, on Linux, macOS or Windows.
Checklist
Keep these seven inputs the same on a supported platform and a run repeats bit for bit, within the limits below.
| Input | Pin it with | Rules |
|---|---|---|
| Seed | seed= on tf.Engine and tf.evaluate, seeds= on tf.rank | The inputs |
| Universe, in order | the same roster in the same order, which universe.fingerprint covers | The inputs |
| Economy on day zero | macro_state= on tf.Engine, macro= on tf.evaluate, or leave it out every time | The inputs |
| Preset | model="pt-v22" by name, never the default | Preset names and preset values |
| Scenario | the same scenario file, whose fingerprint is recorded | The inputs, Run a scenario |
| Agent actions | a deterministic agent, or a recorded transcript for an LLM agent | Markets with and without an agent, Record and replay |
| Release | pip install "tradefloor==0.11.0" | Across releases, Support policy |
A RunManifest stores all seven for one run and rebuilds the market from them (Saving a run). The supported platforms are the five wheel targets: Linux x86_64 and aarch64, macOS arm64 and x86_64, and Windows x86_64. Named presets replay unchanged in later releases. Within the 0.8 long-term support line a patch release may not change any known-answer digest (Changes allowed in a patch release). The default preset changes between minor releases. A traded run recorded before 0.8.5 matches up to its first trade, then differs. Your agent's own code isn't covered by any of this.
The inputs
Change any one of these and you get a different market.
- The universe, the companies in order. The engine draws random numbers in roster order, so the same companies in another order give a different market.
universe.fingerprintis a sha256 of the roster and covers the order too. - The economy on day zero,
macro_stateontf.Engine. If you leave it out, the engine picks its own opening. That gives a different market from passingtf.Macro(), even with the same values. - The seed,
seedontf.Engine, any integer from 0 to2**64 - 1.Universe.randomhas a separate seed, which only picks the companies. - The preset,
modelontf.Engineortf.evaluate. If you leave it out you get the installed version's default, pt-v22 in 0.11.0. - The package version. It decides the default preset and which code runs.
- Any scenario applied to the market, day by day.
- For a traded run, the agent's orders in the order it sent them, and for an LLM agent the model's answers.
The snippets on this page run in order in one Python session. This one changes one input at a time on a 20-day market and compares a digest of the whole engine state:
import tradefloor as tf
universe = tf.Universe.random(5, seed=11)
def final_state(roster=universe, seed=42, macro=None, model=None):
"""Run 20 days and return a digest of the whole engine state."""
engine = tf.Engine(seed=seed, universe=roster, macro_state=macro, model=model)
engine.run_days(20)
return engine.state_hash()
reference = final_state()
print("same inputs again: ", final_state() == reference)
print("roster reversed: ", final_state(roster=tf.Universe(reversed(universe))) == reference)
print("VIX 30 on day zero: ", final_state(macro=tf.Macro(vix=30.0)) == reference)
print("seed 43: ", final_state(seed=43) == reference)
print("preset pt-v19: ", final_state(model="pt-v19") == reference)same inputs again: True roster reversed: False VIX 30 on day zero: False seed 43: False preset pt-v19: False
Markets with and without an agent
A market with no agent orders in it depends only on the inputs above, and the same inputs give the same market bit for bit on Linux, macOS and Windows. tradefloor has its own exp, log, pow, sin and cos, so the platform's math library can't change a result. Every release runs fixed simulations on all five wheel targets and stops if any digest differs.
A run with an agent has one more input, the agent's decisions. Its orders fill against the order book and move prices, and the agent sees those prices at its next decision. Two agents on the same seed are trading different markets after their first trade.
- A Python agent that decides the same way from the same observations repeats its run on the same release. An unseeded random number or a value read from the clock changes its orders, and with them the market. tradefloor doesn't check the agent's arithmetic either. Python 3.12 changed how
sum()adds floats, and an agent that sums prices withsum()can send different orders on 3.11 and 3.12. - An LLM agent can answer differently each time you ask it. The LLM adapters record each call and its answer in a transcript, and a replay feeds those answers back without calling the model. A replay looks up each answer by a digest of the exact observation the model saw. If anything upstream has changed, it stops with
ReplayMiss. Replay mismatches lists the messages.
engine.order_log holds every input the engine consumed, orders included. tf.replay(log, seed=..., universe=...) rebuilds the market from that log without the agent's code.
Across releases
A preset's coefficients are fixed when it first ships in a tagged release. A better coefficient goes into a new preset with a new name. An untraded market on a named preset replays exactly in any later release, and you can still select any shipped preset from pt-v1 on with model="pt-v12" or similar. From 0.8.5 on, each release checks one known-answer digest per shipped preset on all five targets.
The default preset changes between releases. pt-v22 is the default from 0.11.0, after pt-v21 from 0.10.0 and pt-v20 from 0.8.5. A run that left model out gives a different market on a release with another default, so name the preset in anything you publish.
For traded runs, in 0.8.5 and later an agent's fills reach the market once, on the next tick. In 0.8.1 they went in as order flow on every tick of the next step. The change applies to all presets, so a traded run recorded before 0.8.5 matches up to its first trade and differs after it. Each release also checks one traded run on all five targets. It runs the reference agents through tf.evaluate on the default preset, pt-v22, and checks their orders, fills and scorecards. Runs with your agents go through that code too. Within the 0.8 long-term support line a patch release has to leave all of these digests unchanged (Support policy).
Preset names and preset values
A preset name stands for fixed values only in a tagged release. A development build or an edited source tree can have other values under that name. A RunManifest and a transcript both store the values and refuse a mismatch. If you change a coefficient through the API, as in tf.ModelParams.from_preset("pt-v20", momentum_theta=0.05), the fingerprint is custom- and eight hex digits, never the preset name. To pin a model, install a tagged release from PyPI or crates.io and name the preset.
Saving a run
A RunManifest holds what someone else needs to rebuild a market: the version, the preset and its coefficients, the seed, the universe, the economy on day zero, any scenario and the order log, plus a digest of the market the run ended on.
engine = tf.Engine(seed=42, universe=universe) engine.run_days(20) text = tf.RunManifest.of(engine, seed=42, universe=universe).to_json() rebuilt = tf.RunManifest.from_json(text).reproduce() # replays, then checks print(rebuilt.state_hash() == engine.state_hash())
True
reproduce() checks each component against its fingerprint before it replays, and raises an error naming the part that disagrees. Before that it runs a small fixed probe simulation on the default preset. A manifest written on a release with a different default, such as 0.8.1 read on 0.8.5 or later, fails the probe and is refused. Rebuild a run like that from its named preset, seed and universe.
A manifest checks the market and holds no score. tf.evaluate and tf.rank don't write one. If you want readers to check a score, publish the agent's code, the call that scored it and the seeds. Citing tradefloor lists what to report with a result.