Ant Colony Optimization (#157)

* adding first ant * Ant path building * Implementing stigmergy and ACO * TSP benchmark * refactor 01 * app fix * simple fix, isort, clean * lint * readme * adding default args to pass unit tests * addressing PR comments * comment fix 2 * PR comments iter --------- Co-authored-by: Zak Jost <[email protected]>
projectmesa · Aug 24, 2024 · 2b944ff · 2b944ff
1 parent 43622b9
commit 2b944ff
Show file tree

Hide file tree

Showing 7 changed files with 540 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -103,6 +103,10 @@ This is the same [Boltzmann Wealth](https://github.com/projectmesa/mesa-examples
 
 This model is based on the NetLogo [Virus on a Network](https://ccl.northwestern.edu/netlogo/models/VirusonaNetwork) model.
 
+### [Ant System for Traveling Salesman Problem](https://github.com/projectmesa/mesa-examples/tree/main/examples/aco_tsp)
+
+This is based on Dorigo's Ant System "Swarm Intelligence" algorithm for generating solutions for the Traveling Salesman Problem.
+
 ## Visualization Examples
 
 ### [Boltzmann Wealth Model (Experimental)](https://github.com/projectmesa/mesa-examples/tree/main/examples/boltzmann_wealth_model_experimental)

diff --git a/examples/aco_tsp/README.md b/examples/aco_tsp/README.md
@@ -0,0 +1,55 @@
+Ant System for the Traveling Salesman Problem
+========================
+
+This is an implementation of the Ant System (AS) algorithm for solving the Traveling Salesman Problem (TSP).  This example uses Mesa's Network Grid to model a TSP by representing cities as nodes and the possible paths between them as edges.  Ants are then modeled as Mesa Agents that generate solutions by traversing the network using a "swarm intelligence" algorithm.
+
+When an ant is choosing its next city, it consider both a pheromone trail laid down by previous ants and a greedy heuristic based on city proximity.  Pheromone evaporates over time and the strength of new pheromone trail laid by an ant is proportional to the quality of its TSP solution.  This produces an emergent solution as the pheromone trail is continually updated and guides ants to high quality solutions as they are discovered.
+
+As this model runs, more pheromone will be laid on better solutions, and less traveled paths will have their pheromone evaporate.  Ants will therefore reinforce good paths and abandon bad ones.  Since decisions are ultimately samples from a weighted probability distribution, ants will sometimes explore unlikely paths, which might lead to new strong solutions that will be reflected in the updated pheromone levels.
+
+Here, we plot the best solution per iteration, the best solution so far in all iterations, and a graph representation where the edge width is proportional to the pheromone quantity.  You will quickly see most of the edges in the fully connected graph disappear and a subset of the paths emerge as reasonable candidates in the final TSP solution.
+
+## How to run
+To launch the interactive visualization, run `solara run app.py` in this directory.  Tune the $\alpha$ and $\beta$ parameters to modify how much the pheromone and city proximity influence the ants' decisions, respectively.  See the Algorithm details section for more.
+
+Alternatively, to run for a fixed number of iterations, run `python run_tsp.py` from this directory (and update that file with the parameters you want).
+
+## Algorithm details
+Each agent/ant is initialized to a random city and constructs a solution by choosing a sequence of cities until all are visited, but none are visited more than once.  Ants then deposit a "pheromone" signal on each path in their solution that is proportional to 1/d, where d is the final distance of the solution.  This means shorter paths are given more pheromone.
+
+When an ant is on city $i$ and deciding which city to choose next, it samples randomly using the following probabilities of transition from city $i$ to $j$:
+
+$$
+p_{ij}^k =  \frac{\tau_{ij}^\alpha \eta_{ij}^\beta}{\sum_{l \in J_i^k} \tau_{il}^\alpha \eta_{il}^\beta}
+$$
+
+where:
+- $\tau_{ij}$ is the amount of path pheromone
+- $\eta_{ij}$ the a greedy heuristic of desireability
+  - In this case, $\eta_{ij} = 1/d_{ij}$, where $d_{ij}$ is the distance between
+    cities
+- $\alpha$ is a hyperparameter setting the importance of the pheromone
+- $\beta$ a hyperparameter for setting the importance of the greedy heuristic
+- And the denominator sum is over $J_i^k$, which is the set of cities not yet
+  visited by ant $k$.
+
+In other words, $\alpha$ and $\beta$ are tuned to set the relative importance of the phermone trail left by prior ants, and the greedy heuristic of 1-over-distance.
+
+## Data collection
+The following data is collected and can be used for further analysis:
+- Agent-level (individual ants, reset after each iteration)
+  - `tsp_distance`: TSP solution distance
+  - `tsp_solution`: TSP solution path
+- Model-level (collection of ants over many iterations)
+  - `num_steps`: number of algorithm iterations, where one step means each ant generates a full TSP solution and the pheromone trail is updated
+  - `best_distance`: the distance of the best path found in all iterations
+    - This is the best solution yet and can only stay flat or improve over time
+  - `best_distance_iter`: the distance of the best path of all ants in a single iteration
+    - This changes over time as the ant colony explores different solutions and can be used to understand the explore/exploit trade-off.  E.g., if the colony quickly finds a good solution, but then this value trends upward and stays high, then this suggests the ants are stuck re-inforcing a suboptimal solution.
+  - `best_path`: the best path found in all iterations
+
+## References
+- Original paper:  Dorigo, M., Maniezzo, V., & Colorni, A. (1996). Ant system: optimization by a
+colony of cooperating agents. IEEE transactions on systems, man, and cybernetics,
+part b (cybernetics), 26(1), 29-41.
+- Video series of this code being implemented:  https://www.youtube.com/playlist?list=PLSgGvve8UweGk2TLSO-q5OSH59Q00ZxCQ
diff --git a/examples/aco_tsp/aco_tsp/__init__.py b/examples/aco_tsp/aco_tsp/__init__.py
diff --git a/examples/aco_tsp/aco_tsp/data/kroA100.tsp b/examples/aco_tsp/aco_tsp/data/kroA100.tsp
@@ -0,0 +1,107 @@
+NAME: kroA100
+TYPE: TSP
+COMMENT: 100-city problem A (Krolak/Felts/Nelson)
+DIMENSION: 100
+EDGE_WEIGHT_TYPE : EUC_2D
+NODE_COORD_SECTION
+1 1380 939
+2 2848 96
+3 3510 1671
+4 457 334
+5 3888 666
+6 984 965
+7 2721 1482
+8 1286 525
+9 2716 1432
+10 738 1325
+11 1251 1832
+12 2728 1698
+13 3815 169
+14 3683 1533
+15 1247 1945
+16 123 862
+17 1234 1946
+18 252 1240
+19 611 673
+20 2576 1676
+21 928 1700
+22 53 857
+23 1807 1711
+24 274 1420
+25 2574 946
+26 178 24
+27 2678 1825
+28 1795 962
+29 3384 1498
+30 3520 1079
+31 1256 61
+32 1424 1728
+33 3913 192
+34 3085 1528
+35 2573 1969
+36 463 1670
+37 3875 598
+38 298 1513
+39 3479 821
+40 2542 236
+41 3955 1743
+42 1323 280
+43 3447 1830
+44 2936 337
+45 1621 1830
+46 3373 1646
+47 1393 1368
+48 3874 1318
+49 938 955
+50 3022 474
+51 2482 1183
+52 3854 923
+53 376 825
+54 2519 135
+55 2945 1622
+56 953 268
+57 2628 1479
+58 2097 981
+59 890 1846
+60 2139 1806
+61 2421 1007
+62 2290 1810
+63 1115 1052
+64 2588 302
+65 327 265
+66 241 341
+67 1917 687
+68 2991 792
+69 2573 599
+70 19 674
+71 3911 1673
+72 872 1559
+73 2863 558
+74 929 1766
+75 839 620
+76 3893 102
+77 2178 1619
+78 3822 899
+79 378 1048
+80 1178 100
+81 2599 901
+82 3416 143
+83 2961 1605
+84 611 1384
+85 3113 885
+86 2597 1830
+87 2586 1286
+88 161 906
+89 1429 134
+90 742 1025
+91 1625 1651
+92 1187 706
+93 1787 1009
+94 22 987
+95 3640 43
+96 3756 882
+97 776 392
+98 1724 1642
+99 198 1810
+100 3950 1558
+EOF