@rian8337/osu-base 3.0.0-beta.4 → 3.0.0-beta.7

package/dist/index.js

@@ -2797,6 +2797,49 @@ class Precision {
         return (this.almostEqualsNumber(vec1.x, vec2.x, acceptableDifference) &&
             this.almostEqualsNumber(vec1.y, vec2.y, acceptableDifference));
     }
+    /**
+     * Checks whether two real numbers are almost equal.
+     *
+     * @param a The first number.
+     * @param b The second number.
+     * @param maximumError The accuracy required for being almost equal. Defaults to `10 * 2^(-53)`.
+     * @returns Whether the two values differ by no more than 10 * 2^(-52).
+     */
+    static almostEqualRelative(a, b, maximumError = 10 * Math.pow(2, -53)) {
+        return this.almostEqualNormRelative(a, b, a - b, maximumError);
+    }
+    /**
+     * Compares two numbers and determines if they are equal within the specified maximum error.
+     *
+     * @param a The norm of the first value (can be negative).
+     * @param b The norm of the second value (can be negative).
+     * @param diff The norm of the difference of the two values (can be negative).
+     * @param maximumError The accuracy required for being almost equal.
+     * @returns Whether both numbers are almost equal up to the specified maximum error.
+     */
+    static almostEqualNormRelative(a, b, diff, maximumError) {
+        // If A or B are infinity (positive or negative) then
+        // only return true if they are exactly equal to each other -
+        // that is, if they are both infinities of the same sign.
+        if (!Number.isFinite(a) || !Number.isFinite(b)) {
+            return a === b;
+        }
+        // If A or B are a NAN, return false. NANs are equal to nothing,
+        // not even themselves.
+        if (Number.isNaN(a) || Number.isNaN(b)) {
+            return false;
+        }
+        // If one is almost zero, fall back to absolute equality.
+        const doublePrecision = Math.pow(2, -53);
+        if (Math.abs(a) < doublePrecision || Math.abs(b) < doublePrecision) {
+            return Math.abs(diff) < maximumError;
+        }
+        if ((a === 0 && Math.abs(b) < maximumError) ||
+            (b === 0 && Math.abs(a) < maximumError)) {
+            return true;
+        }
+        return (Math.abs(diff) < maximumError * Math.max(Math.abs(a), Math.abs(b)));
+    }
 }
 
 /**
@@ -6200,6 +6243,236 @@ class BeatmapEncoder extends Encoder {
     }
 }
 
+class ZeroCrossingBracketing {
+    /**
+     * Detect a range containing at least one root.
+     *
+     * This iterative method stops when two values with opposite signs are found.
+     *
+     * @param f The function to detect roots from.
+     * @param bounds The upper and lower value of the range.
+     * @param factor The growing factor of research. Defaults to 1.6.
+     * @param maxIterations Maximum number of iterations. Defaults to 50.
+     * @returns Whether the bracketing operation succeeded.
+     */
+    static expand(f, bounds, factor = 1.6, maxIterations = 50) {
+        const originalUpperBound = bounds.upperBound;
+        const originalLowerBound = bounds.lowerBound;
+        if (originalLowerBound >= originalUpperBound) {
+            throw new RangeError("Upper bound must be greater than lower bound.");
+        }
+        let fmin = f(originalLowerBound);
+        let fmax = f(originalUpperBound);
+        for (let i = 0; i < maxIterations; ++i) {
+            if (Math.sign(fmin) !== Math.sign(fmax)) {
+                return true;
+            }
+            if (Math.abs(fmin) < Math.abs(fmax)) {
+                bounds.lowerBound +=
+                    factor * (bounds.lowerBound - bounds.upperBound);
+                fmin = f(bounds.lowerBound);
+            }
+            else {
+                bounds.upperBound +=
+                    factor * (bounds.upperBound - bounds.lowerBound);
+                fmax = f(bounds.upperBound);
+            }
+        }
+        bounds.lowerBound = originalLowerBound;
+        bounds.upperBound = originalUpperBound;
+        return false;
+    }
+    static reduce(f, bounds, subdivisions = 1000) {
+        const originalUpperBound = bounds.upperBound;
+        const originalLowerBound = bounds.lowerBound;
+        if (originalLowerBound >= originalUpperBound) {
+            throw new RangeError("Upper bound must be greater than lower bound.");
+        }
+        // TODO: Consider binary-style search instead of linear scan
+        const fmin = f(bounds.lowerBound);
+        const fmax = f(bounds.upperBound);
+        if (Math.sign(fmin) != Math.sign(fmax)) {
+            return true;
+        }
+        const subdiv = (bounds.upperBound - bounds.lowerBound) / subdivisions;
+        let smin = bounds.lowerBound;
+        const sign = Math.sign(fmin);
+        for (let i = 0; i < subdivisions; ++i) {
+            const smax = smin + subdiv;
+            const sfmax = f(smax);
+            if (!Number.isFinite(sfmax)) {
+                // expand interval to include pole
+                smin = smax;
+                continue;
+            }
+            if (Math.sign(sfmax) != sign) {
+                bounds.upperBound = smax;
+                bounds.lowerBound = smin;
+                return true;
+            }
+            smin = smax;
+        }
+        bounds.lowerBound = originalLowerBound;
+        bounds.upperBound = originalUpperBound;
+        return false;
+    }
+    static expandReduce(f, bounds, expansionFactor = 1.6, expansionMaxIterations = 50, reduceSubdivisions = 100) {
+        return (this.expand(f, bounds, expansionFactor, expansionMaxIterations) ||
+            this.reduce(f, bounds, reduceSubdivisions));
+    }
+}
+
+/**
+ * Algorithm by Brent, Van Wijngaarden, Dekker et al.
+ *
+ * Implementation inspired by Press, Teukolsky, Vetterling, and Flannery, "Numerical Recipes in C", 2nd edition, Cambridge University Press.
+ */
+class Brent {
+    /**
+     * Finds a solution to the equation f(x) = 0.
+     *
+     * @param f The function to find roots from.
+     * @param bounds The upper and lower root bounds.
+     * @param accuracy The desired accuracy. The root will be refined until the accuracy or the maximum number of iterations is reached. Defaults to 1e-8. Must be greater than 0.
+     * @param maxIterations The maximum number of iterations. Defaults to 100.
+     * @param expandFactor The factor at which to expand the bounds, if needed. Defaults to 1.6.
+     * @param maxExpandIterations The maximum number of expand iterations. Defaults to 100.
+     * @returns The root with the specified accuracy. Throws an error if the algorithm failed to converge.
+     */
+    static findRootExpand(f, bounds, accuracy = 1e-8, maxIterations = 100, expandFactor = 1.6, maxExpandIterations = 100) {
+        ZeroCrossingBracketing.expandReduce(f, bounds, expandFactor, maxExpandIterations, maxExpandIterations * 10);
+        return this.findRoot(f, bounds, accuracy, maxIterations);
+    }
+    /**
+     * Finds a solution to the equation f(x) = 0.
+     *
+     * @param f The function to find roots from.
+     * @param bounds The upper and lower root bounds.
+     * @param accuracy The desired accuracy. The root will be refined until the accuracy or the maximum number of iterations is reached. Defaults to 1e-8. Must be greater than 0.
+     * @param maxIterations The maximum number of iterations. Defaults to 100.
+     * @returns The root with the specified accuracy. Throws an error if the algorithm failed to converge.
+     */
+    static findRoot(f, bounds, accuracy = 1e-8, maxIterations = 100) {
+        const root = this.tryFindRoot(f, bounds, accuracy, maxIterations);
+        if (root === null) {
+            throw new Error("The algorithm has failed, exceeded the number of iterations allowed or there is no root within the provided bounds.");
+        }
+        return root;
+    }
+    /**
+     * Finds a solution to the equation f(x) = 0.
+     *
+     * @param f The function to find roots from.
+     * @param bounds The upper and lower root bounds.
+     * @param accuracy The desired accuracy. The root will be refined until the accuracy or the maximum number of iterations is reached. Must be greater than 0.
+     * @param maxIterations The maximum number of iterations. Usually 100.
+     * @returns The root with the specified accuracy, `null` if not found.
+     */
+    static tryFindRoot(f, bounds, accuracy, maxIterations) {
+        if (accuracy <= 0) {
+            throw new RangeError("Accuracy must be greater than 0.");
+        }
+        let { lowerBound, upperBound } = bounds;
+        let fmin = f(lowerBound);
+        let fmax = f(upperBound);
+        let froot = fmax;
+        let d = 0;
+        let e = 0;
+        let root = upperBound;
+        let xMid = Number.NaN;
+        // Root must be bracketed.
+        if (Math.sign(fmin) === Math.sign(fmax)) {
+            return null;
+        }
+        for (let i = 0; i <= maxIterations; ++i) {
+            // Adjust bounds.
+            if (Math.sign(froot) === Math.sign(fmax)) {
+                upperBound = lowerBound;
+                fmax = fmin;
+                e = d = root - lowerBound;
+            }
+            if (Math.abs(fmax) < Math.abs(froot)) {
+                lowerBound = root;
+                root = upperBound;
+                upperBound = lowerBound;
+                fmin = froot;
+                froot = fmax;
+                fmax = fmin;
+            }
+            // Convergence check
+            const xAcc1 = 2 * Math.pow(2, -53) * Math.abs(root) + accuracy / 2;
+            const xMidOld = xMid;
+            xMid = (upperBound - root) / 2;
+            if (Math.abs(xMid) <= xAcc1 ||
+                Precision.almostEqualNormRelative(froot, 0, froot, accuracy)) {
+                return root;
+            }
+            if (xMid === xMidOld) {
+                // accuracy not sufficient, but cannot be improved further
+                return null;
+            }
+            if (Math.abs(e) >= xAcc1 && Math.abs(fmin) > Math.abs(froot)) {
+                // Attempt inverse quadratic interpolation
+                const s = froot / fmin;
+                let p;
+                let q;
+                if (Precision.almostEqualRelative(lowerBound, upperBound)) {
+                    p = 2 * xMid * s;
+                    q = 1 - s;
+                }
+                else {
+                    q = fmin / fmax;
+                    const r = froot / fmax;
+                    p =
+                        s *
+                            (2 * xMid * q * (q - r) -
+                                (root - lowerBound) * (r - 1));
+                    q = (q - 1) * (r - 1) * (s - 1);
+                }
+                if (p > 0) {
+                    // Check whether in bounds
+                    q = -q;
+                }
+                p = Math.abs(p);
+                if (2 * p <
+                    Math.min(3 * xMid * q - Math.abs(xAcc1 * q), Math.abs(e * q))) {
+                    // Accept interpolation
+                    e = d;
+                    d = p / q;
+                }
+                else {
+                    // Interpolation failed, use bisection
+                    d = xMid;
+                    e = d;
+                }
+            }
+            else {
+                // Bounds decreasing too slowly, use bisection
+                d = xMid;
+                e = d;
+            }
+            lowerBound = root;
+            fmin = froot;
+            if (Math.abs(d) > xAcc1) {
+                root += d;
+            }
+            else {
+                root += this.sign(xAcc1, xMid);
+            }
+            froot = f(root);
+        }
+        return null;
+    }
+    /**
+     * Helper method useful for preventing rounding errors.
+     *
+     * @returns a * sign(b)
+     */
+    static sign(a, b) {
+        return b >= 0 ? (a >= 0 ? a : -a) : a >= 0 ? -a : a;
+    }
+}
+
 /**
  * Types of easing.
  *
@@ -6665,6 +6938,29 @@ class ErrorFunction {
         }
         return this.erfImp(x, false);
     }
+    /**
+     * Calculates the complementary error function.
+     *
+     * @param x The value to evaluate.
+     * @returns The complementary error function evaluated at given value, or:
+     * - 0 if `x === Number.POSITIVE_INFINITY`;
+     * - 2 if `x === Number.NEGATIVE_INFINITY`.
+     */
+    static erfc(x) {
+        if (x === 0) {
+            return 1;
+        }
+        if (x === Number.POSITIVE_INFINITY) {
+            return 0;
+        }
+        if (x === Number.NEGATIVE_INFINITY) {
+            return 2;
+        }
+        if (Number.isNaN(x)) {
+            return Number.NaN;
+        }
+        return this.erfImp(x, true);
+    }
     /**
      * Calculates the inverse error function evaluated at z.
      *
@@ -7508,6 +7804,16 @@ class MapInfo {
     }
 }
 
+/**
+ * Represents the osu! playfield.
+ */
+class Playfield {
+    /**
+     * The size of the playfield, which is 512x384.
+     */
+    static baseSize = new Vector2(512, 384);
+}
+
 dotenv.config();
 
 exports.Accuracy = Accuracy;
@@ -7526,6 +7832,7 @@ exports.BeatmapMetadata = BeatmapMetadata;
 exports.BeatmapVideo = BeatmapVideo;
 exports.BlendingParameters = BlendingParameters;
 exports.BreakPoint = BreakPoint;
+exports.Brent = Brent;
 exports.Circle = Circle;
 exports.Command = Command;
 exports.CommandLoop = CommandLoop;
@@ -7570,6 +7877,7 @@ exports.ModUtil = ModUtil;
 exports.OsuAPIRequestBuilder = OsuAPIRequestBuilder;
 exports.OsuHitWindow = OsuHitWindow;
 exports.PathApproximator = PathApproximator;
+exports.Playfield = Playfield;
 exports.Polynomial = Polynomial;
 exports.Precision = Precision;
 exports.RGBColor = RGBColor;
@@ -7595,4 +7903,5 @@ exports.TimingControlPoint = TimingControlPoint;
 exports.TimingControlPointManager = TimingControlPointManager;
 exports.Utils = Utils;
 exports.Vector2 = Vector2;
+exports.ZeroCrossingBracketing = ZeroCrossingBracketing;
 //# sourceMappingURL=index.js.map