KSLCore/ksl.controls

Package-level declarations

Types

@Serializable

data class ControlData(val controlType: ControlType, val value: Double, val keyName: String, val lowerBound: Double = Double.NEGATIVE_INFINITY, val upperBound: Double = Double.POSITIVE_INFINITY, val elementName: String, val elementId: Int, val elementType: String, val propertyName: String, val comment: String, val modelName: String, val parentElementName: String? = null, val parentElementId: Int? = null, val parentElementType: String? = null, val elementPath: List<String> = emptyList())

A data class for transferring the data associated with a control.

ControlIfc

interface ControlIfc

A control represents an element within a model that can be changed by the user. Every control has a type (DOUBLE, INTEGER, LONG, FLOAT, SHORT, BYTE, BOOLEAN). The user can set the value of the control. If the supplied value is not within the allowed range of the control, the value will be limited to within the range. If the user assigns the value of the control to less than the lower bound, then the value is set to the lower bound. If the user assigns the value greater than the upper bound, then the value is set at the upper bound. For example, suppose the lower bound of the control is 1.0 and the upper bound is 10.0. Setting the control value to 0.0 will set the control to 1.0. Setting the control value to 12.0 will set the control to 10.0. Thus, out-of-range values are not permitted and corrected (silently). The limitToRange() function can be used to inspect the value that will result if the control is set to the supplied value.

ControlImportResult

data class ControlImportResult(val successCount: Int, val failures: List<ControlUpdateException>, val missingKeys: List<String> = emptyList())

Summary result returned by Controls.importAll and Controls.importAllFromJson.

Controls

class Controls(aModel: Model)

Holds all controls associated with a model instance, across three parallel families:

ControlType

enum ControlType : Enum<ControlType>

Defines the set of valid control types. The valid types are (DOUBLE, INTEGER, LONG, FLOAT, SHORT, BYTE, BOOLEAN). All control types are ultimately coerced to type Double, with BOOLEAN mapping true to 1.0 and false to 0.0.

ControlUpdateException

class ControlUpdateException(message: String, val controlKey: String, val attemptedValue: String, cause: Throwable? = null) : RuntimeException

Thrown when a JsonControlIfc or StringControlIfc cannot apply an incoming value.

ControlValueDoubleSerializer

object ControlValueDoubleSerializer : NullTolerantDoubleSerializer

Decodes a null control value as +∞ — the only non-finite value a real control carries (an EventGenerator's "run forever" initialEndingTime). A control value of -∞ or NaN does not occur in practice, so mapping null to +∞ round-trips every real control exactly.

JsonControlData

@Serializable

data class JsonControlData(val keyName: String, val jsonValue: String, val typeHint: String, val elementName: String, val elementId: Int, val elementType: String, val propertyName: String, val comment: String, val modelName: String, val parentElementName: String? = null, val parentElementId: Int? = null, val parentElementType: String? = null, val elementPath: List<String> = emptyList())

A data-transfer object carrying the state of a single JsonControlIfc.

JsonControlIfc

interface JsonControlIfc

Represents a JSON-valued simulation control extracted from a property annotated with KSLJsonControl.

KSLControl

@Inherited

@Target(allowedTargets = [AnnotationTarget.PROPERTY_SETTER])

annotation class KSLControl(val controlType: ControlType, val name: String = "", val lowerBound: Double = Double.NEGATIVE_INFINITY, val upperBound: Double = Double.POSITIVE_INFINITY, val comment: String = "", val include: Boolean = true)

A KSLControl annotation is used on the setter method of properties within model elements to indicate that those properties should be used to control the execution of the simulation model. The annotation field type must be supplied and must be one of the valid control types as specified by the enum ControlType. The user is responsible for making sure that the type field matches (or is consistent with) the type of the property. Even though the optional annotation fields (lowerBound and upperBound) are specified as double values, they will be converted to an appropriate value for the specified type. Boolean properties are represented as a 1.0 (true) and 0.0 (false) within the numerical conversion for the controls. If a control is BOOLEAN, then the user can supply a 1.0 to represent true and a 0.0 to represent false when setting the control, which will then be set to true or false, appropriately.

KSLJsonControl

@Inherited

@Target(allowedTargets = [AnnotationTarget.PROPERTY_SETTER])

annotation class KSLJsonControl(val expectedTypeHint: String = "", val name: String = "", val comment: String = "", val include: Boolean = true)

Marks a property setter as a JSON-valued simulation control.

KSLStringControl

@Inherited

@Target(allowedTargets = [AnnotationTarget.PROPERTY_SETTER])

annotation class KSLStringControl(val allowedValues: Array<String> = [], val name: String = "", val comment: String = "", val include: Boolean = true)

Marks a property setter as a string-valued simulation control.

LowerBoundDoubleSerializer

object LowerBoundDoubleSerializer : NullTolerantDoubleSerializer

Decodes a null lower bound as -∞ (unbounded below).

ModelControlsExport

@Serializable

data class ModelControlsExport(val modelName: String, val numericControls: List<ControlData> = emptyList(), val stringControls: List<StringControlData> = emptyList(), val jsonControls: List<JsonControlData> = emptyList())

A serializable snapshot of all controls extracted from a model instance, spanning all three control families.

NullTolerantDoubleSerializer

sealed class NullTolerantDoubleSerializer(whenNull: Double) : KSerializer<Double>

A Double serializer that tolerates a JSON null on decode, mapping it to whenNull, while keeping the field a non-nullable Double.

StringControlData

@Serializable

data class StringControlData(val keyName: String, val value: String, val allowedValues: List<String>, val elementName: String, val elementId: Int, val elementType: String, val propertyName: String, val comment: String, val modelName: String, val parentElementName: String? = null, val parentElementId: Int? = null, val parentElementType: String? = null, val elementPath: List<String> = emptyList())

A data-transfer object carrying the state of a single StringControlIfc.

StringControlIfc

interface StringControlIfc

Represents a string-valued simulation control extracted from a property annotated with KSLStringControl.

UpperBoundDoubleSerializer

object UpperBoundDoubleSerializer : NullTolerantDoubleSerializer

Decodes a null upper bound as +∞ (unbounded above).