diff options
Diffstat (limited to 'opendc-harness/src/main/kotlin/org/opendc/harness/api')
4 files changed, 151 insertions, 0 deletions
diff --git a/opendc-harness/src/main/kotlin/org/opendc/harness/api/ExperimentDefinition.kt b/opendc-harness/src/main/kotlin/org/opendc/harness/api/ExperimentDefinition.kt new file mode 100644 index 00000000..88b26ee1 --- /dev/null +++ b/opendc-harness/src/main/kotlin/org/opendc/harness/api/ExperimentDefinition.kt @@ -0,0 +1,39 @@ +/* + * Copyright (c) 2020 AtLarge Research + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +package org.opendc.harness.api + +/** + * A definition for a repeatable experiment which consists of multiple scenarios derived from pre-defined experiment + * parameters. + * + * @property name The name of the experiment. + * @property parameters The parameters of the experiments. + * @property evaluator The function to evaluate a single experiment trial. + * @property meta The metadata for the experiment. + */ +public data class ExperimentDefinition( + val name: String, + val parameters: Set<Parameter<*>>, + val evaluator: (Trial) -> Unit, + val meta: Map<String, Any> = emptyMap() +) diff --git a/opendc-harness/src/main/kotlin/org/opendc/harness/api/Parameter.kt b/opendc-harness/src/main/kotlin/org/opendc/harness/api/Parameter.kt new file mode 100644 index 00000000..bb5c8c2b --- /dev/null +++ b/opendc-harness/src/main/kotlin/org/opendc/harness/api/Parameter.kt @@ -0,0 +1,38 @@ +/* + * Copyright (c) 2020 AtLarge Research + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +package org.opendc.harness.api + +/** + * A [Parameter] defines a single dimension of exploration in the design space of an experiment. + */ +public sealed class Parameter<T> { + /** + * The name of the parameter. + */ + public abstract val name: String + + /** + * A generic dimension of the experiment design space that is defined fully by a collection of [values]. + */ + public data class Generic<T>(override val name: String, val values: Collection<T>) : Parameter<T>() +} diff --git a/opendc-harness/src/main/kotlin/org/opendc/harness/api/Scenario.kt b/opendc-harness/src/main/kotlin/org/opendc/harness/api/Scenario.kt new file mode 100644 index 00000000..a8dbf01e --- /dev/null +++ b/opendc-harness/src/main/kotlin/org/opendc/harness/api/Scenario.kt @@ -0,0 +1,46 @@ +/* + * Copyright (c) 2021 AtLarge Research + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +package org.opendc.harness.api + +/** + * A [Scenario] represents a single point in the design space of an experiment. + */ +public interface Scenario { + /** + * A unique identifier that identifies a single scenario. + */ + public val id: Int + + /** + * The [ExperimentDefinition] describing the experiment this scenario is part of. + */ + public val experiment: ExperimentDefinition + + /** + * Obtain the instantiated value for a [parameter][param] of the experiment. + * + * @param param The parameter to obtain the value of. + * @throws IllegalArgumentException if [param] is not defined for the experiment. + */ + public operator fun <T> get(param: Parameter<T>): T +} diff --git a/opendc-harness/src/main/kotlin/org/opendc/harness/api/Trial.kt b/opendc-harness/src/main/kotlin/org/opendc/harness/api/Trial.kt new file mode 100644 index 00000000..2d6ecd19 --- /dev/null +++ b/opendc-harness/src/main/kotlin/org/opendc/harness/api/Trial.kt @@ -0,0 +1,28 @@ +/* + * Copyright (c) 2021 AtLarge Research + * + * Permission is hereby granted, free of charge, to any person obtaining a copy + * of this software and associated documentation files (the "Software"), to deal + * in the Software without restriction, including without limitation the rights + * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + * copies of the Software, and to permit persons to whom the Software is + * furnished to do so, subject to the following conditions: + * + * The above copyright notice and this permission notice shall be included in all + * copies or substantial portions of the Software. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + * SOFTWARE. + */ + +package org.opendc.harness.api + +/** + * A [Trial] represents a single trial (run) of an experiment. + */ +public data class Trial(val scenario: Scenario, val repeat: Int) |