Search
View source code
Display the source code in std/numeric.d from which this page was generated on github.
Report a bug
Quickly fork, edit online, and submit a pull request for this page. Requires a signed-in GitHub account. This works well for small changes. If you'd like to make larger changes you may want to consider using local clone.

# Module `std.numeric`

This module is a port of a growing fragment of the numeric header in Alexander Stepanov's Standard Template Library, with a few additions.

## Functions

NameDescription
``` cosineSimilarity(a, b) ``` Computes the cosine similarity of input ranges `a` and `b`. The two ranges must have the same length. If both ranges define length, the check is done once; otherwise, it is done at each iteration. If either range has all-zero elements, return 0.
``` decimalToFactorial(decimal, fac) ``` This function transforms `decimal` value into a value in the factorial number system stored in `fac`.
``` dotProduct(a, b) ``` Computes the dot product of input ranges `a` and `b`. The two ranges must have the same length. If both ranges define length, the check is done once; otherwise, it is done at each iteration.
``` entropy(r) ``` Computes entropy of input range `r` in bits. This function assumes (without checking) that the values in `r` are all in `[0, 1]`. For the entropy to be meaningful, often `r` should be normalized too (i.e., its values should sum to 1). The two-parameter version stops evaluating as soon as the intermediate result is greater than or equal to `max`.
``` euclideanDistance(a, b) ``` Computes Euclidean distance between input ranges `a` and `b`. The two ranges must have the same length. The three-parameter version stops computation as soon as the distance is greater than or equal to `limit` (this is useful to save computation if a small distance is sought).
``` fft(range) ``` Convenience functions that create an `Fft` object, run the FFT or inverse FFT and return the result. Useful for one-off FFTs.
``` findLocalMin(f, ax, bx, relTolerance, absTolerance) ``` Find a real minimum of a real function `f(x)` via bracketing. Given a function `f` and a range `(ax .. bx)`, returns the value of `x` in the range which is closest to a minimum of `f(x)`. `f` is never evaluted at the endpoints of `ax` and `bx`. If `f(x)` has more than one minimum in the range, one will be chosen arbitrarily. If `f(x)` returns NaN or -Infinity, `(x, f(x), NaN)` will be returned; otherwise, this algorithm is guaranteed to succeed.
``` findRoot(f, a, b, tolerance) ``` Find a real root of a real function f(x) via bracketing.
``` findRoot(f, ax, bx, fax, fbx, tolerance) ``` Find root of a real function f(x) by bracketing, allowing the termination condition to be specified.
``` gapWeightedSimilarity(s, t, lambda) ``` The so-called "all-lengths gap-weighted string kernel" computes a similarity measure between `s` and `t` based on all of their common subsequences of all lengths. Gapped subsequences are also included.
``` gapWeightedSimilarityIncremental(r1, r2, penalty) ``` Similar to `gapWeightedSimilarity`, just works in an incremental manner by first revealing the matches of length 1, then gapped matches of length 2, and so on. The memory requirement is Ο(```s.length * t.length```). The time complexity is Ο(`s.length * t.length`) time for computing each step. Continuing on the previous example:
``` gapWeightedSimilarityNormalized(s, t, lambda, sSelfSim, tSelfSim) ``` The similarity per `gapWeightedSimilarity` has an issue in that it grows with the lengths of the two strings, even though the strings are not actually very similar. For example, the range ```["Hello", "world"]``` is increasingly similar with the range ```["Hello", "world", "world", "world",...]``` as more instances of `"world"` are appended. To prevent that, `gapWeightedSimilarityNormalized` computes a normalized version of the similarity that is computed as ```gapWeightedSimilarity(s, t, lambda) / sqrt(gapWeightedSimilarity(s, t, lambda) * gapWeightedSimilarity(s, t, lambda))```. The function `gapWeightedSimilarityNormalized` (a so-called normalized kernel) is bounded in `[0, 1]`, reaches `0` only for ranges that don't match in any position, and `1` only for identical ranges.
``` gcd(a, b) ``` Computes the greatest common divisor of `a` and `b` by using an efficient algorithm such as Euclid's or Stein's algorithm.
``` inverseFft(range) ``` Convenience functions that create an `Fft` object, run the FFT or inverse FFT and return the result. Useful for one-off FFTs.
``` jensenShannonDivergence(a, b) ``` Computes the Jensen-Shannon divergence between `a` and `b`, which is the sum ```(ai * log(2 * ai / (ai + bi)) + bi * log(2 * bi / (ai + bi))) / 2```. The base of logarithm is 2. The ranges are assumed to contain elements in `[0, 1]`. Usually the ranges are normalized probability distributions, but this is not required or checked by `jensenShannonDivergence`. If the inputs are normalized, the result is bounded within `[0, 1]`. The three-parameter version stops evaluations as soon as the intermediate result is greater than or equal to `limit`.
``` kullbackLeiblerDivergence(a, b) ``` Computes the Kullback-Leibler divergence between input ranges `a` and `b`, which is the sum `ai * log(ai / bi)`. The base of logarithm is 2. The ranges are assumed to contain elements in `[0, 1]`. Usually the ranges are normalized probability distributions, but this is not required or checked by `kullbackLeiblerDivergence`. If any element `bi` is zero and the corresponding element `ai` nonzero, returns infinity. (Otherwise, if `ai == 0 && bi == 0`, the term `ai * log(ai / bi)` is considered zero.) If the inputs are normalized, the result is positive.
``` lcm(a, b) ``` Computes the least common multiple of `a` and `b`. Arguments are the same as `gcd`.
``` normalize(range, sum) ``` Normalizes values in `range` by multiplying each element with a number chosen such that values sum up to `sum`. If elements in `range` sum to zero, assigns `sum / range.length` to all. Normalization makes sense only if all elements in `range` are positive. `normalize` assumes that is the case without checking it.
``` sumOfLog2s(r) ``` Compute the sum of binary logarithms of the input range `r`. The error of this method is much smaller than with a naive sum of log2.

