API/SCENARIO

Scenario API

Reference for Scenario, Intervention, Firing, the target registry and run_scenario. Signatures are the package's own, and usage and examples are on Scenarios.

Scenario

A macro path and a set of explicit interventions, applied a day at a time, imported from the top level as tradefloor.Scenario.

Scenario(
    label: str = "",
    *,
    name: str | None = None,
    description: str = "",
    interventions: Sequence[Intervention] = (),
    shocks: Sequence[Intervention] = (),
    transmission: Sequence[Intervention] = (),
)

hold(**fields)Pin fields to a constant from day zero. Returns self. Field names outside the twelve-field registry raise ValidationError.

ramp(field, *, start, end, over, begin=0)Move a field linearly from start to end over the given days. Held at start before begin and at end after. over < 1 or begin < 0 raise.

step(field, *, before, after, at)Jump a field from before to after on day at. Pins on one field layer as consecutive segments; start days must strictly increase or the call raises.

shock(target, *, operation="multiply", value=None, at=0, duration=None, shape=None)Add an exogenous intervention. Returns self.

assume(...)Same signature and machinery as shock, filed under assumed transmission. describe() prints the two under separate headings.

intervene(intervention)Add one built Intervention. Declared order is kept and breaks same-day ties.

apply(engine, day)Drive one day of one run: pins first, then shocks, then transmission. Returns the list of Firings. Day counts from when the scenario starts being applied.

at(day) / table(days)The pins for one day, or the whole path, for inspection before running.

load(name)Classmethod. A packaged scenario by name: geopolitical_conflict, liquidity_crisis, oil_price_spike, policy_regime_shift, rate_shock, recession.

from_yaml(source) / from_json(text)Classmethods. Parse a document. Validation errors name the target and the operation.

rate_shock(*, start=0.025, end=0.05, over=30, begin=0, credit_spread=0.02)Constructor. Moves the policy rate and the corporate yield together, held apart by credit_spread. Raises if called on an instance.

vix_shock(*, calm=15.0, peak=45.0, at=10, over=20)Constructor. A step up at day at, a ramp back over the given days.

document() / fingerprintThe canonical resolved document, and the sha256 over it. The YAML and Python forms of one experiment fingerprint identically.

describe()The scenario as text, shocks above assumptions.

log / firing_table()The last run's audit trail: each firing with the values it saw.

without_interventions() / copy()The same macro path with interventions removed, and an independent copy for driving two runs at once.

name / description / sourceIdentity, description, and the file name the scenario was read from, when it was.

Intervention

One explicit change to one target at one time, immutable and validated at construction, imported from the top level as tradefloor.Intervention.

Intervention(
    target: str,
    *,
    operation: str = "multiply",   # "set" | "add" | "multiply"
    value: Any = None,
    at: int = 0,                   # days from scenario start
    duration: int | None = None,
    shape: str | None = None,      # "impulse" | "permanent" | "hold" | "ramp"
    role: str = "shock",           # "shock" | "transmission"
)

as_dict() / from_dict()The serialised form, with every default present, so the fingerprint does not depend on typing habits.

active_on(day) / last_dayWhether the intervention acts on a day, and the last day of its window.

describe()One line, in the units the target declares.

ScenarioValidationErrorRaised for a malformed scenario document or an unknown target. A subclass of ValidationError.

FiringOne application of one intervention: target, day, the value read and the value written. as_dict() for a machine, str() for a person.

The target registry

tradefloor.TARGETS maps the twelve target names to Target objects; tradefloor.UNSUPPORTED_TARGETS maps refused names to the mechanism to use instead. The names, what each reaches and what a move measures are tabulated on Scenarios.

Target.read(engine) / write(engine, value)How the target reads and writes the engine.

Target.check(operation, value)Validation at construction: rates as fractions in [-0.05, 0.50], positive prices, named cycle phases.

Target.show(value)The value in the target's own units, for messages and audit trails.

run_scenario

tf.run_scenario(
    scenario: Scenario,
    *,
    seed: int,
    universe: Sequence[Instrument],
    days: int,
    macro: Macro | None = None,
    ticks_per_day: int = 390,
    start: tuple[int, int, int] = (9, 30, 3),
    record: bool = False,
    model: str | ModelParams | None = None,
) -> Engine

Runs a market under the scenario and returns the finished engine. The scenario is applied at the start of each day, so day zero is already under the path. days < 1 raises ValidationError. tf.evaluate, tf.rank, tf.tca.analyse and tf.run_many take the same scenario= keyword.

Scenario API

Scenario

Intervention

The target registry

run_scenario

See also

All pages