KSLCore/ksl.controls.experiments/ScenarioRunner

ScenarioRunner

class ScenarioRunner @JvmOverloads constructor(name: String, scenarioList: List<Scenario> = emptyList(), val pathToOutputDirectory: Path = KSL.createSubDirectory(sanitizeForFilesystem(name) + "_OutputDir"), val kslDb: KSLDatabase? = KSLDatabase("${sanitizeForFilesystem(name)}.db", pathToOutputDirectory)) : Identity(source)

Facilitates the running of many scenarios in a sequence. Each scenario is treated like a different experiment and captures its inputs and results in a SimulationRun (exposed via observationsAsMap); an optional KSLDatabase persists those statistics. The scenarios can be based on the same or different models.

Parameters

name

of the scenario runner. By default, this name is used as the name of the database

scenarioList

a list of scenarios to execute

kslDb

optional KSLDatabase that persists the results from the scenarios; when null, no database is opened or written and results remain in-memory only

Constructors

ScenarioRunner

@JvmOverloads

constructor(name: String, scenarioList: List<Scenario> = emptyList(), pathToOutputDirectory: Path = KSL.createSubDirectory(sanitizeForFilesystem(name) + "_OutputDir"), kslDb: KSLDatabase? = KSLDatabase("${sanitizeForFilesystem(name)}.db", pathToOutputDirectory))

Properties

dbObservers

val dbObservers: List<KSLDatabaseObserver>

The database observers that were attached to the models. This property could be used to turn off all or some of the observers

kslDb

val kslDb: KSLDatabase?

pathToOutputDirectory

val pathToOutputDirectory: Path

scenarioList

val scenarioList: List<Scenario>

A read-only list of the scenarios to be run.

scenariosByName

val scenariosByName: Map<String, Scenario>

Functions

addScenario

@JvmOverloads

fun addScenario(model: Model, name: String, inputs: Map<String, Double>, runParameters: ExperimentRunParameters, stringInputs: Map<String, String> = emptyMap(), jsonInputs: Map<String, String> = emptyMap()): Scenario

Creates a Scenario from a full ExperimentRunParameters snapshot and adds it to this runner. Use this overload when you need to configure run parameters beyond the three scalar values (e.g. antithetic option, stream-reset behaviour, stream advances).

@JvmOverloads

fun addScenario(modelBuilder: ModelBuilderIfc, name: String, inputs: Map<String, Double>, runParameters: ExperimentRunParameters, stringInputs: Map<String, String> = emptyMap(), jsonInputs: Map<String, String> = emptyMap()): Scenario

Creates a Scenario from a ModelBuilderIfc and a full ExperimentRunParameters snapshot and adds it to this runner.

@JvmOverloads

fun addScenario(model: Model, name: String, inputs: Map<String, Double>, stringInputs: Map<String, String> = emptyMap(), jsonInputs: Map<String, String> = emptyMap(), numberReplications: Int = model.numberOfReplications, lengthOfReplication: Double = model.lengthOfReplication, lengthOfReplicationWarmUp: Double = model.lengthOfReplicationWarmUp): Scenario

Creates a Scenario from the three most common run-parameter scalars and adds it to this runner. All other run parameters are captured from model's current state. String and JSON control overrides may be supplied via stringInputs and jsonInputs.

databaseObserverByName

fun databaseObserverByName(name: String): KSLDatabaseObserver?

Gets the database observer by the scenario name or null if not there.

numReplicationsPerScenario

fun numReplicationsPerScenario(numReps: Int)

Sets a common number of replications for every scenario managed by this runner. Updates Scenario.scenarioRunParameters directly so that the model is not mutated and scenarios that share a model remain independent.

observationsAsMap

fun observationsAsMap(responseName: String): Map<String, DoubleArray>

Returns a map of scenario name → per-replication observations for responseName across all executed scenarios.

fun print()

Prints basic half-width summary reports for each scenario to the console

scenarioByName

fun scenarioByName(name: String): Scenario?

Gets the scenario by its name or null if not there.

simulate

@JvmOverloads

fun simulate(scenarios: IntProgression = myScenarios.indices, clearAllData: Boolean = true)

Interprets the integer progression as the indices of the contained scenarios that should be simulated. If the progression is not a valid index then no scenario is simulated.

toReport

fun ScenarioRunner.toReport(title: String = "Scenario Runner ", confidenceLevel: Double = 0.95, showTimings: Boolean = false, boxPlotResponses: List<String> = emptyList(), block: ReportBuilder.() -> Unit = { scenarioRunner(this@toReport, confidenceLevel, showTimings, boxPlotResponses) }): ReportNode.Document

Builds a ReportNode.Document containing a full scenario runner report via scenarioRunner.

useIndependentRandomStreams

@JvmOverloads

fun useIndependentRandomStreams(scenarios: IntProgression = myScenarios.indices, startingStreamAdvance: Int = 0, streamAdvanceSpacing: Int? = null)

Assigns non-overlapping pre-run sub-stream advances to selected scenarios.

write

@JvmOverloads

fun write(out: PrintWriter = KSL.out)

Writes basic half-width summary reports to the provided PrintWriter