Engine and data

Type aliases

Literal types the signatures below refer to.

Engine

A running market. You build it from a seed (the number that fixes every random draw), a roster and the economy on day zero, then advance it a day or a tick at a time.

Engine(
    *,
    seed: int,
    universe: Sequence[Instrument],
    macro_state: Macro | None = None,
    model: str | ModelParams | None = None,
) -> None

An Engine is mutable. Every run and tick method advances it in place and returns None unless the table says otherwise. fork() returns independent copies of the current engine state. Checkpoint is the serialized form, which you can save and load in a later process. From 0.8.0, state_snapshot carries thirteen more fields, including the crisis episode, the sector variance and the slow variance levels, and state_hash covers them. So the same prices hash differently under 0.7.x and 0.8.0. A snapshot taken under 0.7.x cannot be restored, because the engine now draws from ten random streams where 0.7.x drew from eight. From 0.8.5, state_snapshot and state_hash also cover the rate indices on an engine that holds them, and the agent-facing book once an agent has sent it an order. An engine with neither hashes as it did under 0.8.1.

Instrument

One tradable company. Every monetary field is in currency units per share unless it says otherwise.

Instrument(
    ticker: str,
    sector: str,
    *,
    initial_price: float,
    shares_outstanding: float,
    eps: float | None = None,
    book_value_per_share: float | None = None,
    revenue_growth: float | None = None,
    avg_volume: float = 1000000.0,
    beta: float = 1.0,
    short_interest: float = 0.0,
) -> None

A simulated rate index is an Instrument too, with sector "rates", and tf.bonds() builds all three. Instrument() accepts that sector only for UST2Y, UST10Y and IGCORP, and refuses eps, book_value_per_share, revenue_growth or a non-zero short_interest on one.

Macro

The economy on day zero. Rates are always decimal fractions, so 0.052 is 5.2%. Passing 5.2 raises ValidationError, and the message names the fraction you probably meant.

Macro(
    *,
    vix: float = 15.0,
    federal_funds_rate: float = 0.025,
    corporate_bond_yield: float | None = None,
    inflation_rate: float = 0.02,
    qe_pe_boost: float = 0.0,
    qe_assets_ratio: float = 1.0,
    fear_greed_index: float = 50.0,
    cycle: CycleName = 'expansion',
) -> None

This is the state on day zero only, and every close advances it. To set a path for the whole run, use a Scenario, or hold fields still with Engine.pin_macro.

OrderBook

One company's order book. Orders match against resting orders on price-time priority (best price first, then earliest), so an order's price depends on how many levels it uses up.

OrderBook(
    company_id: str,
    last_price: float | None = None,
) -> None

A book from Engine.book() is a detached copy. Reading it or filling orders against it leaves the engine unchanged, byte for byte.

PriceLevel

One price level with its resting orders added together, as price_levels() returns it.

PriceLevel

SweepCost

What a sweep, one order that takes several price levels, would cost. sweep_cost() returns it without executing anything.

SweepCost

MatchResult

The outcome of submit().

MatchResult

Fill

One match between an incoming order and a resting one.

Fill

Universe

The roster, meaning the list of companies in a market, followed by any rate indices. It is a list subclass, so indexing and iteration work as usual.

Roster order is part of the universe's identity and is included in fingerprint. If you reorder the roster, the same seed gives a different market. Reproducibility explains how the fingerprint is built.

Rate indices

Three simulated rate indices can trade beside the equities from 0.8.5. UST2Y and UST10Y are constant-maturity 2-year and 10-year treasury indices, and IGCORP is an investment-grade corporate bond index. None is a real security. They are priced off the engine's own curve and take no random draws, so every equity price, draw and macro value is identical to the same run without them.

Each index reads one yield. UST2Y reads the 2-year treasury yield and UST10Y the 10-year. IGCORP reads the 10-year plus a credit spread, which is re-marked whenever the engine sets the corporate yield or a caller pins it. When that yield changes by dy, the level moves by carry - D * dy + 0.5 * C * dy**2, where carry is the yield over 252 at the first open after a close and zero otherwise. Duration D and convexity C are 1.9 and 4.6 for UST2Y, 8.5 and 84 for UST10Y, and 7.0 and 100 for IGCORP.

