The simulation in start.py

The best way to start creating a simulation is by copying the start.py file and other files from ‘abce/template’ in https://github.com/AB-CE/examples.

To see how to create a simulation read Interactive jupyter / IPython notebook Tutorial.

This is a minimal template for a start.py:

from agent import Agent
from abce import *


simulation = Simulation(name='ABCE')
agents = simulation.build_agents(Agent, 'agent', 2)
for r in range(100):
    simulation.advance_round(r)
    agents.one()
    agents.two()
    agents.three()
simulation.graphs()
class abce.Simulation(name='abce', random_seed=None, trade_logging='off', processes=1)[source]

Bases: object

This class in which the simulation is run. Actions and agents have to be added. databases and resource declarations can be added. Then runs the simulation.

Args:
name:
name of the simulation
random_seed (optional):
a random seed that controls the random number of the simulation
trade_logging:
Whether trades are logged,trade_logging can be ‘group’ (fast) or ‘individual’ (slow) or ‘off’
processes (optional):
The number of processes that run in parallel. Each process hosts a share of the agents. Default is all your logical processor cores times two, using hyper-threading when available. For easy debugging set processes to one and the simulation is executed without parallelization. Sometimes it is advisable to decrease the number of processes to the number of logical or even physical processor cores on your computer. ‘None’ for all processor cores times 2. For easy debugging set processes to 1, this way only one agent runs at a time and only one error message is displayed

Example:

simulation = Simulation(name='ABCE',
                        trade_logging='individual',
                        processes=None)

Example for a simulation:

num_firms = 5
num_households = 2000

w = Simulation(name='ABCE',
               trade_logging='individual',
               processes=None)

w.declare_round_endowment(resource='labor_endowment',
                          productivity=1,
                          product='labor')

w.panel('firm', command='after_sales_before_consumption')

firms = w.build_agents(Firm, 'firm', num_firms)
households = w.build_agents(Household, 'household', num_households)

all = firms + households

for r in range(100):
    self.advance_round(r)
    households.recieve_connections()
    households.offer_capital()
    firms.buy_capital()
    firms.production()
    if r == 250:
        centralbank.intervention()
    households.buy_product()
    all.after_sales_before_consumption()
    households.consume()

w.finalize()
w.graphs()
add_and_delete_agents(round)[source]
advance_round(time)[source]
aggregate(group, possessions=[], variables=[])[source]

aggregate(.) writes summary statistics of variables and possessions of a group of agents into the database, so that it is displayed in the gui. Aggregate must be declared before the agents are build. (‘agent_group’, ‘aggregate’) must be in the action_list, so that the simulation knows when to make the aggregate snapshot.

Args:
group:
can be either a group or ‘all’ for all agents
possessions (list, optional):
a list of all possessions you want to track as ‘strings’
variables (list, optional):
a list of all variables you want to track as ‘strings’

Example in start.py:

simulation_parameters.build_agents(Firm, 'firm', number=5)

...

simulation.aggregate('firm', possessions=['money', 'input'],
                     variables=['production_target',
                                'gross_revenue'])

for round in simulation.next_round():
    firms.produce_and_sell()
    firms.aggregate()
    households.buying()
build_agents(AgentClass, group_name, number=None, parameters={}, agent_parameters=None)[source]

This method creates agents.

Args:

AgentClass:
is the name of the AgentClass that you imported
group_name:
the name of the group, as it will be used in the action list and transactions. Should generally be lowercase of the AgentClass.
number:
number of agents to be created.
parameters:
a dictionary of parameters
agent_parameters:
a list of dictionaries, where each agent gets one dictionary. The number of agents is the length of the list

Example:

firms = simulation.build_agents(Firm, 'firm',
    number=simulation_parameters['num_firms'])