## Classes

NameDescription
``` Fft ``` A class for performing fast Fourier transforms of power of two sizes. This class encapsulates a large amount of state that is reusable when performing multiple FFTs of sizes smaller than or equal to that specified in the constructor. This results in substantial speedups when performing multiple FFTs with a known maximum size. However, a free function API is provided for convenience if you need to perform a one-off FFT.

## Structs

NameDescription
``` CustomFloat ``` Allows user code to define custom floating-point formats. These formats are for storage only; all operations on them are performed by first implicitly extracting them to `real` first. After the operation is completed the result can be stored in a custom floating-point value via assignment.
``` GapWeightedSimilarityIncremental ``` Similar to `gapWeightedSimilarity`, just works in an incremental manner by first revealing the matches of length 1, then gapped matches of length 2, and so on. The memory requirement is Ο(```s.length * t.length```). The time complexity is Ο(`s.length * t.length`) time for computing each step. Continuing on the previous example:

## Enums

NameDescription
``` CustomFloatFlags ``` Format flags for CustomFloat.

## Templates

NameDescription
``` secantMethod ``` Implements the secant method for finding a root of the function `fun` starting from points `[xn_1, x_n]` (ideally close to the root). `Num` may be `float`, `double`, or `real`.

## Aliases

NameTypeDescription
`CustomFloat` `CustomFloat!(CustomFloatParams!bits)` Allows user code to define custom floating-point formats. These formats are for storage only; all operations on them are performed by first implicitly extracting them to `real` first. After the operation is completed the result can be stored in a custom floating-point value via assignment.
`FPTemporary` `real` Defines the fastest type to use when storing temporaries of a calculation intended to ultimately yield a result of type `F` (where `F` must be one of `float`, `double`, or `real`). When doing a multi-step computation, you may want to store intermediate results as `FPTemporary!F`.

## Authors

Andrei Alexandrescu, Don Clugston, Robert Jacques, Ilya Yaroshenko