Author: adam-rumpf

GameMakerScripts.yyp

@@ -1,6 +1,6 @@
 # GameMaker Scripts
 
-A collection of general utility scripts for GameMaker Studio 2 (Version 2.3).
+A collection of general utility and mathematical functions for GameMaker Studio 2 (Version 2.3).
 
 All scripts are included in the `scripts/` folder of this repository. Each script defines a single function. Most functions are standalone and are meant to be taken à la carte, but some of the more mathematically complicated functions depend on other scripts, indicated in a `@requires` tag. All function names begin with an underscore (`_`) in order to distinguish them from built-in functions.
 
@@ -19,6 +19,13 @@ Common array functions (such as searching and counting).
 * [`_permute`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_permute/_permute.gml): Permutes the elements of an array according to a given permutation array.
 * [`_range`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_range/_range.gml): Generates an array of equally-spaced values over a specified range with a specified step size.
 
+## Computational Mathematics Functions
+
+Numerical algorithms for computational mathematics.
+
+* [`_root_bisection`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_root_bisection/_root_bisection.gml): Finds a function root on a specified interval using the bisection method.
+* [`_root_newton`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_root_newton/_root_newton.gml): Finds a function root given a derivative and an initial guess using Newton's method.
+
 ## Linear Algebra Functions
 
 Common linear algebra algorithms for dealing with matrices and vectors. In all functions, _vectors_ are considered to be 1D arrays while _matrices_ are 2D arrays.

README.md

@@ -0,0 +1,19 @@
+/// @func _array_function(f, arr)
+/// @desc Applies a given function to every value in an array.
+/// @func {function} f Function to be applied. Should accept a single input.
+/// @func {*[]} arr 1D array to apply function to.
+/// @return {*[]} Array consisting of f applied to every value in arr.
+
+function _array_function(f, arr)
+{
+	// Get array size
+	var n = array_length(arr);
+	
+	// Apply function to all values in input array
+	var out = array_create(n); // output array
+	for (var i = 0; i < n; i++)
+		out[i] = f(arr[i]);
+	
+	// Return output array
+	return out;
+}

scripts/_array_function/_array_function.gml

@@ -1,4 +1,4 @@
-/// @func _array_max(arr[, val=true])
+/// @func _array_max(arr[, val])
 /// @desc Finds the maximum value (or its index) in an array.
 /// @param {real[]} arr Array to search.
 /// @param {bool} [val=true] If true the maximum value is returned, if false the (first) index of the maximum value is returned.

scripts/_array_max/_array_max.gml

@@ -1,4 +1,4 @@
-/// @func _array_min(arr[, val=true])
+/// @func _array_min(arr[, val])
 /// @desc Finds the minimum value (or its index) in an array.
 /// @param {real[]} arr Array to search.
 /// @param {bool} [val=true] If true the minimum value is returned, if false the (first) index of the minimum value is returned.

scripts/_array_min/_array_min.gml

@@ -1,6 +1,6 @@
 /// @func _random_weighted_index(wt)
 /// @desc Returns a random array index with probabilities defined by a given weight array.
-/// @param {*[]} wt Array of weights (corresponding to indices 0, 1, 2, ...).
+/// @param {real[]} wt Array of weights (corresponding to indices 0, 1, 2, ...). Negative weights are treated as zero.
 /// @return {int} Randomly chosen array index.
 
 function _random_weighted_index(wt)
@@ -10,7 +10,13 @@ function _random_weighted_index(wt)
 	tot = 0.0; // total weight
 	n = array_length(wt); // number of indices
 	for (var i = 0; i < n; i++)
+	{
+		// Ignore negative weights
+		if (wt[i] < 0)
+			continue;
+		
 		tot += wt[i];
+	}
 
 	// Generate a random number
 	var r = random_range(0, tot);

scripts/_random_weighted_index/_random_weighted_index.gml

