Metadata-Version: 2.4
Name: simulor
Version: 0.2.0b1
Summary: Event-driven backtesting framework with institutional-grade analytics
Author: Simulor Contributors
License: MIT
Project-URL: Bug Tracker, https://github.com/alasdairpan/simulor/issues
Project-URL: Documentation, https://simulor.readthedocs.io
Project-URL: Homepage, https://github.com/alasdairpan/simulor
Project-URL: Repository, https://github.com/alasdairpan/simulor
Keywords: backtesting,trading,quantitative,finance,algorithmic-trading
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Rust
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyarrow>=12.0.0
Requires-Dist: polars>=0.19.0
Requires-Dist: plotly>=5.14.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dateutil>=2.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-xdist>=3.3.0; extra == "dev"
Requires-Dist: hypothesis>=6.82.0; extra == "dev"
Requires-Dist: ruff==0.14.6; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: black>=23.7.0; extra == "dev"
Requires-Dist: pre-commit>=3.3.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
Requires-Dist: myst-parser>=2.0.0; extra == "docs"
Provides-Extra: jupyter
Requires-Dist: jupyter>=1.0.0; extra == "jupyter"
Requires-Dist: ipywidgets>=8.0.0; extra == "jupyter"
Requires-Dist: matplotlib>=3.7.0; extra == "jupyter"
Provides-Extra: longport
Requires-Dist: longport>=3.0.20; extra == "longport"
Dynamic: license-file

# Simulor

[![PyPI](https://img.shields.io/pypi/v/simulor.svg)](https://pypi.org/project/simulor/)
[![Python Version](https://img.shields.io/pypi/pyversions/simulor.svg)](https://pypi.org/project/simulor/)
[![License](https://img.shields.io/github/license/alasdairpan/simulor.svg)](https://github.com/alasdairpan/simulor/blob/main/LICENSE)
[![CI](https://github.com/alasdairpan/simulor/workflows/CI/badge.svg)](https://github.com/alasdairpan/simulor/actions)

Simulor is a sophisticated backtesting framework designed for quantitative traders and researchers who demand institutional-grade realism and performance. Built on an event-driven architecture with pluggable components, it seamlessly transitions from historical backtesting to paper trading and live execution.

> **⚠️ Active Development**: Simulor is currently in beta. APIs may change before v1.0. We welcome feedback and contributions!

## Key Features

- **Event-Driven Architecture**: True event-driven simulation with point-in-time data delivery, multiple resolutions (tick/minute/hour/daily), and compositional data structures
- **Pluggable Strategy Components**: Modular alpha models, portfolio construction, risk management, execution models, and universe selection. Swap components without rewriting strategy logic
- **Institutional-Grade Execution**: Realistic fill models, transaction costs (commissions, spreads, slippage, market impact), T+0 settlement, and corporate actions handling
- **Comprehensive Analytics**: Performance metrics (Sharpe, Sortino, Calmar), risk analysis (VaR, CVaR, beta), trade statistics, and interactive Plotly visualizations
- **Environment Parity**: Same strategy code runs in backtest, paper trading, and live execution modes. Seamless transition from research to production

## Installation

```bash
pip install simulor
```

## Quick Start

```python
from decimal import Decimal
from pathlib import Path
from simulor import (
    Strategy, Engine, Fund,
    MovingAverageCrossover, EqualWeight, PositionLimit, Immediate, Static,
    CsvFeed, SimulatedBroker, Resolution, Instrument, Tearsheet
)

# Define strategy with pluggable components
# Workflow: Universe Selection -> Alpha Model -> Portfolio Construction -> Risk Management -> Execution
strategy = Strategy(
    name='MA_Crossover',
    universe=Static([
        Instrument.stock('SPY'),
        Instrument.stock('QQQ'),
        Instrument.stock('IWM')
    ]),
    alpha=MovingAverageCrossover(fast_period=10, slow_period=20),
    construction=EqualWeight(),
    risk=PositionLimit(max_position=Decimal('0.1')),
    execution=Immediate()
)

# Run backtest
engine = Engine(
    data=CsvFeed(path=Path('data/bars.csv'), resolution=Resolution.DAILY),
    fund=Fund(
        strategies=[strategy],  # Add more strategies as needed
        capital=Decimal('100000')
    ),
    broker=SimulatedBroker()
)
results = engine.run(
    start='2020-01-01',
    end='2025-12-31',
    mode='backtest'
)

# Analyze results
print(f"Total Return: {results.total_return:.2%}")
print(f"Sharpe Ratio: {results.sharpe_ratio:.2f}")
print(f"Max Drawdown: {results.max_drawdown:.2%}")

# Generate tearsheet
tearsheet = Tearsheet(results)
tearsheet.save('tearsheet.html')
```

## Roadmap

### v0.1.0

- [x] Event-driven engine with CSV data provider
- [x] Pluggable strategy framework
- [x] Basic execution (InstantFill, SpreadFill)
- [x] Core analytics (returns, Sharpe, drawdown)
- [ ] Simple transaction costs

### v0.2.0+ (Planned)

- [ ] Parquet data provider and advanced data layer features
- [ ] History API with type-safe lookback
- [ ] Advanced fill models (L2 matching, probabilistic)
- [ ] T+2 settlement and realistic cash management
- [ ] Overfitting detection (WFA, PBO, CSCV)
- [ ] Advanced analytics (execution quality, attribution)
- [ ] ML integration and model registry
- [ ] Broker integrations for live trading

## Acknowledgments

Simulor implements the industry-standard modular pipeline architecture (Universe Selection → Alpha Generation → Portfolio Construction → Risk Management → Execution). This separation of concerns allows for maximum flexibility, testability, and maintainability, similar to the architecture found in institutional quantitative systems and platforms like Lean.

## Contributing

Contributions are welcome!

## License

This project is licensed under the [MIT License](LICENSE).
