serf: github.com/hashicorp/serf/coordinate

## package coordinate

`import "github.com/hashicorp/serf/coordinate"`

### func GenerateCircle¶Uses

`func GenerateCircle(nodes int, radius time.Duration) [][]time.Duration`

GenerateCircle returns a truth matrix for a set of nodes, evenly distributed around a circle with the given radius. The first node is at the "center" of the circle because it's equidistant from all the other nodes, but we place it at double the radius, so it should show up above all the other nodes in height.

### func GenerateGrid¶Uses

`func GenerateGrid(nodes int, spacing time.Duration) [][]time.Duration`

GenerateGrid returns a truth matrix as if all the nodes are in a two dimensional grid with the given spacing between them.

### func GenerateLine¶Uses

`func GenerateLine(nodes int, spacing time.Duration) [][]time.Duration`

GenerateLine returns a truth matrix as if all the nodes are in a straight linke with the given spacing between them.

### func GenerateRandom¶Uses

`func GenerateRandom(nodes int, mean time.Duration, deviation time.Duration) [][]time.Duration`

GenerateRandom returns a truth matrix for a set of nodes with normally distributed delays, with the given mean and deviation. The RNG is re-seeded so you always get the same matrix for a given size.

### func GenerateSplit¶Uses

`func GenerateSplit(nodes int, lan time.Duration, wan time.Duration) [][]time.Duration`

GenerateSplit returns a truth matrix as if half the nodes are close together in one location and half the nodes are close together in another. The lan factor is used to separate the nodes locally and the wan factor represents the split between the two sides.

### func Simulate¶Uses

`func Simulate(clients []*Client, truth [][]time.Duration, cycles int)`

Simulate runs the given number of cycles using the given list of clients and truth matrix. On each cycle, each client will pick a random node and observe the truth RTT, updating its coordinate estimate. The RNG is re-seeded for each simulation run to get deterministic results (for this algorithm and the underlying algorithm which will use random numbers for position vectors when starting out with everything at the origin).

### type Client¶Uses

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

Client manages the estimated network coordinate for a given node, and adjusts it as the node observes round trip times and estimated coordinates from other nodes. The core algorithm is based on Vivaldi, see the documentation for Config for more details.

#### func GenerateClients¶Uses

`func GenerateClients(nodes int, config *Config) ([]*Client, error)`

GenerateClients returns a slice with nodes number of clients, all with the given config.

#### func NewClient¶Uses

`func NewClient(config *Config) (*Client, error)`

NewClient creates a new Client and verifies the configuration is valid.

#### func (*Client) DistanceTo¶Uses

`func (c *Client) DistanceTo(other *Coordinate) time.Duration`

DistanceTo returns the estimated RTT from the client's coordinate to other, the coordinate for another node.

#### func (*Client) ForgetNode¶Uses

`func (c *Client) ForgetNode(node string)`

ForgetNode removes any client state for the given node.

#### func (*Client) GetCoordinate¶Uses

`func (c *Client) GetCoordinate() *Coordinate`

GetCoordinate returns a copy of the coordinate for this client.

#### func (*Client) SetCoordinate¶Uses

`func (c *Client) SetCoordinate(coord *Coordinate) error`

SetCoordinate forces the client's coordinate to a known state.

#### func (*Client) Stats¶Uses

`func (c *Client) Stats() ClientStats`

Stats returns a copy of stats for the client.

#### func (*Client) Update¶Uses

`func (c *Client) Update(node string, other *Coordinate, rtt time.Duration) (*Coordinate, error)`

Update takes other, a coordinate for another node, and rtt, a round trip time observation for a ping to that node, and updates the estimated position of the client's coordinate. Returns the updated coordinate.

### type ClientStats¶Uses

```type ClientStats struct {
// Resets is incremented any time we reset our local coordinate because
// our calculations have resulted in an invalid state.
Resets int
}```

ClientStats is used to record events that occur when updating coordinates.

### type Config¶Uses

```type Config struct {
// The dimensionality of the coordinate system. As discussed in [2], more
// dimensions improves the accuracy of the estimates up to a point. Per [2]
// we chose 8 dimensions plus a non-Euclidean height.
Dimensionality uint

// VivaldiErrorMax is the default error value when a node hasn't yet made
// any observations. It also serves as an upper limit on the error value in
// case observations cause the error value to increase without bound.
VivaldiErrorMax float64

// VivaldiCE is a tuning factor that controls the maximum impact an
// observation can have on a node's confidence. See [1] for more details.
VivaldiCE float64

// VivaldiCC is a tuning factor that controls the maximum impact an
// observation can have on a node's coordinate. See [1] for more details.
VivaldiCC float64

// AdjustmentWindowSize is a tuning factor that determines how many samples
// we retain to calculate the adjustment factor as discussed in [3]. Setting
// this to zero disables this feature.

// HeightMin is the minimum value of the height parameter. Since this
// always must be positive, it will introduce a small amount error, so
// the chosen value should be relatively small compared to "normal"
// coordinates.
HeightMin float64

// LatencyFilterSamples is the maximum number of samples that are retained
// per node, in order to compute a median. The intent is to ride out blips
// but still keep the delay low, since our time to probe any given node is
// pretty infrequent. See [2] for more details.
LatencyFilterSize uint

// GravityRho is a tuning factor that sets how much gravity has an effect
// to try to re-center coordinates. See [2] for more details.
GravityRho float64
}```

