larvaworld.lib.sim.ABM_model

Basic Agent-based modeling classes

Classes

BasicABModel	Basic Class for the Agent-based model
ABModel	Basic Class for the Agent-based model

Module Contents

class larvaworld.lib.sim.ABM_model.BasicABModel(id: str = 'ABModel', parameters: Any | None = None, _run_id: Any | None = None, **kwargs: Any)

Basic Class for the Agent-based model Extends the agentpy Model class

p

type = 'BasicABModel'

id = 'ABModel'

t = 0

running = False

random

nprandom

reporters

output

classmethod as_function(**kwargs: Any)

Converts the model into a function that can be used with the ema_workbench library.

Arguments:

**kwargs: Additional keyword arguments that will passed

to the model in addition to the parameters.

Returns:

function:

The model as a function that takes parameter values as keyword arguments and returns a dictionary of reporters.

property info

report(rep_keys: Any, value: Any | None = None) → None

Reports a new simulation result. Reporters are meant to be ‘summary statistics’ or ‘evaluation measures’ of the simulation as a whole, and only one value can be stored per run. In comparison, variables that are recorded with Model.record() can be recorded multiple times for each time-step and object.

Arguments:

rep_keys (str or list of str):

Name(s) of the reporter(s) to be documented.

value (int or float, optional): Value to be reported.

The same value will be used for all rep_keys. If none is given, the values of object attributes with the same name as each rep_key will be used.

Examples:

Store a reporter x with a value 42:

model.report('x', 42)

Define a custom model that stores a reporter sum_id with the sum of all agent ids at the end of the simulation:

class MyModel(ap.Model):
    def setup(self):
        agents = ap.AgentList(self, self.p.agents)
    def end(self):
        self.report('sum_id', sum(self.agents.id))

Running an experiment over different numbers of agents for this model yields the following datadict of reporters:

>>> sample = ap.sample({'agents': (1, 3)}, 3)
>>> exp = ap.Experiment(MyModel, sample)
>>> results = exp.run()
>>> results.reporters
        sum_id
run_id
0            1
1            3
2            6

setup() → None

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

step() → None

Defines the model’s actions during each simulation step (excluding t==0). Can be overwritten to define the models’ main dynamics.

update() → None

Defines the model’s actions after each simulation step (including t==0). Can be overwritten for the recording of dynamic variables.

end() → None

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

set_parameters(parameters: Any) → None

Adds and/or updates the parameters of the model.

sim_setup(steps: Any | None = None, seed: Any | None = None) → None

Prepares time-step 0 of the simulation. Initiates (additional) steps and the two random number generators, and then calls Model.setup() and Model.update().

sim_step() → None

Proceeds the simulation by one step, incrementing Model.t by 1 and then calling Model.step() and Model.update().

sim_reset() → None

Reset model to initial conditions.

stop() → None

Stops Model.run() during an active simulation.

run(steps: Any | None = None, seed: Any | None = None)

Executes the simulation of the model. Can also be used to continue a partly-run simulation for a given number of additional steps.

It starts by calling Model.run_setup() and then calls Model.run_step() until the method Model.stop() is called or steps is reached. After that, Model.end() and Model.create_output() are called. The simulation results can be found in Model.output.

Arguments:

steps (int, optional):

Number of (additional) steps for the simulation to run. If passed, the parameter ‘Model.p.steps’ will be ignored. The simulation can still be stopped with :func:’Model.stop’.

seed (int, optional):

Seed to initialize the model’s random number generators. If none is given, the parameter ‘Model.p.seed’ is used. If there is no such parameter, a random seed will be used. For a partly-run simulation, this argument will be ignored.

display (bool, optional):

Whether to display simulation progress (default True).

Returns:

DataDict: Recorded variables and reporters.

create_output() → None

Generates a DataDict with dataframes of all recorded variables and reporters, which will be stored in Model.output.

class larvaworld.lib.sim.ABM_model.ABModel(**kwargs: Any)

Bases: BasicABModel, larvaworld.lib.reg.generators.SimConfigurationParams

Basic Class for the Agent-based model Extends the agentpy Model class