Metadata-Version: 2.4
Name: jamfree
Version: 0.1.0
Summary: Traffic simulation library with microscopic models
Author: Gildas Morvan
Author-email: gildas.morvan@univ-artois.fr
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: License :: OSI Approved :: CeCILL-B Free Software License Agreement (CECILL-B)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: C++
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: pybind11>=2.6.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# JamFree C++ Implementation

## 🚗 Overview

JamFree is a traffic simulation framework built on SIMILAR, now being implemented in C++ for high performance.

## 📦 Current Status

### ✅ Implemented

#### Kernel - Tools
- **GeometryTools** (`kernel/include/tools/GeometryTools.h`)
  - Distance calculations
  - Angle computations
  - Point-to-segment projections
  - Geometric utilities

- **MathTools** (`kernel/include/tools/MathTools.h`)
  - Clamping and interpolation
  - Unit conversions (km/h ↔ m/s)
  - Safe division
  - Floating-point comparisons

#### Kernel - Model
- **Point2D** (`kernel/include/model/Point2D.h`)
  - 2D coordinates and vectors
  - Distance and angle calculations
  - Vector operations (add, subtract, multiply)
  - Normalization and dot product

### 🚧 In Progress

#### Kernel - Model (Next)
- **Lane** - Lane representation within roads
- **Road** - Road segment with geometry
- **Vehicle** - Vehicle entity and state
- **Network** - Road network graph

#### Microscopic Models (Planned)
- **IDM** - Intelligent Driver Model (car-following)
- **MOBIL** - Lane-changing model
- **VehicleController** - Decision making

## 🏗️ Directory Structure

```
cpp/jamfree/
├── kernel/
│   ├── include/
│   │   ├── model/
│   │   │   └── Point2D.h ✅
│   │   ├── tools/
│   │   │   ├── GeometryTools.h ✅
│   │   │   └── MathTools.h ✅
│   │   └── initializations/
│   └── src/
│       ├── model/
│       ├── tools/
│       └── initializations/
├── microscopic/
│   ├── include/
│   └── src/
├── macroscopic/
│   ├── include/
│   └── src/
├── realdata/
│   ├── include/
│   └── src/
├── supervision/
│   ├── include/
│   └── src/
└── python/
    └── bindings.cpp (planned)
```

## 🎯 Design Principles

### 1. **Performance First**
- Header-only utilities for inlining
- Efficient data structures
- Minimal allocations

### 2. **Clean API**
- Intuitive class names
- Consistent naming conventions
- Well-documented interfaces

### 3. **Python Integration**
- All classes will have Python bindings
- Pythonic API design
- NumPy compatibility where appropriate

### 4. **Traffic Simulation Standards**
- SI units (meters, m/s, m/s²)
- Standard traffic models (IDM, MOBIL, LWR)
- Compatible with SUMO, MATSim conventions

## 📐 Coordinate System

- **Distance**: Meters (m)
- **Speed**: Meters per second (m/s)
- **Acceleration**: Meters per second squared (m/s²)
- **Time**: Seconds (s)
- **Angles**: Radians (rad)

## 🔧 Usage Examples

### C++ Usage

```cpp
#include "jamfree/kernel/model/Point2D.h"
#include "jamfree/kernel/tools/GeometryTools.h"
#include "jamfree/kernel/tools/MathTools.h"

using namespace jamfree::kernel;

// Create points
model::Point2D start(0, 0);
model::Point2D end(100, 0);

// Calculate distance
double dist = start.distanceTo(end);  // 100.0 meters

// Calculate angle
double angle = start.angleTo(end);  // 0.0 radians (east)

// Convert speed
double speed_ms = tools::MathTools::kmhToMs(120);  // 33.33 m/s

// Geometric calculations
double perp_dist = tools::GeometryTools::distanceToSegment(
    50, 10,  // Point
    0, 0, 100, 0  // Line segment
);  // 10.0 meters
```

### Python Usage (Planned)

```python
from jamfree import *

# Create network
network = Network()
road = Road(
    start=Point2D(0, 0),
    end=Point2D(1000, 0),
    lanes=3,
    speed_limit=33.3  # m/s (120 km/h)
)
network.add_road(road)

# Create vehicle with IDM model
vehicle = Vehicle(
    position=Point2D(100, 0),
    lane=0,
    speed=30.0,
    model=IDMModel(
        desired_speed=33.3,
        time_headway=1.5,
        min_gap=2.0
    )
)
network.add_vehicle(vehicle)

# Run simulation
sim = Simulation(network, dt=0.1)
sim.run(steps=1000)

# Access results
print(f"Final position: {vehicle.position}")
print(f"Final speed: {vehicle.speed} m/s")
```

## 🎓 Traffic Simulation Concepts

### Microscopic Simulation
Simulates individual vehicles with:
- **Car-following**: How vehicles follow the one ahead
- **Lane-changing**: When and how to change lanes
- **Driver behavior**: Reaction times, aggressiveness

### Key Models

#### IDM (Intelligent Driver Model)
Most widely used car-following model:
```
a = a_max * [1 - (v/v₀)⁴ - (s*/s)²]
s* = s₀ + v*T + v*Δv / (2√(a*b))
```
Where:
- `a` = acceleration
- `v` = current speed
- `v₀` = desired speed
- `s` = gap to leader
- `T` = desired time headway

#### MOBIL (Lane Changing)
Minimizing Overall Braking Induced by Lane changes:
- Incentive criterion (is it worth it?)
- Safety criterion (is it safe?)
- Politeness factor (consider others)

## 📚 References

### Academic
- Treiber & Kesting (2013) - "Traffic Flow Dynamics"
- Kesting et al. (2007) - "General Lane-Changing Model MOBIL"
- Nagel & Schreckenberg (1992) - "Cellular Automaton Model"

### Software
- SUMO - Simulation of Urban MObility
- MATSim - Multi-Agent Transport Simulation
- VISSIM - Commercial traffic simulator

## 🚀 Next Steps

1. **Complete Kernel Models**:
   - Implement Lane class
   - Implement Road class
   - Implement Vehicle class
   - Implement Network class

2. **Microscopic Models**:
   - Implement IDM car-following
   - Implement MOBIL lane-changing
   - Implement vehicle dynamics

3. **Python Bindings**:
   - Create pybind11 bindings
   - Develop Python DSL
   - Write examples

4. **Testing**:
   - Unit tests for all classes
   - Integration tests
   - Validation against known results

5. **Documentation**:
   - API documentation
   - User guide
   - Tutorial examples

## 📝 Contributing

When adding new components:
1. Follow existing naming conventions
2. Add comprehensive documentation
3. Include unit tests
4. Update this README

## 📄 License

Follows the SIMILAR project license (CeCILL-B).

---

**Status**: Foundation phase - Core utilities implemented ✅
**Next**: Implement Lane, Road, Vehicle, Network classes
**Goal**: Complete microscopic simulation framework with Python bindings
