SUGARSCAPE

Python implementation of the Sugarscape agent-based computational model introduced in Growing Artificial Societies (1996) by Epstein and Axtell.

Inspired by previous work from Herve Lange (https://github.com/langerv/sugarscape) and Joshua Palicka (https://github.com/joshuapalicka/sugarscape).

Requirements: Python 3

Optional Dependencies: Matplotlib TkInter

Usage: python sugarscape.py

Makefile Options: make clean Clean up working files and logs created by the software. Note: This will remove any JSON files created by the other make options.

make data Run a number of random seeds comparing selected decision models. Note: Results will be saved in the data subdirectory.

make plots Generate graph plots from any JSON files in the data subdirectory. Note: Plots are dependent on a dataset existing and will create it if necessary.

make seeds Generate a set of random seeds comparing selected decision models. Note: Results will be saved in the data subdirectory.

make setup Change preconfigured settings for the system Python alias. Note: Changed settings may alter Makefile and configuration file in-place.

make test Run the simulation using the default config.json file and storing a local log in the log.json file.

Preconfigured Examples from Growing Artificial Societies: A selection of examples can be found in the examples directory. Each demonstrates a concept from the book Growing Artificial Societies. Examples are included to demonstrate adherence to or deviation from the source material.

immediate_growback.json: Agent sugar collection with immediate sugar growback (pgs. 21-26).

constant_growback.json: Agent sugar collection with constant sugar growback (pgs. 28-30).

agent_replacement.json: Agent replacement with constant sugar growback (pgs. 32-33).

seasonal_migration.json: Agent migration with seasonal sugar growback (pgs. 44-46).

pollution_formation.json: Agent sugar collection with constant sugar growback and pollution (pgs. 45-50).

reproduction_basic.json: Agent reproduction with constant sugar growback (pgs. 55-58).

reproduction_oscillation_small.json: Agent reproduction with lower infertility age and constant sugar growback (pg. 64).

reproduction_oscillation_large.json: Agent reproduction with lower reproduction cost and constant sugar growback (pg. 65).

reproduction_oscillation_severe.json: Agent reproduction with lower infertility age, lower reproduction cost, and constant sugar growback (pg. 66).

reproduction_inheritance.json: Agent reproduction with child wealth inheritance and constant sugar growback (pgs. 67-68).

cultural_tagging.json Agent cultural tagging with constant sugar growback (pgs. 72-79).

combat_unlimited.json: Agent combat with unlimited combat loot and constant sugar growback (pgs. 82-83).

combat_limited.json: Agent combat with unlimited combat loot and constant sugar growback (pgs. 86-90).

cultural_combat_unlimited.json: Agent combat with agent cultural tagging and unlimited combat loot (pg. 91).

spice_growback.json: Agent sugar and spice collection with constant sugar and spice growback (pgs. 96-99).

trade_basic.json: Agent sugar and spice collection with trading and constant sugar and spice growback (pgs. 101-107).

trade_replacement.json: Agent trading with agent replacement and constant sugar and spice growback (pgs. 120-122).

trade_reproduction.json: Agent trading with agent reproduction and constant sugar and spice growback (pg. 124).

trade_tagging.json: Agent trading with agent cultural tagging and constant sugar and spice growback (pgs. 125-126).

trade_tagging_reproduction.json: Agent trading with agent cultural tagging, agent reproduction, and constant sugar and spice growback (pg. 127).

trade_pollution.json: Agent trading with sugar pollution and constant sugar and spice growback (pgs. 127-129).

foresight_basic.json: Agent sugar and spice collection with foresight consideration and constant sugar and spice growback (pgs. 129-130).

lending_basic.json: Agent sugar and spice collection with lending and constant sugar and spice growback (pgs. 131-133).

disease_basic.json: Agent sugar and spice collection with disease and constant sugar and spice growback (pgs. 141-147).

JSON Configuration File Options: The simulation provides a default set of options in a dictionary in the sugarscape.py file. A JSON configuration file can be passed to the simulation, overwriting the default configuration, with the --conf option.

agentAggressionFactor: [float, float] Set the aggressiveness of an agent. Note: The more aggressive an agent the more likely they will be enticed by combat options. Default: [0, 0]

agentBaseInterestRate: [float, float] Set the interest rate for an agent's lending as a percentage. Default: [0.0, 0.0]

agentDecisionModelLookaheadDiscount: [float, float] Set the agent's discount applied to considering possible rewards in future timesteps. Note: This feature is used in agent decision models besides the "none" and "rawSugarscape" models. Default: [0, 0]

agentDecisionModelLookaheadFactor: float Set the agent's consideration of future rewards out to the provided forecasting horizon. Options: 0, 0.5 Note: This feature is used in agent decision models besides the "none" and "rawSugarscape" models. Default: 0

agentDecisionModelFactor: [float, float] Set the agent weight of their decision model over biological imperatives. Default: [0, 0]

agentDecisionModels: [string, ...] Set the agent decision models for different decisionmaking. Options: "altruistBinary", "altruistTop", "benthamBinary", "benthamTop", "egoistBinary", "egoistTop", "negativeBentham", "none", "rawSugarscape" Note: Adding either "HalfLookahead" or "NoLookahead" after a decision model name will enforce a particular decision model lookahead factor. Default: ["none"]

agentDecisionModelTribalFactor: [float, float] Set how much agents prioritize the welfare of their own tribe members over others. Note: Valid range is [0.0, 1.0], use -1 to disable. Default: [-1, -1]

agentDepressionPercentage: float Set the percentage chance an agent will experience depression symptoms at birth. Note: The starting agent population will have this same percentage of depressed agents. Default: 0.0

agentFemaleInfertilityAge: [int, int] Set the timestep age at which female agents become infertile. Default: [0, 0]

agentFemaleFertilityAge: [int, int] Set the timestep age at which female agents become fertile. Default: [0, 0]

agentFertilityFactor: [float, float] Set the fertility bonus for the agent. The higher the factor, the fewer resources the agent expends to reproduce. Default: [0, 0]

agentImmuneSystemLength: int Set the length of agent immune system tags to integer length. Default: 0

agentInheritancePolicy: string Set wealth inheritance policy on agent death to given string. Options: "children". "daughters", "friends", "none", "sons" Default: "none"

agentLendingFactor: [float, float] Set lending aggressiveness of agent. The more aggressive an agent is to lend, the higher the offered interest rate will be. Default: [0, 0]

agentLoanDuration: [int, int] Set the agent's provided loan duration in timesteps. Default: [0, 0]

agentLookaheadFactor: [int, int] Set the agent's consideration of metabolic costs in timesteps ahead. Default: [0, 0]

agentMaleInfertilityAge: [int, int] Set the timestep age at which male agents become infertile. Default: [0, 0]

agentMaleFertilityAge: [int, int] Set the timestep age at which male agents become fertile. Default: [0, 0].

agentMaleToFemaleRatio: float Set the ratio of males to females in starting population as a real number. Default: 1.0

agentMaxAge: [int, int] Set maximum agent age in timesteps. Note: A value of -1 indicates an infinitely lived agent. Default: [-1, -1]

agentMaxFriends: [int, int] Set maximum number of friends tracked by an agent. Default: [0, 0]

agentMovement: [int, int] Set maximum movement distance per timestep for agent. Default: [1, 6]

agentMovementMode: string Set the directionality used to figure out which cells an agent can move to. Options: "cardinal", "radial" Default: "cardinal"

agentReplacements: int Set maximum number of agents to replace in environment on agent death. Default: 0

agentSelfishnessFactor: [float, float] Set the weight agents provide to their own welfare and to other agents. Note: Valid range is [0.0, 1.0], use -1 to disable. Default: [-1, -1]

agentSpiceMetabolism: [float, float] Set agent metabolism for spice per timestep. Default: [0, 0]

agentStartingSpice: [float, float] Set agent starting spice hold. Default: [0, 0]

agentStartingSugar: [float, float] Set agent starting sugar hold. Default: [10, 40]

agentSugarMetabolism: [float, float] Set agent metabolism for sugar per timestep. Default: [1, 4]

agentTagPreferences: bool Set whether agents calculate welfare based on cultural tag preferences. Note: Requires agents have a cultural tag string length greater than zero. Default: false

agentTagStringLength: int Set agent cultural tags string length. Default: 0

agentTagging: boolean Set whether agents will exert cultural pressure by flipping neighboring agent cultural tags. Default: true

agentTradeFactor: [float, float] Set agent trade aggressiveness. Note: The more aggressive in trading an agent, the more resources they will attempt to trade. Default: [0, 0]

agentUniversalSpice: [float, float] Set the amount agents recieve for universal basic spice income. Default: [0, 0]

agentUniversalSugar: [float, float] Set the amount agents recieve for universal basic sugar income. Default: [0, 0]

agentVision: [int, int] Set the distance in the four cardinal directions an agent can see. Default: [1, 6]

agentVisionMode: string Set the directionality used to figure out which cells an agent can see. Options: "cardinal", "radial" Default: "cardinal"

debugMode: [string, ...] Set the debug printing mode. Options: "agent", "all", "cell", "disease", "environment", "ethics", "none", "sugarscape" Default: "none" Note: Some options may cause no output in current impementation. Can select multiple debug modes simultaneously.

diseaseAggressionPenalty: [float, float] Set the impact a disease will have on an agent's aggressiveness. Note: Negative values constitute an aggressiveness decrease. Default: [0, 0]

diseaseFertilityPenalty: [float, float] Set the impact a disease will have on an agent's fertility. Note: Negative values constitute a fertility decrease. Default: [0, 0]

diseaseMovementPenalty: [int, int] Set the impact a disease will have on an agent's movement distance. Note: Negative values constitute a decrease in movement range. Default: [0, 0]

diseaseSpiceMetabolismPenalty: [float, float] Set the impact a disease will have on an agent's spice metabolism rate. Note: Negative values constitute a decrease in agent spice metabolism. Default: [0, 0]

diseaseSugarMetabolismPenalty: [float, float] Set the impact a disease will have on an agent's sugar metabolism rate. Note: Negative values constitute a decrease in agent sugar metabolism. Default: [0, 0]

diseaseTagStringLength: [int, int] Set the length of disease tags. The longer the length, the longer an agent will have the disease. Default: [0, 0]

diseaseVisionPenalty: [int, int] Set the impact a disease will have on an agent's vision. Note: Negative values constitute a decrease in agent vision. Default: [0, 0]

environmentEquator: int Set the equator of the environment for seasonal changes. Note: Value of -1 causes equator to be set at the midpoint of the environment. Default: -1

environmentHeight: int Set the height in cells of the Sugarscape environment. Default: 50

environmentMaxCombatLoot: float Set the maximum reward agents receive from winning combat. Default: 0

environmentMaxSpice: int Set the maximum amount of spice at any cell in the environment. This amount will only be present at spice peaks. Default: 0

environmentMaxSugar: int Set the maximum amount of sugar at any cell in the environment. This amount will only be present at sugar peaks. Default: 4

environmentMaxTribes: int Set the maximum number of tribes in the starting population. Default: 0

environmentPollutionDiffusionDelay: int Set the delay interval in timesteps when pollution is diffused across the environment. Default: 0

environmentPollutionDiffusionTimeframe: [int, int] Set the start and end timesteps during which pollution diffusion is active. Note: Value of -1 for the start sets the start timestep to 0. Note: Value of -1 for the end sets the end timestep to the end of the simulation. Default: [0, 0]

environmentPollutionTimeframe: [int, int] Set the start and end timesteps during which consumption and production pollution are active. Note: Value of -1 for the start sets the start timestep to 0. Note: Value of -1 for the end sets the end timestep to the end of the simulation. Default: [0, 0]

environmentQuadrantSizeFactor: float Set the proportion of each corner of the screen taken up by the agents' starting quadrants. Default: 1

environmentSeasonalGrowbackDelay: int Set the delay interval in timesteps when resources are regrown when cell is in a dry season. Default: 0

environmentSeasonInterval: int Set the interval in timesteps when environment seasons change. Seasons change along the equator of the environment. Default: 0

environmentSpiceConsumptionPollutionFactor: float Set the amount of pollution generated by an agent consuming spice at a cell. Default: 0

environmentSpicePeaks: [[int, int], ...] Set the coordinates for spice peaks in the environment. Default: [[15, 15], [35, 35]]

environmentSpiceProductionPollutionFactor: float Set the amount of pollution generated by an agent collecting spice at a cell. Default: 0

environmentSpiceRegrowRate: int Set the amount of spice regrown across the environment per timestep. Each cell can only grow up to their maximum spice value. Default: 0

environmentStartingQuadrants: [int (,int, int, int)] Set environment quadrants in which agents will initially be placed. Quadrant 1 begins in the top left. Quadrant 2 begins in the top right. Quadrant 3 begins in the bottom right. Quadrant 4 begins in the bottom left. Default: [1, 2, 3, 4]

environmentSugarConsumptionPollutionFactor: float Set the amount of pollution generated by an agent consuming sugar at a cell. Default: 0

environmentSugarPeaks: [[int, int], ...] Set the coordinates for sugar peaks in the environment. Default: [[15, 35], [35, 15]]

environmentSugarProductionPollutionFactor: float Set the amount of pollution generated by an agent collecting sugar at a cell. Default: 0

environmentSugarRegrowRate: int Set the amount of sugar regrown across the environment per timestep. Each cell can only grow up to their maximum sugar value. Default: 1

environmentTribePerQuadrant: bool Set whether starting quadrants are initially populated by a single tribe. Note: This will overwrite the number of tribes with the number of starting quadrants. Default: false

environmentUniversalSpiceIncomeInterval: int Set the interval in timesteps when environment produces universal basic spice income. Default: 0

environmentUniversalSugarIncomeInterval: int Set the interval in timesteps when environment produces universal basic sugar income. Default: 0

environmentWidth: int Set the width in cells of the Sugarscape environment. Default: 50

environmentWraparound: bool Set whether the environment is a torus (wraparound) or a plane (no wraparound). Default: true

experimentalGroup: string Set the experimental group of agents under study for finer-grained logging. Options: "depressed", "female", "male", "sick" Default: null

headlessMode: bool Set whether the GUI is enabled. Default: false

interfaceHeight: int Set number of pixels for GUI height. Note: Values below zero will cause the interface to fit to 1/2 total display height. Default: 1000

interfaceWidth: int Set number of pixels for GUI width. Default: 900 Note: Values below zero will cause the interface to fit to 1/2 total display width.

logfile: path Set the path of the log file. Default: null

logfileFormat: string Set the file format for the log file. Default: "json"

neighborhoodMode: string Set the type of neighborhood adjacency used by agents and environment cells. Options: "moore", "vonNeumann" Default: "vonNeumann"

profileMode: bool Set whether performance profiling mode is enabled. Default: false

seed: int Set the seed value for the random number generator. Note: Value of -1 causes simulation to generate a random seed. Note: Reusing a seed ensures deterministic simulation outcomes. Default: -1

startingAgents: int Set the number of agents placed in the initial population. Default: 500

startingDiseases: int Set the number of distinct diseases at simulation start. Default: 0

startingDiseasesPerAgent: [int, int] Set the number of diseases given to each agent at simulation start. Note: [0, 0] will give each starting disease to a unique agent. Default: [0, 0]

timesteps: int Set the number of timesteps the simulation runs. Note: Value of -1 causes simulation to run forever or until there are no more living agents. Default: 200

Other JSON Configurable Options: decisionModels: [[string, ...], ...] Set the agent decision models to be tested in data collection. Default: [["none"]]

jobUpdateFrequency: int Set the frequency at which the number of remaining jobs is reported. Default: 5

numParallelSimJobs: int Set the number of simulations to run in parallel during data collection. Default: 1

numSeeds: int Set the number of random seeds to be tested in data collection. Default: 100

plots: [string, ...] Set the plots to be created once data has been collected. Default: ["deaths", "meanAgeAtDeath", "meanttl", "meanWealth", "population", "wealth"]

plotTimesteps: int Set the number of timesteps to plot in graphs as the X axis. Note: This option does not control how many timesteps the simulation runs. Default: 1000

pythonAlias: string Set the alias to the local Python 3 installation. Note: Python 3 is required to run the simulation. Default: "python"