Quick Start Tutorial

Get your genetic algorithm running in 5 minutes!

⏱️ Time Required: 5 minutes

📋 Prerequisites

• Python 3.7 or higher installed
• pip package manager
• Basic command line knowledge

🚀 Step-by-Step Guide

Step 1: Clone the Repository

git clone https://github.com/adylagad/CSCI-561_Genetic-Algorithm.git
cd CSCI-561_Genetic-Algorithm

Time: 1 minute

Step 2: Install Dependencies

pip install -r requirements.txt

Note: This project uses only Python standard library, so installation should be instant.

Time: 10 seconds

Step 3: Verify Installation

python test_ga.py

You should see:

test_euclidean_distance (__main__.TestUtilityFunctions) ... ok
test_read_input (__main__.TestUtilityFunctions) ... ok
...
======================================================================
🎉 ALL TESTS PASSED! 🎉
Ran 40 tests successfully
======================================================================

Time: 30 seconds

Step 4: Run the Algorithm

python main.py

Time: 3 minutes

Step 5: Understand the Output

You'll see output like this:

2025-11-03 10:15:23 - Reading input from: input/input1.txt
2025-11-03 10:15:23 - Loaded 500 cities
2025-11-03 10:15:23 - Starting Genetic Algorithm...
2025-11-03 10:15:25 - Generation 0: Best Fitness = 0.000016, Best Cost = 62308.19
2025-11-03 10:15:27 - Generation 100: Best Fitness = 0.000018, Best Cost = 55432.12
2025-11-03 10:15:30 - Generation 200: Best Fitness = 0.000019, Best Cost = 52156.89
...
================================================================
GENETIC ALGORITHM TSP SOLVER - RESULTS
================================================================

Optimal Tour Cost: 48234.56
Optimal Probability: 0.000021

Optimal Tour Path:
  1. (66, 153, 121)
  2. (116, 152, 189)
  3. (95, 47, 90)
  ...

================================================================

Algorithm Statistics:
  Total Generations: 3500
  Convergence Generation: 2847
  Best Cost: 48234.56
  Average Cost: 52341.23
  Worst Cost: 78901.45
  Converged: True
================================================================

📊 Understanding the Results

Key Metrics

1. Optimal Tour Cost (48234.56)

   • The total distance of the best route found
   • Lower is better
   • Measured in Euclidean distance units

2. Total Generations (3500)

   • Number of evolution cycles completed
   • Default: 3500 generations
   • Can be customized

3. Convergence Generation (2847)

   • When the best solution was found
   • Algorithm stopped improving after this
   • Useful for tuning parameters

4. Average/Worst Cost

   • Shows population diversity
   • Gap between best and worst indicates exploration

🎯 What Just Happened?

The genetic algorithm:

1. ✅ Created 500 random tours (initial population)
2. ✅ Evaluated each tour's quality (fitness)
3. ✅ Selected better tours as parents
4. ✅ Combined parents to create offspring (crossover)
5. ✅ Randomly modified some tours (mutation)
6. ✅ Repeated for 3500 generations
7. ✅ Found the best tour with distance ~48,000

🔄 Next Steps

Customize Your Configuration

Edit config/default_config.json:

{
	"mutation_rate": 0.1,
	"number_of_generations": 5000,
	"convergence_threshold": 100
}

Then run again:

python main.py

Try Different Operators

See Custom Operators Tutorial

Understand How It Works

Read GA Explained

Optimize Performance

See Performance Tuning Guide

🐛 Common Issues

Issue: ModuleNotFoundError

Problem:

ModuleNotFoundError: No module named 'genetic_algorithm'

Solution: Make sure you're in the project root directory:

cd CSCI-561_Genetic-Algorithm
python main.py

Issue: Algorithm is Slow

Problem: Takes too long to run

Solution: Reduce generations in config:

{
	"number_of_generations": 1000
}

Issue: Poor Solution Quality

Problem: Tour cost is very high

Solution:

1. Increase generations to 5000+
2. Try Nearest Neighbor initialization (see Custom Operators)

📚 Learn More

• GA Explained - Understand genetic algorithms
• Architecture Deep Dive - How the code works
• Performance Tuning - Optimize results
• FAQ - Common questions

✅ Success Checklist

• Cloned repository
• Installed dependencies
• Tests passed
• Algorithm ran successfully
• Understood the output
• Ready to customize!

---

Congratulations! 🎉 You've successfully run your first genetic algorithm. Ready to dive deeper? → GA Explained