{"data":{"markdownRemark":{"html":"

The RunnerBackend and ModelRunner classes need to be used together to setup and run a simulation that can run multiple times.

\n

This guide assumes you have a Model created which implements simudyne.core.Model\nThe following imports are assumed

\n

Imports required for multirun (Java)

\n
import simudyne.core.exec.runner.ModelRunner;\nimport simudyne.core.exec.runner.RunResult;\nimport simudyne.core.exec.runner.RunnerBackend;
\n

The RunnerBackend class is needed to set up the ModelRunner. The default RunnerBackend can be created by using the RunnerBackend create method. This will create an instance of the RunnerBackend that can be used to run the model locally.

\n

Create a model runner (Java)

\n
RunnerBackend runnerBackend = RunnerBackend.create();
\n

Create the ModelRunner for a specific model with RunnerBackend#forModel passing the class of the model or RunnerBackend#forConfig passing the ModelConfiguration for the model

\n

Create a model runner for a specific model (Java)

\n
ModelRunner modelRunner = runnerBackend.forModel(myModel.class);
\n

Setting up the multirun

\n

Use the ModelRunner to create 'definitions' which define the parameters of the multiruns, as well as the export path to be used and config to set for all runs.

\n

Settings for a ModelRun

\n
modelRunner\n    .forExportPath(\"Some/absolute/path\")\n    .withConfig(\"configField\", \"configValue\");
\n

ModelRunner Definitions

\n

There are three types of ModelRunner Definitions that can be used.

\n\n

BatchDefinitionsBuilder

\n

This is used to run a model multiple times for a set number of ticks. A single set of inputs can be specified that will be applied to all runs before setup.

\n

The default data output for batch runs.

\n\n

Define the parameters for the Batch run by creating an instance of BatchDefinitionsBuilder and setting this instance as the run definition to use for the model runner.

\n
  BatchDefinitionsBuilder runDefinitionBuilder = \n    BatchDefinitionsBuilder.create()\n    .forRuns(100) // a required field, must be greater than 0.\n    .forTicks(50) // a required field, must be greater than 0.\n    .withInput(\"preference\", 0.75) // can be used as many or little times depending on how many input fields you want to specify.\n    .forGeneratorSeed(467854386543L); // This is an optional field - if set, this will be the root seed that is used to set the seeds for the individual runs. If not set, the seed will be pulled from the Simudyne SDK properties file.\n    \n  modelRunner.forRunDefinitionBuilder(runDefinitionBuilder)
\n

Setting input values for variables in custom objects, or variables in the global state is more complex. This is explained further below (Setting nested input values).

\n

The seeds can also be defined for the individual runs. If specifying the seeds for the runs, the number of seeds provided must match the number of runs specified.

\n
  BatchDefinitionsBuilder runDefinitionBuilder = \n    BatchDefinitionsBuilder.create()\n    .forRuns(3) // a required field, must be greater than 0.\n    .forTicks(50) // a required field, must be greater than 0.\n    .forSeeds(2344, 95846, 474654);    \n\n  modelRunner.forRunDefinitionBuilder(runDefinitionBuilder)
\n

ModelSamplerDefinitionsBuilder

\n

This is used to run a model multiple times, for a set number of ticks. The input fields can be set for the individual runs by drawing from a list of samples.

\n

The data output for model sampler runs

\n\n

The sample input values to use can be generated by the SDK by providing the SDK with the bounds for your input fields to generate samples for, or they can be provided by the user.

\n

SDK generated samples

\n
  ModelSamplerDefinitionsBuilder runDefinitionsBuilder =\n    ModelSamplerDefinitionsBuilder.create()\n    .forRuns(5)\n    .forTicks(100)\n    .forSamples(9)\n    .withBoundedDimension(\"gridSize\", 12, 100)\n    .withBoundedDimension(\"price\", 0.2, 0.5);\n\n  modelRunner.forRunDefinitionBuilder(runDefinitionBuilder)
\n

This will generate 9 integer samples between the values of 12 and 100 to apply to the gridSize field, and 9 double samples between the values of 0.2 and 0.5 to apply to the price field when running the model. Each sample set will be run for 5 runs, so this configuration will run for a total of 45 runs.

\n

User specified samples

\n
  ModelSamplerDefinitionsBuilder runDefinitionsBuilder =\n    ModelSamplerDefinitionsBuilder.create()\n    .forRuns(100)\n    .forTicks(100)\n    .withListedDimension(\"gridSize\", 12, 34, 67, 34, 100)\n    .withListedDimension(\"price\", 0.1, 0.2, 0.3, 0.4, 0.5);\n\n  modelRunner.forRunDefinitionBuilder(runDefinitionBuilder)
\n

This will pair up the samples provided for gridSize and price so that we have 5 unique sample definitions, and run each of these sample defintions 100 times, for a total of 500 runs.

\n

The seeds for the runs can either be set by setting the generator seed which will be used to create the seeds for the individual runs, or by providing a list of seeds explicitly.

\n

Full Example:

\n
  ModelSamplerDefinitionsBuilder runDefinitionsBuilder =\n    ModelSamplerDefinitionsBuilder.create()\n    .forRuns(3)\n    .forTicks(100)\n    .withListedDimension(\"gridSize\", 12, 34, 67)\n    .withListedDimension(\"price\", 0.1, 0.2, 0.3)\n    .forSeeds(123,345,678);\n\n  modelRunner.forRunDefinitionBuilder(runDefinitionBuilder)
\n

This will create the following set of runs.

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
seedgridSizeprice
123120.1
123340.2
123670.3
345120.1
345340.2
345670.3
678120.1
678340.2
678670.3
\n

The ModelSampler cannot be used to set input fields of global state fields.

\n

ScenarioDefinitionsBuilder

\n

This is used to build a set of scenarios for running the model, where every scenario defines input values that can be set at various ticks throughout the model.

\n

The data output for model sampler runs:

\n\n

Multiple scenarios can be built using the builder, with each scenario requiring a unique name, and the ending of each scenario definition being marked with done()

\n
  ScenarioDefinitionsBuilder runDefinitionsBuilder =\n    ScenarioDefinitionsBuilder.create()\n      .createScenario(\"firstScenario\").done()\n      .createScenario(\"secondName\").done();\n\n  modelRunner.forRunDefinitionBuilder(runDefinitionBuilder)
\n

Once created, each scenario can be setup with the runs, seeds, ticks and inputs to use when running the model, as with batch runs. Differently to the the batch runs, the scenario runs can also have the input values specified to be applied before running various ticks of the model.

\n
  ScenarioDefinitionsBuilder runDefinitionsBuilder =\n    ScenarioDefinitionsBuilder.create()\n      .createScenario(\"firstScenario\")\n        .forRuns(5)\n        .forTicks(50)\n        .withInput(\"griSize\", 8, 1000)\n        .done();\n\n  modelRunner.forRunDefinitionBuilder(runDefinitionBuilder)
\n

This will set the value of gridSize to 1000 before running tick 8.

\n

Setting input values for variables in custom objects, or variables in the global state is more complex. This is explained further below (Setting nested input values).

\n

Running the multirun

\n

ModelRunner.run will return a MultirunController, which is a view onto the async running simulation. This can be used to cancel the simulation, check its progress, and get the output of the simulation.

\n
MultirunController run = modelRunner.run();\n\nrun.cancelRun(); // This will cancel the run\n\nrun.getProgress(); // This returns a value between 0 and 1 which reflects the progress of the simulation\n\nrun.awaitOutput(); // Block and wait for the simulation to complete and all output to be written to file\nrun.asyncOutput(); // This returns the future that can be used to track the completion of writing all output data to file.\n\nrun.asyncResult();// This returns the future that can be used to track the run.\nRunResult runResult = run.awaitResult(); // This returns the run results object (explained below)
\n

To understand the RunResult output, see Multirun Output

\n
\n

Improving multirun performance

\nThe multirun results are stored in memory to be returned to the user. If only the file output matters, this behaviour can be disabled in order to improve performance by setting the config field 'core.return-data' to false.\n

To read more on flags and configuration, see Model Config.

\n

If this field is set to false, the returned RunResult will be empty.

\n
\n

Running a distributed multirun

\n

Using Spark

\n

Running a distributed multirun simulation depends on different packages and imports.

\n

These elements can be found in the spark requirement tutorial and the spark runner tutorial tutorials.

\n

To setup a distributed multirun, create a new instance of the SparkRunnerBackend as the RunnerBackend. All other methods are the same as for the local RunnerBackend.

\n

Multirun with spark (Java)

\n
RunnerBackend runnerBackend = new SparkRunnerBackend();\nModelRunner modelRunner = runnerBackend.forModel(myModel.class);
\n

Extracting information from the RunResult is explained in Multirun Output

\n

Setting nested input values

\n

When the input fields are nested objects, as is the case with fields inside the global state, setting the input values is slightly more complicated.\nA Map of key-values needs to be used to as the value for the input field.

\n

For example, if there is a field \"fillFactor\" inside the global state object, setting this field would work as follows.

\n
 HashMap<String, Object> valueMap = new HashMap<>();\n    valueMap.put(\"fillFactor\", 0.55);\n\n    RunnerBackend.create()\n        .forModel(GameOfLife.class)\n        .forRunDefinitionBuilder(\n            BatchDefinitionsBuilder.create().forRuns(2).forTicks(2).withInput(\"system\", valueMap))\n        .run();
\n

The input field has a name \"system\" (the outer field name for all global state values), and the value set for \"system\" is actually a Map, which has a key \"fillFactor\" and the value to set for it.

","headings":[{"value":"Setting up the multirun","depth":2},{"value":"ModelRunner Definitions","depth":2},{"value":"BatchDefinitionsBuilder","depth":3},{"value":"ModelSamplerDefinitionsBuilder","depth":3},{"value":"ScenarioDefinitionsBuilder","depth":3},{"value":"Running the multirun","depth":2},{"value":"Running a distributed multirun","depth":1},{"value":"Using Spark","depth":2},{"value":"Setting nested input values","depth":2}],"frontmatter":{"title":"Multirun Setup","toc":null,"experimental":null}},"site":{"siteMetadata":{"title":"Simudyne Docs","latestVersion":"2.6"}}},"pageContext":{"absolutePath":"/home/vsts/work/1/s/content/2.4/reference/run_mode/multirun_setup.md","versioned":true,"version":"2.4","kind":"reference","pagePath":"/reference/run_mode/multirun_setup","chronology":{"prev":{"name":"Run Mode","path":"/reference/run_mode"},"next":{"name":"Multirun Output","path":"/reference/run_mode/multirun_output"}},"lastUpdated":"2026-04-21T13:56:54.853Z"}}