## Documentation ¶

### Overview ¶

Package measure contains cost measures based on indices or points.

#### Measures ¶

Engines models frequently need to determine the cost of connecting two things together. This may mean assigning one item to another, clustering two points together, or routing a vehicle from one location to another. These cost computations are generically referred to as "measures". Engines provides a number of common patterns for constructing and using them inside models.

#### Point-to-Point Measures ¶

When cost must be computed based on distance between two points, a model can use a measure.ByPoint implementation. These is the case for models where points are determined dynamically within the model logic, such as in k-means clustering. Such measures map two points to a cost.

cost := m.Cost(fromPoint, toPoint)

The following measure.ByPoint implementations are available.

measure.EuclideanByPoint: Euclidean distance between two points measure.HaversineByPoint: Haversine distance between two points measure.TaxicabByPoint: Taxicab distance between two points

Unassigned may be of any dimension. If the points passed in to any of these measures have differing dimensionality, they will project the lower dimension point into the higher dimension by appending 0s.

#### Indexed Measures ¶

Models that do not require points operate on indices. These indices may or may not refer to points. An measure.ByIndex implementation provides the same functionality as a measure.ByPoint implementation, except its cost method accepts two indices instead of two points.

cost := m.Cost(fromIndex, toIndex)

Index measures are more common, and a number of them embed and operate on results from other index measures.

The following measure.ByIndex implementations are available.

measure.Bin: select from a slice of measure by some function measure.Location: adds fixed location costs to another measure measure.Constant: always returns the same cost measure.Matrix: looks up cost from a row to a column index measure.Override: overrides some other measure given a condition measure.Power: takes some other measure to a power measure.Scale: scales some other measure by a constant measure.Sparse: sparse matrix measure with a backup measure.Sum: adds the costs of other measures together measure.Truncate: truncates cost values provided by another measure measure.Location: adds cost of visiting a location to another measure

In addition, Engines provides measure.Indexed, which adapts any measure.ByPoint into a measure.ByIndex. In addition to the measure.ByPoint to be converted, Indexed accepts a fixed slice of points that it will use to look up the positions of indexes passed to Cost.

### Index ¶

- func ByClockwise(center Point, points []Point) sort.Interface
- func IsTriangular(m any) bool
- func LessClockwise(center, a, b Point) bool
- type ByIndex
- func Bin(measures []ByIndex, selector func(from, to int) int) ByIndex
- func Constant(c float64) ByIndex
- func DebugOverride(defaultByIndex ByIndex, overrideByIndex ByIndex, ...) ByIndex
- func DebugSparse(m ByIndex, arcs map[int]map[int]float64) ByIndex
- func Indexed(m ByPoint, points []Point) ByIndex
- func Matrix(arcs [][]float64) ByIndex
- func Override(defaultByIndex ByIndex, overrideByIndex ByIndex, ...) ByIndex
- func OverrideZeroPoints(points []Point, m ByIndex) ByIndex
- func Power(m ByIndex, exponent float64) ByIndex
- func Scale(m ByIndex, constant float64) ByIndex
- func Sparse(m ByIndex, arcs map[int]map[int]float64) ByIndex
- func Sum(m ...ByIndex) ByIndex
- func Truncate(m ByIndex, lower, upper float64) ByIndex
- func Unique(m ByIndex, references []int) ByIndex

- type ByIndexLoader
- type ByPoint
- type ByPointLoader
- type DependentByIndex
- type Point
- type Times
- type Triangular
- type VehicleData

### Constants ¶

This section is empty.

### Variables ¶

This section is empty.

### Functions ¶

#### func ByClockwise ¶

ByClockwise implements sort.Interface for sorting points clockwise around a central point.

#### func IsTriangular ¶

IsTriangular returns true if the triangle inequality holds for the provided measure.

#### func LessClockwise ¶

LessClockwise returns true if a is closer to a central point than b, and false if it is not.

### Types ¶

#### type ByIndex ¶

