similar2logo 1.0.0

Python bindings for SIMILAR2Logo multi-agent simulation framework

SIMILAR & JamFree: High-Performance Agent-Based Simulation Framework

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.

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/gildasmorvan/similar
cd similar

# Build C++ engine (recommended for 10-100x performance boost)
./build_cpp_engine.sh

# Install Python dependencies
pip install -r requirements.txt

📖 New to SIMILAR? See Getting Started Guide for a complete walkthrough!

⚡ Quick Commands? Check Quick Reference for a command cheat sheet!

Your First Simulation (SIMILAR2Logo)

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:8080

Your First Traffic Simulation (JamFree)

cd cpp/jamfree

# Build JamFree
./build.sh

# Run web interface
./run_web_ui.sh
# Open http://localhost:5001

📚 What's Included

SIMILAR2Logo - Agent-Based Modeling

A 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!

JamFree - Traffic Simulation

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

🎯 Key Features

Performance

• 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

Flexibility

• 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

Usability

• Clean DSL: Intuitive Python API
• Web Visualization: No GUI installation needed
• Rich Examples: 18+ SIMILAR2Logo + traffic examples
• Documentation: Comprehensive guides and tutorials

📖 Documentation

📚 Complete Documentation Index - Find any document quickly!

SIMILAR2Logo

• Quick Start Guide - Get started in 5 minutes
• Examples README - All 18 examples explained
• DSL Reference - API documentation
• Implementation Status - What's implemented

JamFree

• 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

🎨 Examples

SIMILAR2Logo Examples

All located in examples/python/:

Basic

• simple_random_walk.py - Basic movement
• circle.py - Formation patterns
• passive_turtle.py - Physics simulation

Flocking & Collective

• boids_dsl.py - Classic flocking behavior
• boids_obstacles.py - Flocking with obstacle avoidance
• ant_foraging_dsl.py - Pheromone-based foraging

Biological

• virus_spread.py - Epidemiology (SIR model)
• predator_prey.py - Lotka-Volterra dynamics
• heatbugs.py - Temperature-seeking agents

Social & Urban

• segregation_model.py - Schelling's model
• transport.py - Traffic simulation

Patterns & Emergence

• turmite.py - Langton's Ant
• multiturmite.py - Multiple ants
• forest_fire.py - Cellular automaton

And more! See examples/python/README.md for the complete list.

JamFree Examples

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

🏃 Running Examples

SIMILAR2Logo

# 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.py

JamFree

cd 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

🔧 Building from Source

SIMILAR2Logo C++ Engine

# Build C++ engine
./build_cpp_engine.sh

# Verify it works
SIMILAR_VERBOSE=1 python3 examples/python/boids_dsl.py
# Should see: ✓ Using C++ reaction engine

JamFree

cd cpp/jamfree

# Build core library
./build.sh

# Build with Python bindings
./build_python.sh

# Build with GPU support (macOS only)
./build_metal.sh

🌐 Web Interfaces

SIMILAR2Logo Web UI

Most examples include a built-in web interface:

# In your simulation
sim.run_web(port=8080, steps_per_frame=1)

Then open http://localhost:8080

JamFree Web UI

Full-featured traffic simulation interface:

cd cpp/jamfree
./run_web_ui.sh

Features:

• 🗺️ Load OSM maps (upload or download)
• 🚗 Configure vehicles and parameters
• ⚡ Enable/disable optimizations
• 📊 Real-time performance metrics
• 🎨 Lane mode visualization (micro/macro)

📊 Performance

SIMILAR2Logo

With C++ engine enabled:

• 10-100x faster than pure Python
• Handles 1000+ agents in real-time
• Efficient spatial indexing
• Optimized influence resolution

JamFree

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

🔬 Research & Education

Perfect for:

• Agent-Based Modeling courses
• Complex Systems research
• Traffic Engineering studies
• Artificial Life experiments
• Swarm Intelligence research
• Computational Biology teaching

🤝 Contributing

We welcome contributions! To contribute:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests and documentation
5. Submit a pull request

See individual component READMEs for specific guidelines.

📄 License

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.

👥 Authors

• Gildas Morvan - Original SIMILAR framework
• Contributors - See AUTHORS.txt

🔗 Resources

Documentation

• SIMILAR2Logo Quick Start
• JamFree Documentation
• Examples Collection

Academic References

• Traffic Flow Dynamics - Treiber & Kesting (2013)
• MOBIL Model - Kesting et al. (2007)
• Agent-Based Modeling - Wilensky & Rand (2015)

Related Projects

• SUMO - Traffic simulation
• MATSim - Multi-agent transport
• NetLogo - Agent-based modeling

🎯 Project Structure

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

🚦 Status

SIMILAR2Logo

✅ Complete - All Java examples ported to Python DSL with C++ engine

JamFree

✅ 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

🎉 Getting Help

• Issues: GitHub Issues
• Examples: Check examples/python/ for working code
• Documentation: See individual README files
• Verbose Mode: Use SIMILAR_VERBOSE=1 to see what's happening

💡 Tips

• Start simple: Try simple_random_walk.py first
• 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:

• SIMILAR2Logo Quick Start
• JamFree Quick Start
• Examples Guide