added pso algorithm

[anishk85]

Particle Swarm Optimization (PSO) Path Planning - Contribution

🎯 Overview

This contribution adds a Particle Swarm Optimization (PSO) algorithm for 2D path planning to the PythonRobotics project, following all contribution guidelines and standards.

🎬 Video Demonstration

pso.webm

Live demonstration of PSO particles converging to find optimal collision-free path from start zone (green) to target (red star) while avoiding obstacles (gray circles).

🚀 Changes Made

1. Algorithm Implementation

File: PathPlanning/ParticleSwarmOptimization/particle_swarm_optimization.py

• ✅ PSO-based path planning with collision avoidance
• ✅ Real-time visualization showing particle convergence
• ✅ Dynamic inertia weight scheduling (0.9 → 0.4)
• ✅ Line-circle intersection for obstacle collision detection
• ✅ Configurable parameters (particles, iterations, coefficients)
• ✅ Signal handling for graceful interruption

2. Comprehensive Documentation

File: docs/modules/5_path_planning/particleSwarmOptimization/particleSwarmOptimization.rst

• ✅ Complete mathematical foundation with LaTeX equations
• ✅ Algorithm overview and step-by-step explanation
• ✅ Fitness function and collision detection details
• ✅ Parameter tuning guide and performance analysis
• ✅ Code examples and academic references

3. Unit Testing

File: tests/test_particle_swarm_optimization.py

• ✅ Headless test mode for CI/CD compatibility
• ✅ Non-GUI backend support (matplotlib.use('Agg'))
• ✅ Follows PythonRobotics testing conventions

4. Documentation Update

File: README.md (Main project README)

• ✅ Added PSO section in Path Planning category
• ✅ Algorithm description and references
• ✅ Consistent formatting with existing algorithms

🔧 Technical Specifications

Component	Implementation
Algorithm	Particle Swarm Optimization (PSO)
Dimension	2D path planning
Swarm Size	15 particles (configurable)
Max Iterations	150 (configurable)
Search Space	(-50, 50) × (-50, 50)
Obstacles	Circular with radius-based collision detection
Fitness Function	f(x) = distance_to_goal + obstacle_penalties
Visualization	Real-time matplotlib animation
Backend Support	GUI and headless (Agg) modes

📁 Files Modified/Added

📦 PythonRobotics/
├── 📁 PathPlanning/ParticleSwarmOptimization/
│   └── 📄 particle_swarm_optimization.py          [NEW - 300+ lines]
├── 📁 docs/modules/5_path_planning/particleSwarmOptimization/
│   └── 📄 particleSwarmOptimization.rst          [NEW - 150+ lines]  
├── 📁 tests/
│   └── 📄 test_particle_swarm_optimization.py    [NEW - 15 lines]
└── 📄 README.md                                  [MODIFIED - Added PSO section]

🧮 Algorithm Details

PSO Velocity Update Equation

v(t+1) = w·v(t) + c1·r1·(pbest - x(t)) + c2·r2·(gbest - x(t))

Key Features

• Global Optimization: Escapes local minima unlike gradient-based methods
• Swarm Intelligence: Multiple particles explore search space simultaneously
• Collision Avoidance: Line-circle intersection detection
• Parameter Tuning: Configurable inertia weight, cognitive/social coefficients
• Real-time Visualization: Shows particle movement and convergence

Algorithm Steps

1. Initialize particles randomly near start position
2. Evaluate fitness (distance to goal + obstacle penalties)
3. Update personal and global best positions
4. Move particles using PSO velocity equation
5. Check collisions and adjust velocities
6. Repeat until convergence or maximum iterations

📊 Performance Characteristics

Aspect	Rating	Notes
Optimality	⭐⭐⭐	No guarantee, but good practical results
Speed	⭐⭐⭐	Medium - depends on swarm size
Memory	⭐⭐⭐⭐	Low memory usage
Complexity	⭐⭐⭐⭐⭐	Simple implementation and tuning

🎓 Educational Value

• Algorithm Understanding: Clear implementation of PSO fundamentals
• Mathematical Foundation: Complete equations and explanations
• Visualization: Real-time animation showing algorithm behavior
• Parameter Effects: Demonstrates impact of different PSO parameters
• Research References: Links to original papers and resources

📚 References

• Particle swarm optimization - Wikipedia
• PSO Tutorial - Machine Learning Mastery

🎃 Hacktoberfest 2025

This contribution is part of Hacktoberfest 2025 and follows all PythonRobotics contribution guidelines:

• ✅ Educational focus over performance optimization
• ✅ Clear, readable code with comprehensive comments
• ✅ Complete documentation with mathematical foundation
• ✅ Unit tests for CI/CD compatibility
• ✅ Consistent formatting and style
• ✅ Academic references and proper attribution

🔗 Usage Example

import matplotlib.pyplot as plt
from PathPlanning.ParticleSwarmOptimization.particle_swarm_optimization import main

# Run PSO path planning with visualization
main()

🚦 Testing

# Run the test
python tests/test_particle_swarm_optimization.py

# Or with pytest
pytest tests/test_particle_swarm_optimization.py -v

---

Author: Anish (@anishk85)
Date: October 2025

[anishk85]

please do let me know if you require any further changes also for the gif part i mocked the url

[anishk85]

@AtsushiSakai

[AtsushiSakai]

@codex review

[Copilot]

Pull Request Overview

This PR adds a Particle Swarm Optimization (PSO) algorithm for 2D path planning to the PythonRobotics project. PSO is a metaheuristic optimization algorithm inspired by bird flocking behavior that finds collision-free paths by treating path planning as an optimization problem where particles explore the search space.

• Complete PSO implementation with real-time visualization and collision avoidance
• Comprehensive documentation with mathematical foundations and algorithm explanations
• Unit test with headless mode support for CI/CD compatibility

Reviewed Changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 4 comments.

File	Description
PathPlanning/ParticleSwarmOptimization/particle_swarm_optimization.py	New PSO path planning implementation with visualization and collision detection
docs/modules/5_path_planning/particleSwarmOptimization/particleSwarmOptimization.rst	Complete documentation with mathematical equations and algorithm overview
tests/test_particle_swarm_optimization.py	Unit test for PSO algorithm with headless mode support
README.md	Added PSO section to Path Planning category with description and references

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[Copilot]

[nitpick] The pragma comment should be on its own line above the if statement for better readability and consistency with coverage tools.

Suggested change

	if show_animation: # pragma: no cover
	# pragma: no cover
	if show_animation:

[anishk85]

fixed in next commit

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

[anishk85]

@AtsushiSakai could you please merge this pr as all builds checks have been passed also i have resolved all the issue created by codex and copilot.
Thanks

[AtsushiSakai]

I will start review by myself, please wait.