KSLCore/ksl.controls.experiments/Scenario

Scenario

class Scenario(val modelBuilder: ModelBuilderIfc, name: String, inputs: Map<String, Double> = emptyMap(), stringInputs: Map<String, String> = emptyMap(), jsonInputs: Map<String, String> = emptyMap(), runParameters: ExperimentRunParameters, modelConfiguration: Map<String, String>? = null, val modelConstructionMode: ScenarioModelConstructionMode = ScenarioModelConstructionMode.MODEL_BUILDER) : Identity(source)

A scenario is a specification of a model to run with a fixed set of inputs and run parameters. Each call to simulate produces a new SimulationRun.

In the context of running multiple scenarios it is important that scenario names are unique so that each experiment can be identified within a ksl.utilities.io.dbutil.KSLDatabase. The scenario name is used as the experiment name for the simulation run.

Model construction semantics

modelBuilder is called at the start of each simulate invocation to produce a fresh Model instance. This design enables concurrent execution of independent scenarios via ConcurrentScenarioRunner: each run is isolated and leaves no shared state behind.

For backward compatibility, constructors that accept a pre-built Model are provided. They wrap the supplied instance in a ModelBuilderIfc that always returns the same model, so the sequential behaviour is identical to the previous implementation.

Concurrency note: scenarios constructed via the model: Model backward-compatible constructors wrap a single shared model instance. They are safe for sequential execution via ScenarioRunner but must not be submitted to ConcurrentScenarioRunner, which requires each scenario to produce a fresh, independent Model on every simulate call.

Run-parameter semantics

scenarioRunParameters is an owned snapshot captured at construction time. All 15 fields of ExperimentRunParameters are stored. The snapshot's experiment name is automatically set to name.

At run time the snapshot is applied to the model via Model.changeRunParameters inside SimulationRunner.

Parameters

modelBuilder

Factory that creates the Model instance for each run.

name

The scenario name. Must be unique within the set of scenarios executed by a runner. Also used as the experiment name.

inputs

Numeric control and RV-parameter overrides (key → Double).

stringInputs

String control overrides (key → String).

jsonInputs

JSON control overrides (key → JSON String).

runParameters

Full experimental run configuration for this scenario.

modelConfiguration

Optional model configuration map forwarded to ModelBuilderIfc.build before each run.

Constructors

Scenario

constructor(modelBuilder: ModelBuilderIfc, name: String, inputs: Map<String, Double> = emptyMap(), stringInputs: Map<String, String> = emptyMap(), jsonInputs: Map<String, String> = emptyMap(), runParameters: ExperimentRunParameters, modelConfiguration: Map<String, String>? = null, modelConstructionMode: ScenarioModelConstructionMode = ScenarioModelConstructionMode.MODEL_BUILDER)

@JvmOverloads

constructor(model: Model, name: String, inputs: Map<String, Double> = emptyMap(), stringInputs: Map<String, String> = emptyMap(), jsonInputs: Map<String, String> = emptyMap(), runParameters: ExperimentRunParameters = model.extractRunParameters(), modelConfiguration: Map<String, String>? = null)

Backward-compatible constructor. The supplied model is wrapped so that each simulate call operates on the same instance.

@JvmOverloads

constructor(model: Model, name: String, inputs: Map<String, Double> = emptyMap(), numberReplications: Int, lengthOfReplication: Double = model.lengthOfReplication, lengthOfReplicationWarmUp: Double = model.lengthOfReplicationWarmUp, modelConfiguration: Map<String, String>? = null)

Convenience constructor for the common case where only the three scalar run-parameter values need to differ from model's current settings.

@JvmOverloads

constructor(modelBuilder: ModelBuilderIfc, name: String, inputs: Map<String, Double> = emptyMap(), numberReplications: Int, lengthOfReplication: Double, lengthOfReplicationWarmUp: Double = 0.0, modelConfiguration: Map<String, String>? = null)

Convenience constructor for use with a ModelBuilderIfc. The builder is invoked once at construction time to extract default run parameters; the returned model is then discarded. The three scalar values override the defaults.

Properties

inputs

val inputs: Map<String, Double>

Read-only view of the numeric control and RV-parameter overrides for this scenario. Used by runner classes that build the model and invoke SimulationRunner directly.

jsonInputs

val jsonInputs: Map<String, String>

Read-only view of the JSON control overrides for this scenario. Used by runner classes that build the model and invoke SimulationRunner directly.

lengthOfReplication

val lengthOfReplication: Double

Replication length configured for this scenario.

lengthOfReplicationWarmUp

val lengthOfReplicationWarmUp: Double

Warm-up length configured for this scenario.

modelBuilder

val modelBuilder: ModelBuilderIfc

modelConfiguration

val modelConfiguration: Map<String, String>?

The model configuration map forwarded to ModelBuilderIfc.build at run time, or null if no configuration was supplied at construction time. Used by runner classes that build the model directly.

modelConstructionMode

val modelConstructionMode: ScenarioModelConstructionMode

numberOfReplications

val numberOfReplications: Int

Number of replications configured for this scenario.

scenarioRunParameters

val scenarioRunParameters: ExperimentRunParameters

The run parameters that will be applied when this scenario is simulated. This is the scenario's owned snapshot — not the model's live state.

simulationRun

var simulationRun: SimulationRun?

The SimulationRun produced by the most recent call to simulate, or null if simulate has not yet been called.

stringInputs

val stringInputs: Map<String, String>

Read-only view of the string control overrides for this scenario. Used by runner classes that build the model and invoke SimulationRunner directly.

supportsConcurrentExecution

val supportsConcurrentExecution: Boolean

True when this scenario is not known to reuse a pre-built model instance.

Functions

simulate

fun simulate(): SimulationRun

Convenience method for standalone scenario execution.

toReport

fun Scenario.toReport(title: String = "Scenario ", confidenceLevel: Double = 0.95, showTimings: Boolean = false, block: ReportBuilder.() -> Unit = { scenario(this@toReport, confidenceLevel, showTimings) }): ReportNode.Document

Builds a ReportNode.Document containing a standalone scenario report via scenario.

useCommonRandomNumbers

fun useCommonRandomNumbers(): Scenario

Restores default common-random-number behavior for this scenario by clearing any pre-run sub-stream advance.

useStreamAdvance

fun useStreamAdvance(numberOfAdvances: Int): Scenario

Sets the number of sub-stream advances applied before this scenario runs.