simQuant 0.1.0

An event-driven backtesting and execution simulation engine for quantitative trading strategies.

🚀 QuantSim: Professional Event-Driven Backtesting Framework

QuantSim is a modern, event-driven backtesting framework for quantitative trading strategies. Built with Python 3.9+, it provides institutional-grade simulation capabilities with a focus on performance, accuracy, and extensibility.

✨ Why QuantSim?

• 🏗️ Event-Driven Architecture: Realistic simulation that processes market events chronologically
• 📊 Multiple Data Sources: Yahoo Finance, CSV files, synthetic data generation
• ⚡ High Performance: Optimized for speed with comprehensive caching and vectorized operations
• 🧪 Battle-Tested: 178 unit tests with 95%+ coverage ensuring reliability
• 🔧 Highly Extensible: Plugin architecture for strategies, indicators, and execution models
• 📈 Professional Reporting: Rich markdown reports with equity curves and performance metrics
• 🤖 ML Integration: Optional machine learning components for advanced strategies
• 🛡️ Production Ready: Comprehensive error handling, logging, and validation

---

📦 Quick Installation

From PyPI (Recommended)

# Core package
pip install quantsim

# With ML capabilities
pip install quantsim[ml]

# With pairs trading (requires statsmodels)
pip install quantsim[pairs]

# Full installation with all features
pip install quantsim[ml,pairs]

For Development

git clone https://github.com/yash-tr/quantsim.git
cd quantsim
pip install -e .[dev]

---

🚀 Quick Start

1. Simple Strategy Backtest

import quantsim as qs

# Create and run a simple SMA crossover strategy
engine = qs.SimulationEngine(
    data_source='yahoo',
    symbols=['AAPL'],
    start_date='2022-01-01',
    end_date='2023-01-01',
    strategy='sma_crossover',
    initial_capital=100000
)

results = engine.run()
print(f"Total Return: {results.total_return:.2%}")
print(f"Sharpe Ratio: {results.sharpe_ratio:.2f}")

2. Command Line Interface

# Run a single backtest
quantsim run --strategy sma_crossover --symbol AAPL --start 2022-01-01 --end 2023-01-01

# Batch backtesting from YAML config
quantsim batch my_strategies.yaml

# Get help
quantsim --help

3. Custom Strategy Development

from quantsim.strategies import Strategy
from quantsim.core.events import OrderEvent

class MyStrategy(Strategy):
    def __init__(self, symbols, **kwargs):
        super().__init__(symbols, **kwargs)
        self.window = kwargs.get('window', 20)
    
    def on_market_event(self, event):
        # Your strategy logic here
        if self.should_buy(event.symbol):
            order = OrderEvent(
                symbol=event.symbol,
                order_type='MKT',
                quantity=100,
                direction='BUY'
            )
            self.event_queue.put(order)
    
    def should_buy(self, symbol):
        # Implement your buy logic
        return True

---

🏗️ Core Features

Event-Driven Simulation Engine

• Realistic Order Processing: Market, limit, and stop orders with configurable slippage
• Portfolio Management: Real-time P&L tracking, risk metrics, and position management
• Execution Simulation: Latency modeling, partial fills, and commission structures

Built-in Strategies

• SMA Crossover: Moving average crossover with customizable windows
• Momentum: Trend-following strategy with momentum indicators
• Mean Reversion: Statistical arbitrage based on price deviations
• Pairs Trading: Cointegration-based pairs trading (requires statsmodels)
• ML Strategies: Integration with scikit-learn and TensorFlow

Data Sources

• Yahoo Finance: Automatic data fetching with symbol validation
• CSV Files: Flexible parser supporting multiple formats
• Synthetic Data: Configurable data generation for testing

Advanced Analytics

• Performance Metrics: Sharpe ratio, Sortino ratio, maximum drawdown, VaR
• Trade Analysis: Win rate, profit factor, average trade duration
• Risk Metrics: Beta, alpha, tracking error, information ratio
• Visualizations: Equity curves, drawdown plots, trade distributions

---

📊 Performance Metrics

QuantSim calculates comprehensive performance metrics:

Metric	Description
Total Return	Cumulative return over the backtest period
CAGR	Compound Annual Growth Rate
Sharpe Ratio	Risk-adjusted return measure
Sortino Ratio	Downside deviation-adjusted returns
Maximum Drawdown	Largest peak-to-trough decline
Calmar Ratio	CAGR divided by maximum drawdown
Win Rate	Percentage of profitable trades
Profit Factor	Ratio of gross profits to gross losses

---

🛠️ Architecture Overview

┌─────────────────┐    ┌──────────────┐    ┌─────────────┐
│  Data Handler   │───▶│ Event Queue  │───▶│  Strategy   │
└─────────────────┘    └──────────────┘    └─────────────┘
                              │                      │
                              ▼                      ▼
