Adding some functions for mapping between the integers, natural numbers, and ordered pairs of natural numbers.

Author: adam-rumpf

GameMakerScripts.yyp

@@ -6,6 +6,15 @@ All scripts are included in the `scripts/` folder of this repository. Each scrip
 
 The following is a brief description of the included functions, divided into rough categories.
 
+## Analysis Functions
+
+A variety of scripts dealing with functions and sets, which may have some uses for managing data structures.
+
+* [`_integer_to_natural`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_integer_to_natural/_integer_to_natural.gml): Converts an integer to a unique natural number using the zig-zagging bijection from _0, 1, -1, 2, -2, ..._ to _0, 1, 2, 3, 4, ..._. The inverse of `_natural_to_integer`.
+* [`_natural_to_integer`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_natural_to_integer/_natural_to_integer.gml): Converts a natural number to a unique integer using the zig-zagging bijection from _0, 1, 2, 3, 4, ..._ to _0, 1, -1, 2, -2, ..._. The inverse of `_integer_to_natural`.
+* [`_natural_to_pair`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_natural_to_pair/_natural_to_pair.gml): Converts a natural number to a unique ordered pair of natural numbers using the [inverse Cantor pairing function](https://en.wikipedia.org/wiki/Pairing_function#Inverting_the_Cantor_pairing_function). The inverse of `_pair_to_natural`.
+* [`_pair_to_natural`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_pair_to_natural/_pair_to_natural.gml): Converts an ordered pair of natural numbers to a unique natural number using the [Cantor pairing function](https://en.wikipedia.org/wiki/Pairing_function#Cantor_pairing_function). The inverse of `_pair_to_natural`.
+
 ## Array Functions
 
 Common array functions (such as searching and counting).
@@ -23,20 +32,20 @@ Common array functions (such as searching and counting).
 
 Numerical algorithms for computational mathematics.
 
-* [`_cubic_spline_coefficients`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_cubic_spline_coefficients/_cubic_spline_coefficients.gml): Calculates vectors of coefficients for the natural cubic polynomial interpolating a given data set.
+* [`_cubic_spline_coefficients`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_cubic_spline_coefficients/_cubic_spline_coefficients.gml): Calculates vectors of polynomial coefficients for the natural [cubic spline](https://en.wikipedia.org/wiki/Spline_interpolation) interpolating a given data set.
 * [`_cubic_spline_evaluate`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_cubic_spline_evaluate/_cubic_spline_evaluate.gml): Evaluates a piecewise cubic polynomial at a specific value given a given set of coefficient vectors and intervals.
-* [`_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.
+* [`_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](https://en.wikipedia.org/wiki/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](https://en.wikipedia.org/wiki/Newton%27s_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.
+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 (i.e. arrays of arrays).
 
-* [`_linear_solve`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_linear_solve/_linear_solve.gml): Solves a linear system given a coefficient matrix and righthand vector (using Gaussian elimination with partial pivoting).
+* [`_linear_solve`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_linear_solve/_linear_solve.gml): Solves a linear system given a coefficient matrix and righthand vector (using [Gaussian elimination with partial pivoting](https://en.wikipedia.org/wiki/Pivot_element)).
 * [`_matrix_multiply`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_matrix_multiply/_matrix_multiply.gml): Performs matrix-matrix, matrix-vector, and vector-vector multiplication.
 * [`_matrix_transpose`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_matrix_transpose/_matrix_transpose.gml): Transposes a 2D matrix.
-* [`_tridiagonal_solve`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_tridiagonal_solve/_tridiagonal_solve.gml): Solves a tridiagonal system (using the Thomas algorithm).
-* [`_triangular_solve`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_triangular_solve/_triangular_solve.gml): Solves an upper or lower triangular system (using forward or back substitution).
+* [`_tridiagonal_solve`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_tridiagonal_solve/_tridiagonal_solve.gml): Solves a tridiagonal system (using the [Thomas algorithm](https://en.wikipedia.org/wiki/Tridiagonal_matrix_algorithm)).
+* [`_triangular_solve`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_triangular_solve/_triangular_solve.gml): Solves an upper or lower triangular system (using [forward or back substitution](https://www.cs.cornell.edu/~bindel/class/cs6210-f12/notes/lec08.pdf)).
 * [`_unit_vector`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_unit_vector/_unit_vector.gml): Defines a unit direction vector between two coordinates.
 * [`_vector_angle`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_vector_angle/_vector_angle.gml): Calculates the acute angle between two vectors.
 * [`_vector_distance`](https://github.com/adam-rumpf/game-maker-scripts/blob/master/scripts/_vector_distance/_vector_distance.gml): Calculates the Lp-distance between two vectors.

README.md

@@ -1,5 +1,5 @@
 /// @func _cubic_spline_evaluate(a, b, c, d, x, t)
-/// @desc Evaluate a natural cubic spline at point t for coefficient vectors a, b, c, and d and input data vector x.
+/// @desc Evaluates a natural cubic spline at point t for coefficient vectors a, b, c, and d and input data vector x.
 /// @param {real[]} a Vector of cubic coefficients [a0, a1, ..., a(n-1)].
 /// @param {real[]} b Vector of quadratic coefficients [b0, b1, ..., b(n-1)].
 /// @param {real[]} c Vector of linear coefficients [c0, c1, ..., c(n-1)].
@@ -26,6 +26,7 @@ function _cubic_spline_evaluate(a, b, c, d, xx, t)
 	while ((t >= xx[ii+1]) && (ii < n-2))
 		ii++;
 
-	// Evaluate the function using the corresponding coefficients
-	return a[ii]*power((t-xx[ii]), 3) + b[ii]*sqr(t-xx[ii]) + c[ii]*(t-xx[ii]) + d[ii];
+	// Evaluate the polynomial using Horner's method and the coefficients for the chosen interval
+	var dx = t - xx[ii]; // position within interval
+	return ((a[ii]*dx + b[ii])*dx + c[ii])*dx + d[ii];
 }

scripts/_cubic_spline_evaluate/_cubic_spline_evaluate.gml

@@ -0,0 +1,22 @@
+/// @func _integer_to_natural(n)
+/// @desc Returns a unique natural number (beginning with 0) for a given integer, according to the straightforward zig-zagging bijection (0, 1, -1, 2, -2, ...).
+/// @param {int} n Integer for which to generate a unique natural number.
+/// @return {int} Natural number (at least 0) corresponding to integer n.
+/**
+ * This function is meant to be the inverse of the _nautral_to_integer()
+ * function. Both are based on the bijection which maps (0, 1, -1, 2, -2, ...)
+ * to (0, 1, 2, 3, 4, ...).
+ *
+ * For the Z -> N bijection we use the following piecewise definition:
+ *     |2n|-1    if n > 0
+ *     |2n|      if n <= 0
+ */
+
+function _integer_to_natural(n)
+{
+	// Apply piecewise definition depending on the sign of n
+	if (n > 0)
+		return floor(2*n - 1);
+	else
+		return floor(-2*n);
+}

scripts/_integer_to_natural/_integer_to_natural.gml

@@ -0,0 +1,22 @@
+/// @func _natural_to_integer(n)
+/// @desc Returns a unique integer for a given natural number (beginning with 0), according to the straightforward zig-zagging bijection (0, 1, -1, 2, -2, ...).
+/// @param {int} n Natural number for which to generate a unique integer.
+/// @return {int} Integer corresponding to natural number n.
+/**
+ * This function is meant to be the inverse of the _integer_to_natural()
+ * function. Both are based on the bijection which maps (0, 1, 2, 3, 4, ...)
+ * to (0, 1, -1, 2, -2, ...).
+ *
+ * For the N -> Z bijection we use the following piecewise definition:
+ *        -n/2    if n is even
+ *     (n+1)/2    if n is odd
+ */
+
+function _natural_to_integer(n)
+{
+	// Apply piecewise definition depending on the parity of n
+	if (n % 2 == 0)
+		return floor(-n/2);
+	else
+		return floor((n+1)/2);
+}

scripts/_natural_to_integer/_natural_to_integer.gml

@@ -0,0 +1,13 @@
+/// @func _natural_to_pair(x)
+/// @desc Returns a unique ordered pair of natural numbers (beginning with 0) for a given natural numbers (via the inverse Cantor pairing function).
+/// @param {int} x Nonnegative integer for which to find a coordinate.
+/// @return {int[]} Array of length 2 containing a pair of natural numbers (at least 0) corresponding to the input number.
+
+function _natural_to_pair(xx)
+{
+	// Apply the inverse Cantor pairing function
+	var sum = floor((sqrt(8*xx+1)-1)/2);
+	var triangle = (sqr(sum)+sum)/2;
+	var yy = xx - triangle;
+	return [sum - yy, yy];
+}

scripts/_natural_to_pair/_natural_to_pair.gml

@@ -0,0 +1,11 @@
+/// @func _pair_to_natural(m, n)
+/// @desc Returns a unique natural number (beginning with 0) for a given ordered pair of natural numbers (via the Cantor pairing function).
+/// @param {int} m First nonnegative integer coordinate.
+/// @param {int} n Second nonnegative integer coordinate.
+/// @return {int} Natural number (at least 0) corresponding to the ordered pair (m, n).
+
+function _pair_to_natural(m, n)
+{
+	// Apply the definition of the Cantor pairing function
+	return floor(((m+n)*(m+n+1))/2 + n);
+}