The economy moves yields only at the close, so a level holds still through a session unless pin_macro writes a yield. The level reprices at the next open, or on the first tick after the pin. Nothing interpolates toward a later yield, so no price shows a yield before the close that sets it. Engine.rate_attribution splits the day's move into carry, duration, convexity and the book's flow.

An index trades like an equity through Portfolio.execute, the fills= argument of run_session, the tape and tca.analyse, on a book of its own. That book is the maker's ladder around the index level, 0.6 basis points wide before cent rounding for the treasuries and 0.8 for IGCORP, and it widens with the VIX by the equity rule. Its depth comes from the median dollar volume of SHY, IEF and LQD over 2015 to 2025. The maker lays off a trade's inventory with a 15-minute half-life, so a trade's impact on an index fades.

Rate indices come after every equity. An engine refuses a roster that lists an equity after one, lists one twice, or holds rate indices and no equities. The agent-facing book holds equities only, so Engine.submit and Portfolio.submit_limit refuse a rate index. So do run_until, a News item that names one, explain, list_instrument, delist and EngineBatch. To move an index, write the yield it reads with pin_macro(treasury_yield_2y=..., treasury_yield_10y=...), or with a scenario on macro.treasury_2y or macro.treasury_10y.

import tradefloor as tf

u = tf.Universe.random(20, seed=101, bonds=True)
u.tickers()[-3:]    # ['UST2Y', 'UST10Y', 'IGCORP']

e = tf.Engine(seed=3, universe=u)
e.run_days(5)
e.curve["treasury_10y"]
e.rate_instruments[1]["level"]

On pt-v20, the default, the 2-year yield moves 3.87 basis points a day against 5.23 in the real market over 2015 to 2025, and the 10-year 4.96 against 5.41. The index's daily correlation with a Treasury bond's return is -0.14 against a real -0.16 (IEF), and with an investment-grade bond's +0.20 against +0.27 (LQD). These are long-run rows R1 to R4. Under pt-v19 the curve is much quieter, 0.46 and 3.1 basis points a day, and bonds and stocks are uncorrelated. The library's tools/bonds/realism.py makes that comparison. Scenarios documents curve_shock.yml, which moves the whole curve 200 basis points in one day, and Agents and evaluation documents baselines.Balanced, a 60/40 book with a bond sleeve.

The agent-facing book

Engine.submit sends an order to the engine's own book under an agent's label, and the engine keeps each fill until take_fills collects it. Every share an order takes reaches the market once, on the next tick the market is open, and take_impacts reports the permanent impact it left. Portfolio.submit_limit and a tf.Limit in a World agent's orders both go through it. The table under Engine lists the seven methods.

Seven ModelParams dials, listed on Model parameters, decide what the book holds. They are 0.0 on pt-v1 through pt-v19, where Engine.book_live is False: an order meets the maker's ladder exactly as Engine.book shows it, two agents trading one name in one step fill at the same prices because neither order removes a level, and a limit order's unfilled part waits outside the book, with mode range, and fills in full at its limit on the first tick whose print reaches it. pt-v20, the default, sets all seven, so Engine.book_live is True there and an order executes in the engine's own book. A waiting limit order then has mode queue.

book_depth_coefficient, book_depth_exponent and book_depth_reach put latent depth beside the maker's ladder, where a larger order pays more per share, by the square-root law unless the exponent sets another power. book_shared makes an order consume what it takes. The maker's ladder is whole again when the maker quotes at the next tick, and the latent depth refills with a half-life of book_refill_half_life ticks. book_resting queues a limit order's unfilled part in the book, behind the depth already at its price, where the market's own flow or another agent can fill it. The flow fills it only at a price inside the maker's quote for that tick, so an order resting past the quote waits until the price comes to it. An order that the maker's next quote crosses trades at the maker's price, and its fill is recorded as liquidity="taker". fill_impact_coefficient gives each agent's fills a linear permanent impact and attributes it to that agent.

None of the seven changes a market nobody trades, and an engine no agent has sent an order to hashes and snapshots as it did under 0.8.1. The book holds equities only, so a rate index trades through Portfolio.execute on a book of its own.

e.open_market()
r = e.submit("alice", u[0].ticker, 1_000)
r["filled"], r["average_price"]

w = e.submit("alice", u[0].ticker, 500,
             limit_price=0.98 * r["reference"])
