KSLCore/ksl.app.session/RunEvent

RunEvent

Sealed lifecycle event hierarchy emitted on RunHandle.events during a simulation run.

Event sequence guarantees

For every submitted run exactly one terminal event is emitted as the final event on the flow: RunCompleted, RunCancelled, or RunFailed. No further events are emitted after a terminal event.

Each execution path emits its own concrete "started" variant — see Started — followed by orchestrator-specific progress events:

per-replication runs (Runner / SingleRunOrchestrator) emit ReplicationRunStarted then ReplicationStarted / ReplicationEnded pairs;
scenario sweeps (ScenarioOrchestrator) emit ScenarioRunStarted then one ScenarioCompleted per scenario;
designed experiments (ExperimentOrchestrator) emit ExperimentRunStarted then one DesignPointCompleted per point;
simulation optimization (OptimizationOrchestrator) emits OptimizationRunStarted then one IterationCompleted per iteration.

A typical successful per-replication run produces:

[RunWarning]?                  (zero or more, emitted before the run starts)
ReplicationRunStarted
ReplicationStarted(1)
ReplicationEnded(1)
ReplicationStarted(2)
ReplicationEnded(2)
...
RunCompleted(summary)          ← terminal

What these events do NOT carry

These events are lifecycle-only and carry no statistical observations. Per-replication and across-replication statistics live in the output sinks the user configured on the model (database, CSV, in-memory responses) and are accessed through normal KSL APIs after RunCompleted is received.

Inheritors

ScenarioReplicationStarted

ScenarioReplicationEnded

ScenarioReplicationsCompleted

Constructors

RunEvent

protected constructor()

Types

DesignPointCompleted

data class DesignPointCompleted(val pointId: Int, val index: Int, val totalDesignPoints: Int, val snapshot: SimulationSnapshot.ExperimentCompleted?, val wasCancelled: Boolean = false) : RunEvent

Emitted by ExperimentOrchestrator after each design point completes.

DesignPointStarted

data class DesignPointStarted(val pointId: Int, val index: Int, val totalDesignPoints: Int, val startTime: Instant) : RunEvent

Emitted by ParallelDesignedExperiment immediately before each design-point coroutine begins its model build + run. Lets consumers track per-design-point state (PENDING → RUNNING) before the corresponding DesignPointCompleted event arrives.

ExperimentRunStarted

data class ExperimentRunStarted(val runId: String, val modelIdentifier: String, val totalDesignPoints: Int, val startTime: Instant) : RunEvent.Started

Emitted once by ExperimentOrchestrator immediately before the designed experiment begins, after any pre-run warnings.

IterationCompleted

data class IterationCompleted(val iteration: Int, val bestInputs: Map<String, Double>, val estimatedObjectiveValue: Double, val solverSpecificState: Map<String, Double>? = null) : RunEvent

Emitted by OptimizationOrchestrator after each solver iteration completes.

OptimizationRunStarted

data class OptimizationRunStarted(val runId: String, val modelIdentifier: String, val maxIterations: Int, val startTime: Instant) : RunEvent.Started

Emitted once by OptimizationOrchestrator immediately before solver iteration begins, after any pre-run warnings.

ReplicationEnded

data class ReplicationEnded(val repNumber: Int, val totalReplications: Int) : RunEvent

Emitted by Runner immediately after model.runNextReplication() returns for replication repNumber.

ReplicationRunStarted

data class ReplicationRunStarted(val runId: String, val modelIdentifier: String, val totalReplications: Int, val startTime: Instant) : RunEvent.Started

Emitted once by Runner immediately after model.initializeReplications() on the per-replication execution path used by SingleRunOrchestrator.

ReplicationStarted

data class ReplicationStarted(val repNumber: Int, val totalReplications: Int) : RunEvent

Emitted by Runner immediately before model.runNextReplication() is called for replication repNumber.

RunCancelled

data class RunCancelled(val reason: String) : RunEvent

Terminal event — emitted when the run is stopped by an explicit call to RunHandle.cancel. Always the last event on the flow.

RunCompleted

data class RunCompleted(val summary: RunSummary) : RunEvent

Terminal event — emitted when the run ends normally (all replications completed, execution-time limit reached, or the model stopped itself via endSimulation()). Always the last event on the flow.

RunFailed

data class RunFailed(val error: KSLRuntimeError) : RunEvent

Terminal event — emitted when an unexpected exception is thrown during replication execution. Always the last event on the flow.

RunWarning

data class RunWarning(val warning: RunWarningType) : RunEvent

Emitted when a potentially problematic configuration is detected before the run starts. Does not prevent the run from proceeding; the receiving GUI or test driver should surface it to the user.

ScenarioCompleted

data class ScenarioCompleted(val scenarioName: String, val index: Int, val totalScenarios: Int, val snapshot: SimulationSnapshot.ExperimentCompleted?) : RunEvent

Emitted by ScenarioOrchestrator after each scenario completes (or fails).

ScenarioReplicationEnded

data class ScenarioReplicationEnded(val scenarioName: String, val repNumber: Int, val totalReplications: Int) : RunEvent

Emitted by ScenarioOrchestrator immediately after scenario scenarioName finishes replication repNumber. Counterpart to ScenarioReplicationStarted.

ScenarioReplicationsCompleted

data class ScenarioReplicationsCompleted(val scenarioName: String, val index: Int, val totalScenarios: Int) : RunEvent

Emitted by ScenarioOrchestrator the moment a scenario successfully finishes its replications — i.e. its in-memory simulation has completed cleanly but the per-scenario commit to KSLDatabase has not yet run. Sits between ScenarioReplicationEnded (per-replication) and ScenarioCompleted (post-commit) in the per-scenario event timeline.

ScenarioReplicationStarted

data class ScenarioReplicationStarted(val scenarioName: String, val repNumber: Int, val totalReplications: Int) : RunEvent

Emitted by ScenarioOrchestrator immediately before scenario scenarioName begins replication repNumber. Carries the same payload as ReplicationStarted but tagged with the scenario name, so multi-scenario consumers (the Scenario app's GUI in particular) can attribute per-replication progress to the right row.

ScenarioRunStarted

data class ScenarioRunStarted(val runId: String, val modelIdentifier: String, val totalScenarios: Int, val startTime: Instant) : RunEvent.Started

Emitted once by ScenarioOrchestrator immediately before the scenario sweep begins, after any pre-run warnings.

ScenarioStarted

data class ScenarioStarted(val scenarioName: String, val index: Int, val totalScenarios: Int) : RunEvent

Emitted by ScenarioOrchestrator when an individual scenario's simulation begins. Under ksl.app.config.ExecutionMode.SEQUENTIAL scenarios start one at a time; under ksl.app.config.ExecutionMode.CONCURRENT every scenario emits this event before any of them begin replications.

SimTimeAdvanced

data class SimTimeAdvanced(val simTime: Double, val eventsExecuted: Long) : RunEvent

Carries the current simulation clock value and event execution count.

Started

sealed class Started : RunEvent

Sealed parent of every "the run has started" event.

StdOutLine

data class StdOutLine(val text: String, val fromErr: Boolean) : RunEvent

One line of output captured from System.out or System.err while a GUI host (e.g. kslSingleApp(...)) had its Capture stdout toggle enabled. The framework itself does not emit these — they are injected by the host's capture machinery into the host's console pipeline so user println output appears alongside framework events. Listeners that filter on framework lifecycle events should ignore this variant.