iscpp-simulator 0.1.0__tar.gz

iscpp_simulator-0.1.0/CITATION.cff

@@ -0,0 +1,10 @@
+cff-version: 1.2.0
+message: "If you use this simulator in academic work, please cite it using this metadata."
+title: "Intermittent Cooperation Multiagent Path Planning Simulation"
+authors:
+  - family-names: "Shedlezki"
+    given-names: "Itay"
+  - family-names: "Agmon"
+    given-names: "Noa"
+year: 2026
+license: "MIT"

iscpp_simulator-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Itay Shedlezki and Noa Agmon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

iscpp_simulator-0.1.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include LICENSE
+include CITATION.cff
+recursive-include src/iscpp_simulator/data/graphs *.edges *.gephi *.gexf *.gml *.graphml *.map *.mtx
+prune graphs/scen-even
+prune graphs/scen-random
+global-exclude __pycache__ *.py[cod] .DS_Store

iscpp_simulator-0.1.0/PKG-INFO

@@ -0,0 +1,394 @@
+Metadata-Version: 2.4
+Name: iscpp-simulator
+Version: 0.1.0
+Summary: Intermittent Strategic Cooperation path planning simulator
+Author: Itay Shedlezki, Noa Agmon
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/shedlezki/ISCPP-Simulator
+Project-URL: Repository, https://github.com/shedlezki/ISCPP-Simulator
+Keywords: multi-agent path finding,path planning,simulation,cooperation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: networkx>=2.6
+Requires-Dist: matplotlib>=3.5.0
+Requires-Dist: numpy>=1.21.0
+Dynamic: license-file
+
+# Intermittent Cooperation Multiagent Path Planning Simulation
+
+This repository contains the implementation of a simulator for the **Intermittent Cooperation Path Planning (ICPP)** problem in multi-agent systems, enabling evaluation of path planning strategies where agents can benefit from selective cooperation to reduce task completion times.
+
+## 🎯 Problem Overview
+
+In the Intermittent Cooperation Path Planning problem, agents must navigate from their starting positions to their respective goal positions in a graph-based environment. Certain nodes provide **cooperative opportunities** where agents can work together to reduce traversal time.
+
+### Key Concepts
+
+- **Individual Travel Time (τ₁)**: Time to traverse a node alone
+- **Cooperative Travel Time (τ₂)**: Reduced time to traverse a node when cooperating with another agent
+- **Cooperation Nodes**: Specially marked nodes where agents benefit from cooperation
+- **Path Planning**: Finding optimal routes that leverage cooperation strategically
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Python 3.9+
+- Required packages are installed automatically when installing the package.
+
+### Installation
+
+```bash
+pip install iscpp-simulator
+```
+
+For local development from a clone:
+
+```bash
+pip install -e .
+```
+
+### Running the Simulator
+
+#### Basic Usage
+
+The project includes a simple `main.py` entry point that demonstrates the basic workflow. It finds the Shortest Independent Path (SIP) and Shortest Cooperation Path (SCP) for both agents, then uses the simulator to evaluate and visualize the resulting plans.
+
+```bash
+# Run with default parameters (empty 8x8 map)
+iscpp-simulator
+
+# Specify a simple map from the bundled benchmark maps
+iscpp-simulator -m "empty-16-16" -d 0.5 -mt 10
+
+# Use a random simple map
+iscpp-simulator --size small
+```
+
+#### Command-Line Arguments
+
+| Argument | Short | Type | Required | Default | Description |
+|----------|-------|------|----------|---------|-------------|
+| `--map` | `-m` | str | No | `empty-8-8` | Map name/path from the [MAPF benchmark provider](MAPF_BENCHMARK_PROVIDER.md) |
+| `--scenario` | `-s` | str | No | - | Scenario file with agent start/goal positions (if not prvoided - starting and target nodes are auto-generated using extent and seperation parameters) |
+| `--density` | `-d` | float | No | 0.5 | Ratio of cooperation nodes to all graph nodes (0.0-1.0) |
+| `--magnitude` | `-mt` | int | No | 10 | Multiplication factor between non-cooperative and cooperative travel time at cooperation nodes |
+| `--extent` | `-e` | int | No | 5 | Manhattan distance between each agent's start node and target node |
+| `--seperation` | `-se` | int | No | 4 | Manhattan distance between the two agents' start nodes and between their target nodes |
+| `--size` | `-si` | str | No | - | Random map size: `small`, `medium`, or `large` |
+| `--data-dir` | - | str | No | - | External `graphs/` or `mapf-map/` directory to use instead of bundled maps |
+| `--scenario-dir` | - | str | No | - | External directory containing `.scen` files |
+
+### Example Commands
+
+```bash
+# Default empty map simulation
+iscpp-simulator
+
+# Simple maze map with custom cooperation parameters
+iscpp-simulator -m "maze-32-32-2" -d 0.6 -mt 15 -e 7
+
+# Use external scenario files from a local checkout or downloaded benchmark set
+iscpp-simulator --scenario-dir graphs/scen-even --size small -s "even-1" -d 0.5
+```
+
+## 🖥️ GUI Usage
+
+The repository includes a GUI that can be used to see an interactive visualization of paths.
+
+### GUI Controls
+
+1. **Map Visualization**: The central graph display showing:
+   - Regular nodes (light gray)
+   - Cooperation nodes (darker gray)
+   - Edges connecting nodes
+   - Agents as colored circles (Agent 1: pink, Agent 2: cyan)
+
+2. **Path Selection**: 
+   - **Checkboxes** display different path options with their costs
+   - Format: `path <name> (cost_agent1, cost_agent2)`
+   - Click checkbox to highlight the path
+
+3. **Animation Controls**:
+   - **Play Button**: Animates agents following selected path
+   - Shows real-time agent movement and cooperation events
+   - Status updates show what each agent is doing
+
+4. **Metadata**:
+   - Top display shows simulation parameters (map, density, magnitude, etc.)
+   - **EID** (Experiment ID) can be copied to clipboard by clicking
+
+### Understanding the Animation
+
+The animation displays the agents’ states at each time step, accompanied by commentary describing the current state:
+
+- **"executes task at node X alone"**: Agent working independently
+- **"cooperates with Agent Y at node X"**: Two agents cooperating
+- **"waits for Agent Y at node X"**: Agent waiting for other agent to arrive
+- **"travels from X to Y"**: Agent moving along edge
+- **"reached target"**: Agent successfully completed journey
+
+## 📊 Path Simulation
+The simulator evaluates and visualizes path pairs supplied by the caller.
+The `main.py` demonstration supplies two example path pairs:
+
+- Shortest Independent Paths (SIP)
+- Shortest Cooperation Paths (SCP)
+
+## 🏗️ Project Architecture
+
+### Core Components
+
+#### `simulation.py` (Core Module)
+- **Path Evaluation**: Evaluates discrete paths on graphs with node execution times (τ₁ for independent execution, τ₂ for cooperative execution)
+- **Path Interpolation**: Converts abstract paths to time-indexed state sequences for event tracking
+- **Visualization Engine**: Renders graph topology, node states, and agent positions
+- `GraphVisualizer` class: Primary interface for visualization
+
+#### `gui.py` (User Interface)
+- Tkinter-based interactive interface for accessing simulator functionality
+- Path selection and visualization controls
+- Animation playback for step-by-step analysis
+- Experiment metadata display and tracking
+
+#### `mapfBenchmarkProvider.py` (Data Interface)
+- Loads MAPF (Multi-Agent Path Finding) benchmark maps
+- Converts map files to graph representations
+- Generates cooperation node distributions based on specified parameters
+- See the [MAPF benchmark provider](MAPF_BENCHMARK_PROVIDER.md) page for more details
+
+#### `main.py` (Demonstration)
+- Example usage of the simulator
+- Command-line interface for common scenarios
+- Handles argument parsing and map/scenario loading
+- Demonstrates integration of multiple path planning strategies
+
+### Data Flow
+
+```
+Command-line arguments
+        ↓
+Map/Scenario Loading (mapfBenchmarkProvider)
+        ↓
+Graph Construction & Cooperation Node Generation
+        ↓
+Path Planning
+        ↓
+Path Interpolation (simulation)
+        ↓
+GUI Creation & Visualization (gui)
+        ↓
+User Interaction & Animation
+```
+
+## 📁 Directory Structure
+
+```
+project/
+├── README.md                          # This file
+├── DOCUMENTATION.md                   # Detailed technical documentation
+├── ARCHITECTURE.md                    # System architecture guide
+├── pyproject.toml                     # Python package metadata
+├── src/
+│   └── iscpp_simulator/
+│       ├── main.py                    # Main entry point
+│       ├── mapf_benchmark_provider.py # Map and scenario loading
+│       ├── simulation.py              # Visualization and animation
+│       ├── gui.py                     # GUI interface
+│       └── data/graphs/               # Bundled maps and non-scenario graphs
+├── graphs/
+│   ├── scen-even/                     # Even-distribution scenarios
+│   └── scen-random/                   # Random scenarios
+```
+
+PyPI builds include the bundled maps and graph files under
+`src/iscpp_simulator/data/graphs/`, but exclude the heavier `.scen` scenario
+files. Scenario mode remains available by passing `--scenario-dir`.
+
+## 🔧 Advanced Usage
+
+### Custom Map Creation
+
+Maps must be in the MAPF `.map` format:
+
+```
+type octile
+height 8
+width 8
+map
+. . . . . . . .
+. @ @ . . . . .
+. @ @ . . . @ @
+. . . . . . . .
+...
+```
+
+Where:
+- `.` = free cell
+- `@` or `T` = obstacle
+- `X` = cooperation node (extension for ICMPP instances)
+
+### Custom Scenarios
+
+Scenario files (`.scen`) follow the standard MAPF scene format. After the
+`version` header, each row describes one agent:
+
+```
+version 1
+bucket map width height start_x start_y goal_x goal_y optimal_length
+0 empty-8-8.map 8 8 0 0 7 7 14
+1 empty-8-8.map 8 8 0 7 7 0 14
+...
+```
+
+Where:
+- `bucket` = numerical scenario ID, often arbitrary or used to number agents
+- `map` = map file associated with the scenario
+- `width` and `height` = grid dimensions
+- `start_x` and `start_y` = agent start coordinates
+- `goal_x` and `goal_y` = agent goal coordinates
+- `optimal_length` = shortest start-to-goal path length for that agent when
+  other agents are ignored, usually computed with octile or Manhattan distance
+
+
+### Extending Path Planners
+A joint path is represented as a tuple of per-agent path results. Each
+agent result is a dictionary with a `path` key containing an ordered list of
+node IDs from start to goal, and a `length` key containing the total path cost.
+
+Paths may also contain synthetic wait markers in the form `WAIT_<n>`, where
+`n` is the number of time steps an agent waits before continuing. These markers
+are not graph nodes; they are inserted between real node IDs to encode
+synchronization delays, specifically when one agent must wait for another before
+cooperating at a node. Simulation and visualization code include their duration when computing the
+time-indexed agent states.
+
+To add a custom path planning strategy:
+
+1. Create a function in `main.py`:
+```python
+def custom_path_strategy(G, v_s, v_g):
+    # Your algorithm here
+    return {'path': path, 'length': cost}
+```
+
+2. Add to paths dictionary:
+```python
+paths["Custom Strategy"] = (
+    custom_path_strategy(G, 's_1', 'g_1'),
+    custom_path_strategy(G, 's_2', 'g_2')
+)
+```
+
+3. Results will appear as selectable options in the GUI
+
+## 📈 Key Parameters Explained
+
+### Cooperation Density (`-d`, `--density`)
+- **Range**: 0.0 to 1.0
+- **Effect**: Controls the ratio of cooperation nodes to all nodes in the graph
+- **Higher values**: More opportunities for cooperation
+- **Lower values**: Sparser cooperation opportunities
+
+### Cooperation Magnitude (`-mt`, `--magnitude`)
+- **Range**: Integer > 0
+- **Effect**: Sets the multiplication factor between non-cooperative and cooperative travel time at cooperation nodes
+- **Calculation**: cooperative travel time is derived from non-cooperative travel time using this factor
+- **Higher values**: Greater cooperation benefit
+
+### Extent (`-e`, `--extent`)
+- **Range**: Integer > 0
+- **Effect**: Manhattan distance between each agent's starting node and target node
+- **Higher values**: Longer start-to-target task distance
+
+### Separation (`-se`, `--seperation`)
+- **Range**: Integer > 0
+- **Effect**: Manhattan distance between the two agents' starting nodes and between the two agents' target nodes
+- **Higher values**: Agents start and finish farther apart
+
+## 🧪 Testing & Examples
+
+### Example 1: Basic Comparison
+```bash
+iscpp-simulator
+# Compares shortest independent vs. cooperative paths on default 8x8 map
+```
+
+### Example 2: Simple Scenario
+```bash
+iscpp-simulator -m "empty-16-16" -s "empty-16-16-even-1" -d 0.4 -mt 20
+# Uses a simple 16x16 empty map with first even-distribution scenario
+# 40% cooperation nodes with benefit of 20 time units
+```
+
+### Example 3: Parameter Sweep
+```bash
+for d in 0.3 0.5 0.7; do
+  for mt in 5 10 15; do
+    iscpp-simulator -d $d -mt $mt
+  done
+done
+```
+
+## 🤝 Contributing
+
+Enhancements welcomed in:
+- Additional path planning algorithms
+- New visualization features
+- Performance optimizations
+- Support for more than 2 agents
+- Integration with other MAPF research
+
+## 📚 References
+
+This project is based on research in Intermittent Strategic Cooperation of Two Selfish Agents on Graphs (IC2PP). The benchmark maps and scenarios are from the MAPF community benchmarks.
+
+### Related Work
+- {Link to paper}
+
+## 📖 Citation
+
+If you use this simulator in academic work, please cite it as:
+
+```bibtex
+@software{shedlezki_2026_icpp_simulation,
+  author = {Shedlezki, Itay and Agmon, Noa},
+  title = {Intermittent Cooperation Multiagent Path Planning Simulation},
+  year = {2026},
+  license = {MIT}
+}
+```
+
+## ⚙️ System Requirements
+
+- **Python**: 3.7+
+- **Memory**: 512 MB minimum
+- **Disk**: 100 MB for benchmark datasets
+- **Display**: Required for GUI (X11/Wayland on Linux, native on Windows/macOS)
+
+
+## 📝 License
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
+
+## Authors
+
+**Itay Shedlezki** (Corresponding Author)
+- Email: i.shedlezki@gmail.com
+- Affiliation: Department of Computer Science and Artificial Intelligence, Bar-Ilan University, Ramat Gan, Israel
+
+**Noa Agmon**
+- Email: agmon@cs.biu.ac.il
+- Affiliation: Department of Computer Science and Artificial Intelligence, Bar-Ilan University, Ramat Gan, Israel
+
+---
+
+For detailed technical information, see [DOCUMENTATION.md](DOCUMENTATION.md) and [ARCHITECTURE.md](ARCHITECTURE.md).