git.sesse.net Git - bcachefs-tools-debian/blob - linux/mean_and_variance.c

   1 // SPDX-License-Identifier: GPL-2.0
   2 /*
   3  * Functions for incremental mean and variance.
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 as published by
   7  * the Free Software Foundation.
   8  *
   9  * This program is distributed in the hope that it will be useful, but WITHOUT
  10  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  11  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  12  * more details.
  13  *
  14  * Copyright © 2022 Daniel B. Hill
  15  *
  16  * Author: Daniel B. Hill <daniel@gluo.nz>
  17  *
  18  * Description:
  19  *
  20  * This is includes some incremental algorithms for mean and variance calculation
  21  *
  22  * Derived from the paper: https://fanf2.user.srcf.net/hermes/doc/antiforgery/stats.pdf
  23  *
  24  * Create a struct and if it's the weighted variant set the w field (weight = 2^k).
  25  *
  26  * Use mean_and_variance[_weighted]_update() on the struct to update it's state.
  27  *
  28  * Use the mean_and_variance[_weighted]_get_* functions to calculate the mean and variance, some computation
  29  * is deferred to these functions for performance reasons.
  30  *
  31  * see lib/math/mean_and_variance_test.c for examples of usage.
  32  *
  33  * DO NOT access the mean and variance fields of the weighted variants directly.
  34  * DO NOT change the weight after calling update.
  35  */
  36
  37 #include <linux/bug.h>
  38 #include <linux/compiler.h>
  39 #include <linux/export.h>
  40 #include <linux/limits.h>
  41 #include <linux/math.h>
  42 #include <linux/math64.h>
  43 #include <linux/mean_and_variance.h>
  44 #include <linux/module.h>
  45 #include <linux/printbuf.h>
  46
  47
  48 /**
  49  * fast_divpow2() - fast approximation for n / (1 << d)
  50  * @n: numerator
  51  * @d: the power of 2 denominator.
  52  *
  53  * note: this rounds towards 0.
  54  */
  55 s64 fast_divpow2(s64 n, u8 d)
  56 {
  57         return (n + ((n < 0) ? ((1 << d) - 1) : 0)) >> d;
  58 }
  59
  60 /**
  61  * mean_and_variance_update() - update a mean_and_variance struct @s1 with a new sample @v1
  62  * and return it.
  63  * @s1: the mean_and_variance to update.
  64  * @v1: the new sample.
  65  *
  66  * see linked pdf equation 12.
  67  */
  68 struct mean_and_variance mean_and_variance_update(struct mean_and_variance s1, s64 v1)
  69 {
  70         struct mean_and_variance s2;
  71         u64 v2 = abs(v1);
  72
  73         s2.n           = s1.n + 1;
  74         s2.sum         = s1.sum + v1;
  75         s2.sum_squares = u128_add(s1.sum_squares, u128_square(v2));
  76         return s2;
  77 }
  78 EXPORT_SYMBOL_GPL(mean_and_variance_update);
  79
  80 /**
  81  * mean_and_variance_get_mean() - get mean from @s
  82  */
  83 s64 mean_and_variance_get_mean(struct mean_and_variance s)
  84 {
  85         return div64_u64(s.sum, s.n);
  86 }
  87 EXPORT_SYMBOL_GPL(mean_and_variance_get_mean);
  88
  89 /**
  90  * mean_and_variance_get_variance() -  get variance from @s1
  91  *
  92  * see linked pdf equation 12.
  93  */
  94 u64 mean_and_variance_get_variance(struct mean_and_variance s1)
  95 {
  96         u128 s2 = u128_div(s1.sum_squares, s1.n);
  97         u64  s3 = abs(mean_and_variance_get_mean(s1));
  98
  99         return u128_to_u64(u128_sub(s2, u128_square(s3)));
 100 }
 101 EXPORT_SYMBOL_GPL(mean_and_variance_get_variance);
 102
 103 /**
 104  * mean_and_variance_get_stddev() - get standard deviation from @s
 105  */
 106 u32 mean_and_variance_get_stddev(struct mean_and_variance s)
 107 {
 108         return int_sqrt64(mean_and_variance_get_variance(s));
 109 }
 110 EXPORT_SYMBOL_GPL(mean_and_variance_get_stddev);
 111
 112 /**
 113  * mean_and_variance_weighted_update() - exponentially weighted variant of mean_and_variance_update()
 114  * @s1: ..
 115  * @s2: ..
 116  *
 117  * see linked pdf: function derived from equations 140-143 where alpha = 2^w.
 118  * values are stored bitshifted for performance and added precision.
 119  */
 120 struct mean_and_variance_weighted mean_and_variance_weighted_update(struct mean_and_variance_weighted s1,
 121                                                                     s64 x)
 122 {
 123         struct mean_and_variance_weighted s2;
 124         // previous weighted variance.
 125         u64 var_w0 = s1.variance;
 126         u8 w = s2.w = s1.w;
 127         // new value weighted.
 128         s64 x_w = x << w;
 129         s64 diff_w = x_w - s1.mean;
 130         s64 diff = fast_divpow2(diff_w, w);
 131         // new mean weighted.
 132         s64 u_w1     = s1.mean + diff;
 133
 134         BUG_ON(w % 2 != 0);
 135
 136         if (!s1.init) {
 137                 s2.mean = x_w;
 138                 s2.variance = 0;
 139         } else {
 140                 s2.mean = u_w1;
 141                 s2.variance = ((var_w0 << w) - var_w0 + ((diff_w * (x_w - u_w1)) >> w)) >> w;
 142         }
 143         s2.init = true;
 144
 145         return s2;
 146 }
 147 EXPORT_SYMBOL_GPL(mean_and_variance_weighted_update);
 148
 149 /**
 150  * mean_and_variance_weighted_get_mean() - get mean from @s
 151  */
 152 s64 mean_and_variance_weighted_get_mean(struct mean_and_variance_weighted s)
 153 {
 154         return fast_divpow2(s.mean, s.w);
 155 }
 156 EXPORT_SYMBOL_GPL(mean_and_variance_weighted_get_mean);
 157
 158 /**
 159  * mean_and_variance_weighted_get_variance() -- get variance from @s
 160  */
 161 u64 mean_and_variance_weighted_get_variance(struct mean_and_variance_weighted s)
 162 {
 163         // always positive don't need fast divpow2
 164         return s.variance >> s.w;
 165 }
 166 EXPORT_SYMBOL_GPL(mean_and_variance_weighted_get_variance);
 167
 168 /**
 169  * mean_and_variance_weighted_get_stddev() - get standard deviation from @s
 170  */
 171 u32 mean_and_variance_weighted_get_stddev(struct mean_and_variance_weighted s)
 172 {
 173         return int_sqrt64(mean_and_variance_weighted_get_variance(s));
 174 }
 175 EXPORT_SYMBOL_GPL(mean_and_variance_weighted_get_stddev);
 176
 177 MODULE_AUTHOR("Daniel B. Hill");
 178 MODULE_LICENSE("GPL");