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 lean
    Clean up working files and plots created by the software but keep any logs and datasets. 

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 run
    Run the simulation using the default config.json file and storing a local log in the log.json file.

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 a testing suite in the tests directory using the configuration files in the examples directory.
    Note: It is suggested to run make test after modifying or adding Sugarscape features.

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]

agentDecisionModelAgeismFactor: [float, float]
    Set how much agents prioritize the welfare of agents close in age over agents farther in age.
    Note: Valid range is [0.0, 1.0], use -1 to disable.
    Default: [-1, -1]

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: "altruist", "asimov", "bentham", "egoist", "negativeBentham", "none", "rawSugarscape", "temperance", "temperancePECS"
    Note: Adding either "HalfLookahead" or "NoLookahead" after some decision model names will enforce a particular decision model lookahead factor.
    Note: Adding "Dynamic" after some decision model names enforces dynamic selfishness.
    Default: ["none"]

agentDecisionModelRacismFactor: [float, float]
    Set how much agents prioritize the welfare of their own race or configured in-group races over others.
    Note: Valid range is [0.0, 1.0], use -1 to disable.
    Default: [-1, -1]

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

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.
    Note: Valid range is [0.0, 1.0].
    Default: 0.0

agentDiseaseProtectionChance: [float, float]
    Set the chance an agent resists disease infection by another agent.
    Note: Value of 0.0 means no protection.
    Note: Value of 1.0 means perfect protection.
    Default: [0.0, 0.0]

agentDynamicSelfishnessFactor: [float, float]
    Set the amount the agent dynamically changes their selfishness in response to life circumstances.
    Note: Only functional for certain decision models.
    Default: [0.0, 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"

agentLeader: bool
    Set whether there is an immortal, omniscient leader agent to coordinate agent movements.
    Default: false

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"

agentRacialTagStringLength: int
    Set agent racial tags string length.
    Default: 0

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.
    Note: 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]

diseaseFriendlinessPenalty: [float, float]
    Set the impact a disease will have on an agent's maximum number of friends.
    Note: Negative values constitute a friendliness decrease.
    Default: [0, 0]

diseaseIncubationPeriod: [int, int]
    Set the number of timesteps disease symptoms can remain hidden while still being infectious.
    Default: [0, 0]

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

diseaseList: [string, ...]
    Set the named diseases in the environment.
    Options: "zombieVirus"
    Default: []

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]

diseaseTimeframe: [int, int]
    Set the timestep a disease can be initialized.
    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]

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]

diseaseTransmissionChance: [float, float]
    Set the chance a disease successfully transmits between agents.
    Note: Value of 0.0 means no transmission.
    Note: Value of 1.0 means perfect transmission.
    Default: [1.0, 1.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

environmentFile: string
    Set the path to the environment description file.
    Default: null

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

environmentAgeistAbsoluteRanges: [[int, int], ...]
    Set specific range(s) within which agents are considered in-group for age.
    Note: A value of -1 as the second element of an age range sets the value to the maximum possible age for agents.
    Note: Providing an empty list disables in-groups defined by specific age ranges.
    Default: []

environmentAgeistRelativeRange: int
    Set the value for which agents are considered in-group for age when within the specified number of timesteps in age to another agent.
    Note: Use -1 to disable.
    Default: -1

environmentInGroupRaces: [int, ...]
    Set which races are treated as in-group and do not experience racism from other agents.
    Note: Including all races neutralizes racism.
    Default: []

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

environmentMaxRaces: int
    Set the maximum number of races in the starting population.
    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

environmentSexistGroups: [string, ...]
    Set which sexes engage in sexism.
    Note: Empty array disables sexism.
    Default: []

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

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

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, int], ...]
    Set the coordinates and maximum sugar for sugar peaks in the environment.
    Default: [[15, 35, 4], [35, 15, 4]]

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: "ageInGroup", "ageRange" "depressed", "disease", "female", "male", "race", "raceInGroup", "sick", decision model names
    Note: Add an integer after "ageRange" such as "ageRange0" to track a specific age range.
    Note: Add an integer after "disease" such as "disease1" to track a specific disease.
    Note: Add an integer after "race" such as "race0" to track a specific race, otherwise use raceInGroup to track any race considered in-group.
    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.
    Options: "csv", "json"
    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"]]

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.
    Options: "combatHappiness", "deaths", "familyHappiness", "happiness", "healthHappiness", "lifeExpectancy", "population", "selfishness", "socialHappiness", "totalWealth", "ttl", "wealth", "wealthHappiness"
    Default: ["deaths", "giniCoefficient", "happiness", "lifeExpectancy", "population", "sickness", "tradeVolume", "ttl", "wealth"]

plotStatistic: string
    Set the statistic to use for plotting.
    Options: "mean", "median"
    Default: "mean"

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"