banks = simulation.build_agents(Bank, 'bank',
                                parameters=simulation_parameters,
                                agent_parameters=[{'name': UBS'},
                                {'name': 'amex'},{'name': 'chase'})

centralbanks = simulation.build_agents(CentralBank, 'centralbank',
                                       number=1,
                                       parameters={'rounds':
                                                    num_rounds})
declare_expiring(good, duration)[source]

This type of good lasts for several rounds, but eventually expires. For example computers would last for several years and than become obsolete.

Args:

good:
the good, which expires
duration:
the duration before the good expires
declare_perishable(good)[source]

This good only lasts one round and then disappears. For example labor, if the labor is not used today today’s labor is lost. In combination with resource this is useful to model labor or capital.

In the example below a worker has an endowment of labor and capital. Every round he can sell his labor service and rent his capital. If he does not the labor service for this round and the rent is lost.

Args:

good:
   the good that perishes

Example::

    w.declare_perishable(good='LAB')
    w.declare_perishable(good='CAP')
declare_round_endowment(resource, units, product, groups)[source]

At the beginning of very round the agent gets ‘units’ units of good ‘product’ for every ‘resource’ he possesses.

Round endowments are group specific, that means that when somebody except the specified group holds them they do not produce.

Args:

resource:
    The good that you have to hold to get the other

units:
    the multiplier to get the produced good

product:
    the good that is produced if you hold the first good

groups:
    a list of agent groups, which gain the second good,
    if they hold the first one

Example:

A farmer gets a ton of harvest for every acre:

w.declare_round_endowment(resource='land',
                          units=1000,
                          product='wheat')
declare_service(human_or_other_resource, units, service, groups=['all'])[source]

When the agent holds the human_or_other_resource, he gets ‘units’ of service every round the service can be used only with in this round.

Args:

human_or_other_resource:
    the good that needs to be in possessions to create the other
    good 'self.create('adult', 2)'
units:
    how many units of the service is available
service:
    the service that is created
groups:
    a list of agent groups that can create the service

Example:

For example if a household has two adult family members, it gets
16 hours of work

w.declare_service('adult', 8, 'work')
execute_advance_round_parallel(time)[source]
execute_advance_round_seriel(time)[source]
finalize()[source]

simulation.finalize() must be run after each simulation. It will write all data to disk

Example:

simulation = Simulation(...)
...
for r in range(100):
    simulation.advance_round(r)
    agents.do_something()
    ...

simulation.finalize()
graphs(open=True, new=1)[source]

after the simulation is run, graphs() shows graphs of all data collected in the simulation. Shows the same output as the @gui decorator shows.

Args:

open (True/False):
whether to open a new window
new:
If new is 0, the url is opened in the same browser window if possible. If new is 1, a new browser window is opened if possible. If new is 2, a new browser page (tab) is opened if possible.

Example:

simulation = Simulation(...)
for r in range(100):
    simulation.advance_round(r)
    agents.do_something()
    ...

simulation.graphs()
network(frequency=1, savefig=False, savegml=True, figsize=(24, 20), dpi=100, pos_fixed=False, alpha=0.8)[source]

network(.) prepares abce to write network data.

Args:
frequency:
the frequency with which the network is written, default=1
savefig:
wether to save a png file, default=False
savegml:
wether to save a gml file, default=True
figsize:
size of the graph in inch. (see matplotlib)
dpi:
resulution of the picture
pos_fixed:
positions are fixed after the first round

Example:

simulation.network(savefig=True)
panel(group, possessions=[], variables=[])[source]
panel(.) writes a panel of variables and possessions

of a group of agents into the database, so that it is displayed in the gui. Aggregate must be declared before the agents are build. (‘agent_group’, ‘panel’) must be in the action_list, so that the simulation knows when to make the aggregate snapshot.

Args:
group:
can be either a group or ‘all’ for all agents
possessions (list, optional):
a list of all possessions you want to track as ‘strings’
variables (list, optional):
a list of all variables you want to track as ‘strings’

Example in start.py:

simulation_parameters.build_agents(Firm, 'firm', number=5)

...

simulation.panel('firm', possessions=['money', 'input'],
                 variables=['production_target', 'gross_revenue'])

for round in simulation.next_round():
    firms.do('produce_and_sell)
    firms.do('panel')
    households.do('buying')
path = None

the path variable contains the path to the simulation outcomes it can be used to generate your own graphs as all resulting csv files are there.