e.open_orders("alice")    # mode "queue" on pt-v20
e.cancel(w["order_id"], agent="alice")
e.take_fills("alice")     # the market order's fill

Portfolio

Cash, positions and P&L for one trader. evaluate, TradingEnv, tca.analyse and World keep one per agent, and a loop of your own can use one the same way. execute fills an order at the prices the book gives and adds the trade to pending_flow, which the loop hands to the next session as run_session(fills=...).

Portfolio(
    cash: float = 1_000_000.0,
    *,
    max_leverage: float | None = None,
    cash_interest: bool = False,
    owner: str = "agent",
    margin_interest: bool = True,
)

When Engine.book_live is True, execute sends the order to Engine.submit under owner instead of pricing it off a copy of the book. The engine then applies the flow itself and pending_flow holds nothing for that trade, so a loop that passes fills=p.pending_flow() still counts it once. A rate index is always priced off its own book.

import tradefloor as tf

u = tf.Universe.random(20, seed=7)
e = tf.Engine(seed=42, universe=u)
p = tf.Portfolio(cash_interest=True)

e.open_market()
minute = 9 * 60 + 30
for step in range(6):             # six 65-tick steps make one day
    if step == 0:
        p.execute(e, u[0].ticker, 500)
    e.run_session(minute // 60, minute % 60, 3, 65,
                  fills=p.pending_flow())
    p.clear_flow()
    minute += 65
p.accrue(e)                       # a day's interest, before the close
e.close_market()
p.net_worth(e)

Exceptions

EngineBatch

Runs one market under many seeds in lockstep, in one process. Build it like Engine, with seeds in place of seed. The run and read methods match Engine's and return one result per seed. It runs equities only and refuses a roster that holds a rate index. Run one on Engine, or through run_many, one seed per engine.

seeds: list[int]
tickers: list[str]
draws_consumed: list[int]
shape: tuple[int, int]
model: ModelParams
model_fingerprint: str

EngineBatch(*, seeds, universe, ...)
__len__() -> int
open_market() -> None
tick(...) / run_session(...)
prices() -> bytes
column(field) -> bytes

News

One news item that you inject into the market.

News(
    *,
    ticker: str | None = None,
    sector: str | None = None,
    price_impact: float = 0.0,
) -> None

NewsImpact

The effect of one news item on prices.

NewsImpact(
    *,
    ticker: str | None = None,
    sector: str | None = None,
    sectors: Sequence[str] | None = None,
    remaining_impact: float = 0.0,
    reversal_phase: bool = False,
) -> None

TickResult

What one tick did, as tick() returns it.

market_status: str
draws_consumed: int
active: int

run_many

tf.run_many(
    seeds: Iterable[int],
    *,
    universe: Sequence[Instrument],
    macro: Macro | None = None,
    days: int = 1,
    ticks: int = 390,
    start: tuple[int, int, int] = (9, 30, 3),
    workers: int | None = None,
    collect: str = "prices",
    scenario: Any = None,
    model: str | ModelParams | None = None,
) -> list[Any]

Runs one simulation per seed in a thread pool and returns the results in input order. collect chooses what comes back: "prices" (raw f64 bytes), "attribution" (the factor columns) or "summary" (prices, draw count, tickers and fingerprints). Every seed runs the same model. A single seed always runs in-process.

Examples

e = tf.Engine(seed=42, universe=u)
e.run_days(60)

a, b = e.fork(2)      # two engines, one past
b.pin_macro(vix=45.0)
a.run_days(20)
b.run_days(20)        # same noise, higher fear

e.run_days(30, record=True)

bars = e.bars(grain="day")   # every recorded day
one  = e.truth(day=12)       # that day alone
# day=None means every recorded day;
# an unrecorded day raises

book = e.book(u[0].ticker)

est = book.sweep_cost("buy", 50_000)
# cost without executing; None on an empty side

res = book.submit("buy", 50_000, taker="me")
[f.price for f in res.fills]

u  = tf.Universe.random(40, seed=7)
u2 = tf.Universe.from_json(u.to_json())
u.fingerprint == u2.fingerprint   # True
# order is contractual: a reordered roster
# is a different market from the same seed

See also

How prices are made explains how truth() breaks each price move into parts. Model parameters lists the coefficient set. Forks and counterfactuals covers saving, forking and resuming a market.