Agent-based models

class Model(parameters=None, run_id=None, scenario=None, **kwargs)

An agent-based model that can hold environments and agents.

This class can be used as a parent class for custom models. Class attributes can be accessed like dictionary items. To define the procedures of a simulation, override the methods Model.setup(), Model.step(), Model.update(), and Model.end(). See Model.run() for more information on the simulation procedure.

Variables

• name (str) – The models’ name.

• envs (EnvList) – The models’ environments.

• agents (AgentList) – The models’ agents.

• p (AttrDict) – The models’ parameters.

• t (int) – Current time-step of the model.

• log (dict) – The models’ recorded variables.

• output (DataDict) – Output data after simulation.

Parameters

• parameters (dict, optional) – Dictionary of model parameters. Recommended types for parameters are int, float, str, list, numpy.integer, numpy.floating, and numpy.ndarray. Other types might cause errors.

• run_id (int, optional) – Number of current run (default None).

• scenario (str, optional) – Current scenario (default None).

• **kwargs – Will be forwarded to Model.setup()

add_agents(agents=1, agent_class=<class 'agentpy.objects.Agent'>, **kwargs)

Adds agents to the environment.

Parameters

• agents (int or AgentList, optional) – Either number of new agents to be created or list of existing agents (default 1).

• agent_class (type, optional) – Type of new agents to be created if int is passed for agents (default Agent).

• **kwargs – Forwarded to Agent.setup() if new agents are created (i.e. if an integer number is passed to agents).

Returns

List of the new agents.

Return type

AgentList

add_env(env_class=<class 'agentpy.objects.Environment'>, **kwargs)

Creates a new environment.

add_grid(shape, **kwargs)

Creates a new environment with a spatial grid. Arguments are forwarded to Grid.

add_network(graph=None, agents=None, **kwargs)

Creates a new environment with a network. Arguments are forwarded to Network.

end()

Defines the model’s actions after the last simulation step. Can be overwritten and used for final calculations and measures.

property env

The objects first environment.

get_obj(obj_id)

Return model object with obj_id (int).

measure(measure, value)

Records an evaluation measure.

property objects

The models agents and environments (list of objects).

record(var_keys, value=None)

Records an objects variables.

Parameters

• var_keys (str or list of str) – Names of the variables to be recorded.

• value (optional) – Value to be recorded. The same value will be used for all var_keys. If none is given, the values of object attributes with the same name as each var_key will be used.

Examples

Record the existing attributes x and y of an object a:

a.record(['x', 'y'])

Record a variable z with the value 1 for an object a:

a.record('z', 1)

Record all variables of an object:

a.record(a.var_keys)

remove_agents(agents)

Removes agents from the environment.

run(steps=None, seed=None, display=True)

Executes the simulation of the model.

The simulation proceeds as follows. It starts by calling Model.setup() and Model.update(). After that, Model.t is increased by 1 and Model.step() and Model.update() are called. This step is repeated until the method Model.stop() is called or steps is reached. After the last step, Model.end() is called.

Parameters

• steps (int, optional) – Maximum number of steps for the simulation to run. If none is given, the parameter ‘Model.p.steps’ will be used. If there is no such parameter, ‘steps’ will be set to 1000.

• seed (int, optional) – Seed to set for random at the beginning of the simulation. If none is given, the parameter ‘Model.p.seed’ will be used. If there is no such parameter, no custom seed will be set.

• display (bool, optional) – Whether to display simulation progress (default True).

Returns

Recorded model data, which can also be found in Model.output.

Return type

DataDict

setup(**kwargs)

Defines the model’s actions before the first simulation step. Can be overwritten and used to initiate agents and environments.

step()

Defines the model’s actions during each simulation step. Can be overwritten and used to set the models’ main dynamics.

stop()

Stops Model.run() during an active simulation.

property type

Class name of the object (str).

update()

Defines the model’s actions after setup and each simulation step. Can be overwritten and used for the recording of dynamic variables.

property var_keys

The object’s variables (list of str).