-
Notifications
You must be signed in to change notification settings - Fork 11
Home
This reimplementation of the Sugarscape model (from Growing Artificial Societies) is an agent-based simulation platform for exploring how individual agent behaviors result in emergent societal behavior. This implementation of Sugarscape is maintained by the Digital Terraria Lab at Seattle University, and it is used as an experimental platform for computational social science and machine ethics research.
Sugarscape is a two-dimensional n x m grid landscape, where each grid cell contains some amount of two resources: sugar and spice. These resources are metaphors for material wealth and are gathered by agents who then consume sugar and spice over time. In Sugarscape, agents can lead long, rich lives where they interact with the environment and other agents. Or, if conditions are poor, lead nasty, brutish, and short lives.
Sugarscape is written entirely in Python, but there are additional software requirements for helper programs. In order to run Sugarscape, you need the following software packages installed on your system:
- GNU Make
- Python 3
- tk (optional but recommended for the graphical interface)
Additionally, the following Python packages provide optional features:
- matplotlib (optional for generating graphs)
- tkinter (optional but recommended for the graphical interface)
The easiest way to get our software is to clone this repository from GitHub:
git clone https://github.com/nkremerh/sugarscape.git
This brief tutorial will introduce how to configure your runtime environment to successfully run Sugarscape, how to run the simulation, and how to change a few (of many) options to make the simulation more interesting. It is assumed you are interacting with this software on a Linux or MacOS operating system. The Windows Subsystem for Linux is highly recommended for Windows users, though it is possible to run the simulation entirely on Windows.
Run the setup command to check for your local installation of Python and automatically configure the necessary aliases for you:
make setup
To run the Sugarscape simulation with the bare minimum default settings, run:
python sugarscape.py
Note: your system alias for your local Python 3 installation may not simply be python. If you receive an error trying to run the above command, try replacing python with python3. If that does not work, investigate what the alias is for your local Python 3 installation or contact your system administrator.
If all the requirements have been met, a graphical interface should pop up showing the grid environment. The red cells indicate the presence of an agent. Yellow cells indicate the presence of sugar. The more saturated the color, the more sugar is at that cell. Spice is disabled in this bare minimum example, and agents are configured to only need to eat sugar and not sugar and spice.
This example is simplistic, but it is enough to introduce the interface and the gist of the simulation. Pressing the spacebar or clicking Play Simulation will start the simulation. Pressing the spacebar or clicking Pause Simulation will pause it. Pressing the right arrowkey or clicking Step Forward will advance the simulation one timestep at a time. There are other options in the interface, including recoloring the agents by their different properties as well as the environment. You are invited to explore those options, but none of the necessary configuration options to make use of them are enabled in this bare minimum example.
To see a more complete example with most features enabled, first quit the current example by letting it finish running, pressing the escape key, or closing the graphical window. Once finished, you can run a more interesting configuration of the simulation (provided in the config.json file) by running:
make test
This configuration includes spice as a resource (colored brown). Cells colored tan have both sugar and spice (which make them very desirable for agents). The various agent recoloring options will now provide useful recoloring in the interface. This more advanced configuration does not make use of additional environmental recoloring options (such as pollution).
Provided in the repository is a set of examples which reproduce diagrams and described scenarios from the source book Growing Artificial Societies by Joshua Epstein and Robert Axtell. Each example which reproduces a book scenario cites the relevant pages it reproduces. Also included is a blank JSON template for writing new configurations and a fun example which attempts to envision a scenario from Frank Herbert's Dune.
To run a specific example, you run Sugarscape and specify the relevant configuration file. To run the example demonstrating seasonal migratory patterns, run the following:
python sugarscape.py --conf examples/seasonal_migration.json
Changing a configuration involves changing values in a configuration JSON file. The provided config.json is a convenient file to edit since it lists every option in the software (even if those options are disabled). An entirely new mechanism unique to our implementation of Sugarscape is the decision layer. By changing the decision model used in the decision layer, you can alter how agents behave in the simulation.
By default, agents are greedy and are more than happy to kill and swindle to better their position. As part of the Digital Terraria Lab's research mission, we implement socio-ethical decision models which encourage more cooperative behavior (to varying degrees). To change the decision model to instead use our implementation of Jeremy Bentham's utilitarianism, change the agentDecisionModels option from ["none"] to ["bentham"].
You may have noticed that the agentDecisionModels field takes an array of strings. This means you can enable multiple decision models in the simulation. As a result, the initial set of agents placed at the beginning of the simulation will have each have one of the provided decision models. There will be a roughly equal number of agents using each model.
To run the simulation with this new configuration, you can use the Makefile provided like before:
make test
Or, you can specify the configuration file manually like so:
python sugarscape.py --conf config.json
If you would like to run a lot of simulations for the purpose of experimentation and data collection, there is built-in functionality in the Makefile to support this. While we do not cover all the necessary options here, you can find all the relevant data collection options in our README. Once you have all the options you would like specified, you can run the data collection like so:
make data
Additionally, you may want to generate graphs of the simulation runs. Each run will store a log file in the data directory of the repository. The provided plotting script in the plots directory will read those logs and attempt to produce a set of prepared graphs. You can do this by running:
make plots
Note: if you have not completed data collection, the Makefile will attempt to finish running any unfinished simulations (which will mean all of them if you have not done any data collection).