sim_platform.execution¶
Local simulation execution, separate from market data and decision policies.
- class sim_platform.execution.ExecutionConfig(model='displayed-limit-v1', latency_ns=0, fee_per_share=0, max_order_quantity=1000000, latency_jitter_ns=0, impact_bps=0, latency_sigma_milli=0, borrow_bps_per_year=0)[source]¶
Bases:
objectRules for accepting and filling simulated orders in one run.
modelselects the matching rule (EXECUTION_MODELS).latency_nsdelays when an accepted order may first match;latency_jitter_nsadds a further delay drawn uniformly from 0 to that value, fixed by the order’s ID so every replay sees the same delay.latency_sigma_milliabove 0 instead draws a lognormal delay with medianlatency_nsand sigmalatency_sigma_milli / 1000(heavy right tail, as measured network and queueing delays have), also fixed by the order ID and capped at 1,000 times the median.fee_per_shareis charged on every filled share and reserved in advance for buys.impact_bpsis the square-root market impact coefficient: a fill taking a fraction f of the displayed opposite side paysimpact_bps * sqrt(f)basis points worse than the quoted price, never beyond the order’s limit.borrow_bps_per_yearcharges short positions an annual borrow rate on their sale proceeds for the market time they were open; it is added to the fee of the buy that covers them, and the fill records it asborrow_fee.- Parameters:
model (str)
latency_ns (int)
fee_per_share (int)
max_order_quantity (int)
latency_jitter_ns (int)
impact_bps (int)
latency_sigma_milli (int)
borrow_bps_per_year (int)
- model: str = 'displayed-limit-v1'¶
- latency_ns: int = 0¶
- max_order_quantity: int = 1000000¶
- latency_jitter_ns: int = 0¶
- impact_bps: int = 0¶
- latency_sigma_milli: int = 0¶
- borrow_bps_per_year: int = 0¶
- property max_delay_ns: int¶
The longest delay an order can draw, for range checks at acceptance.
- class sim_platform.execution.ExecutionSnapshot(run_id, status, time_ns, market_sequence, account, reserved_cash, available_cash, reserved_shares, config)[source]¶
Bases:
objectRead-only view of a run’s account, including cash and shares held for open orders.
- Parameters:
run_id (str)
status (str)
time_ns (int)
market_sequence (int)
account (AccountSnapshot)
reserved_cash (int)
available_cash (int)
reserved_shares (tuple[tuple[str, int], ...])
config (ExecutionConfig)
- run_id: str¶
- status: str¶
- time_ns: int¶
- market_sequence: int¶
- account: AccountSnapshot¶
- reserved_cash: int¶
- available_cash: int¶
- config: ExecutionConfig¶
- class sim_platform.execution.OrderResult(intent_id, order_id, status, reason=None)[source]¶
Bases:
objectOutcome of submitting one intent;
reasonexplains a rejection.- Parameters:
intent_id (str)
order_id (str | None)
status (str)
reason (str | None)
- intent_id: str¶
- order_id: str | None¶
- status: str¶
- reason: str | None = None¶
- class sim_platform.execution.ExecutionSession(operations, profile, run_id, maker, market, *, ownership)[source]¶
Bases:
objectThe single owner that drives one market session for one account run.
Creating a session takes exclusive write access to the account, claims the run and the market, and records the starting position. From then on every market step goes through this object, so the market and the account ledger cannot drift apart. If the market is advanced by anyone else, the next call fails the run.
Ending the run (
finish,fail,close) or a processing error releases all three claims. A session is not restartable: a finished run needs a new run.- Parameters:
operations (Any) – Financial reads and writes (ExecutionCoordinator through Platform).
profile (str) – Profile that owns the run.
run_id (str) – The run to execute; it must be active and have no history.
maker (str) – Decision maker that currently holds authority for the run.
market (Any) – The market session to drive.
ownership (Any) – Registry that allows one execution owner per run.
- control_boundary()[source]¶
Serialize observation and authority checks with the resulting operation.
- Return type:
Iterator[None]
- on_close(callback)[source]¶
Register one callback to run when this session releases its ownership.
- Parameters:
callback (Callable[[], None])
- Return type:
None
- property snapshot: ExecutionSnapshot¶
The account with current reservations, at the last processed market position.
- property market_snapshot: MarketSnapshot¶
- property last_fills: Tuple[Dict[str, Any], ...]¶
Fills produced by the most recent market event; empty if there were none.
- property account_sequence: int¶
Committed account version without projecting a full execution view.
- property closed: bool¶
- property replay_state: Dict[str, Any]¶
A detached copy of the financial frontier, for verifying a recorded replay.
- validate_control()[source]¶
Check lifecycle, callback reentrancy and synchronization before a decision.
- Return type:
None
- adopt_maker(maker)[source]¶
Follow an authority change only after the database has committed it.
- Parameters:
maker (str)
- Return type:
None
- fail(reason)[source]¶
Terminate a failed decision run and release its execution ownership.
- Parameters:
reason (str)
- Return type:
- submit(intent)[source]¶
Submit an order directly; runs with a decision policy must use their runner.
- Parameters:
intent (Intent)
- Return type:
Any
- cancel(order_id)[source]¶
Cancel an order directly; runs with a decision policy must use their runner.
- Parameters:
order_id (str)
- Return type:
Any
- abandon()[source]¶
Release execution after an untrusted storage failure, without more SQL.
The lifecycle owner must stop driving the market. Committed orders and the unresolved DB run are preserved for explicit recovery.
- Return type:
None
- step()[source]¶
Advance a ready or paused market by exactly one event and process it.
- Return type:
MarketEvent
- pump(count=1)[source]¶
Process up to
countevents while the market is playing.Stops early when the market stops playing or the run ends.
- Parameters:
count (int)
- Return type:
Tuple[MarketEvent, …]
- advance_idle_prefix(end_prefix)[source]¶
Batch only immutable, no-fill source transitions on the same owner.
No financial submission/commit path is bypassed. A possible fill, publication or observer requires ordinary per-event execution.
- Parameters:
end_prefix (int)
- Return type:
Tuple[int, Optional[MarketEvent]]