Skip to main content

XXSim

Exchange Execution Simulator, development package. This package simulates order(s) execution based on provided market OHLCV data. This is not an independent package, but its the core logic required to implement backtesting when it comes on running on candlebar data.

This is the first drop and wasn't tested out in the wild yet, more functionality and capabilities to come

disclaimer

Own risk warning - Execution prices are best estimations base on worst case scenarios and statistics, there will be price differences between simulations and real-world execution, using this package the user acknowledges his consent and takes full responsibility on the implications caused due to any error or misinterpetation of this package and it's results.

Trailing commands warning - Trailing commands are currently roughly estimated and carry high deviation from the real world

The challenge

Core Problem: Reconstructing intra-bar price movement to determine order execution.

The golden standard of market data comes in chunks of Candle-bars providing Open, High, Low, Close and Volume of predefined time range ie. 1-minute, 5-minutes, an hour, a day, a week, a month, etc... Within each such data-unit there is a gap of the inner price motions, unless you work with tick-by-tick data which is expensive, noisy and resource intense. On top of that, fill prices are results of a consiquent rules and formations that are hard to simulate.

The solution

Output: Realistic execution fills within statistical uncertainty. or consiquent order either original or modified.

XSim relies on OHLC Data to simulate the inner motion of prices within single data-unit, and attempt to perform a set of decision to execute orders in the most authentic way.

Supported order types

  • MarketOrder
  • LimitOrder
  • StopOrder
  • StopLimitOrder
  • TrailingStopMarket
  • MarketOnCloseOrder (MOC) — fills at bar.close only on bars where BarData.is_close_bar=True

Not supported order types (at the moment)

  • Trailing Stop Limit Orders
  • Limit-on-Close (LOC)
  • Market-if-Touched (MIT)
  • Others...

Current Execution algorithm assumptions

  • Optional fill drift model — volatility-based normal distribution drift, configurable via ExecutionConfig
    • fill_drift_model="none" (default): deterministic fills at exact price
    • fill_drift_model="normal": drift drawn from N(0, bar_range / std_divider)
    • Direction follows intra-bar price movement (not order side) — fill drifts where the market moves
    • Trail orders use next price fragment for direction; other orders use close vs fill price
    • Result always clamped to [bar.low, bar.high]
    • Seeded RNG via random_seed for reproducible backtests
  • No partial fills
  • Aggressive approach - Order will be filled if there's a possible path between order's formation and the candlebar.
  • Trail orders assume the following order of the candles: On Bullish bar: prev_extremePrice [optional] -> open -> low -> high -> close On Bearish bar: prev_extremePrice [optional] -> open -> high -> low -> close

Installation

pip install XXSim

Usage

Single-Bar Execution

For direct single-bar execution using the low-level engine:

from XXSim import ExecutionEngine, MarketOrder, BarData
from datetime import datetime

engine = ExecutionEngine()
bar = BarData(
    date=datetime(2025, 1, 1, 9, 30),
    open=100.00,
    high=105.00,
    low=95.00,
    close=102.00,
    volume=1000000,
)
order = MarketOrder(action='BUY', totalQuantity=100)
fills = engine.execute(order, bar)
print(fills)

Multi-Bar Simulation

For backtesting across multiple bars with order lifecycle management:

from XXSim import Simulator, MarketOrder, LimitOrder, BarData

sim = Simulator()

# Register callbacks
sim.on_fill(lambda trade, fill: print(f"Filled: {fill.execution.price}"))
sim.on_cancel(lambda trade: print(f"Cancelled: {trade.log[-1].message}"))

# Submit orders
sim.submit_order(MarketOrder(action='BUY', totalQuantity=100))
sim.submit_order(LimitOrder(action='SELL', totalQuantity=100, price=110.0))

# Process bars
for bar in historical_bars:
    fills = sim.process_bar(bar)

# Or use ib_insync-style event loop
def strategy(bar, fills):
    if should_buy(bar):
        sim.submit_order(MarketOrder(action='BUY', totalQuantity=100))

sim.on_bar(strategy)
sim.run(historical_bars)

The Simulator supports:

  • Order management: submit, cancel, update, query orders
  • TIF (Time-In-Force): GTC, DAY (expires on date change), GTD (expires after date)
  • GAT (Good After Time): Orders with goodAfterTime are not active until that time
  • OCO (One-Cancels-Other): Link orders via ocaGroup - when one fills, siblings are cancelled
  • Callbacks: on_fill, on_cancel, on_update, on_bar

Development

Running Tests

pytest tests/ -v

Visualizations

Stop-limit and Trailing test cases can be visualized For stop-limit visualization run:

python docs/stop-limit-chart-generator.py test-data/stop-limit/<filename.csv>

For trailing visualization run:

python docs/trailing-stop-chart-generator.py test-data/trailing-stop/<filename.csv>

TODO: Trailing cases are not organized systemactically enough

Contributing

Contributions are welcome! Please see the documentation in the docs folder for more details and test specifications.

Metadata

Release files for XXSim 0.16.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for XXSim 0.16.0
File Size Uploaded Provenance Actions
xxsim-0.16.0.tar.gz 34.0 kB Without provenance Details for xxsim-0.16.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for XXSim 0.16.0
File Interpreter ABI Platform Actions
xxsim-0.16.0-py3-none-any.whl Python 3 none any Details for xxsim-0.16.0-py3-none-any.whl

Total release size: 48.7 kB

Release files / xxsim-0.16.0.tar.gz

Download URL xxsim-0.16.0.tar.gz
Size 34.0 kB
Tags Source
SHA-256 checksum
How to use checksums
dac6c8bc1aed0dc2175eb5825053ed4052991becbcffc7395874eb2840b320b8
BLAKE2b-256 checksum
How to use checksums
fb687de346c27f45b486e6454024b78f024b0712282e89c29d63b27f03c2b67b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.8

Release files / xxsim-0.16.0-py3-none-any.whl

Download URL xxsim-0.16.0-py3-none-any.whl
Size 14.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cff52cdd334bae0d26bad445e3761f9cf7ad9f9b272514efb384f6f8938b4f5f
BLAKE2b-256 checksum
How to use checksums
48acd6712df53053beb719297bc9262c494eb4e7d08e9022f0d6d3bddc1436a7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.8

Security for XXSim 0.16.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page