Distances
A SpatialModel that stores pairwise travel distances between named locations in a directed sparse table.
Distances are directed: adding a distance from A to B does not automatically create one from B to A. Use symmetric = true on addDistance to insert both directions in one call.
Adding locations and distances
Locations can be created explicitly with the inner Location class and then connected, or created implicitly by passing string names to the string-based addDistance overload:
val dm = DistancesModel()
val enter = dm.Location("Enter")
val station1 = dm.Location("Station1")
dm.addDistance(enter, station1, 60.0, symmetric = true)A square distance matrix can be loaded in one call via addDistances; each location is named Loc_k where k is its row/column index.
Bulk configuration via DistancesData
The distancesData property accepts a List<DistanceData> (aliased as DistancesData). Setting it clears the existing table and reloads from the supplied list. The getter returns a snapshot of the current table.
JSON round-trip methods are available directly:
settingsToJson — serializes the current distance table to a pretty-printed JSON string
configureFromJson — parses a JSON string and applies it via distancesData
Integration with the KSL controls framework
DistancesModel does not extend ksl.simulation.ModelElement, so its properties are not visited by the ksl.controls.Controls extraction walk. The recommended pattern is to expose thin delegate properties on the owning ModelElement subclass and annotate them for control extraction:
class MyModel(parent: ModelElement, name: String) : ModelElement(parent, name) {
private val dm = DistancesModel()
// Exposes the full distance table as a JSON control.
// The setter performs a complete clear-and-reload of the table.
@set:KSLJsonControl(comment = "Pairwise distances between locations")
var distancesData: List<DistanceData>
get() = dm.distancesData
set(value) { dm.distancesData = value }
// Exposes the same-location default as a numeric control.
@set:KSLControl(
controlType = ControlType.DOUBLE,
lowerBound = 0.0,
comment = "Distance used when origin and destination are the same location"
)
var defaultSameLocationDistance: Double
get() = dm.defaultSameLocationDistance
set(value) { dm.defaultSameLocationDistance = value }
}The delegate getter is called at extraction time to capture the initial JSON snapshot; the delegate setter delegates to distancesData, which performs the full clear-and-reload. No changes to DistancesModel are required.
Same-location distances
When the distance from a location to itself is queried and no explicit entry was added for that pair, defaultSameLocationDistance is returned. The default value is 0.0.
Properties
The default initial location.
The default distance from a location to itself must be greater than or equal to 0.0
The data associated with the schedule
The names of the locations.
The locations that have been added to the model.
Functions
Adds the distance data to the distances model.
Adds the distance from location fromLoc to location toLoc where fromLoc and toLoc are string names of locations. If a location with the name does not already exist in the model, then a new location with the name is created. The flag symmetric will cause an additional distance to be added going from toLoc to location fromLoc that has the same distance. The default value of the flag is false. The pair must not have been added to the model.
Adds a distance value between the pair of locations, going from fromLocation to toLocation. The distance must be greater than or equal to 0.0. The flag symmetric will cause an additional distance to be added going from toLocation to location fromLocation that has the same distance. The default value of the flag is false. The pair must not have been added to the model. Use changeDistance() in that case.
Assumes that matrix is square and contains the from-to distances. Any values on the diagonal are ignored. No values can be 0.0
Changes a distance value between the pair of locations, going from fromLocation to toLocation. The distance must be greater than or equal to 0.0. The pair must already be part of the model.
Clears all distances from the distance model
For this model, this returns true if and only if the locations are the same object instances.
Computes the distance between fromLocation and toLocation based on the spatial model's distance metric