KSLCore/ksl.modeling.supplychain.spec

Package-level declarations

Types

data class BuildResult(val supplyChainModel: SupplyChainModel, val network: MultiEchelonNetwork, val itemsByName: Map<String, ItemType>, val nodesByName: Map<String, NetworkNodeIfc>)

The result of SupplyChainBuilder.build: the running MultiEchelonNetwork plus the handles a caller needs to post-mutate it (the v1 escape hatch for custom carriers, backlog policies, delivery endpoints, RULE formation, and custom cost formulations).

CostFormulationSpec

@Serializable

sealed class CostFormulationSpec

Serializable description of a cost formulation to attach to the network. A NetworkSpec may carry several (a comparative study on one simulation — see the cost-redesign doc's multi-attach support). The builder constructs and attaches each one last, after the topology is final, satisfying the cost-formulation ordering and coverage guards.

CostParamsSpec

@Serializable

data class CostParamsSpec(val carryingRate: Double = 0.1, val backorderRate: Double = 0.0, val orderingCost: Double = 5.5, val unloadingCost: Double = 30.0, val loadingCost: Double = 40.0, val shippingCost: Double = 15.0, val stockoutCost: Double = 0.0, val lostSaleCost: Double = 0.0, val unitShortageCost: Double = 0.0, val esLoadingCost: Double = 40.0)

Serializable twin of the framework's CostParams. Kept separate from the runtime type so the runtime CostParams stays free of serialization annotations. The builder (D5) constructs a CostParams from these fields.

DemandGeneratorSpec

@Serializable

data class DemandGeneratorSpec(val node: String, val itemTypeName: String, val interArrival: RVSpec, val name: String? = null, val transportTime: RVSpec? = null, val shipmentFormation: ShipmentFormationSpec? = null)

Serializable description of a customer-demand arrival process at a node.

FormingOption

enum FormingOption : Enum<FormingOption>

Per-edge shipment-formation forming option, mirroring the framework's DemandLoadBuilder.LoadFormingOption — minus RULE, which carries a user-supplied function and cannot be serialized (use the v1 escape hatch: build the spec, then install the rule in Kotlin).

InventoryScope

class InventoryScope

Configures the policy and initial stock of one inventory.

InventorySpec

@Serializable

data class InventorySpec(val itemTypeName: String, val policy: PolicySpec, val initialOnHand: Int)

Serializable description of one inventory (one item type) held at a node.

ItemRef

class ItemRef

A handle to an item declared via SupplyChainScope.item. Carries just the item name; inventories and demand generators reference an item by handle for type-safety and refactor tolerance.

ItemSpec

@Serializable

data class ItemSpec(val name: String, val leadTime: RVSpec, val weight: Double = 1.0, val cube: Double = 1.0, val unitCost: Double = 1.0)

Serializable description of an item type.

LimitsSpec

@Serializable

data class LimitsSpec(val min: Double, val max: Double)

A [min, max] limit pair for FormingOption.WEIGHT / FormingOption.CUBE formation. A small data class rather than a Pair so it serializes cleanly to TOML and JSON.

NetworkSpec

@Serializable

data class NetworkSpec(val name: String, val transportStrategy: TransportStrategySpec = TransportStrategySpec.SharedCarrier, val items: List<ItemSpec>, val nodes: List<NodeSpec>, val demandGenerators: List<DemandGeneratorSpec> = emptyList(), val costFormulations: List<CostFormulationSpec> = emptyList())

The canonical, serializable description of a multi-echelon supply-chain network — the single data form that the Kotlin DSL, the TOML/JSON loaders, and programmatic generators all produce, and that SupplyChainBuilder consumes to instantiate a running MultiEchelonNetwork.

NodeScope

class NodeScope

A node scope: configures one IHP/CD and may nest children under it.

NodeSpec

@Serializable

data class NodeSpec(val name: String, val type: NodeType, val parent: String, val transportTimeFromParent: RVSpec? = null, val inventory: List<InventorySpec> = emptyList(), val enableShipmentFormation: Boolean = false, val shipmentFormationFromParent: ShipmentFormationSpec? = null)

Serializable description of a network node and its edge to its supplier.

NodeType

enum NodeType : Enum<NodeType>

The kind of network node.

PolicySpec

@Serializable

sealed class PolicySpec

Serializable description of an inventory replenishment policy on an InventorySpec. Maps to the three concrete policy factory methods on the framework's Inventory:

RVSpec

@Serializable

sealed class RVSpec

Serializable description of a random variable used in a NetworkSpec (an item lead time, a transport time, an inter-arrival time, a periodic review interval).

ShipmentFormationSpec

@Serializable

data class ShipmentFormationSpec(val option: FormingOption, val countLimit: Int? = null, val weightLimits: LimitsSpec? = null, val cubeLimits: LimitsSpec? = null)

Serializable description of a per-edge shipment-formation policy, mirroring the framework's ShipmentFormation. Attached to a NodeSpec (NodeSpec.shipmentFormationFromParent) or a DemandGeneratorSpec (DemandGeneratorSpec.shipmentFormation).

SpecError

data class SpecError(val message: String)

A single validation problem found in a NetworkSpec. The message carries enough context (node / item / edge names) to fix the data without reading a KSL stack trace.

StreamRange

class StreamRange(val base: Int, val count: Int)

Allocates unique stream numbers from a documented base, up to count of them. Useful for reserving a contiguous block of streams for a subsystem so a saved spec stays deterministic and non-overlapping. See also SupplyChainScope.autoStream.

SupplyChainBuilder

object SupplyChainBuilder

Instantiates a running MultiEchelonNetwork from a NetworkSpec.

SupplyChainDsl

@DslMarker

annotation class SupplyChainDsl

Marks the supply-chain DSL receiver types so that members of an outer scope cannot be called implicitly from an inner one (e.g. you cannot declare an SupplyChainScope.item from inside a node block).

SupplyChainScope

class SupplyChainScope

Top-level DSL scope: items, root nodes, cost formulations, strategy.

TransportStrategySpec

@Serializable

sealed class TransportStrategySpec

Serializable description of a network's transport strategy, mirroring the framework's TransportStrategy sealed class.

Functions

alwaysFormation

fun alwaysFormation(): ShipmentFormationSpec

FormingOption.ALWAYS single-demand-per-load formation.

constant

fun constant(value: Double): RVSpec

A deterministic RVSpec.Constant.

countFormation

fun countFormation(limit: Int): ShipmentFormationSpec

FormingOption.COUNT formation: ship a load every limit demands.

cubeFormation

fun cubeFormation(min: Double, max: Double): ShipmentFormationSpec

FormingOption.CUBE formation with the given [min, max] cube window.

exponential

fun exponential(mean: Double, stream: Int): RVSpec

An RVSpec.Exponential with the given mean and explicit stream number.

fromJson

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

Parse a NetworkSpec from a JSON string produced by toJson.

fromToml

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

Parse a NetworkSpec from a TOML string produced by toToml.

lognormal

fun lognormal(mean: Double, variance: Double, stream: Int): RVSpec

A RVSpec.Lognormal with the given mean and variance.

supplyChain

fun supplyChain(name: String, autoStreamBase: Int = 1, block: SupplyChainScope.() -> Unit): NetworkSpec

Author a NetworkSpec with a Kotlin DSL. The DSL is pure sugar over the data layer: it builds and returns a NetworkSpec and never touches runtime framework types. Visual nesting (holdingPoint { holdingPoint { } }) lowers to the flat node list, with each node's parent inferred from the enclosing scope.

toJson

fun NetworkSpec.toJson(): String

Serialize this spec to a JSON string.

toToml

fun NetworkSpec.toToml(): String

Serialize this spec to a TOML string.

triangular

fun triangular(min: Double, mode: Double, max: Double, stream: Int): RVSpec

A RVSpec.Triangular with the given min / mode / max.

uniform

fun uniform(min: Double, max: Double, stream: Int): RVSpec

A continuous RVSpec.Uniform on [min, max].

validate

fun NetworkSpec.validate(): List<SpecError>

Validate the structural and reference integrity of this NetworkSpec, returning every problem found (not just the first). An empty list means the spec is well-formed and safe to pass to SupplyChainBuilder.build.

weightFormation

fun weightFormation(min: Double, max: Double): ShipmentFormationSpec

FormingOption.WEIGHT formation with the given [min, max] weight window.