KSLCore/ksl.modeling.decision.descriptor

Package-level declarations

Types

CounterRef

@Serializable

@SerialName(value = "counter")

data class CounterRef(val name: String) : SourceRef

A reward source that is a Counter.

DecisionSurfaceDescriptor

@Serializable

data class DecisionSurfaceDescriptor(val schemaVersion: SchemaVersion = SchemaVersion(), val name: String, val observations: List<ObservationDescriptor>, val levers: List<LeverDescriptor>, val constraints: List<JointConstraint> = emptyList(), val rewards: List<RewardDescriptor> = emptyList(), val episode: EpisodeDescriptor = EpisodeDescriptor(), val feasibility: FeasibilityPolicy = FeasibilityPolicy.REJECT)

The complete description of one element's decision surface — what it may read, what it may write, what it is scored on, and when it decides.

EpisodeDescriptor

@Serializable

data class EpisodeDescriptor(val maxEpochs: Int = Int.MAX_VALUE, val hasTerminalCondition: Boolean = false)

How a decision episode can end, besides the replication ending underneath it.

EpochProvenance

enum EpochProvenance : Enum<EpochProvenance>

Where the state on a transition row was read (S§C.11.3).

FeasibilityPolicy

enum FeasibilityPolicy : Enum<FeasibilityPolicy>

What the element does with an action outside a lever's feasible range.

JointConstraint

@Serializable

sealed interface JointConstraint

A budget over several levers — the constraint that makes a multi-lever action a joint choice rather than several independent ones (§4.4.6).

LeverDescriptor

@Serializable

data class LeverDescriptor(val name: String, val domain: LeverDomain, val kind: LeverKind = LeverKind.SETTING, val modelLowerLimit: Double, val modelUpperLimit: Double, val lowerBound: Double, val upperBound: Double, val stateDependent: Boolean = false, val levels: List<String>? = null, val unit: String? = null)

One declared lever: what a rule may write, and what the ith entry of an action vector means. Order is significant, as for observations.

LeverDomain

enum LeverDomain : Enum<LeverDomain>

What values a lever can take, which decides how an out-of-range request may be repaired.

LeverKind

enum LeverKind : Enum<LeverKind>

What a lever is, distinguished by the only thing the machinery needs to tell apart: what it means to do nothing (§8.2.2, §8.2.3).

ObservationDescriptor

@Serializable

data class ObservationDescriptor(val name: String, val domain: LeverDomain = LeverDomain.CONTINUOUS, val unit: String? = null)

One declared observation: what a rule may read, and what the ith entry of an observation vector means. Order is significant — the position in the descriptor's list is the position in the array (§4.2.3).

ResponseRef

@Serializable

@SerialName(value = "response")

data class ResponseRef(val name: String) : SourceRef

A reward source that is a Response or TWResponse.

RewardDescriptor

@Serializable

data class RewardDescriptor(val name: String, val source: SourceRef, val kind: RewardKind, val rate: Double, val sense: RewardSense)

One declared reward term: (source, kind, rate, sense).

RewardKind

enum RewardKind : Enum<RewardKind>

How a reward source accumulates, which is the one thing the epoch algorithm must know about it and the only place in the design that knows the three sources differ (§4.2.5).

RewardSense

enum RewardSense : Enum<RewardSense>

Whether a declared term is something to maximise or something to minimise.

SchemaVersion

@Serializable

data class SchemaVersion(val major: Int = 2, val minor: Int = 0)

The version of the descriptor's own format, carried so a stored description can say what it was written by. It is the schema's version, not the model's and not the library's.

SchemaVersionException

class SchemaVersionException(message: String) : RuntimeException

A stored description whose SchemaVersion this library cannot read.

SourceRef

@Serializable

sealed interface SourceRef

A reference to the model quantity a reward term reads, by name and by what kind of thing it is.

SumAtMost

@Serializable

@SerialName(value = "sumAtMost")

data class SumAtMost(val names: List<String>, val total: Double) : JointConstraint

The named levers may sum to at most total — a ceiling that need not be reached.

SumEquals

@Serializable

@SerialName(value = "sumEquals")

data class SumEquals(val names: List<String>, val total: Double) : JointConstraint

The named levers must sum to exactly total — a fixed pool that is entirely allocated.

TerminationSource

enum TerminationSource : Enum<TerminationSource>

Why a decision episode ended — recorded on every emitted transition, because that it ended is not enough to interpret the last row (§4.6.3).

WarmUpOrdering

enum WarmUpOrdering : Enum<WarmUpOrdering>

Which runs first when a decision epoch coincides with the element's warm-up (§4.6.4).

Properties

DESCRIPTOR_SCHEMA_VERSION

val DESCRIPTOR_SCHEMA_VERSION: SchemaVersion

The descriptor format this library writes, and the one it understands.

Functions

fromJson

fun DecisionSurfaceDescriptor.Companion.fromJson(text: String): DecisionSurfaceDescriptor

Parse a descriptor from JSON produced by toJson.

fromToml

fun DecisionSurfaceDescriptor.Companion.fromToml(text: String): DecisionSurfaceDescriptor

Parse a descriptor from TOML produced by toToml.

toJson

fun DecisionSurfaceDescriptor.toJson(): String

Serialize this descriptor to JSON.

toToml

fun DecisionSurfaceDescriptor.toToml(): String

Serialize this descriptor to TOML.

validationProblems

fun DecisionSurfaceDescriptor.validationProblems(): List<String>

Every way this descriptor fails to describe a surface a model could have declared, or an empty list if it describes one.