From 654d5b5b0828449d8f7dc121a00a36fe22f7eab0 Mon Sep 17 00:00:00 2001
From: Oliver Booth <me@olivr.me>
Date: Mon, 3 Apr 2023 16:21:43 +0100
Subject: [PATCH] feat: Add MathUtility.ExponentialDecay (#60)

---
 CHANGELOG.md                            |  1 +
 X10D.Tests/src/Math/MathUtilityTests.cs | 26 +++++++++++++++++++++++++
 X10D/src/Math/MathUtility.cs            | 24 +++++++++++++++++++++++
 3 files changed, 51 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9fc730b..32229ec 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added .NET 7 target.
 - X10D: Added `IntrinsicExtensions` and `IntrinsicUtility` which offer methods for vectors in `System.Runtime.Instrinsics`. (#70)
 - X10D: Added `MathUtility.Bias(float, float)` and `MathUtility.Bias(double, double)`.
+- X10D: Added `MathUtility.ExponentialDecay(float, float, float)` and `MathUtility.ExponentialDecay(double, double, double)`.
 - X10D: Added `MathUtility.InverseLerp(float, float, float)` and `MathUtility.InverseLerp(double, double, double)`
 - X10D: Added `MathUtility.ScaleRange(float, float, float, float, float)`
   and `MathUtility.ScaleRange(double, double, double, double, double)`
diff --git a/X10D.Tests/src/Math/MathUtilityTests.cs b/X10D.Tests/src/Math/MathUtilityTests.cs
index b230986..2834643 100644
--- a/X10D.Tests/src/Math/MathUtilityTests.cs
+++ b/X10D.Tests/src/Math/MathUtilityTests.cs
@@ -39,6 +39,32 @@ public class MathUtilityTests
         Assert.AreEqual(0.8f, floatResult, 1e-4f);
     }
 
+    [TestMethod]
+    public void ExponentialDecay_ShouldReturnCorrectValue_GivenDouble()
+    {
+        const double value = 100.0;
+        const double alpha = 0.5;
+        const double decay = 0.1;
+
+        const double expected = 95.122942;
+        double actual = MathUtility.ExponentialDecay(value, alpha, decay);
+
+        Assert.AreEqual(expected, actual, 1e-6);
+    }
+
+    [TestMethod]
+    public void ExponentialDecay_ShouldReturnCorrectValue_GivenSingle()
+    {
+        const float value = 100.0f;
+        const float alpha = 0.5f;
+        const float decay = 0.1f;
+
+        const float expected = 95.12295f;
+        float actual = MathUtility.ExponentialDecay(value, alpha, decay);
+
+        Assert.AreEqual(expected, actual, 1e-6f);
+    }
+
     [TestMethod]
     public void GammaToLinear_ShouldReturnQuarter_GivenQuarterAndGamma1()
     {
diff --git a/X10D/src/Math/MathUtility.cs b/X10D/src/Math/MathUtility.cs
index d76b03a..a3549a0 100644
--- a/X10D/src/Math/MathUtility.cs
+++ b/X10D/src/Math/MathUtility.cs
@@ -39,6 +39,30 @@ public static class MathUtility
         return value / ((1.0 / bias - 2.0) * (1.0 - value) + 1.0);
     }
 
+    /// <summary>
+    ///     Calculates exponential decay for a value.
+    /// </summary>
+    /// <param name="value">The value to decay.</param>
+    /// <param name="alpha">A factor by which to scale the decay.</param>
+    /// <param name="decay">The decay amount.</param>
+    /// <returns>The exponentially decayed value.</returns>
+    public static float ExponentialDecay(float value, float alpha, float decay)
+    {
+        return value * MathF.Exp(-decay * alpha);
+    }
+
+    /// <summary>
+    ///     Calculates exponential decay for a value.
+    /// </summary>
+    /// <param name="value">The value to decay.</param>
+    /// <param name="alpha">A factor by which to scale the decay.</param>
+    /// <param name="decay">The decay amount.</param>
+    /// <returns>The exponentially decayed value.</returns>
+    public static double ExponentialDecay(double value, double alpha, double decay)
+    {
+        return value * System.Math.Exp(-decay * alpha);
+    }
+
     /// <summary>
     ///     Converts a gamma-encoded value to a linear value using a gamma value of <c>2.2</c>.
     /// </summary>