1.3 MultipleRuns

#Type Multiple Runs

The Multiple Runs type includes various model execution strategies that can be used by the modeller to compare the results of a model and analyse its behaviour in different scenarios.

When executed, it creates a new model for each parameter set combination defined by the selected strategy. Each of these models is executed using the TerraME modelling platform. The result is passed to one or more user defined output functions, which can be used to perform comparisons, storage, logging, etc. The return values of all the output functions are send in the class output. The MultipleRuns type also creates a folder for each of the executed simulations. Any files generated by the output functions are saved inside those folders. After this step the new instantiated model is discarded.

Output

This class returns a MultipleRuns table with the results organized as follows:

• simulations: A table of folder names, a folder is created for each model instance to save the output functions result. Its indexed by execution order.
• parameters: A table with parameters used to instantiate the model in this simulation. Also indexed by execution order.
• "output": A table with the return value of an output function. A different table is created for each of the output functions and its name depend on the user defined functions.

Input

• Complete Example:

import("calibration")
local MyModel = Model{
  x = Choice{-100, -1, 0, 1, 2, 100},
  y = Choice{min = 1, max = 10, step = 1},
  finalTime = 1,
  init = function(self)
    self.timer = Timer{
      Event{action = function()
        self.value = 2 * self.x ^2 - 3 * self.x + 4 + self.y
      end}
  }
  end
}
c = MultipleRuns{
  model = MyModel,
  strategy = "sample",
  quantity = 5,
  parameters = {
    x = Choice{-100, -1, 0, 1, 2, 100},
    y = Choice{min = 1, max = 10, step = 1},
    finalTime = 1
   },
  output = {"value"},
  additionalFunction = function(model)
    return model.value/2
  end
}

• quantity: Number of different runs to be executed in 'sample' strategy.
• repeat: Number of runs to be executed with the same parameters. Default value is 1.
• model: The model to be instantiated and executed several times.
• parameters: A table with the parameters to be tested and their range (the range must be a subset of the valid range for that parameter).
• output: An optional user defined table of model attributes. The values of these attributes, for each of the model executions, are returned in a table in the result of MultipleRuns.
• Additional functions: MultipleRuns also supports additional user-defined functions, such as output(). These functions also receives a Model instance after each simulation, to be created and passed as parameters to the multiple runs type. They may have any name the modeller chooses.
• folderName: Name or file path of the folder where the simulations' output will be saved.
• strategy: Strategy to be used when testing the model. See the list below:

Strategies:

• "factorial" Simulate the Model with all combinations of the argument parameters.
• "sample" Run the model with a random combination of the possible parameters & parameters.
• "selected" This should test the Model with a given set of parameters values. In this case, the argument parameters must be a named table, where each position is another table describing the parameters to be used in such simulation.

Examples

• Factorial Example:

 A Susceptible-Infected-Recovered (SIR) model with a public campaign. The
-- campaign asks the population to stop leaving home, which reduces the number of
-- contacts by half. It is activated whenever there are more than 1000
-- infected individuals in the population.
-- The full example is available inside the examples folder of the terrame package.
local m = MultipleRuns{
	model = SIR,
	strategy = "factorial",
	parameters = {
		policy = Choice{min = 100, max = 4000, step = 10},
	},
	max = function(model)
		return model.maxInfected
	end,
	susceptible = function(model)
		return model.susceptible
	end

}

This should run the model (4000-100)/10 times to test all the possibilities for the policy parameter

• Repeated Example:

local m = MultipleRuns{
	model = Fire,
	strategy = "repeated",
	quantity = 10,
	parameters = {
		empty = 0.3,
		dim = 30
	},
	forest = function(model)
		print(i)
		i = i + 1
		return model.cs:forest()
	end
}
sum = 0

forEachElement(m.forest, function(idx, value)
	sum = sum + value
end)

print("Average forest in the end of "..m.quantity.." simulations: "..sum / m.quantity)

This should run the model 10 times with the same parameters.

• Sample Example:

MultipleRuns{
  model = MyModel,
  strategy = "sample",
  parameters = {
    water = Choice{min = 10, max = 20, step = 1},
     rain = Choice{min = 10, max = 20, step = 2},
    finalTime = 10,
  },
  quantity = 5
}

This should run the model 5 times selecting random values from the defined parameters (if they are choice, otherwise use the only available value).

• Selected Example:

x = MultipleRuns{
  model = RainModel,
  strategy = "selected",
  parameters = {
    scenario1 = {water = 10, rain = 20, finalTime = 10},
     scenario2 = {water = 5, rain = 10, finalTime = 10}
  }
}