Config is used to set the parameters of the Vivaldi-based coordinate mapping algorithm.

The following references are called out at various points in the documentation here:

[1] Dabek, Frank, et al. "Vivaldi: A decentralized network coordinate system."

```ACM SIGCOMM Computer Communication Review. Vol. 34. No. 4. ACM, 2004.
```

[2] Ledlie, Jonathan, Paul Gardner, and Margo I. Seltzer. "Network Coordinates

```in the Wild." NSDI. Vol. 7. 2007.
```

[3] Lee, Sanghwan, et al. "On suitability of Euclidean embedding for

```host-based network coordinate systems." Networking, IEEE/ACM Transactions
on 18.1 (2010): 27-40.
```

#### func DefaultConfig¶Uses

`func DefaultConfig() *Config`

DefaultConfig returns a Config that has some default values suitable for basic testing of the algorithm, but not tuned to any particular type of cluster.

### type Coordinate¶Uses

```type Coordinate struct {
// Vec is the Euclidean portion of the coordinate. This is used along
// with the other fields to provide an overall distance estimate. The
// units here are seconds.
Vec []float64

// Err reflects the confidence in the given coordinate and is updated
// dynamically by the Vivaldi Client. This is dimensionless.
Error float64

// Adjustment is a distance offset computed based on a calculation over
// observations from all other nodes over a fixed window and is updated
// dynamically by the Vivaldi Client. The units here are seconds.

// Height is a distance offset that accounts for non-Euclidean effects
// which model the access links from nodes to the core Internet. The access
// links are usually set by bandwidth and congestion, and the core links
// usually follow distance based on geography.
Height float64
}```

Coordinate is a specialized structure for holding network coordinates for the Vivaldi-based coordinate mapping algorithm. All of the fields should be public to enable this to be serialized. All values in here are in units of seconds.

#### func NewCoordinate¶Uses

`func NewCoordinate(config *Config) *Coordinate`

NewCoordinate creates a new coordinate at the origin, using the given config to supply key initial values.

#### func (*Coordinate) ApplyForce¶Uses

`func (c *Coordinate) ApplyForce(config *Config, force float64, other *Coordinate) *Coordinate`

ApplyForce returns the result of applying the force from the direction of the other coordinate.

#### func (*Coordinate) Clone¶Uses

`func (c *Coordinate) Clone() *Coordinate`

Clone creates an independent copy of this coordinate.

#### func (*Coordinate) DistanceTo¶Uses

`func (c *Coordinate) DistanceTo(other *Coordinate) time.Duration`

DistanceTo returns the distance between this coordinate and the other coordinate, including adjustments.

#### func (*Coordinate) IsCompatibleWith¶Uses

`func (c *Coordinate) IsCompatibleWith(other *Coordinate) bool`

IsCompatibleWith checks to see if the two coordinates are compatible dimensionally. If this returns true then you are guaranteed to not get any runtime errors operating on them.

#### func (*Coordinate) IsValid¶Uses

`func (c *Coordinate) IsValid() bool`

IsValid returns false if any component of a coordinate isn't valid, per the componentIsValid() helper above.

### type DimensionalityConflictError¶Uses

`type DimensionalityConflictError struct{}`

ErrDimensionalityConflict will be panic-d if you try to perform operations with incompatible dimensions.

#### func (DimensionalityConflictError) Error¶Uses

`func (e DimensionalityConflictError) Error() string`

### type Stats¶Uses

```type Stats struct {
ErrorMax float64
ErrorAvg float64
}```

Stats is returned from the Evaluate function with a summary of the algorithm performance.

#### func Evaluate¶Uses

`func Evaluate(clients []*Client, truth [][]time.Duration) (stats Stats)`

Evaluate uses the coordinates of the given clients to calculate estimated distances and compares them with the given truth matrix, returning summary stats.

Package coordinate imports 7 packages (graph) and is imported by 982 packages. Updated 2019-11-30. Refresh now. Tools for package owners.