174 lines · c
1// SPDX-License-Identifier: GPL-2.02/*3 * Functions for incremental mean and variance.4 *5 * This program is free software; you can redistribute it and/or modify it6 * under the terms of the GNU General Public License version 2 as published by7 * the Free Software Foundation.8 *9 * This program is distributed in the hope that it will be useful, but WITHOUT10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for12 * more details.13 *14 * Copyright © 2022 Daniel B. Hill15 *16 * Author: Daniel B. Hill <daniel@gluo.nz>17 *18 * Description:19 *20 * This is includes some incremental algorithms for mean and variance calculation21 *22 * Derived from the paper: https://fanf2.user.srcf.net/hermes/doc/antiforgery/stats.pdf23 *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 computation29 * 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/module.h>44 45#include "mean_and_variance.h"46 47u128_u u128_div(u128_u n, u64 d)48{49 u128_u r;50 u64 rem;51 u64 hi = u128_hi(n);52 u64 lo = u128_lo(n);53 u64 h = hi & ((u64) U32_MAX << 32);54 u64 l = (hi & (u64) U32_MAX) << 32;55 56 r = u128_shl(u64_to_u128(div64_u64_rem(h, d, &rem)), 64);57 r = u128_add(r, u128_shl(u64_to_u128(div64_u64_rem(l + (rem << 32), d, &rem)), 32));58 r = u128_add(r, u64_to_u128(div64_u64_rem(lo + (rem << 32), d, &rem)));59 return r;60}61EXPORT_SYMBOL_GPL(u128_div);62 63/**64 * mean_and_variance_get_mean() - get mean from @s65 * @s: mean and variance number of samples and their sums66 */67s64 mean_and_variance_get_mean(struct mean_and_variance s)68{69 return s.n ? div64_u64(s.sum, s.n) : 0;70}71EXPORT_SYMBOL_GPL(mean_and_variance_get_mean);72 73/**74 * mean_and_variance_get_variance() - get variance from @s175 * @s1: mean and variance number of samples and sums76 *77 * see linked pdf equation 12.78 */79u64 mean_and_variance_get_variance(struct mean_and_variance s1)80{81 if (s1.n) {82 u128_u s2 = u128_div(s1.sum_squares, s1.n);83 u64 s3 = abs(mean_and_variance_get_mean(s1));84 85 return u128_lo(u128_sub(s2, u128_square(s3)));86 } else {87 return 0;88 }89}90EXPORT_SYMBOL_GPL(mean_and_variance_get_variance);91 92/**93 * mean_and_variance_get_stddev() - get standard deviation from @s94 * @s: mean and variance number of samples and their sums95 */96u32 mean_and_variance_get_stddev(struct mean_and_variance s)97{98 return int_sqrt64(mean_and_variance_get_variance(s));99}100EXPORT_SYMBOL_GPL(mean_and_variance_get_stddev);101 102/**103 * mean_and_variance_weighted_update() - exponentially weighted variant of mean_and_variance_update()104 * @s: mean and variance number of samples and their sums105 * @x: new value to include in the &mean_and_variance_weighted106 * @initted: caller must track whether this is the first use or not107 * @weight: ewma weight108 *109 * see linked pdf: function derived from equations 140-143 where alpha = 2^w.110 * values are stored bitshifted for performance and added precision.111 */112void mean_and_variance_weighted_update(struct mean_and_variance_weighted *s,113 s64 x, bool initted, u8 weight)114{115 // previous weighted variance.116 u8 w = weight;117 u64 var_w0 = s->variance;118 // new value weighted.119 s64 x_w = x << w;120 s64 diff_w = x_w - s->mean;121 s64 diff = fast_divpow2(diff_w, w);122 // new mean weighted.123 s64 u_w1 = s->mean + diff;124 125 if (!initted) {126 s->mean = x_w;127 s->variance = 0;128 } else {129 s->mean = u_w1;130 s->variance = ((var_w0 << w) - var_w0 + ((diff_w * (x_w - u_w1)) >> w)) >> w;131 }132}133EXPORT_SYMBOL_GPL(mean_and_variance_weighted_update);134 135/**136 * mean_and_variance_weighted_get_mean() - get mean from @s137 * @s: mean and variance number of samples and their sums138 * @weight: ewma weight139 */140s64 mean_and_variance_weighted_get_mean(struct mean_and_variance_weighted s,141 u8 weight)142{143 return fast_divpow2(s.mean, weight);144}145EXPORT_SYMBOL_GPL(mean_and_variance_weighted_get_mean);146 147/**148 * mean_and_variance_weighted_get_variance() -- get variance from @s149 * @s: mean and variance number of samples and their sums150 * @weight: ewma weight151 */152u64 mean_and_variance_weighted_get_variance(struct mean_and_variance_weighted s,153 u8 weight)154{155 // always positive don't need fast divpow2156 return s.variance >> weight;157}158EXPORT_SYMBOL_GPL(mean_and_variance_weighted_get_variance);159 160/**161 * mean_and_variance_weighted_get_stddev() - get standard deviation from @s162 * @s: mean and variance number of samples and their sums163 * @weight: ewma weight164 */165u32 mean_and_variance_weighted_get_stddev(struct mean_and_variance_weighted s,166 u8 weight)167{168 return int_sqrt64(mean_and_variance_weighted_get_variance(s, weight));169}170EXPORT_SYMBOL_GPL(mean_and_variance_weighted_get_stddev);171 172MODULE_AUTHOR("Daniel B. Hill");173MODULE_LICENSE("GPL");174