KSLCore/ksl.app.config

Package-level declarations

Types

@Serializable

data class BundleRef(val paths: List<String> = emptyList(), val bundleId: String)

A document-level reference to a bundle JAR. Used by the Scenario-app workflow (and by the analogous Single / Experiment workflows) to declare which bundle JARs a ksl.app.config.RunConfiguration depends on, so the runtime can load each one and route per-scenario (bundleId, modelId) references against the resulting registry.

CaptureLevel

@Serializable

enum CaptureLevel : Enum<CaptureLevel>

Controls the volume of animation events captured during a run.

DatabasePolicy

@Serializable

enum DatabasePolicy : Enum<DatabasePolicy>

How the ScenarioOrchestrator should handle an existing <analysisName>.db file at the start of a Simulate. Stored on OutputConfig.databasePolicy.

ExecutionMode

@Serializable

enum ExecutionMode : Enum<ExecutionMode>

Whether the scenarios in a ksl.app.config.RunConfiguration run one at a time or in parallel. Per scenario workflow §10:

ExperimentRunOverrides

@Serializable

data class ExperimentRunOverrides(val numberOfReplications: Int? = null, val numChunks: Int? = null, val startingRepId: Int? = null, val lengthOfReplication: Double? = null, val lengthOfReplicationWarmUp: Double? = null, val replicationInitializationOption: Boolean? = null, val maximumAllowedExecutionTimePerReplication: Duration? = null, val resetStartStreamOption: Boolean? = null, val advanceNextSubStreamOption: Boolean? = null, val antitheticOption: Boolean? = null, val numberOfStreamAdvancesPriorToRunning: Int? = null, val garbageCollectAfterReplicationFlag: Boolean? = null)

Partial-override counterpart to ksl.controls.experiments.ExperimentRunDefaults.

ModelReference

@Serializable

sealed class ModelReference

Serialisable pointer to a model source.

ModelRunTemplate

@Serializable

data class ModelRunTemplate(val modelReference: ModelReference, val modelConfiguration: Map<String, String>? = null, val runParameters: ExperimentRunParameters, val controls: ModelControlsExport = ModelControlsExport(modelName = ""), val rvOverrides: List<RVParameterOverride> = emptyList())

Serializable model-construction template for app-layer workflows that need configured model instances without depending on a full RunConfiguration.

ModelRunTemplateJson

object ModelRunTemplateJson

JSON codec for ModelRunTemplate.

ModelRunTemplateToml

object ModelRunTemplateToml

TOML codec for ModelRunTemplate.

OutputConfig

@Serializable

data class OutputConfig(val enableKSLDatabase: Boolean = false, val enableReplicationCSV: Boolean = false, val enableExperimentCSV: Boolean = false, val reports: Set<ReportFormat> = setOf(ReportFormat.HTML), val outputDirectory: String? = null, val analysisName: String = "Untitled", val databasePolicy: DatabasePolicy = DatabasePolicy.OVERWRITE)

Per-run output choices: which side-effects the framework wires before the run starts and which reports it materializes after the run completes.

ReportFormat

@Serializable

enum ReportFormat : Enum<ReportFormat>

Report renderings the framework can materialize from a completed run's SimulationSnapshot. Used as the set-valued field ksl.app.config.OutputConfig.reports.

RunConfiguration

@Serializable

data class RunConfiguration(val outputConfig: OutputConfig = OutputConfig(), val executionMode: ExecutionMode = ExecutionMode.SEQUENTIAL, val tracingConfig: TracingConfig = TracingConfig(), val scenarios: List<ScenarioSpec> = emptyList(), val bundleRefs: List<BundleRef> = emptyList())

Serialisable scenarios document — the input directive for a ksl.app.RunSpec.Scenarios (or RunSpec.Single) submission.

RunConfigurationJson

object RunConfigurationJson

JSON codec for RunConfiguration.

RunConfigurationToml

object RunConfigurationToml

TOML codec for RunConfiguration.

RVParameterOverride

@Serializable

data class RVParameterOverride(val rvName: String, val paramName: String, val value: Double)

A human-authored override for a single random-variable parameter.

ScenarioSpec

@Serializable

data class ScenarioSpec(val name: String, val modelReference: ModelReference, val runOverrides: ExperimentRunOverrides? = null, val controlOverrides: ModelControlsExport = ModelControlsExport(modelName = ""), val rvOverrides: List<RVParameterOverride> = emptyList(), val modelConfiguration: Map<String, String>? = null, val skipOnRun: Boolean = false, val enableReplicationCSV: Boolean = false, val enableExperimentCSV: Boolean = false)

Serialisable specification for a single scenario in a scenarios document.

TracingConfig

@Serializable

data class TracingConfig(val animationTraceFile: String? = null, val captureLevel: CaptureLevel = CaptureLevel.MINIMAL, val flushEveryNEvents: Int = 1000)

Animation trace capture settings embedded in a RunConfiguration.

Functions

analysisNameFromFileStem

fun analysisNameFromFileStem(path: Path, currentName: String, sentinel: String = "Untitled", sanitizer: (String) -> String = { it }): String?

Once-at-default auto-fill helper for markSaved paths in configuration-shaped apps: derive a fresh analysis name from a just-saved file's stem, but only when the current analysisName is still at its default sentinel.

sanitizeAnalysisName

fun sanitizeAnalysisName(raw: String): String

Coerce raw into a filesystem-safe form suitable for both a directory name and a database file stem. Replaces any character outside [A-Za-z0-9_-] with _, trims the result to at most 64 characters, and returns "Untitled" when the coerced form is empty (for example, when the user typed only whitespace).

toOverrides

fun ExperimentRunParameters.toOverrides(): ExperimentRunOverrides

Captures every model-intrinsic field of this ExperimentRunParameters as a fully-populated ExperimentRunOverrides block (12 of the 15 fields; the runtime-identity triple experimentName / experimentId / runName is intentionally omitted because those fields belong to a run, not to a document).