Defining Batch Experiments

Batch experiments allow to execute numerous successive simulation runs. They are used to explore the parameter space of a model or to optimize a set of model parameters. Exploration methods are detailed in this page.

A Batch experiment is defined by:

experiment exp_title type: batch until: condition {
   [parameter to explore]
   [exploration method]
   [reflex]
   [permanent]
}

Table of contents

• The batch experiment facets
• Action _step_ and reflexes
• Permanent

The batch experiment facets

Batch experiments have the following three facets:

• until: (expression) Specifies when to stop each simulation. Its value is a condition on variables defined in the model. The run will stop when the condition is evaluated to true. If omitted, the first simulation run will go forever, preventing any subsequent run to take place (unless a halt command is used in the model itself).
• repeat: (integer) A parameter configuration corresponds to a set of values assigned to each parameter. The attribute repeat specifies the number of times each configuration will be repeated, meaning that as many simulations will be run with the same parameter values. Different random seeds are given to the pseudo-random number generator. This allows to get some statistical power from the experiments conducted. The default value is 1.
• keep_seed: (boolean) If true, the same series of random seeds will be used from one parameter configuration to another. The default value is false.

experiment my_batch_experiment type: batch repeat: 5 keep_seed: true until: (cycle = 300) {
   [parameter to explore]
   [exploration method]
}

Action _step_ and reflexes

As for any species, experiment can define as many reflex as needed. In a batch experiment, they will be executed at the end of each bunch of simulations (set of replications) for a given parameters configuration. Note that at the experiment level, you have access to all the species and all the global variables and to all the simulations (variable simulations).

To be complete, in fact, each experiment (as any agent) will call at each step (i.e. the end of the replications set) the _step_ action: this action is in charge of executing the behavior of the experiment agent, that is by default the execution of each of its reflex. So it is also possible to redefine the action _step_, but it will inhibit the reflexes.

For instance, the following experiment runs the simulation 5 times, and, at the end of the 5 simulations, saves the people agents in a shapefile.

experiment 'Run 5 simulations' type: batch repeat: 5 keep_seed: true until: ( time > 1000 ) {
    int cpt <- 0;

    reflex save_people {
	save people type:"shp" to:"people_shape" + cpt + ".shp" with: [is_infected::"INFECTED", is_immune::"IMMUNE"];
	cpt <- cpt + 1;
    }
}

The same can be done using the action _step_ { instead of reflex save_people {.

But if now we want to save information from the 5 simulations as save 1 shapefile per replication or save aggregated values over the five simulations, we need to use the built-in attribute simulations.

To save 1 shapefile per simulation run, we thus need to write:

experiment 'Run 5 simulations' type: batch repeat: 5 keep_seed: true until: ( time > 1000 ) {
    reflex end_of_runs {
	int cpt <- 0;
	ask simulations {
	    save people type: "shp" to: "result/people_shape" + cpt + ".shp" with: [is_infected::"INFECTED", is_immune::"IMMUNE"];
	    cpt <- cpt + 1;
	}
    }
}

If now we want to save in a file the average number of infected people over the five simulations.

experiment 'Run 5 simulations' type: batch repeat: 5 keep_seed: true until: ( cycle > 1000 ) {
    reflex t {
        save [cycle, simulations mean_of each.nb_infected] to: "result.txt" type: "csv";
    }
}

Permanent

The permanent statement allows the modeler to define an output block that will not be re-initialized at the beginning of each simulation but will be filled at the end of each simulation. For instance, this permanent section will plot for each simulation the end value of the food_gathered variable (defined as a global variable in the model).

permanent {
    display Ants background: #white refresh: every(1#cycle) {
	chart "Food Gathered" type: series {
	    data "Food" value: food_gathered;
	}
    }
}