Merge pull request #8 from kgrygiel/master

Base Recommender model classes: Histogram and CircularBuffer.

vertical-pod-autoscaler/recommender/util/histogram.go

@@ -0,0 +1,127 @@
+/*
+Copyright 2017 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package util
+
+// Histogram represents an approximate distribution of some variable.
+type Histogram interface {
+	// Returns an approximation of the given percentile of the distribution.
+	// Note: the argument passed to Percentile() is a number between
+	// 0 and 1. For example 0.5 corresponds to the median and 0.9 to the
+	// 90th percentile.
+	// If the histogram is empty, Percentile() returns 0.0.
+	Percentile(percentile float64) float64
+
+	// Add a sample with a given value and weight.
+	AddSample(value float64, weight float64)
+
+	// Remove a sample with a given value and weight. Note that the total
+	// weight of samples with a given value cannot be negative.
+	SubtractSample(value float64, weight float64)
+
+	// Returns true if the histogram is empty.
+	IsEmpty() bool
+}
+
+// NewHistogram returns a new Histogram instance using given options.
+func NewHistogram(options HistogramOptions) Histogram {
+	return &histogram{
+		&options, make([]float64, options.NumBuckets()), 0.0,
+		options.NumBuckets() - 1, 0}
+}
+
+// Simple bucket-based implementation of the Histogram interface. Each bucket
+// holds the total weight of samples that belong to it.
+// Percentile() returns the middle of the correspodning bucket.
+// Resolution (bucket boundaries) of the histogram depends on the options.
+// There's no interpolation within buckets (i.e. one sample falls to exactly one
+// bucket).
+// A bucket is considered empty if its weight is smaller than options.Epsilon().
+type histogram struct {
+	// Bucketing scheme.
+	options *HistogramOptions
+	// Cumulative weight of samples in each bucket.
+	bucketWeight []float64
+	// Total cumulative weight of samples in all buckets.
+	totalWeight float64
+	// Index of the first non-empty bucket if there's any. Otherwise index
+	// of the last bucket.
+	minBucket int
+	// Index of the last non-empty bucket if there's any. Otherwise 0.
+	maxBucket int
+}
+
+func (h *histogram) AddSample(value float64, weight float64) {
+	if weight < 0.0 {
+		panic("sample weight must be non-negative")
+	}
+	bucket := (*h.options).FindBucket(value)
+	h.bucketWeight[bucket] += weight
+	h.totalWeight += weight
+	if bucket < h.minBucket {
+		h.minBucket = bucket
+	}
+	if bucket > h.maxBucket {
+		h.maxBucket = bucket
+	}
+}
+func (h *histogram) SubtractSample(value float64, weight float64) {
+	if weight < 0.0 {
+		panic("sample weight must be non-negative")
+	}
+	bucket := (*h.options).FindBucket(value)
+	epsilon := (*h.options).Epsilon()
+	if weight > h.bucketWeight[bucket]-epsilon {
+		weight = h.bucketWeight[bucket]
+	}
+	h.totalWeight -= weight
+	h.bucketWeight[bucket] -= weight
+	lastBucket := (*h.options).NumBuckets() - 1
+	for h.bucketWeight[h.minBucket] < epsilon && h.minBucket < lastBucket {
+		h.minBucket++
+	}
+	for h.bucketWeight[h.maxBucket] < epsilon && h.maxBucket > 0 {
+		h.maxBucket--
+	}
+}
+
+func (h *histogram) Percentile(percentile float64) float64 {
+	if h.IsEmpty() {
+		return 0.0
+	}
+	partialSum := 0.0
+	threshold := percentile * h.totalWeight
+	bucket := h.minBucket
+	for ; bucket < h.maxBucket; bucket++ {
+		partialSum += h.bucketWeight[bucket]
+		if partialSum >= threshold {
+			break
+		}
+	}
+	bucketStart := (*h.options).GetBucketStart(bucket)
+	if bucket < (*h.options).NumBuckets()-1 {
+		// Return the middle point between the bucket boundaries.
+		bucketEnd := (*h.options).GetBucketStart(bucket + 1)
+		return (bucketStart + bucketEnd) / 2.0
+	}
+	// Return the start of the last bucket (note that the last bucket
+	// doesn't have an upper bound).
+	return bucketStart
+}
+
+func (h *histogram) IsEmpty() bool {
+	return h.bucketWeight[h.minBucket] < (*h.options).Epsilon()
+}

vertical-pod-autoscaler/recommender/util/histogram_options.go

@@ -0,0 +1,135 @@
+/*
+Copyright 2017 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package util
+
+import (
+	"errors"
+	"fmt"
+	"math"
+)
+
+// HistogramOptions define the number and size of buckets of a histogram.
+type HistogramOptions interface {
+	// Returns the number of buckets in the histogram.
+	NumBuckets() int
+	// Returns the index of the bucket to which the given value falls.
+	// If the value is outside of the range covered by the histogram, it
+	// returns the closest bucket (either the first or the last one).
+	FindBucket(value float64) int
+	// Returns the start of the bucket with a given index. If the index is
+	// outside the [0..NumBuckets() - 1] range, the result is undefined.
+	GetBucketStart(bucket int) float64
+	// Returns the minimum weight for a bucket to be considered non-empty.
+	Epsilon() float64
+}
+
+// NewLinearHistogramOptions returns HistogramOptions describing a histogram
+// with a given number of fixed-size buckets, with the first bucket start at 0.0
+// and the last bucket start larger or equal to maxValue.
+// Requires maxValue > 0, bucketSize > 0, epsilon > 0.
+func NewLinearHistogramOptions(
+	maxValue float64, bucketSize float64, epsilon float64) (HistogramOptions, error) {
+	if maxValue <= 0.0 || bucketSize <= 0.0 || epsilon <= 0.0 {
+		return nil, errors.New("maxValue and bucketSize must both be positive")
+	}
+	numBuckets := int(math.Ceil(maxValue/bucketSize)) + 1
+	return &linearHistogramOptions{numBuckets, bucketSize, epsilon}, nil
+}
+
+// NewExponentialHistogramOptions returns HistogramOptions describing a
+// histogram with exponentially growing bucket boundaries. The first bucket
+// covers the range [0..firstBucketSize). Consecutive buckets are of the form
+// [x(n)..x(n) * ratio) for n = 1 .. numBuckets - 1.
+// The last bucket start is larger or equal to maxValue.
+// Requires maxValue > 0, firstBucketSize > 0, ratio > 1, epsilon > 0.
+func NewExponentialHistogramOptions(
+	maxValue float64, firstBucketSize float64, ratio float64, epsilon float64) (HistogramOptions, error) {
+	if maxValue <= 0.0 || firstBucketSize <= 0.0 || ratio <= 1.0 || epsilon <= 0.0 {
+		return nil, errors.New(
+			"maxValue, firstBucketSize and epsilon must be > 0.0, ratio must be > 1.0")
+	}
+	numBuckets := int(math.Ceil(math.Log(maxValue/firstBucketSize)/math.Log(ratio))) + 2
+	return &exponentialHistogramOptions{numBuckets, firstBucketSize, ratio, epsilon}, nil
+}
+
+type linearHistogramOptions struct {
+	numBuckets int
+	bucketSize float64
+	epsilon    float64
+}
+
+type exponentialHistogramOptions struct {
+	numBuckets      int
+	firstBucketSize float64
+	ratio           float64
+	epsilon         float64
+}
+
+func (o *linearHistogramOptions) NumBuckets() int {
+	return o.numBuckets
+}
+
+func (o *linearHistogramOptions) FindBucket(value float64) int {
+	bucket := int(value / o.bucketSize)
+	if bucket < 0 {
+		return 0
+	}
+	if bucket >= o.numBuckets {
+		return o.numBuckets - 1
+	}
+	return bucket
+}
+
+func (o *linearHistogramOptions) GetBucketStart(bucket int) float64 {
+	if bucket < 0 || bucket >= o.numBuckets {
+		panic(fmt.Sprintf("index %d out of range [0..%d]", bucket, o.numBuckets-1))
+	}
+	return float64(bucket) * o.bucketSize
+}
+
+func (o *linearHistogramOptions) Epsilon() float64 {
+	return o.epsilon
+}
+
+func (o *exponentialHistogramOptions) NumBuckets() int {
+	return o.numBuckets
+}
+
+func (o *exponentialHistogramOptions) FindBucket(value float64) int {
+	if value < o.firstBucketSize {
+		return 0
+	}
+	bucket := int(math.Log(value/o.firstBucketSize)/math.Log(o.ratio)) + 1
+	if bucket >= o.numBuckets {
+		return o.numBuckets - 1
+	}
+	return bucket
+}
+
+func (o *exponentialHistogramOptions) GetBucketStart(bucket int) float64 {
+	if bucket < 0 || bucket >= o.numBuckets {
+		panic(fmt.Sprintf("index %d out of range [0..%d]", bucket, o.numBuckets-1))
+	}
+	if bucket == 0 {
+		return 0.0
+	}
+	return o.firstBucketSize * math.Pow(o.ratio, float64(bucket-1))
+}
+
+func (o *exponentialHistogramOptions) Epsilon() float64 {
+	return o.epsilon
+}

vertical-pod-autoscaler/recommender/util/histogram_options_test.go

@@ -0,0 +1,64 @@
+/*
+Copyright 2017 The Kubernetes Authors.
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+package util
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+var (
+	epsilon = 0.001
+)
+
+// Test all methods of LinearHistogramOptions using a sample bucketing scheme.
+func TestLinearHistogramOptions(t *testing.T) {
+	o, err := NewLinearHistogramOptions(5.0, 0.3, epsilon)
+	assert.Nil(t, err)
+	assert.Equal(t, epsilon, o.Epsilon())
+	assert.Equal(t, 18, o.NumBuckets())
+
+	assert.Equal(t, 0.0, o.GetBucketStart(0))
+	assert.Equal(t, 5.1, o.GetBucketStart(17))
+
+	assert.Equal(t, 0, o.FindBucket(-1.0))
+	assert.Equal(t, 0, o.FindBucket(0.0))
+	assert.Equal(t, 4, o.FindBucket(1.3))
+	assert.Equal(t, 17, o.FindBucket(100.0))
+}
+
+// Test all methods of ExponentialHistogramOptions using a sample bucketing scheme.
+func TestExponentialHistogramOptions(t *testing.T) {
+	o, err := NewExponentialHistogramOptions(100.0, 10.0, 2.0, epsilon)
+	assert.Nil(t, err)
+	assert.Equal(t, epsilon, o.Epsilon())
+	assert.Equal(t, 6, o.NumBuckets())
+
+	assert.Equal(t, 0.0, o.GetBucketStart(0))
+	assert.Equal(t, 10.0, o.GetBucketStart(1))
+	assert.Equal(t, 20.0, o.GetBucketStart(2))
+	assert.Equal(t, 40.0, o.GetBucketStart(3))
+	assert.Equal(t, 80.0, o.GetBucketStart(4))
+	assert.Equal(t, 160.0, o.GetBucketStart(5))
+
+	assert.Equal(t, 0, o.FindBucket(-1.0))
+	assert.Equal(t, 0, o.FindBucket(9.99))
+	assert.Equal(t, 1, o.FindBucket(10.0))
+	assert.Equal(t, 2, o.FindBucket(20.0))
+	assert.Equal(t, 5, o.FindBucket(200.0))
+}