class Experiment(model_class, parameters=None, name=None, scenarios=None, iterations=1, record=False, **kwargs)[source]

Experiment for an agent-based model. Allows for multiple iterations, parameter samples, scenario comparison, and parallel processing. See Experiment.run() for standard simulations and Experiment.interactive() for interactive output.

  • model_class (type) – The model class type that the experiment should use.

  • parameters (dict or list of dict, optional) – Parameter dictionary or sample (default None).

  • name (str, optional) – Name of the experiment (default model.name).

  • scenarios (str or list, optional) – Experiment scenarios (default None).

  • iterations (int, optional) – Experiment repetitions (default 1).

  • record (bool, optional) – Whether to keep the record of dynamic variables (default False). Note that this does not affect evaluation measures.

  • **kwargs – Will be forwarded to the creation of every model instance during the experiment.


output (DataDict) – Recorded experiment data

interactive(plot, *args, **kwargs)[source]

Displays interactive output for Jupyter notebooks, using IPython and ipywidgets. A slider will be shown for varied parameters. Every time a parameter value is changed on the slider, the experiment will re-run the model and pass it to the ‘plot’ function.

  • plot – Function that takes a model instance as input and prints or plots the desired output..

  • *args – Will be forwarded to ‘plot’.

  • **kwargs – Will be forwarded to ‘plot’.


Interactive output widget

Return type



The following example uses a custom model MyModel and creates a slider for the parameters ‘x’ and ‘y’, both of which can be varied interactively over 10 different values. Every time a value is changed, the experiment will simulate the model with the new parameters and pass it to the plot function:

def plot(model):
    # Display interactive output here

param_ranges = {'x': (0, 10), 'y': (0., 1.)}
sample = ap.sample(param_ranges, n=10)
exp = ap.Experiment(MyModel, sample)
run(pool=None, display=True)[source]

Executes a multi-run experiment.

The simulation will run the model once for each set of parameters and will repeat this process for the set number of iterations. Parallel processing is possible if a pool is passed. Simulation results will be stored in Experiment.output.

  • pool (multiprocessing.Pool, optional) – Pool of active processes for parallel processing. If none is passed, normal processing is used.

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


Recorded experiment data.

Return type



To run a normal experiment:

exp = ap.Experiment(MyModel, parameters)
results = exp.run()

To use parallel processing:

import multiprocessing as mp
if __name__ ==  '__main__':
    exp = ap.Experiment(MyModel, parameters)
    pool = mp.Pool(mp.cpu_count())
    results = exp.run(pool)