From 9aec87247a29895bc3581665bcf577225ac1c562 Mon Sep 17 00:00:00 2001 From: Revar Desmera Date: Mon, 1 May 2023 21:44:51 -0700 Subject: [PATCH] Synopses, etc for math.scad --- math.scad | 205 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 193 insertions(+), 12 deletions(-) diff --git a/math.scad b/math.scad index 29fec3b..9089dea 100644 --- a/math.scad +++ b/math.scad @@ -14,18 +14,30 @@ // Section: Math Constants // Constant: PHI -// Description: The golden ratio phi. +// Synopsis: The golden ratio φ (phi). Approximately 1.6180339887 +// Topics: Constants, Math +// See Also: EPSILON, INF, NAN +// Description: The golden ratio φ (phi). Approximately 1.6180339887 PHI = (1+sqrt(5))/2; // Constant: EPSILON -// Description: A really small value useful in comparing floating point numbers. ie: abs(a-b)0 ? // Function: hypot() +// Synopsis: Returns the hypotenuse length of a 2D or 3D triangle. +// Topics: Math +// See Also: hypot(), sqr(), log2() // Usage: // l = hypot(x, y, [z]); // Description: @@ -173,6 +202,9 @@ function hypot(x,y,z=0) = // Function: factorial() +// Synopsis: Returns the factorial of the given integer. +// Topics: Math +// See Also: hypot(), sqr(), log2() // Usage: // x = factorial(n, [d]); // Description: @@ -191,6 +223,9 @@ function factorial(n,d=0) = // Function: binomial() +// Synopsis: Returns the binomial coefficients of the integer `n`. +// Topics: Math +// See Also: hypot(), sqr(), log2(), factorial() // Usage: // x = binomial(n); // Description: @@ -210,10 +245,13 @@ function binomial(n) = // Function: binomial_coefficient() +// Synopsis: Returns the `k`-th binomial coefficient of the integer `n`. +// Topics: Math +// See Also: hypot(), sqr(), log2(), factorial() // Usage: // x = binomial_coefficient(n, k); // Description: -// Returns the k-th binomial coefficient of the integer `n`. +// Returns the `k`-th binomial coefficient of the integer `n`. // Arguments: // n = The integer to get the binomial coefficient of // k = The binomial coefficient index @@ -233,6 +271,9 @@ function binomial_coefficient(n,k) = // Function: gcd() +// Synopsis: Returns the Greatest Common Divisor/Factor of two integers. +// Topics: Math +// See Also: hypot(), sqr(), log2(), factorial(), binomial(), gcd(), lcm() // Usage: // x = gcd(a,b) // Description: @@ -256,6 +297,9 @@ function _lcmlist(a) = // Function: lcm() +// Synopsis: Returns the Least Common Multiple of two or more integers. +// Topics: Math +// See Also: hypot(), sqr(), log2(), factorial(), binomial(), gcd(), lcm() // Usage: // div = lcm(a, b); // divs = lcm(list); @@ -276,6 +320,9 @@ function lcm(a,b=[]) = // Section: Hyperbolic Trigonometry // Function: sinh() +// Synopsis: Returns the hyperbolic sine of the given value. +// Topics: Math, Trigonometry +// See Also: sinh(), cosh(), tanh(), asinh(), acosh(), atanh() // Usage: // a = sinh(x); // Description: Takes a value `x`, and returns the hyperbolic sine of it. @@ -285,6 +332,9 @@ function sinh(x) = // Function: cosh() +// Synopsis: Returns the hyperbolic cosine of the given value. +// Topics: Math, Trigonometry +// See Also: sinh(), cosh(), tanh(), asinh(), acosh(), atanh() // Usage: // a = cosh(x); // Description: Takes a value `x`, and returns the hyperbolic cosine of it. @@ -294,6 +344,9 @@ function cosh(x) = // Function: tanh() +// Synopsis: Returns the hyperbolic tangent of the given value. +// Topics: Math, Trigonometry +// See Also: sinh(), cosh(), tanh(), asinh(), acosh(), atanh() // Usage: // a = tanh(x); // Description: Takes a value `x`, and returns the hyperbolic tangent of it. @@ -303,6 +356,9 @@ function tanh(x) = // Function: asinh() +// Synopsis: Returns the hyperbolic arc-sine of the given value. +// Topics: Math, Trigonometry +// See Also: sinh(), cosh(), tanh(), asinh(), acosh(), atanh() // Usage: // a = asinh(x); // Description: Takes a value `x`, and returns the inverse hyperbolic sine of it. @@ -312,6 +368,9 @@ function asinh(x) = // Function: acosh() +// Synopsis: Returns the hyperbolic arc-cosine of the given value. +// Topics: Math, Trigonometry +// See Also: sinh(), cosh(), tanh(), asinh(), acosh(), atanh() // Usage: // a = acosh(x); // Description: Takes a value `x`, and returns the inverse hyperbolic cosine of it. @@ -321,6 +380,9 @@ function acosh(x) = // Function: atanh() +// Synopsis: Returns the hyperbolic arc-tangent of the given value. +// Topics: Math, Trigonometry +// See Also: sinh(), cosh(), tanh(), asinh(), acosh(), atanh() // Usage: // a = atanh(x); // Description: Takes a value `x`, and returns the inverse hyperbolic tangent of it. @@ -332,6 +394,9 @@ function atanh(x) = // Section: Quantization // Function: quant() +// Synopsis: Returns `x` quantized to the nearest integer multiple of `y`. +// Topics: Math, Quantization +// See Also: quant(), quantdn(), quantup() // Usage: // num = quant(x, y); // Description: @@ -370,6 +435,9 @@ function _roundall(data) = // Function: quantdn() +// Synopsis: Returns `x` quantized down to an integer multiple of `y`. +// Topics: Math, Quantization +// See Also: quant(), quantdn(), quantup() // Usage: // num = quantdn(x, y); // Description: @@ -408,6 +476,9 @@ function _floorall(data) = // Function: quantup() +// Synopsis: Returns `x` quantized uo to an integer multiple of `y`. +// Topics: Math, Quantization +// See Also: quant(), quantdn(), quantup() // Usage: // num = quantup(x, y); // Description: @@ -448,6 +519,9 @@ function _ceilall(data) = // Section: Constraints and Modulos // Function: constrain() +// Synopsis: Returns a value constrained between `minval` and `maxval`, inclusive. +// Topics: Math +// See Also: posmod(), modang() // Usage: // val = constrain(v, minval, maxval); // Description: @@ -468,6 +542,9 @@ function constrain(v, minval, maxval) = // Function: posmod() +// Synopsis: Returns the positive modulo of a value. +// Topics: Math +// See Also: constrain(), posmod(), modang() // Usage: // mod = posmod(x, m) // Description: @@ -489,6 +566,9 @@ function posmod(x,m) = // Function: modang() +// Synopsis: Returns an angle normalized to between -180º and 180º. +// Topics: Math +// See Also: constrain(), posmod(), modang() // Usage: // ang = modang(x); // Description: @@ -509,6 +589,9 @@ function modang(x) = // Section: Operations on Lists (Sums, Mean, Products) // Function: sum() +// Synopsis: Returns the sum of a list of values. +// Topics: Math +// See Also: mean(), median(), product(), cumsum() // Usage: // x = sum(v, [dflt]); // Description: @@ -534,6 +617,9 @@ function _sum(v,_total,_i=0) = _i>=len(v) ? _total : _sum(v,_total+v[_i], _i+1); // Function: mean() +// Synopsis: Returns the mean value of a list of values. +// Topics: Math, Statistics +// See Also: sum(), mean(), median(), product() // Usage: // x = mean(v); // Description: @@ -551,6 +637,9 @@ function mean(v) = // Function: median() +// Synopsis: Returns the median value of a list of values. +// Topics: Math, Statistics +// See Also: sum(), mean(), median(), product() // Usage: // middle = median(v) // Description: @@ -567,6 +656,9 @@ function median(v) = // Function: deltas() +// Synopsis: Returns the deltas between a list of values. +// Topics: Math, Statistics +// See Also: sum(), mean(), median(), product() // Usage: // delts = deltas(v,[wrap]); // Description: @@ -585,6 +677,9 @@ function deltas(v, wrap=false) = // Function: cumsum() +// Synopsis: Returns the running cumulative sum of a list of values. +// Topics: Math, Statistics +// See Also: sum(), mean(), median(), product() // Usage: // sums = cumsum(v); // Description: @@ -609,6 +704,9 @@ function _cumsum(v,_i=0,_acc=[]) = // Function: product() +// Synopsis: Returns the multiplicative product of a list of values. +// Topics: Math, Statistics +// See Also: sum(), mean(), median(), product(), cumsum() // Usage: // x = product(v); // Description: @@ -634,6 +732,9 @@ function _product(v, i=0, _tot) = // Function: cumprod() +// Synopsis: Returns the running cumulative product of a list of values. +// Topics: Math, Statistics +// See Also: sum(), mean(), median(), product(), cumsum() // Description: // Returns a list where each item is the cumulative product of all items up to and including the corresponding entry in the input list. // If passed an array of vectors, returns a list of elementwise vector products. If passed a list of square matrices returns matrix @@ -673,6 +774,9 @@ function _cumprod_vec(v,_i=0,_acc=[]) = // Function: convolve() +// Synopsis: Returns the convolution of `p` and `q`. +// Topics: Math, Statistics +// See Also: sum(), mean(), median(), product(), cumsum() // Usage: // x = convolve(p,q); // Description: @@ -706,13 +810,20 @@ function convolve(p,q) = // Function: sum_of_sines() +// Synopsis: Returns the sum of one or more sine waves at a given angle. +// Topics: Math, Statistics +// See Also: sum(), mean(), median(), product(), cumsum() // Usage: // sum_of_sines(a,sines) // Description: -// Gives the sum of a series of sines, at a given angle. +// Given a list of sine waves, returns the sum of the sines at the given angle. +// Each sine wave is given as an `[AMPLITUDE, FREQUENCY, PHASE_ANGLE]` triplet. +// - `AMPLITUDE` is the height of the sine wave above (and below) `0`. +// - `FREQUENCY` is the number of times the sine wave repeats in 360º. +// - `PHASE_ANGLE` is the offset in degrees of the sine wave. // Arguments: // a = Angle to get the value for. -// sines = List of [amplitude, frequency, offset] items, where the frequency is the number of times the cycle repeats around the circle. +// sines = List of [amplitude, frequency, phase_angle] items, where the frequency is the number of times the cycle repeats around the circle. // Example: // v = sum_of_sines(30, [[10,3,0], [5,5.5,60]]); function sum_of_sines(a, sines) = @@ -729,6 +840,9 @@ function sum_of_sines(a, sines) = // Section: Random Number Generation // Function: rand_int() +// Synopsis: Returns a random integer. +// Topics: Random +// See Also: rand_int(), random_points(), gaussian_rands(), random_polygon(), spherical_random_points(), exponential_rands() // Usage: // rand_int(minval, maxval, n, [seed]); // Description: @@ -749,10 +863,11 @@ function rand_int(minval, maxval, n, seed=undef) = // Function: random_points() +// Synopsis: Returns a list of random points. +// Topics: Random, Points +// See Also: rand_int(), random_points(), random_polygon(), spherical_random_points() // Usage: // points = random_points(n, dim, [scale], [seed]); -// See Also: random_polygon(), spherical_random_points() -// Topics: Random, Points // Description: // Generate `n` uniform random points of dimension `dim` with data ranging from -scale to +scale. // The `scale` may be a number, in which case the random data lies in a cube, @@ -776,6 +891,9 @@ function random_points(n, dim, scale=1, seed) = // Function: gaussian_rands() +// Synopsis: Returns a list of random numbers with a gaussian distribution. +// Topics: Random, Statistics +// See Also: rand_int(), random_points(), gaussian_rands(), random_polygon(), spherical_random_points(), exponential_rands() // Usage: // arr = gaussian_rands([n],[mean], [cov], [seed]); // Description: @@ -806,6 +924,9 @@ function gaussian_rands(n=1, mean=0, cov=1, seed=undef) = // Function: exponential_rands() +// Synopsis: Returns a list of random numbers with an exponential distribution. +// Topics: Random, Statistics +// See Also: rand_int(), random_points(), gaussian_rands(), random_polygon(), spherical_random_points() // Usage: // arr = exponential_rands([n], [lambda], [seed]) // Description: @@ -821,11 +942,13 @@ function exponential_rands(n=1, lambda=1, seed) = ) -(1/lambda) * [for(x=unif) x==1 ? 708.3964185322641 : ln(1-x)]; // Use ln(min_float) when x is 1 + // Function: spherical_random_points() +// Synopsis: Returns a list of random points on the surface of a sphere. +// Topics: Random, Points +// See Also: rand_int(), random_points(), gaussian_rands(), random_polygon(), spherical_random_points() // Usage: // points = spherical_random_points([n], [radius], [seed]); -// See Also: random_polygon(), random_points() -// Topics: Random, Points // Description: // Generate `n` 3D uniformly distributed random points lying on a sphere centered at the origin with radius equal to `radius`. // Arguments: @@ -849,10 +972,11 @@ function spherical_random_points(n=1, radius=1, seed) = // Function: random_polygon() +// Synopsis: Returns the CCW path of a simple random polygon. +// Topics: Random, Polygon +// See Also: random_points(), spherical_random_points() // Usage: // points = random_polygon([n], [size], [seed]); -// See Also: random_points(), spherical_random_points() -// Topics: Random, Polygon // Description: // Generate the `n` vertices of a random counter-clockwise simple 2d polygon // inside a circle centered at the origin with radius `size`. @@ -876,6 +1000,9 @@ function random_polygon(n=3,size=1, seed) = // Section: Calculus // Function: deriv() +// Synopsis: Returns the first derivative estimate of a list of data. +// Topics: Math, Calculus +// See Also: deriv(), deriv2(), deriv3() // Usage: // x = deriv(data, [h], [closed]) // Description: @@ -941,6 +1068,9 @@ function _deriv_nonuniform(data, h, closed) = // Function: deriv2() +// Synopsis: Returns the second derivative estimate of a list of data. +// Topics: Math, Calculus +// See Also: deriv(), deriv2(), deriv3() // Usage: // x = deriv2(data, [h], [closed]) // Description: @@ -985,6 +1115,9 @@ function deriv2(data, h=1, closed=false) = // Function: deriv3() +// Synopsis: Returns the third derivative estimate of a list of data. +// Topics: Math, Calculus +// See Also: deriv(), deriv2(), deriv3() // Usage: // x = deriv3(data, [h], [closed]) // Description: @@ -1030,6 +1163,9 @@ function deriv3(data, h=1, closed=false) = // Function: complex() +// Synopsis: Replaces scalars in a list or matrix with complex number 2-vectors. +// Topics: Math, Complex Numbers +// See Also: c_mul(), c_div(), c_conj(), c_real(), c_imag(), c_ident(), c_norm() // Usage: // z = complex(list) // Description: @@ -1041,6 +1177,9 @@ function complex(list) = // Function: c_mul() +// Synopsis: Multiplies two complex numbers. +// Topics: Math, Complex Numbers +// See Also: complex(), c_mul(), c_div(), c_conj(), c_real(), c_imag(), c_ident(), c_norm() // Usage: // c = c_mul(z1,z2) // Description: @@ -1077,6 +1216,9 @@ function _c_mul(z1,z2) = // Function: c_div() +// Synopsis: Divides two complex numbers. +// Topics: Math, Complex Numbers +// See Also: complex(), c_mul(), c_div(), c_conj(), c_real(), c_imag(), c_ident(), c_norm() // Usage: // x = c_div(z1,z2) // Description: @@ -1093,6 +1235,9 @@ function c_div(z1,z2) = // Function: c_conj() +// Synopsis: Returns the complex conjugate of the input. +// Topics: Math, Complex Numbers +// See Also: complex(), c_mul(), c_div(), c_conj(), c_real(), c_imag(), c_ident(), c_norm() // Usage: // w = c_conj(z) // Description: @@ -1104,6 +1249,9 @@ function c_conj(z) = // Function: c_real() +// Synopsis: Returns the real part of a complex number, vector or matrix.. +// Topics: Math, Complex Numbers +// See Also: complex(), c_mul(), c_div(), c_conj(), c_real(), c_imag(), c_ident(), c_norm() // Usage: // x = c_real(z) // Description: @@ -1115,6 +1263,9 @@ function c_real(z) = // Function: c_imag() +// Synopsis: Returns the imaginary part of a complex number, vector or matrix.. +// Topics: Math, Complex Numbers +// See Also: complex(), c_mul(), c_div(), c_conj(), c_real(), c_imag(), c_ident(), c_norm() // Usage: // x = c_imag(z) // Description: @@ -1126,6 +1277,9 @@ function c_imag(z) = // Function: c_ident() +// Synopsis: Returns an n by n complex identity matrix. +// Topics: Math, Complex Numbers +// See Also: complex(), c_mul(), c_div(), c_conj(), c_real(), c_imag(), c_ident(), c_norm() // Usage: // I = c_ident(n) // Description: @@ -1134,6 +1288,9 @@ function c_ident(n) = [for (i = [0:1:n-1]) [for (j = [0:1:n-1]) (i==j)?[1,0]:[0, // Function: c_norm() +// Synopsis: Returns the norm of a complex number or vector. +// Topics: Math, Complex Numbers +// See Also: complex(), c_mul(), c_div(), c_conj(), c_real(), c_imag(), c_ident(), c_norm() // Usage: // n = c_norm(z) // Description: @@ -1144,6 +1301,9 @@ function c_norm(z) = norm_fro(z); // Section: Polynomials // Function: quadratic_roots() +// Synopsis: Computes roots for the quadratic equation. +// Topics: Math, Geometry, Complex Numbers +// See Also: quadratic_roots(), polynomial(), poly_mult(), poly_div(), poly_add() // Usage: // roots = quadratic_roots(a, b, c, [real]) // Description: @@ -1177,6 +1337,9 @@ function quadratic_roots(a,b,c,real=false) = // Function: polynomial() +// Synopsis: Calculates a polynomial equation at a given value. +// Topics: Math, Complex Numbers +// See Also: quadratic_roots(), polynomial(), poly_mult(), poly_div(), poly_add(), poly_roots() // Usage: // x = polynomial(p, z) // Description: @@ -1194,6 +1357,9 @@ function polynomial(p,z,k,total) = // Function: poly_mult() +// Synopsis: Returns the polynomial result of multiplying two polynomial equations. +// Topics: Math +// See Also: quadratic_roots(), polynomial(), poly_mult(), poly_div(), poly_add(), poly_roots() // Usage: // x = polymult(p,q) // x = polymult([p1,p2,p3,...]) @@ -1213,6 +1379,9 @@ function poly_mult(p,q) = // Function: poly_div() +// Synopsis: Returns the polynomial quotient and remainder results of dividing two polynomial equations. +// Topics: Math +// See Also: quadratic_roots(), polynomial(), poly_mult(), poly_div(), poly_add(), poly_roots() // Usage: // [quotient,remainder] = poly_div(n,d) // Description: @@ -1251,6 +1420,9 @@ function _poly_trim(p,eps=0) = // Function: poly_add() +// Synopsis: Returns the polynomial sum of adding two polynomial equations. +// Topics: Math +// See Also: quadratic_roots(), polynomial(), poly_mult(), poly_div(), poly_add(), poly_roots() // Usage: // sum = poly_add(p,q) // Description: @@ -1266,6 +1438,9 @@ function poly_add(p,q) = // Function: poly_roots() +// Synopsis: Returns all complex number roots of the given real polynomial. +// Topics: Math, Complex Numbers +// See Also: quadratic_roots(), polynomial(), poly_mult(), poly_div(), poly_add(), poly_roots() // Usage: // roots = poly_roots(p, [tol]); // Description: @@ -1336,6 +1511,9 @@ function _poly_roots(p, pderiv, s, z, tol, i=0) = // Function: real_roots() +// Synopsis: Returns all real roots of the given real polynomial. +// Topics: Math, Complex Numbers +// See Also: quadratic_roots(), polynomial(), poly_mult(), poly_div(), poly_add(), poly_roots() // Usage: // roots = real_roots(p, [eps], [tol]) // Description: @@ -1378,6 +1556,9 @@ function real_roots(p,eps=undef,tol=1e-14) = // Section: Operations on Functions // Function: root_find() +// Synopsis: Finds a root of the given continuous function. +// Topics: Math +// See Also: quadratic_roots(), polynomial(), poly_mult(), poly_div(), poly_add(), poly_roots() // Usage: // x = root_find(f, x0, x1, [tol]) // Description: