ParallelDesignedExperiment

class ParallelDesignedExperiment @JvmOverloads constructor(name: String, modelBuilder: ModelBuilderIfc, factorSettings: Map<Factor, String>, val design: ExperimentalDesignIfc, val modelConfiguration: Map<String, String>? = null, val pathToOutputDirectory: Path = KSL.createSubDirectory(name.replace(" ", "_") + "_OutputDir"), val kslDb: KSLDatabase = KSLDatabase("${name}.db".replace(" ", "_"), pathToOutputDirectory), experimentName: String? = null, useDesignPointOutputDirs: Boolean = true, lengthOfReplication: Double? = null, lengthOfReplicationWarmUp: Double? = null) : Identity, DesignedExperimentIfc(source)

Parameters

experimentName

Optional override for the base experiment name used to derive per-design-point experiment names ("DP") and the matching output-directory names. When null (the default), the base name comes from the template model's auto-generated Experiment_<counter> identity — which is JVM-counter-driven and changes between runs. Callers that want deterministic, human-readable per- point names (e.g. the Experiment app: anchored to the analysis name) should pass an explicit value. Persists to EXPERIMENT.exp_name in the KSL database, so the column values match the on-disk folder / file names.

useDesignPointOutputDirs

When true (the default, preserving the original behaviour), every design point gets its own subdirectory under pathToOutputDirectory named <experimentName>_DP_<n>_OutputDir; each subdir contains that point's kslOutput.txt (and any per-point CSV / plot artifacts the model writes). When false, every per-point model writes directly into pathToOutputDirectory and the diagnostic log uses a point-distinguished filename (kslOutput_DP_<n>.txt) so concurrent writers don't clash and re-runs overwrite cleanly. False is the right default for callers that rely on the kslDb for per-point results.

Constructors

Link copied to clipboard
constructor(name: String, modelBuilder: ModelBuilderIfc, factorSettings: Map<Factor, String>, design: ExperimentalDesignIfc, modelConfiguration: Map<String, String>? = null, pathToOutputDirectory: Path = KSL.createSubDirectory(name.replace(" ", "_") + "_OutputDir"), kslDb: KSLDatabase = KSLDatabase("${name}.db".replace(" ", "_"), pathToOutputDirectory), experimentName: String? = null, useDesignPointOutputDirs: Boolean = true, lengthOfReplication: Double? = null, lengthOfReplicationWarmUp: Double? = null)
constructor(name: String, modelBuilder: ModelBuilderIfc, twoLevelSettings: Map<TwoLevelFactor, String>, design: TwoLevelFactorialDesign, modelConfiguration: Map<String, String>? = null, pathToOutputDirectory: Path = KSL.createSubDirectory(name.replace(" ", "_") + "_OutputDir"), kslDb: KSLDatabase = KSLDatabase("${name}.db".replace(" ", "_"), pathToOutputDirectory))

Convenience constructor for two-level factor setting maps.

constructor(name: String, modelCreator: () -> Model, factorSettings: Map<Factor, String>, design: ExperimentalDesignIfc, modelConfiguration: Map<String, String>? = null, pathToOutputDirectory: Path = KSL.createSubDirectory(name.replace(" ", "_") + "_OutputDir"), kslDb: KSLDatabase = KSLDatabase("${name}.db".replace(" ", "_"), pathToOutputDirectory))

Convenience constructor for a function that creates a fresh model.

Properties

Link copied to clipboard

A default value for the number of replications per design point.

Link copied to clipboard
open override val design: ExperimentalDesignIfc

The experimental design associated with the executed design points.

Link copied to clipboard
Link copied to clipboard
Link copied to clipboard
open override val numSimulationRuns: Int

The number of design points that have been executed.

Link copied to clipboard
Link copied to clipboard
open override val responseNames: List<String>

The names of the responses or counters in the template model.

Link copied to clipboard
open override val simulationRuns: List<SimulationRun>

Returns the executed runs, one run for each design point simulated.

Link copied to clipboard

The active design-point random stream policy.

Functions