type ByIndex interface { // Cost estimates the cost of going from one index to another. Cost(from, to int) float64 }

ByIndex estimates the cost of going from one index to another.

#### func Bin ¶

Bin is a measure that selects from a slice of indexed measures. Logic defined in the selector function determines which measure is used in the cost calculation.

#### func DebugOverride ¶

func DebugOverride( defaultByIndex ByIndex, overrideByIndex ByIndex, condition func(from, to int) bool, ) ByIndex

DebugOverride returns an Override that when marshalled will include debugging information describing the number of queries for default and override elements.

#### func DebugSparse ¶

DebugSparse returns a Sparse that when marshalled will include debugging information describing the number of queries for elements included in (and not included in) the matrix.

#### func Indexed ¶

Indexed creates a ByIndex measure from the given ByPoint measure and wrapping the provided points.

#### func Matrix ¶

Matrix measure returns pre-computed cost between two locations. Cost is assumed to be asymmetric.

#### func Override ¶

func Override( defaultByIndex ByIndex, overrideByIndex ByIndex, condition func(from, to int) bool, ) ByIndex

Override measure uses a default measure for all arcs that are not true for a condition. It uses an override measure for all arcs that are true for the condition.

#### func OverrideZeroPoints ¶ added in v1.0.4

OverrideZeroPoints overrides points that have been passed as placeholders [0,0] to build the matrix with zero values.

#### func Sparse ¶

Sparse measure returns pre-computed costs between two locations without requiring a full data set. If two locations do not have an associated cost, then a backup measure is used.

#### type ByIndexLoader ¶ added in v1.0.4

```
type ByIndexLoader struct {
// contains filtered or unexported fields
}
```

ByIndexLoader can be embedded in schema structs and unmarshals a ByIndex JSON object into the appropriate implementation.

#### func (ByIndexLoader) MarshalJSON ¶ added in v1.0.4

func (l ByIndexLoader) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON representation for the underlying Byindex.

#### func (*ByIndexLoader) To ¶ added in v1.0.4

func (l *ByIndexLoader) To() ByIndex

To returns the underlying ByIndex.

#### func (*ByIndexLoader) UnmarshalJSON ¶ added in v1.0.4

func (l *ByIndexLoader) UnmarshalJSON(b []byte) error

UnmarshalJSON converts the bytes into the appropriate implementation of ByIndex.

#### type ByPoint ¶

type ByPoint interface { // Cost estimates the cost of going from one point to another. Cost(from, to Point) float64 }

ByPoint estimates the cost of going from one point to another.

#### func ConstantByPoint ¶

ConstantByPoint measure always estimates the same cost.

#### func EuclideanByPoint ¶

func EuclideanByPoint() ByPoint

EuclideanByPoint computes straight line distance connecting two indices.

#### func HaversineByPoint ¶

func HaversineByPoint() ByPoint

HaversineByPoint estimates meters connecting two points along the surface of the earth.

#### func ScaleByPoint ¶

ScaleByPoint scales an underlying measure by a constant.

#### func TaxicabByPoint ¶

func TaxicabByPoint() ByPoint

TaxicabByPoint adds absolute distances between two points in all dimensions.

#### type ByPointLoader ¶ added in v1.0.4

```
type ByPointLoader struct {
// contains filtered or unexported fields
}
```

ByPointLoader can be embedded in schema structs and unmarshals a ByPoint JSON object into the appropriate implementation.

#### func (ByPointLoader) MarshalJSON ¶ added in v1.0.4

func (l ByPointLoader) MarshalJSON() ([]byte, error)

MarshalJSON returns the JSON representation for the underlying ByPoint.

#### func (*ByPointLoader) To ¶ added in v1.0.4

func (l *ByPointLoader) To() ByPoint

To returns the underlying ByPoint.

#### func (*ByPointLoader) UnmarshalJSON ¶ added in v1.0.4

func (l *ByPointLoader) UnmarshalJSON(b []byte) error

UnmarshalJSON converts the bytes into the appropriate implementation of ByPoint.

#### type DependentByIndex ¶ added in v0.21.1

type DependentByIndex interface { TimeDependent() bool Cost( from, to int, data *VehicleData, ) float64 }

DependentByIndex estimates the cost of going from one index to another taking a point in time into account.

#### func DependentIndexed ¶ added in v0.21.1

func DependentIndexed( timeDependent bool, cost func( from, to int, data *VehicleData, ) float64, ) DependentByIndex

DependentIndexed is a measure that uses a custom cost function to calculate parameter dependent costs for connecting two points by index. If the measures are time dependent all future stops in the sequence will be fully recalculated. Otherwise there will be a constant shift to achieve better performance.

#### type Point ¶

type Point []float64

Point represents a point in space. It may have any dimension.

#### func BuildMatrixRequestPoints ¶ added in v1.0.4

BuildMatrixRequestPoints builds a slice of points in the correct format to request a matrix from any of the supported platforms (e.g. OSRM, Routingkit, Google, HERE). It takes the stops to be routed, start and end stops of vehicles (optional) and the number of to be used.

#### type Times ¶ added in v0.21.1

type Times struct { EstimatedArrival []int `json:"estimated_arrival,omitempty"` EstimatedServiceStart []int `json:"estimated_service_start,omitempty"` EstimatedDeparture []int `json:"estimated_departure,omitempty"` }

Times holds the estimated time of arrival (ETA), estimated time of when service starts (ETS) and estimated time of departure (ETD).

#### type Triangular ¶

```
type Triangular interface {
Triangular() bool
}
```

Triangular indicates that the triangle inequality holds for every measure that implements it.