┌─────────────────┐    ┌──────────────┐    ┌─────────────┐
│   Portfolio     │◀───│   Engine     │◀───│   Orders    │
└─────────────────┘    └──────────────┘    └─────────────┘
                              │
                              ▼
                    ┌──────────────┐
                    │  Execution   │
                    │   Handler    │
                    └──────────────┘

---

📈 Example Strategies

SMA Crossover Strategy

from quantsim import SMACrossoverStrategy

strategy = SMACrossoverStrategy(
    symbols=['AAPL', 'GOOGL'],
    short_window=10,
    long_window=30,
    event_queue=event_queue
)

Custom ML Strategy

from quantsim.strategies.ml import MLStrategy
from sklearn.ensemble import RandomForestClassifier

strategy = MLStrategy(
    symbols=['SPY'],
    model=RandomForestClassifier(),
    features=['sma_10', 'rsi_14', 'macd'],
    lookback_window=60
)

---

🧪 Testing & Quality

QuantSim maintains high code quality standards:

• 178 Unit Tests with 95%+ coverage
• Multi-platform Testing (Ubuntu, Windows, macOS)
• Python 3.9+ Support across versions
• Automated CI/CD with GitHub Actions
• Code Quality Checks (Black, Flake8, MyPy)
• Security Scanning (Bandit, Safety)

# Run tests locally
pytest tests/ -v --cov=quantsim

# Generate coverage report
pytest --cov=quantsim --cov-report=html

---

📚 Documentation & Examples

Available Resources

• 📖 API Documentation - Complete API reference
• 📓 Jupyter Notebooks - Interactive examples and tutorials
• 🔧 Configuration Guide - Setup and configuration
• 🤝 Contributing Guide - How to contribute

Example Configurations

# sample_batch_config.yaml
strategies:
  - name: "SPY_SMA_Crossover"
    strategy: "sma_crossover"
    data_source: "yahoo"
    symbols: ["SPY"]
    start_date: "2020-01-01"
    end_date: "2023-01-01"
    short_window: 10
    long_window: 30
    initial_capital: 100000

---

🚀 Advanced Usage

Batch Processing

# Run multiple strategies from YAML config
quantsim batch strategies.yaml --output-dir results/

# Parallel execution
quantsim batch strategies.yaml --parallel --workers 4

Custom Indicators

from quantsim.indicators import Indicator

class RSI(Indicator):
    def __init__(self, period=14):
        self.period = period
    
    def calculate(self, prices):
        # RSI calculation logic
        return rsi_values

Risk Management

from quantsim.risk import RiskManager

risk_manager = RiskManager(
    max_position_size=0.1,  # 10% max position
    max_drawdown=0.05,      # 5% max drawdown
    var_limit=0.02          # 2% VaR limit
)

---

🌟 Competitive Advantages

Feature	QuantSim	Zipline	Backtrader	FreqTrade
Modern Python	✅ 3.9+	❌ 3.6+	✅ 3.7+	✅ 3.8+
Event-Driven	✅	✅	❌	✅
ML Integration	✅	❌	❌	✅
Multi-Asset	✅	✅	✅	❌
Real-time Ready	✅	❌	✅	✅
Professional Reports	✅	❌	❌	✅

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Steps

1. 🍴 Fork the repository
2. 🔄 Clone your fork: git clone https://github.com/yourusername/quantsim.git
3. 🌿 Create a branch: git checkout -b feature/amazing-feature
4. ✨ Make your changes and add tests
5. ✅ Run tests: pytest tests/
6. 📝 Commit: git commit -m "Add amazing feature"
7. 🚀 Push: git push origin feature/amazing-feature
8. 🔄 Create a Pull Request

Development Setup

git clone https://github.com/yash-tr/quantsim.git
cd quantsim
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e .[dev]
pre-commit install  # Optional: setup pre-commit hooks

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Acknowledgments

• Financial Data: Powered by yfinance
• Numerical Computing: Built on NumPy and Pandas
• Visualization: Charts generated with Matplotlib
• Testing: Quality assured with pytest

---

📞 Support & Community

• 🐛 Bug Reports: GitHub Issues
• 💡 Feature Requests: GitHub Discussions
• 📧 Email: [e-mail]
• 💬 Community: Join our discussions for tips, strategies, and support

---

🗺️ Roadmap

Version 0.2.0 (Coming Soon)

• 🔄 Real-time trading integration
• 📊 Advanced portfolio optimization
• 🌐 WebSocket data feeds
• 📱 Interactive dashboard

Version 0.3.0 (Future)

• 🤖 AutoML strategy generation
• ☁️ Cloud deployment options
• 📈 Options and derivatives support
• 🔗 Crypto exchange integration

---

Ready to transform your trading strategies? Install QuantSim today and start building professional backtests in minutes!

pip install quantsim

⭐ Star us on GitHub if QuantSim helps your trading! ⭐