SimLab is a Python package providing a versatile set of simulation tools for modeling complex systems across various domains. It offers a unified interface for different simulation paradigms, making it ideal for educational, research, and business applications.
To install SimLab with all features:
pip install sim-labFor specific interfaces only:
# CLI only
pip install sim-lab[cli]
# Web interface
pip install sim-lab[web]
# TUI (terminal interface)
pip install sim-lab[tui]- Unified Interface: All simulators share a consistent API
- Registry System: Dynamic discovery and instantiation of simulation models
- Multiple Interfaces: CLI, TUI, Web, and Python API
- Visualization Tools: Built-in plotting and visualization capabilities
- Data Import/Export: Support for common data formats
- Parameter Validation: Comprehensive input validation
- Stochastic Processes: Support for random processes with seed control
SimLab ships 18 simulators organised by modelling paradigm — how state and time advance:
- Stock Market — price fluctuations with volatility, drift, and market events
- Resource Fluctuations — resource price dynamics with supply disruptions
- Product Popularity — product demand with growth, marketing, and promotions
- Discrete Event — general-purpose event-driven engine
- Queueing — M/M/1 and M/M/c service systems (arrivals, queues, servers)
- Monte Carlo — sample random processes to estimate numerical results
- Markov Chain — stochastic processes with the Markov property
- Gillespie SSA — exact stochastic simulation of chemical kinetics
- Cellular Automaton — grid models with local update rules (incl. Game of Life)
- Game of Life — Conway's Life seeded with classic patterns (glider, Gosper gun, ...)
- Forest Fire — Drossel-Schwabl forest fire and self-organised criticality
- Agent-Based — emergent behaviour from autonomous interacting agents
- Boids — Reynolds flocking (separation, alignment, cohesion)
- System Dynamics — stocks, flows, and feedback loops (Euler + RK45)
- Network — processes (e.g. epidemic spread) on complex network topologies
- Predator-Prey — Lotka-Volterra population dynamics
- Epidemiological — SIR disease-spread models
- Supply Chain — multi-tier supply chains with inventory management
from sim_lab.core import SimulatorRegistry
# Create a simulation using the registry
sim = SimulatorRegistry.create(
"StockMarket",
start_price=100.0,
days=252,
volatility=0.02,
drift=0.0005,
random_seed=42
)
# Run the simulation
prices = sim.run_simulation()
# Visualize the results
import matplotlib.pyplot as plt
plt.figure(figsize=(10, 6))
plt.plot(prices)
plt.title('Stock Price Simulation')
plt.xlabel('Trading Days')
plt.ylabel('Price ($)')
plt.grid(True)
plt.show()# Run a stock market simulation
simlab stock-market run --start-price 100 --days 365 --volatility 0.02 --drift 0.001 --output prices.csv
# Get help for all commands
simlab --help# Launch the interactive terminal UI
simlab-tui# Start the web server
simlab-web
# Then visit http://localhost:8000 in your browserSimLab is designed with education in mind, helping students:
- Understand complex systems through hands-on simulation
- Explore the impact of parameters on system dynamics
- Develop data analysis and visualization skills
- Apply theoretical concepts to practical scenarios
- Create and test hypotheses in a simulated environment
For comprehensive documentation, visit:
SimLab uses modern Python development tools:
- uv for dependency management
- Ruff for linting and formatting
- pytest for testing
- MkDocs for documentation
To set up a development environment:
# Clone the repository
git clone https://github.com/teaching-repositories/sim-lab.git
cd sim-lab
# Run the setup script
./scripts/setup_dev.sh
# Or manually
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -e .[dev]See DEVELOPMENT.md for more details.
SimLab features a powerful registry system for dynamically discovering and instantiating simulators:
from sim_lab.core import SimulatorRegistry, BaseSimulation
# Register a custom simulator
@SimulatorRegistry.register("MySimulator")
class MyCustomSimulation(BaseSimulation):
# Your implementation here
pass
# List available simulators
simulators = SimulatorRegistry.list_simulators()
print(f"Available simulators: {simulators}")
# Create an instance
sim = SimulatorRegistry.create("MySimulator", days=100, random_seed=42)For more information, see the Registry System documentation.
We welcome contributions to the SimLab project! See the Contributing Guide for more details.
This project is licensed under the MIT License. See the LICENSE file for more details.