KSLCore/ksl.app.config.experiment/ExperimentConfiguration

ExperimentConfiguration

@Serializable

data class ExperimentConfiguration(val outputConfig: OutputConfig = OutputConfig(), val modelReference: ModelReference, val factors: List<FactorSpec>, val designSpec: DesignSpec, val replications: ReplicationSpec = ReplicationSpec.Uniform(10), val executionMode: ExecutionMode = ExecutionMode.CONCURRENT, val streamPolicy: StreamPolicy = StreamPolicy.Independent(), val bundleRefs: List<BundleRef> = emptyList(), val tracingConfig: TracingConfig = TracingConfig(), val experimentOutput: ExperimentOutputSpec = ExperimentOutputSpec(), val runParameterOverrides: RunParameterOverridesSpec = RunParameterOverridesSpec())(source)

Serialisable experiment document — the input directive for a ksl.app.RunSpec.Experiment submission once the Experiment app is wired in Phase E4.

The document binds ONE model (via modelReference) to a set of factors (see factors) and a design that enumerates points from those factors (see designSpec). At submit time the engine glue (Phase E2) materialises a ParallelDesignedExperiment from this shape and hands it to the existing ExperimentOrchestrator.

Compare with ksl.app.config.RunConfiguration, which represents the Single / Scenario document shape (one or many user-authored scenarios per document, each picking its own model). Experiment documents are factor-centric: the user authors O(k) factors and the design enumerates O(2ᵏ) — sometimes far more — points.

Validation

Structural validation runs at init:

At least one factor.
Factor names are unique (case-sensitive).
When designSpec is TwoLevelFactorial or CentralComposite:

Every factor has exactly 2 levels.
If the chosen Fraction is Custom, the defining relations pass DefiningRelationValidator.
CentralComposite with rotatable axial spacing requires at least 2 factors.

Semantic validation (control bindings resolve against the model, factor levels lie within control ranges, group-theoretic validity of fractional generators) happens at submit time in Phase E2.

Constructors

ExperimentConfiguration

constructor(outputConfig: OutputConfig = OutputConfig(), modelReference: ModelReference, factors: List<FactorSpec>, designSpec: DesignSpec, replications: ReplicationSpec = ReplicationSpec.Uniform(10), executionMode: ExecutionMode = ExecutionMode.CONCURRENT, streamPolicy: StreamPolicy = StreamPolicy.Independent(), bundleRefs: List<BundleRef> = emptyList(), tracingConfig: TracingConfig = TracingConfig(), experimentOutput: ExperimentOutputSpec = ExperimentOutputSpec(), runParameterOverrides: RunParameterOverridesSpec = RunParameterOverridesSpec())

Properties

bundleRefs

val bundleRefs: List<BundleRef>

optional list of bundle JARs the modelReference depends on. Reused from ksl.app.config.BundleRef.

designSpec

val designSpec: DesignSpec

how the engine enumerates design points from factors. See DesignSpec.

executionMode

val executionMode: ExecutionMode

whether design points run sequentially (one at a time) or concurrently (parallel on the simulation dispatcher). Defaults to ExecutionMode.CONCURRENT — experiments typically benefit from parallel execution since design points are independent.

experimentOutput

val experimentOutput: ExperimentOutputSpec

factors

val factors: List<FactorSpec>

the factors whose levels the design explores. At least one required.

modelReference

val modelReference: ModelReference

the single model this experiment runs.

outputConfig

val outputConfig: OutputConfig

document-wide output settings — analysis name, database toggle and policy, CSV flags, report formats. Reused verbatim from ksl.app.config.OutputConfig.

replications

val replications: ReplicationSpec

per-point replication strategy — uniform or per-point overrides. Defaults to 10 replications per point.

runParameterOverrides

val runParameterOverrides: RunParameterOverridesSpec

streamPolicy

val streamPolicy: StreamPolicy

random-stream policy across design points. Defaults to StreamPolicy.Independent. Honoured under CONCURRENT only; SEQUENTIAL uses the model's own stream defaults.

tracingConfig

val tracingConfig: TracingConfig

animation / trace capture settings. Reused from ksl.app.config.TracingConfig.

Functions

materializeDesign

fun ExperimentConfiguration.materializeDesign(): ExperimentalDesignIfc

Materialise the experimental design alone — no model build, no database, no factor-binding resolution. Useful for previewing the enumerated design points in the GUI (Design tab "Materialize design points…" dialog). Honours the same per-point replications precedence rule as toDesignedExperiment.

toDesignedExperiment

fun ExperimentConfiguration.toDesignedExperiment(modelBuilder: ModelBuilderIfc, pathToOutputDirectory: Path, kslDatabase: KSLDatabase? = null, name: String? = null): DesignedExperimentIfc

Engine glue — build a runnable DesignedExperimentIfc from a serialised ExperimentConfiguration.