SIMILAR is a powerful agent-based modeling framework with a Python DSL backed by a high-performance C++ engine. JamFree is a traffic simulation framework built on SIMILAR, featuring microscopic and macroscopic models with real-time data integration.
- 🚀 10-50x Performance: Multi-threaded C++ engine with FastMath optimizations
- 🐍 Python DSL: Intuitive fluent API replacing verbose Java builders
- 🌐 Advanced Web UI: Real-time visualization with interactive controls
- 📦 One-command Install:
pip install similar2logoincludes everything - 🔧 Cross-platform: Native binaries for Windows, macOS, and Linux
pip3 install similar2logoThis installs the latest stable version with pre-compiled C++ extensions for optimal performance.
# Clone the repository
git clone https://github.com/gildasmorvan/similar
cd similar
# Build C++ engine (for development or custom builds)
./build_cpp_engine.sh
# Install Python package
pip install -e .📖 New to SIMILAR? See Getting Started Guide for a complete walkthrough!
⚡ Quick Commands? Check Quick Reference for a command cheat sheet!
Create my_first_sim.py:
from similar2logo.dsl import *
import random
class RandomWalker(Turtle):
def decide(self, perception):
influences = []
if random.random() < 0.3:
influences.append(self.influence_turn(random.uniform(-0.5, 0.5)))
influences.append(self.influence_move_forward(1.0))
return influences
# Create environment and simulation
env = Environment(100, 100, toroidal=True)
sim = Simulation(environment=env, title="Random Walk")
# Add 50 agents
for _ in range(50):
sim.add_agent(RandomWalker(
position=env.random_position(),
heading=env.random_heading()
))
# Run with web interface
sim.run_web(port=8080)Run it:
python3 my_first_sim.py
# Open http://localhost:8080cd cpp/jamfree
# Build JamFree
./build.sh
# Run web interface
./run_web_ui.sh
# Open http://localhost:5001A Python DSL for creating agent-based simulations with:
- 🐢 Turtle Agents: Logo-style agents with perception and decision-making
- 🌍 Environments: Toroidal/bounded worlds with pheromones and obstacles
- 🧠 Influences: Clean action system (move, turn, emit signals)
- ⚡ C++ Engine: Automatic 10-100x speedup when available
- 🌐 Web UI: Real-time visualization in browser
- 📊 18+ Examples: From flocking to epidemiology
Examples: Boids, Ant Foraging, Virus Spread, Segregation, Predator-Prey, and more!
A comprehensive traffic simulation framework featuring:
- 🚗 Microscopic Models: IDM car-following, MOBIL lane-changing
- 🌊 Macroscopic Models: LWR, CTM continuum flow
- 🔄 Hybrid Simulation: Automatic micro/macro switching
- 🗺️ OSM Integration: Real-world road networks
- 📡 Real-Time Data: TomTom, HERE, OpenTraffic integration
- 🎯 Routing: A* pathfinding with turn-by-turn navigation
- ⚡ GPU Acceleration: Metal GPU support (macOS)
- 🌐 Web Interface: Interactive visualization
- C++ Engine: Core simulation logic in optimized C++
- Python DSL: Easy-to-use Python interface
- Parallel Processing: Multi-threaded simulation
- GPU Support: Metal acceleration for large-scale traffic sims
- Adaptive Hybrid: Automatic micro/macro switching for optimal speed
- Multiple Paradigms: Microscopic, macroscopic, hybrid
- Real Data: OSM maps, traffic APIs, real-time integration
- Extensible: Easy to add new models and behaviors
- Cross-Platform: Linux, macOS, Windows
- Clean DSL: Intuitive Python API
- Web Visualization: No GUI installation needed
- Rich Examples: 18+ SIMILAR2Logo + traffic examples
- Documentation: Comprehensive guides and tutorials
📚 Complete Documentation Index - Find any document quickly!
- Quick Start Guide - Get started in 5 minutes
- Examples README - All 18 examples explained
- DSL Reference - API documentation
- Implementation Status - What's implemented
- JamFree README - Overview and concepts
- Quick Start - Get running fast
- Web UI Guide - Using the web interface
- Performance Guide - Optimization tips
- Routing & Traffic Data - Real-world integration
All located in examples/python/:
Basic
simple_random_walk.py- Basic movementcircle.py- Formation patternspassive_turtle.py- Physics simulation
Flocking & Collective
boids_dsl.py- Classic flocking behaviorboids_obstacles.py- Flocking with obstacle avoidanceant_foraging_dsl.py- Pheromone-based foraging
Biological
virus_spread.py- Epidemiology (SIR model)predator_prey.py- Lotka-Volterra dynamicsheatbugs.py- Temperature-seeking agents
Social & Urban
segregation_model.py- Schelling's modeltransport.py- Traffic simulation
Patterns & Emergence
turmite.py- Langton's Antmultiturmite.py- Multiple antsforest_fire.py- Cellular automaton
And more! See examples/python/README.md for the complete list.
Located in cpp/jamfree/examples/:
- Basic Simulation - Simple traffic flow
- OSM Integration - Real-world maps
- Hybrid Simulation - Micro/macro switching
- GPU Acceleration - Metal-accelerated simulation
- Routing - Path planning and navigation
# Run any example
python3 examples/python/boids_dsl.py
# With C++ engine verification
SIMILAR_VERBOSE=1 python3 examples/python/virus_spread.py
# Run all examples (testing)
python3 examples/python/run_examples.pycd cpp/jamfree
# Web interface (recommended)
./run_web_ui.sh
# Then open http://localhost:5001
# Command-line simulation
python3 examples/basic_simulation.py
# With performance stats
python3 examples/hybrid_simulation.py# Build C++ engine
./build_cpp_engine.sh
# Verify it works
SIMILAR_VERBOSE=1 python3 examples/python/boids_dsl.py
# Should see: ✓ Using C++ reaction enginecd cpp/jamfree
# Build core library
./build.sh
# Build with Python bindings
./build_python.sh
# Build with GPU support (macOS only)
./build_metal.shMost examples include a built-in web interface:
# In your simulation
sim.run_web(port=8080, steps_per_frame=1)Then open http://localhost:8080
Full-featured traffic simulation interface:
cd cpp/jamfree
./run_web_ui.shFeatures:
- 🗺️ Load OSM maps (upload or download)
- 🚗 Configure vehicles and parameters
- ⚡ Enable/disable optimizations
- 📊 Real-time performance metrics
- 🎨 Lane mode visualization (micro/macro)
With C++ engine enabled:
- 10-100x faster than pure Python
- Handles 1000+ agents in real-time
- Efficient spatial indexing
- Optimized influence resolution
Performance optimizations:
- IDM Lookup Tables: 30-40% faster car-following
- Spatial Indexing: O(log N) neighbor queries
- Adaptive Hybrid: Auto micro/macro switching
- GPU Acceleration: Metal support for macOS
- Multithreading: Parallel vehicle updates
Example: 1000 vehicles on real OSM map at 10+ FPS
Perfect for:
- Agent-Based Modeling courses
- Complex Systems research
- Traffic Engineering studies
- Artificial Life experiments
- Swarm Intelligence research
- Computational Biology teaching
We welcome contributions! To contribute:
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests and documentation
- Submit a pull request
See individual component READMEs for specific guidelines.
This project is licensed under the CeCILL-B license - see LICENSE.txt for details.
CeCILL-B is a BSD-like license compatible with international and French law.
- Gildas Morvan - Original SIMILAR framework
- Contributors - See AUTHORS.txt
- Traffic Flow Dynamics - Treiber & Kesting (2013)
- MOBIL Model - Kesting et al. (2007)
- Agent-Based Modeling - Wilensky & Rand (2015)
similar/
├── cpp/
│ ├── similar2logo/ # C++ engine for SIMILAR2Logo
│ └── jamfree/ # JamFree traffic simulation
│ ├── kernel/ # Core models (Vehicle, Lane, Road)
│ ├── microscopic/ # IDM, MOBIL
│ ├── macroscopic/ # LWR, CTM
│ ├── hybrid/ # Adaptive simulation
│ ├── gpu/ # Metal GPU acceleration
│ ├── realdata/ # OSM parser, traffic APIs
│ ├── python/ # Python bindings
│ └── examples/ # Example simulations
├── python/
│ └── similar2logo/ # Python DSL
│ ├── dsl/ # High-level API
│ ├── model.py # Core classes
│ └── parallel.py # Parallel engine
├── examples/
│ └── python/ # 18+ example simulations
└── docs/ # Additional documentation
✅ Complete - All Java examples ported to Python DSL with C++ engine
✅ Production Ready
- Microscopic simulation (IDM, MOBIL)
- Macroscopic models (LWR, CTM)
- Hybrid adaptive simulation
- OSM integration
- Web UI with visualization
- GPU acceleration (macOS)
- Real-time traffic data integration
- Issues: GitHub Issues
- Examples: Check
examples/python/for working code - Documentation: See individual README files
- Verbose Mode: Use
SIMILAR_VERBOSE=1to see what's happening
- Start simple: Try
simple_random_walk.pyfirst - Use C++ engine: Build it for major speedup
- Check examples: 18+ working examples to learn from
- Web UI: Great for visualization and debugging
- Read docs: Each component has detailed documentation
Happy Simulating! 🚀
For more information, see: