KSLCore/ksl.app.config.experiment

Package-level declarations

Types

AxialSpacing

@Serializable

sealed class AxialSpacing

Axial spacing (α) for a central composite design.

ControlBinding

@Serializable

sealed class ControlBinding

How a FactorSpec's level value is applied to the model. Two variants: bind to a named model control, or bind to a single parameter of a named random variable.

DefiningRelationValidator

object DefiningRelationValidator

Syntactic validator for the words of a custom-fraction two-level design (see Fraction.Custom).

DesignSpec

@Serializable

sealed class DesignSpec

Specifies how the engine should enumerate design points from the document's factors. Four families that mirror the construction APIs in ksl.controls.experiments:

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())

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

ExperimentConfigurationToml

object ExperimentConfigurationToml

TOML codec for ExperimentConfiguration.

ExperimentOutputSpec

@Serializable

data class ExperimentOutputSpec(val usePerPointSubdirs: Boolean = false)

Experiment-app-specific output preferences. Distinct from the shared OutputConfig (which carries analysisName, database policy, report formats — all common across the Single / Scenario / Experiment apps). Lives at the top level of ExperimentConfiguration so the field doesn't pollute the shared OutputConfig with experiment-only concerns.

FactorSpec

@Serializable

data class FactorSpec(val name: String, val levels: List<Double>, val binding: ControlBinding)

One factor in a designed experiment.

Fraction

@Serializable

sealed class Fraction

Selection of which subset of a full 2^k design to enumerate. Used by DesignSpec.TwoLevelFactorial.fraction and by DesignSpec.CentralComposite.factorialFraction (which can build a fractional core inside a CCD).

ManualCsvImportResult

sealed class ManualCsvImportResult

Outcome of parseManualCsv. Either a list of parsed points or a list of human-readable error messages (everything that could be flagged in one pass is reported at once, so the user sees the full picture instead of getting one error per attempt).

ManualPointSpec

@Serializable

data class ManualPointSpec(val factorValues: Map<String, Double>, val replications: Int? = null)

One design point in a DesignSpec.Manual design.

ReplicationSpec

@Serializable

sealed class ReplicationSpec

How many replications each design point should run. Two variants: uniform (every point runs the same count) or per-point (a default plus an index-keyed override map).

RunParameterOverridesSpec

@Serializable

data class RunParameterOverridesSpec(val lengthOfReplication: Double? = null, val lengthOfReplicationWarmUp: Double? = null)

Document-level overrides for the model's baked-in simulation run parameters. Each field is optional; null means "inherit whatever the model author set" (the substrate's default behaviour). When non-null, the value replaces the model's setting on every design point's effective run parameters.

StreamPolicy

@Serializable

sealed class StreamPolicy

Random-stream policy for the design points in an experiment. Maps to ksl.controls.experiments.DesignPointRandomStreamPolicy at submit time (Phase E2).

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.

parseManualCsv

fun parseManualCsv(file: File, factors: List<FactorSpec>): ManualCsvImportResult

Parse a CSV in the shape that the Experiment app's design-points preview Export produces (and that the Custom design-points tab's Import consumes). Substrate-level helper so any host (Swing, web, CLI) can drive the same parser.

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.