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: object

Rules for accepting and filling simulated orders in one run.

model selects the matching rule (EXECUTION_MODELS). latency_ns delays when an accepted order may first match; latency_jitter_ns adds 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_milli above 0 instead draws a lognormal delay with median latency_ns and sigma latency_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_share is charged on every filled share and reserved in advance for buys. impact_bps is the square-root market impact coefficient: a fill taking a fraction f of the displayed opposite side pays impact_bps * sqrt(f) basis points worse than the quoted price, never beyond the order’s limit. borrow_bps_per_year charges 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 as borrow_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
fee_per_share: 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: object

Read-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
reserved_shares: tuple[tuple[str, int], ...]
config: ExecutionConfig
class sim_platform.execution.OrderResult(intent_id, order_id, status, reason=None)[source]

Bases: object

Outcome of submitting one intent; reason explains 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: object

The 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.

finish_recorded_replay(status, reason)[source]
Parameters:
  • status (str)

  • reason (str)

Return type:

ExecutionSnapshot

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:

ExecutionSnapshot

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

play()[source]
Return type:

Any

pause()[source]

Pause the market and save the current financial position.

Return type:

Any

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 count events 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]]

finish(status, reason, *, time_ns=None)[source]

End at an owner clock boundary without consuming the end-time source frame.

Parameters:
  • status (str)

  • reason (str)

  • time_ns (int | None)

Return type:

ExecutionSnapshot

close()[source]

Stop the run if it is still active; closing twice is harmless.

Return type:

None