Name | TraffiSim JSON |
Version |
0.1.1
JSON |
| download |
home_page | None |
Summary | A modular intersection traffic simulator with IDM, MOBIL, and adaptive signals |
upload_time | 2025-02-22 17:03:19 |
maintainer | None |
docs_url | None |
author | A. Sharan |
requires_python | >=3.7 |
license | None |
keywords |
|
VCS |
|
bugtrack_url |
|
requirements |
No requirements were recorded.
|
Travis-CI |
No Travis.
|
coveralls test coverage |
No coveralls.
|
# TraffiSim
TraffiSim is a Python-based intersection traffic simulator designed to capture various driving behaviors (including Indian driving styles and multi-lane configurations) that might not be fully addressed by large-scale simulators like SUMO. It uses the Intelligent Driver Model (IDM) for longitudinal control, MOBIL for lane changes, and supports both adaptive and fixed traffic signal strategies.
## Table of Contents
- [Why TraffiSim?](#why-traffisim)
- [Features](#features)
- [Technical Overview](#technical-overview)
- [Installation](#installation)
- [Usage](#usage)
- [Using in Python Scripts](#using-in-python-scripts)
- [Simulation Parameters](#simulation-parameters)
- [Customization](#customization)
- [Comparison to Other Tools (SUMO, etc.)](#comparison-to-other-tools-sumo-etc)
- [Limitations & Future Work](#limitations--future-work)
- [Contributing](#contributing)
- [License](#license)
## Why TraffiSim?
While powerful traffic simulators exist—such as SUMO, MATSim, and Aimsun—they are often complex to install, configure, and extend. In addition, many of these simulators do not provide country-specific behaviors (e.g., Indian driving styles with freer lateral movement, two-wheelers navigating queues side-by-side, etc.) out of the box.
TraffiSim was created to address these needs:
### India-Specific Queueing & Lateral Movement
- Incorporates concepts like India Mode for simulating two-wheelers and small vehicles weaving side-by-side in queues.
### Lightweight & Extensible
- Focuses on intersection-level simulation, making it easy to add new driving rules or tweak existing ones.
### Educational & Rapid Prototyping
- A simpler codebase suitable for teaching traffic engineering or quickly prototyping new signal control strategies.
## Features
- **Multiple Vehicle Types:** Cars, scooters, motorcycles, trucks, buses (with configurable parameters).
- **IDM & MOBIL:** Intelligent Driver Model for speed control, and MOBIL for lane-change decisions.
- **Adaptive or Fixed Signals:** Choose between a simple queue-based adaptive or a time-based fixed cycle strategy.
- **Multi-Lane Support:** Allows 1 to N lanes in each direction.
- **“India Mode”:** Enables side-by-side queueing for two-wheelers and small vehicles.
- **Optionally Simulate Full Routes:** Vehicles can vanish at the intersection center or continue to an exit point.
- **Pygame Visualization:** Observe your simulation in real-time or disable it for headless runs.
- **Data Collection:** Logs queue length, arrival rates, wait times, and more in CSV format for analysis.
## Technical Overview
TraffiSim’s code is organized into several Python modules:
**intersection.py**:
- Core logic for arrivals, queues, traffic lights, adaptive/fixed signal control, and data recording.
- Main class: `IntersectionSim`.
**models.py**:
- Vehicle-level logic, including IDM for longitudinal control, MOBIL for lane changing.
- Holds default parameters in `DEFAULT_VEHICLE_TYPES`.
**rendering.py**:
- Uses Pygame for drawing roads, vehicles, signals, and queue lines if `show_visuals=True`.
- Entirely optional (the simulator can run without visualization).
**run.py**:
- High-level function `run_multiple_simulations` that can be called multiple times with varying parameters.
- A minimal `main_cli()` function for a command-line interface.
**utils.py**:
- Simple helper functions for geometry (e.g., distance calculations) and exit point definitions.
The Intelligent Driver Model (IDM) controls acceleration based on the gap to the lead vehicle, desired speeds, and comfortable deceleration. MOBIL checks whether lane changes are beneficial and safe based on accelerations for the subject vehicle and adjacent vehicles.
## Installation
### A) From Source (Local Development)
Clone the repository:
```bash
git clone https://github.com/AHSharan/TraffiSim.git
cd TraffiSim
```
Install with pip:
```bash
pip install .
```
To include Pygame automatically, install the optional `[rendering]` extras:
```bash
pip install .[rendering]
```
### B) Installing from PyPI
You can install TraffiSim directly from the Python Package Index (PyPI):
```bash
pip install TraffiSim
```
If you want to include Pygame (used for visualization) right away, install the `[rendering]` extra:
```bash
pip install TraffiSim[rendering]
```
Note: If you only need to run headless simulations (no graphics), you don’t need the extra.
Once installed, verify by running:
```bash
traffisim-run
```
This will execute a default simulation with minimal parameters.
You can then use TraffiSim in your own Python scripts:
```python
from traffisim.run import run_multiple_simulations
run_multiple_simulations(
N_runs=1,
total_time=300,
multiple_lanes=True,
lane_count=3,
show_visuals=True, # True requires pygame
adaptive_signals=True,
)
```
## Usage
### Using in Python Scripts
You can run simulations programmatically:
```python
from traffisim.run import run_multiple_simulations
run_multiple_simulations(
N_runs=1,
junction_type="4way",
total_time=600,
show_visuals=True,
multiple_lanes=True,
lane_count=3,
adaptive_signals=True,
india_mode=True,
save_to_files=False
)
```
Or instantiate `IntersectionSim` directly:
```python
from traffisim.intersection import IntersectionSim
from traffisim.rendering import TrafficRenderer
sim = IntersectionSim(
junction_type="4way",
multiple_lanes=True,
lane_count=2,
total_time=300,
show_visuals=True,
renderer_class=TrafficRenderer,
india_mode=False,
adaptive_signals=True
)
sim.run()
```
## Simulation Parameters
Commonly adjusted parameters:
| Parameter | Default | Description |
|-----------------------|------------|-----------------------------------------------------------------------------|
| `junction_type` | "4way" | Intersection type: "4way" or "3way". |
| `multiple_lights` | False | Use a single traffic light vs. per-approach lights. |
| `total_time` | 300 | Number of simulation steps. |
| `sim_steps_per_sec` | 10 | Internal sub-step resolution (10 or 1). |
| `simulation_speed` | 30 | Frame rate in Pygame visualization. |
| `multiple_lanes` | False | Whether each approach has multiple lanes. |
| `lane_count` | 2 | Number of lanes per approach if multiple lanes are enabled. |
| `india_mode` | False | Allow side-by-side queue for two-wheelers or small vehicles. |
| `adaptive_signals` | True | Use a simple adaptive signal logic vs. fixed-cycle approach. |
| `simulate_full_route` | True | Vehicles continue from entry to exit points; if False, they vanish center. |
| `vehicle_distribution`| dict | Probability distribution for vehicle types (car, scooter, etc.). |
| `save_to_files` | True | Save simulation data to CSV. |
| `output_folder` | "simulation_outputs" | Directory for saving CSV outputs. |
## Customization
**New Vehicle Types**
Add entries in `DEFAULT_VEHICLE_TYPES` in `models.py` with parameters like `desired_speed`, `max_acceleration`, etc.
**Signal Logic**
Default adaptive logic chooses phases based on queue length. Edit `choose_new_green()` in `intersection.py`.
**Queue Behaviors (India Mode)**
For complex lateral movement, modify `reposition_queue()` in `intersection.py`.
**Saving & Analyzing Data**
Per-step data in `sim.per_timestep_data`; summary in `sim.get_results_dict()`. Customize columns or CSV writing in `run.py`.
## Comparison to Other Tools (SUMO, etc.)
**SUMO:**
- Large-scale, open-source traffic simulator.
- TraffiSim focuses on intersection-level details like 2D positioning for Indian driving patterns.
**MATSim / Aimsun:**
- Large or commercial simulators for multi-agent, city-scale traffic.
- TraffiSim is simpler and specialized for intersection-based experiments.
## Limitations & Future Work
- **Geometry:** Physical turn radii or collisions not deeply simulated.
- **No Traffic Signal Optimization:** Basic queue-based adaptive approach.
- **Single Intersection Focus:** Multi-intersection networks need extensions.
- **Performance:** High vehicle counts may impact performance.
## Contributing
Ideas for contribution include:
- Machine learning or optimization for signals
- More realistic India Mode dynamics
- Network-level expansions
- Additional vehicle classes (auto-rickshaws, e-bikes)
Submit pull requests or open issues on GitHub.
## License
TraffiSim is under the GNU License.
Feel free to use, modify, and distribute with attribution.
Raw data
{
"_id": null,
"home_page": null,
"name": "TraffiSim",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": null,
"author": "A. Sharan",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/17/fc/84979839efcedb90aac41566d7d9235cb7f8de49fe8fa6cecc1fb24c8628/traffisim-0.1.1.tar.gz",
"platform": null,
"description": "# TraffiSim\r\nTraffiSim is a Python-based intersection traffic simulator designed to capture various driving behaviors (including Indian driving styles and multi-lane configurations) that might not be fully addressed by large-scale simulators like SUMO. It uses the Intelligent Driver Model (IDM) for longitudinal control, MOBIL for lane changes, and supports both adaptive and fixed traffic signal strategies.\r\n\r\n## Table of Contents\r\n- [Why TraffiSim?](#why-traffisim)\r\n- [Features](#features)\r\n- [Technical Overview](#technical-overview)\r\n- [Installation](#installation)\r\n- [Usage](#usage)\r\n - [Using in Python Scripts](#using-in-python-scripts)\r\n- [Simulation Parameters](#simulation-parameters)\r\n- [Customization](#customization)\r\n- [Comparison to Other Tools (SUMO, etc.)](#comparison-to-other-tools-sumo-etc)\r\n- [Limitations & Future Work](#limitations--future-work)\r\n- [Contributing](#contributing)\r\n- [License](#license)\r\n\r\n## Why TraffiSim?\r\n\r\nWhile powerful traffic simulators exist\u2014such as SUMO, MATSim, and Aimsun\u2014they are often complex to install, configure, and extend. In addition, many of these simulators do not provide country-specific behaviors (e.g., Indian driving styles with freer lateral movement, two-wheelers navigating queues side-by-side, etc.) out of the box.\r\n\r\nTraffiSim was created to address these needs:\r\n\r\n### India-Specific Queueing & Lateral Movement\r\n- Incorporates concepts like India Mode for simulating two-wheelers and small vehicles weaving side-by-side in queues.\r\n\r\n### Lightweight & Extensible\r\n- Focuses on intersection-level simulation, making it easy to add new driving rules or tweak existing ones.\r\n\r\n### Educational & Rapid Prototyping\r\n- A simpler codebase suitable for teaching traffic engineering or quickly prototyping new signal control strategies.\r\n\r\n## Features\r\n- **Multiple Vehicle Types:** Cars, scooters, motorcycles, trucks, buses (with configurable parameters).\r\n- **IDM & MOBIL:** Intelligent Driver Model for speed control, and MOBIL for lane-change decisions.\r\n- **Adaptive or Fixed Signals:** Choose between a simple queue-based adaptive or a time-based fixed cycle strategy.\r\n- **Multi-Lane Support:** Allows 1 to N lanes in each direction.\r\n- **\u201cIndia Mode\u201d:** Enables side-by-side queueing for two-wheelers and small vehicles.\r\n- **Optionally Simulate Full Routes:** Vehicles can vanish at the intersection center or continue to an exit point.\r\n- **Pygame Visualization:** Observe your simulation in real-time or disable it for headless runs.\r\n- **Data Collection:** Logs queue length, arrival rates, wait times, and more in CSV format for analysis.\r\n## Technical Overview\r\nTraffiSim\u2019s code is organized into several Python modules:\r\n\r\n**intersection.py**: \r\n- Core logic for arrivals, queues, traffic lights, adaptive/fixed signal control, and data recording. \r\n- Main class: `IntersectionSim`.\r\n\r\n**models.py**: \r\n- Vehicle-level logic, including IDM for longitudinal control, MOBIL for lane changing. \r\n- Holds default parameters in `DEFAULT_VEHICLE_TYPES`.\r\n\r\n**rendering.py**: \r\n- Uses Pygame for drawing roads, vehicles, signals, and queue lines if `show_visuals=True`. \r\n- Entirely optional (the simulator can run without visualization).\r\n\r\n**run.py**: \r\n- High-level function `run_multiple_simulations` that can be called multiple times with varying parameters. \r\n- A minimal `main_cli()` function for a command-line interface.\r\n\r\n**utils.py**: \r\n- Simple helper functions for geometry (e.g., distance calculations) and exit point definitions.\r\n\r\nThe Intelligent Driver Model (IDM) controls acceleration based on the gap to the lead vehicle, desired speeds, and comfortable deceleration. MOBIL checks whether lane changes are beneficial and safe based on accelerations for the subject vehicle and adjacent vehicles.\r\n\r\n## Installation\r\n### A) From Source (Local Development)\r\n\r\nClone the repository:\r\n```bash\r\ngit clone https://github.com/AHSharan/TraffiSim.git\r\ncd TraffiSim\r\n```\r\nInstall with pip:\r\n```bash\r\npip install .\r\n```\r\nTo include Pygame automatically, install the optional `[rendering]` extras:\r\n```bash\r\npip install .[rendering]\r\n```\r\n\r\n### B) Installing from PyPI\r\nYou can install TraffiSim directly from the Python Package Index (PyPI):\r\n```bash\r\npip install TraffiSim\r\n```\r\nIf you want to include Pygame (used for visualization) right away, install the `[rendering]` extra:\r\n```bash\r\npip install TraffiSim[rendering]\r\n```\r\nNote: If you only need to run headless simulations (no graphics), you don\u2019t need the extra.\r\n\r\nOnce installed, verify by running:\r\n```bash\r\ntraffisim-run\r\n```\r\nThis will execute a default simulation with minimal parameters.\r\n\r\nYou can then use TraffiSim in your own Python scripts:\r\n```python\r\nfrom traffisim.run import run_multiple_simulations\r\n\r\nrun_multiple_simulations(\r\n N_runs=1,\r\n total_time=300,\r\n multiple_lanes=True,\r\n lane_count=3,\r\n show_visuals=True, # True requires pygame\r\n adaptive_signals=True,\r\n)\r\n```\r\n\r\n## Usage\r\n### Using in Python Scripts\r\nYou can run simulations programmatically:\r\n```python\r\nfrom traffisim.run import run_multiple_simulations\r\n\r\nrun_multiple_simulations(\r\n N_runs=1,\r\n junction_type=\"4way\",\r\n total_time=600,\r\n show_visuals=True,\r\n multiple_lanes=True,\r\n lane_count=3,\r\n adaptive_signals=True,\r\n india_mode=True,\r\n save_to_files=False\r\n)\r\n```\r\nOr instantiate `IntersectionSim` directly:\r\n```python\r\nfrom traffisim.intersection import IntersectionSim\r\nfrom traffisim.rendering import TrafficRenderer\r\n\r\nsim = IntersectionSim(\r\n junction_type=\"4way\",\r\n multiple_lanes=True,\r\n lane_count=2,\r\n total_time=300,\r\n show_visuals=True,\r\n renderer_class=TrafficRenderer,\r\n india_mode=False,\r\n adaptive_signals=True\r\n)\r\nsim.run()\r\n```\r\n\r\n## Simulation Parameters\r\nCommonly adjusted parameters:\r\n\r\n| Parameter | Default | Description |\r\n|-----------------------|------------|-----------------------------------------------------------------------------|\r\n| `junction_type` | \"4way\" | Intersection type: \"4way\" or \"3way\". |\r\n| `multiple_lights` | False | Use a single traffic light vs. per-approach lights. |\r\n| `total_time` | 300 | Number of simulation steps. |\r\n| `sim_steps_per_sec` | 10 | Internal sub-step resolution (10 or 1). |\r\n| `simulation_speed` | 30 | Frame rate in Pygame visualization. |\r\n| `multiple_lanes` | False | Whether each approach has multiple lanes. |\r\n| `lane_count` | 2 | Number of lanes per approach if multiple lanes are enabled. |\r\n| `india_mode` | False | Allow side-by-side queue for two-wheelers or small vehicles. |\r\n| `adaptive_signals` | True | Use a simple adaptive signal logic vs. fixed-cycle approach. |\r\n| `simulate_full_route` | True | Vehicles continue from entry to exit points; if False, they vanish center. |\r\n| `vehicle_distribution`| dict | Probability distribution for vehicle types (car, scooter, etc.). |\r\n| `save_to_files` | True | Save simulation data to CSV. |\r\n| `output_folder` | \"simulation_outputs\" | Directory for saving CSV outputs. |\r\n\r\n## Customization\r\n**New Vehicle Types** \r\nAdd entries in `DEFAULT_VEHICLE_TYPES` in `models.py` with parameters like `desired_speed`, `max_acceleration`, etc.\r\n\r\n**Signal Logic** \r\nDefault adaptive logic chooses phases based on queue length. Edit `choose_new_green()` in `intersection.py`.\r\n\r\n**Queue Behaviors (India Mode)** \r\nFor complex lateral movement, modify `reposition_queue()` in `intersection.py`.\r\n\r\n**Saving & Analyzing Data** \r\nPer-step data in `sim.per_timestep_data`; summary in `sim.get_results_dict()`. Customize columns or CSV writing in `run.py`.\r\n\r\n## Comparison to Other Tools (SUMO, etc.)\r\n**SUMO:** \r\n- Large-scale, open-source traffic simulator. \r\n- TraffiSim focuses on intersection-level details like 2D positioning for Indian driving patterns.\r\n\r\n**MATSim / Aimsun:** \r\n- Large or commercial simulators for multi-agent, city-scale traffic. \r\n- TraffiSim is simpler and specialized for intersection-based experiments.\r\n\r\n## Limitations & Future Work\r\n- **Geometry:** Physical turn radii or collisions not deeply simulated. \r\n- **No Traffic Signal Optimization:** Basic queue-based adaptive approach. \r\n- **Single Intersection Focus:** Multi-intersection networks need extensions. \r\n- **Performance:** High vehicle counts may impact performance.\r\n\r\n## Contributing\r\nIdeas for contribution include:\r\n- Machine learning or optimization for signals \r\n- More realistic India Mode dynamics \r\n- Network-level expansions \r\n- Additional vehicle classes (auto-rickshaws, e-bikes)\r\n\r\nSubmit pull requests or open issues on GitHub.\r\n\r\n## License\r\nTraffiSim is under the GNU License. \r\nFeel free to use, modify, and distribute with attribution.\r\n\r\n\r\n\r\n\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A modular intersection traffic simulator with IDM, MOBIL, and adaptive signals",
"version": "0.1.1",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "92622bafd04f5e23b2a7f08af1901d79e527e550c36a04e07defd8b4274ba7f4",
"md5": "c375138bd2d8bc8e7c46cf9cc8bdef5a",
"sha256": "87eb1efd1cd1bea127bdc1af12262c49b71a8d3397d185f64b7623bed5772d27"
},
"downloads": -1,
"filename": "TraffiSim-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c375138bd2d8bc8e7c46cf9cc8bdef5a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 32787,
"upload_time": "2025-02-22T17:03:17",
"upload_time_iso_8601": "2025-02-22T17:03:17.388087Z",
"url": "https://files.pythonhosted.org/packages/92/62/2bafd04f5e23b2a7f08af1901d79e527e550c36a04e07defd8b4274ba7f4/TraffiSim-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "17fc84979839efcedb90aac41566d7d9235cb7f8de49fe8fa6cecc1fb24c8628",
"md5": "76e94f0ec9eff66c40f777cdd319a918",
"sha256": "cbdbddc243e0d62f88604be450bfc632cd7da9e7fa00b806e520d2e16f4b2b27"
},
"downloads": -1,
"filename": "traffisim-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "76e94f0ec9eff66c40f777cdd319a918",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 31084,
"upload_time": "2025-02-22T17:03:19",
"upload_time_iso_8601": "2025-02-22T17:03:19.542220Z",
"url": "https://files.pythonhosted.org/packages/17/fc/84979839efcedb90aac41566d7d9235cb7f8de49fe8fa6cecc1fb24c8628/traffisim-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-22 17:03:19",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "traffisim"
}