@@ -0,0 +1,62 @@
+/// @func _root_bisection(f, a, b[, err[, cutoff]])
+/// @func Finds the root of a real-valued function on a specified interval using the bisection method.
+/// @param {function} f Function (which maps reals to reals) to find the root of. The signs of f(a) and f(b) must be opposite.
+/// @param {real} a Lower bound of search interval.
+/// @param {real} b Upper bound of search interval.
+/// @param {real} [err=0.01] Error bound to define stopping criterion. The search ends as soon as the bound falls below this value.
+/// @param {int} [cutoff=100] Iteration cutoff. The search ends as soon as the number of iterations crosses this bound, regardless of the error.
+/// @return {real} Estimate of root (or undefined in case of problem).
+
+function _root_bisection(f, a, b)
+{
+	// Check for optional arguments
+	var err = (argument_count > 3 ? argument[3] : 0.01);
+	var cutoff = (argument_count > 4 ? argument[4] : 100);
+	
+	// Test for trivial roots at boundaries
+	if (f(a) == 0)
+		return a;
+	if (f(b) == 0)
+		return b;
+	
+	// Verify that sign of function is opposite on boundaries
+	if (sign(f(a)) == sign(f(b)))
+		return undefined;
+	
+	// Define local variables for boundaries
+	var lb, ub;
+	lb = a; // lower bound
+	ub = b; // upper bound
+	
+	// Ensure that boundaries are in order
+	if (lb >= ub)
+	{
+		lb = b;
+		ub = a;
+	}
+	
+	// Main search loop (error bound equals half of search interval)
+	var iter = 0; // iteration number
+	while (((ub - lb)/2 > err) && (iter < cutoff))
+	{
+		iter++;
+		
+		// Find midpoint and its sign
+		var mid, midsign;
+		mid = mean(lb, ub);
+		midsign = sign(f(mid));
+		
+		// Check whether midpoint is a root
+		if (f(mid) == 0)
+			return mid;
+		
+		// Choose upper or lower subinterval so that signs of endpoints remain opposite
+		if (midsign == sign(f(lb)))
+			lb = mid;
+		else
+			ub = mid;
+	}
+	
+	// Return final midpoint
+	return mean(lb, ub);
+}

scripts/_root_bisection/_root_bisection.gml

@@ -0,0 +1,42 @@
+/// @func _root_newton(f, fp, x0[, err[, cutoff]])
+/// @func Finds the root of a real-valued, differentiable function for an initial guess using Newton's method.
+/// @param {function} f Differentiable function (which maps reals to reals) to find the root of.
+/// @param {function} fp First derivative of function.
+/// @param {real} x0 Initial guess.
+/// @param {real} [err=0.01] Error bound to use as a cutoff criterion. The search ends as soon as the absolute function value falls below this bound.
+/// @param {int} [cutoff=100] Iteration cutoff. The search ends as soon as the number of iterations crosses this bound, regardless of the error.
+/// @return {real} Estimate of root (or undefined in case of problem).
+
+function _root_newton(f, fp, x0)
+{
+	// Check for optional arguments
+	var err = (argument_count > 3 ? argument[3] : 0.01);
+	var cutoff = (argument_count > 4 ? argument[4] : 100);
+	
+	// Initialize guess and corresponding function values
+	var xx, fx, fpx;
+	xx = x0; // current guess
+	fx = f(xx); // function value for current guess
+	fpx = fp(xx); // derivative of function guess
+	
+	// Main search loop (error is absolute value of function value)
+	var iter = 0; // iteration number
+	while ((abs(fx) > err) && (iter < cutoff))
+	{
+		iter++;
+		
+		// Check for division by zero
+		if (fpx == 0)
+			return undefined;
+		
+		// Newton iteration
+		xx -= fx/fpx;
+		
+		// Update function values
+		fx = f(xx);
+		fpx = fp(xx);
+	}
+	
+	// Return latest guess
+	return xx;
+}