Experiments

class Experiment(model_class, sample=None, iterations=1, record=False, randomize=True, **kwargs)[source]

Experiment that can run an agent-based model over for multiple iterations and parameter combinations and generate combined output data.

Parameters

  • model (type) – The model class for the experiment to use.

  • sample (dict or list of dict or Sample, optional) – Parameter combination(s) to test in the experiment (default None).

  • iterations (int, optional) – How often to repeat every parameter combination (default 1).

  • record (bool, optional) – Keep the record of dynamic variables (default False).

  • randomize (bool, optional) – Generate different random seeds for every iteration (default True). If True, the parameter ‘seed’ will be used to initialize a random seed generator for every parameter combination in the sample. If False, the same seed will be used for every iteration. If no parameter ‘seed’ is defined, this option has no effect. For more information, see Randomness and reproducibility .

  • **kwargs – Will be forwarded to all model instances created by the experiment.

Variables

output (DataDict) – Recorded experiment data

end()[source]

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

run(n_jobs=1, pool=None, display=True, **kwargs)[source]

Perform the experiment. The simulation will run the model once for each set of parameters and will repeat this process for the set number of iterations. Simulation results will be stored in Experiment.output. Parallel processing is supported based on joblib.Parallel().

Parameters

  • n_jobs (int, optional) – Number of processes to run in parallel (default 1). If 1, no parallel processing is used. If -1, all CPUs are used. Will be forwarded to joblib.Parallel().

  • pool (multiprocessing.Pool, optional) – [This argument is depreciated. Please use ‘n_jobs’ instead.] Pool of active processes for parallel processing. If none is passed, normal processing is used.

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

  • **kwargs – Additional keyword arguments for joblib.Parallel().

Returns

Recorded experiment data.

Return type

DataDict

Examples

To run a normal experiment:

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

To use parallel processing on all CPUs with status updates:

exp = ap.Experiment(MyModel, parameters)
results = exp.run(n_jobs=-1, verbose=10)