categorize example models into groups

Author: wang-boyu

examples/README.md

@@ -1,57 +1,101 @@
 # Example Code
 This directory contains example models meant to test and demonstrate Mesa's features, and provide demonstrations for how to build and analyze agent-based models. For more information on each model, see its own Readme and documentation.
 
-## Models
+## Grid Space Examples
 
-Classic models, some of which can be found in NetLogo's/MASON's example models.
+### [Bank Reserves Model](https://github.com/projectmesa/mesa-examples/blob/main/examples/bank_reserves)
 
-### bank_reserves
 A highly abstracted, simplified model of an economy, with only one type of agent and a single bank representing all banks in an economy.
 
-### color_patches
+### [Boltzmann Wealth Model](https://github.com/projectmesa/mesa-examples/tree/main/examples/boltzmann_wealth_model)
+
+Completed code to go along with the [tutorial](https://mesa.readthedocs.io/en/latest/tutorials/intro_tutorial.html) on making a simple model of how a highly-skewed wealth distribution can emerge from simple rules.
+
+### [Color Patches Model](https://github.com/projectmesa/mesa-examples/tree/main/examples/color_patches)
+
 A cellular automaton model where agents opinions are influenced by that of their neighbors. As the model evolves, color patches representing the prevailing opinion in a given area expand, contract, and sometimes disappear.
 
-### conways_game_of_life
+### [Conway's Game Of "Life" Model](https://github.com/projectmesa/mesa-examples/tree/main/examples/conways_game_of_life)
+
 Implementation of [Conway's Game of Life](https://en.wikipedia.org/wiki/Conway%27s_Game_of_Life), a cellular automata where simple rules can give rise to complex patterns.
 
-### epstein_civil_violence
+### [Conway's Game Of "Life" Model on a Hexagonal Grid](https://github.com/projectmesa/mesa-examples/tree/main/examples/hex_snowflake)
+
+Conway's game of life on a hexagonal grid.
+
+### [Demographic Prisoner's Dilemma on a Grid](https://github.com/projectmesa/mesa-examples/tree/main/examples/pd_grid)
+
+Grid-based demographic prisoner's dilemma model, demonstrating how simple rules can lead to the emergence of widespread cooperation -- and how a model activation regime can change its outcome.
+
+### [Epstein Civil Violence Model](https://github.com/projectmesa/mesa-examples/tree/main/examples/epstein_civil_violence)
+
 Joshua Epstein's [model](http://www.uvm.edu/~pdodds/files/papers/others/2002/epstein2002a.pdf) of how a decentralized uprising can be suppressed or reach a critical mass of support.
 
-### boid_flockers
+### [Forest Fire Model](https://github.com/projectmesa/mesa-examples/tree/main/examples/forest_fire)
+
+Simple cellular automata of a fire spreading through a forest of cells on a grid, based on the NetLogo [Fire](http://ccl.northwestern.edu/netlogo/models/Fire) model.
+
+### [Hotelling's Law Model](https://github.com/projectmesa/mesa-examples/tree/main/examples/hotelling_law)
+
+This project is an agent-based model implemented using the Mesa framework in Python. It simulates market dynamics based on Hotelling's Law, exploring the behavior of stores in a competitive market environment. Stores adjust their prices and locations if it's increases market share to maximize revenue, providing insights into the effects of competition and customer behavior on market outcomes.
+
+### [Schelling Segregation Model](https://github.com/projectmesa/mesa-examples/tree/main/examples/schelling)
+
+Mesa implementation of the classic [Schelling segregation](http://nifty.stanford.edu/2014/mccown-schelling-model-segregation/) model.
+
+### [Sugarscape Constant Growback Model](https://github.com/projectmesa/mesa-examples/tree/main/examples/sugarscape_cg)
+
+This is Epstein & Axtell's Sugarscape Constant Growback model, with a detailed description in the Chapter Two of *Growing Artificial Societies: Social Science from the Bottom Up*. It is based on the Netlogo
+[Sugarscape 2 Constant Growback](http://ccl.northwestern.edu/netlogo/models/Sugarscape2ConstantGrowback) model.
+
+### [Sugarscape Constant Growback Model with Traders](https://github.com/projectmesa/mesa-examples/tree/main/examples/sugarscape_g1mt)
+
+This is Epstein & Axtell's Sugarscape model with Traders, a detailed description is in Chapter four of *Growing Artificial Societies: Social Science from the Bottom Up (1996)*. The model shows an emergent price equilibrium can happen via a decentralized dynamics.
+
+### [Wolf-Sheep Predation Model](https://github.com/projectmesa/mesa-examples/tree/main/examples/wolf_sheep)
+
+Implementation of an ecological model of predation and reproduction, based on the NetLogo [Wolf Sheep Predation](http://ccl.northwestern.edu/netlogo/models/WolfSheepPredation) model.
+
+## Continuous Space Examples
+
+### [Boids Flockers Model](https://github.com/projectmesa/mesa-examples/tree/main/examples/boid_flockers)
+
 [Boids](https://en.wikipedia.org/wiki/Boids)-style flocking model, demonstrating the use of agents moving through a continuous space following direction vectors.
 
-### forest_fire
-Simple cellular automata of a fire spreading through a forest of cells on a grid, based on the NetLogo [Fire model](http://ccl.northwestern.edu/netlogo/models/Fire).
+## Network Examples
 
-### hex_snowflake
-Conway's game of life on a hexagonal grid.
+### [Boltzmann Wealth Model with Network](https://github.com/projectmesa/mesa-examples/tree/main/examples/boltzmann_wealth_model_network)
 
-### pd_grid
-Grid-based demographic prisoner's dilemma model, demonstrating how simple rules can lead to the emergence of widespread cooperation -- and how a model activation regime can change its outcome.
+This is the same [Boltzmann Wealth](https://github.com/projectmesa/mesa-examples/tree/main/examples/boltzmann_wealth_model) Model, but with a network grid implementation.
 
-### schelling (GUI and Text)
-Mesa implementation of the classic [Schelling segregation model](http://nifty.stanford.edu/2014/mccown-schelling-model-segregation/).
+### [Virus on a Network Model](https://github.com/projectmesa/mesa-examples/tree/main/examples/virus_on_network)
 
-### boltzmann_wealth_model
-Completed code to go along with the [tutorial]() on making a simple model of how a highly-skewed wealth distribution can emerge from simple rules.
+This model is based on the NetLogo [Virus on a Network](https://ccl.northwestern.edu/netlogo/models/VirusonaNetwork) model.
 
-### wolf_sheep
-Implementation of an ecological model of predation and reproduction, based on the NetLogo [Wolf Sheep Predation model](http://ccl.northwestern.edu/netlogo/models/WolfSheepPredation).
+## Visualization Examples
 
-### sugarscape_cg
-Implementation of Sugarscape 2 Constant Growback model, based on the Netlogo
-[Sugarscape 2 Constant Growback](http://ccl.northwestern.edu/netlogo/models/Sugarscape2ConstantGrowback)
+### [Boltzmann Wealth Model (Experimental)](https://github.com/projectmesa/mesa-examples/tree/main/examples/boltzmann_wealth_model_experimental)
 
-### virus_on_network
-This model is based on the NetLogo model "Virus on Network".
+Boltzmann Wealth model with the experimental Juptyer notebook visualization feature.
 
-## Feature examples
+### [Charts Example](https://github.com/projectmesa/mesa-examples/tree/main/examples/charts)
 
-Example models specifically for demonstrating Mesa's features.
+A modified version of the [Bank Reserves](https://github.com/projectmesa/mesa-examples/tree/main/examples/bank_reserves) example made to provide examples of Mesa's charting tools.
 
-### charts
+### [Schelling Segregation Model (Experimental)](https://github.com/projectmesa/mesa-examples/tree/main/examples/schelling_experimental)
 
-A modified version of the "bank_reserves" example made to provide examples of mesa's charting tools.
+Schelling segregation model with the experimental Juptyer notebook visualization feature.
+
+### [Shape Example](https://github.com/projectmesa/mesa-examples/tree/main/examples/shape_example)
 
-### Shape Example
 Example of grid display and direction showing agents in the form of arrow-head shape.
+
+## Other Examples
+
+### [El Farol Model](https://github.com/projectmesa/mesa-examples/tree/main/examples/el_farol)
+
+This folder contains an implementation of El Farol restaurant model. Agents (restaurant customers) decide whether to go to the restaurant or not based on their memory and reward from previous trials. Implications from the model have been used to explain how individual decision-making affects overall performance and fluctuation.
+
+### [Schelling Model with Caching and Replay](https://github.com/projectmesa/mesa-examples/tree/main/examples/caching_and_replay)
+
+This example applies caching on the Mesa [Schelling](https://github.com/projectmesa/mesa-examples/tree/main/examples/schelling) example. It enables a simulation run to be "cached" or in other words recorded. The recorded simulation run is persisted on the local file system and can be replayed at any later point.