Link copied to clipboard

Request cancellation of the design point with the given 1-based pointId. If that point's coroutine is currently running (or queued) it will be cancelled; the resulting outcome carries wasCancelled = true so the commit phase fires onDesignPointCancelled instead of treating it as a failure, and skips the database write entirely.

Link copied to clipboard

Clears previously executed simulation runs.

Link copied to clipboard
open override fun observationsAsMap(responseName: String): Map<String, DoubleArray>

Returns a map of design-point label to per-replication observations for responseName.

Link copied to clipboard
fun regressionData(responseName: String, linearModel: LinearModel, coded: Boolean = true): RegressionData

Returns regression data for the supplied response and linear model.

Link copied to clipboard
fun regressionDataAsDataFrame(responseName: String, linearModel: LinearModel, coded: Boolean = true): AnyFrame

Returns regression data as a dataframe for the supplied response and linear model.

Link copied to clipboard
fun regressionResults(responseName: String, linearModel: LinearModel): RegressionResultsIfc
open override fun regressionResults(responseName: String, linearModel: LinearModel, coded: Boolean): RegressionResultsIfc

Performs OLS regression for the supplied response and linear model.

Link copied to clipboard

Returns replicated design point information in execution order as a data frame.

Link copied to clipboard
Link copied to clipboard
fun replicatedDesignPointsAsDataFrame(coded: Boolean = false): AnyFrame

Returns a data frame with columns (point, exp_name, rep_id, factor1, factor2, ..., factorN).

Link copied to clipboard
fun replicatedDesignPointsWithResponse(responseName: String, coded: Boolean = false): AnyFrame

Returns a data frame with one response joined to replicated design points.

Link copied to clipboard
fun replicatedDesignPointsWithResponses(names: Set<String> = responseNames.toSet(), coded: Boolean = false): AnyFrame

Returns a data frame with selected responses joined to replicated design points.

Link copied to clipboard
fun responseAsDataFrame(responseName: String): AnyFrame

Returns a data frame with columns (point, exp_name, rep_id, responseName).

Link copied to clipboard
fun resultsToCSV(fileName: String = name.replace(" ", "_") + ".csv", directory: Path = KSLFileUtil.createSubDirectory(pathToOutputDirectory, "csv"), coded: Boolean = false)

Writes the joined design-point and response results to a CSV file.

Link copied to clipboard
suspend fun simulate(iterator: Iterator<DesignPoint>, numRepsPerDesignPoint: Int? = null, clearRuns: Boolean = true, addRuns: Boolean = true, clearAllData: Boolean = true, onDesignPointComplete: (designPoint: DesignPoint, snapshot: SimulationSnapshot.ExperimentCompleted?) -> Unit? = null, onDesignPointStart: (designPoint: DesignPoint) -> Unit? = null, onDesignPointCancelled: (designPoint: DesignPoint) -> Unit? = null, onDesignPointReplications: (experimentName: String, replications: List<SimulationSnapshot.ReplicationCompleted>) -> Unit? = null)

Simulates the design points presented by iterator concurrently.

Link copied to clipboard
suspend fun simulateAll(numRepsPerDesignPoint: Int? = null, clearRuns: Boolean = true, addRuns: Boolean = true, clearAllData: Boolean = true, onDesignPointComplete: (designPoint: DesignPoint, snapshot: SimulationSnapshot.ExperimentCompleted?) -> Unit? = null, onDesignPointStart: (designPoint: DesignPoint) -> Unit? = null, onDesignPointCancelled: (designPoint: DesignPoint) -> Unit? = null, onDesignPointReplications: (experimentName: String, replications: List<SimulationSnapshot.ReplicationCompleted>) -> Unit? = null)

Simulates all design points concurrently.

Link copied to clipboard

Makes every design point start from the same random stream block.

Link copied to clipboard
fun useIndependentRandomStreams(startingStreamAdvance: Int = 0, streamAdvanceSpacing: Int? = null): ParallelDesignedExperiment

Assigns non-overlapping pre-run sub-stream advances to design points.