# dlib C++ Library - Algorithms

Algorithms

This page documents library components that are all basically just implementations of mathematical functions or algorithms that don't fit in any of the other pages of the dlib documentation. So this includes things like checksums, cryptographic hashes, sorting, etc.

[top]

# bigint

This object represents an arbitrary precision unsigned integer. It's pretty simple. It's interface is just like a normal int, you don't have to tell it how much memory to use or anything unusual. It just goes :)
More Details...
#include <dlib/bigint.h>
Implementations:

> bigint_kernel_1:
> This implementation is done using an array of unsigned shorts. It is also reference counted. For further details see the above link. Also note that kernel_2 should be faster in almost every case so you should really just use that version of the bigint object.

> kernel_1a | is a typedef for bigint_kernel_1
> kernel_1a_c | is a typedef for kernel_1a that checks its preconditions.

> bigint_kernel_2:
> This implementation is basically the same as kernel_1 except it uses the Fast Fourier Transform to perform multiplications much faster.

> kernel_2a | is a typedef for bigint_kernel_2
> kernel_2a_c | is a typedef for kernel_2a that checks its preconditions.

[top]

# binomial_random_vars_are_different

This function performs a simple statistical test to check if two binomially distributed random variables have the same parameter (i.e. the chance of "success"). It uses the simple likelihood ratio test discussed in the following paper:

> Dunning, Ted. "Accurate methods for the statistics of surprise and coincidence." Computational linguistics 19.1 (1993): 61-74.

So for an extended discussion of the method see the above paper.
More Details...
#include <dlib/statistics/statistic.h>
[top]

# correlation

This is a function for computing the correlation between matching elements of two std::vectors.
More Details...
#include <dlib/statistics.h>
[top]

# count_bits

This function counts the number of bits in an unsigned integer which are set to 1.
More Details...
#include <dlib/hash.h>
[top]

# count_steps_without_decrease

Given a potentially noisy time series, this function returns a count of how long the time series has gone without noticeably decreasing in value. It does this by adding the elements of the time series into a running_gradient object and counting how many elements, starting with the most recent, you need to examine before you are confident that the series has been decreasing in value.
More Details...
#include <dlib/statistics/running_gradient.h>
[top]

# count_steps_without_decrease_robust

This function behaves just like count_steps_without_decrease except that it ignores times series values that are anomalously large. This makes it robust to sudden noisy but transient spikes in the time series values.
More Details...
#include <dlib/statistics/running_gradient.h>
[top]

# count_steps_without_increase

Given a potentially noisy time series, this function returns a count of how long the time series has gone without noticeably increasing in value. It does this by adding the elements of the time series into a running_gradient object and counting how many elements, starting with the most recent, you need to examine before you are confident that the series has been increasing in value.
More Details...
#include <dlib/statistics/running_gradient.h>
[top]

# covariance

This is a function for computing the covariance between matching elements of two std::vectors.
More Details...
#include <dlib/statistics.h>
[top]

# crc32

This object represents the CRC-32 algorithm for calculating checksums.
More Details...
#include <dlib/crc32.h>
[top]

# create_max_margin_projection_hash

Creates a random projection based locality sensitive hashing function. This is accomplished using a variation on the random hyperplane generation technique from the paper:

> Random Maximum Margin Hashing by Alexis Joly and Olivier Buisson

In particular, we use a linear support vector machine to generate planes. We train it on randomly selected and randomly labeled points from the data to be hashed.
More Details...
#include <dlib/lsh.h>
[top]

# create_random_projection_hash

Creates a random projection based locality sensitive hashing function. The projection matrix is generated by sampling its elements from a Gaussian random number generator.
More Details...
#include <dlib/lsh.h>
[top]

# disjoint_subsets

This object represents a set of integers which is partitioned into a number of disjoint subsets. It supports the two fundamental operations of finding which subset a particular integer belongs to as well as merging subsets.
More Details...
#include <dlib/disjoint_subsets.h>
[top]

# disjoint_subsets_sized

This object is just like disjoint_subsets except that it also keeps track of the size of each set.
More Details...
#include <dlib/disjoint_subsets.h>
[top]

# event_correlation

This function does a statistical test to determine if two events co-occur in a statistically significant way. It uses the simple likelihood ratio test discussed in the following paper:

> Dunning, Ted. "Accurate methods for the statistics of surprise and coincidence." Computational linguistics 19.1 (1993): 61-74.

So for an extended discussion of the method see the above paper.
More Details...
#include <dlib/statistics/statistic.h>
[top]

# find_optimal_momentum_filter

This function finds the "optimal" settings of a momentum_filter based on unfiltered measurement data.
More Details...
#include <dlib/filtering.h>
[top]

# find_optimal_rect_filter

This function finds the "optimal" settings of a rect_filter based on unfiltered measurement data.
More Details...
#include <dlib/filtering.h>
[top]

# find_upper_quantile

Finds and returns the scalar value such that a user specified percentage of the values in a container are greater than said value. For example, 0.5 would find the median value in a container while 0.1 would find the value that lower bounded the 10% largest values in a container.
More Details...
#include <dlib/statistics/running_gradient.h>
[top]

# gate

This object represents a quantum gate that operates on a quantum_register.
C++ Example Programs: quantum_computing_ex.cpp
More Details...
#include <dlib/quantum_computing.h>
[top]

# gaussian_random_hash

This function uses hashing to generate Gaussian distributed random values with mean 0 and variance 1.
More Details...
#include <dlib/hash.h>
[top]

# hamming_distance

This function returns the hamming distance between two unsigned integers. That is, it returns the number of bits which differer in the two integers.
More Details...
#include <dlib/hash.h>
[top]

# hash

This is a set of convenience functions for invoking murmur_hash3 on std::strings, std::vectors, std::maps, or dlib::matrix objects.

As an aside, the hash() for matrix objects is defined here. It has the same interface as all the others.

More Details...
#include <dlib/hash.h>
[top]

# hash_samples

This is a simple function for hashing a bunch of vectors using a locality sensitive hashing object such as hash_similar_angles_128. It is also capable of running in parallel on a multi-core CPU.
More Details...
#include <dlib/graph_utils_threaded.h>
[top]

# hash_similar_angles_128

This object is a tool for computing locality sensitive hashes that give vectors with small angles between each other similar hash values. In particular, this object creates 128 random planes which pass though the origin and uses them to create a 128bit hash.
More Details...
#include <dlib/lsh.h>
[top]

# hash_similar_angles_256

This object is a tool for computing locality sensitive hashes that give vectors with small angles between each other similar hash values. In particular, this object creates 256 random planes which pass though the origin and uses them to create a 256bit hash.
More Details...
#include <dlib/lsh.h>
[top]

# hash_similar_angles_512

This object is a tool for computing locality sensitive hashes that give vectors with small angles between each other similar hash values. In particular, this object creates 512 random planes which pass though the origin and uses them to create a 512bit hash.
More Details...
#include <dlib/lsh.h>
[top]

# hash_similar_angles_64

This object is a tool for computing locality sensitive hashes that give vectors with small angles between each other similar hash values. In particular, this object creates 64 random planes which pass though the origin and uses them to create a 64bit hash.
More Details...
#include <dlib/lsh.h>
[top]

# hsort_array

hsort_array is an implementation of the heapsort algorithm. It will sort anything that has an array like operator[] interface.
More Details...
#include <dlib/sort.h>
[top]

# integrate_function_adapt_simp

Computes an approximation of the integral of a real valued function using the adaptive Simpson method outlined in

> Gander, W. and W. Gautshi, "Adaptive Quadrature -- Revisited" BIT, Vol. 40, (2000), pp.84-101

C++ Example Programs: integrate_function_adapt_simp_ex.cpp
More Details...
#include <dlib/numerical_integration.h>
[top]

# isort_array

isort_array is an implementation of the insertion sort algorithm. It will sort anything that has an array like operator[] interface.
More Details...
#include <dlib/sort.h>
[top]

# kalman_filter

This object implements the Kalman filter, which is a tool for recursively estimating the state of a process given measurements related to that process. To use this tool you will have to be familiar with the workings of the Kalman filter. An excellent introduction can be found in the paper:

> An Introduction to the Kalman Filter by Greg Welch and Gary Bishop

More Details...
#include <dlib/filtering.h>
[top]

# max_scoring_element

This function finds the element of container that has the largest score, according to a user supplied score function, and returns a std::pair containing that maximal element along with the score.
More Details...
#include <dlib/algs.h>
[top]

# md5

This is an implementation of The MD5 Message-Digest Algorithm as described in rfc1321.
More Details...
#include <dlib/md5.h>
[top]

# mean_sign_agreement

This is a function for computing the probability that matching elements of two std::vectors have the same sign.
More Details...
#include <dlib/statistics.h>
[top]

# mean_squared_error

This is a function for computing the mean squared error between matching elements of two std::vectors.
More Details...
#include <dlib/statistics.h>
[top]

# median

This function takes three parameters and finds the median of the three. The median is swapped into the first parameter and the first parameter ends up in one of the other two, unless the first parameter was the median to begin with of course.
More Details...
#include <dlib/algs.h>
[top]

# min_scoring_element

This function finds the element of container that has the smallest score, according to a user supplied score function, and returns a std::pair containing that minimal element along with the score.
More Details...
#include <dlib/algs.h>
[top]

# momentum_filter

This object is a simple tool for filtering a single scalar value that measures the location of a moving object that has some non-trivial momentum. Importantly, the measurements are noisy and the object can experience sudden unpredictable accelerations. To accomplish this filtering we use a simple Kalman filter with a state transition model of:

       position_{i+1} = position_{i} + velocity_{i}
       velocity_{i+1} = velocity_{i} + some_unpredictable_acceleration

and a measurement model of:

       measured_position_{i} = position_{i} + measurement_noise

Where `some_unpredictable_acceleration` and `measurement_noise` are 0 mean Gaussian noise sources. To allow for really sudden and large but infrequent accelerations, at each step we check if the current measured position deviates from the predicted filtered position by more than a user specified amount, and if so we adjust the filter's state to keep it within these bounds. This allows the moving object to undergo large unmodeled accelerations, far in excess of what would be suggested by the basic Kalman filter's noise model, without then experiencing a long lag time where the Kalman filter has to "catch up" to the new position.
More Details...
#include <dlib/filtering.h>
[top]

# murmur_hash3

This function takes a block of memory and returns a 32bit hash. The hashing algorithm used is Austin Appleby's excellent MurmurHash3.
More Details...
#include <dlib/hash.h>
[top]

# murmur_hash3_128bit

This function takes a block of memory and returns a 128bit hash. The hashing algorithm used is Austin Appleby's excellent MurmurHash3.
More Details...
#include <dlib/hash.h>
[top]

# numeric_constants

This is just a header file containing definitions of common numeric constants such as pi and e.
More Details...
#include <dlib/numeric_constants.h>
[top]

# probability_values_are_increasing

Given a potentially noisy time series, this function returns the probability that those values are increasing in magnitude.
More Details...
#include <dlib/statistics/running_gradient.h>
[top]

# probability_values_are_increasing_robust

This function behaves just like probability_values_are_increasing except that it ignores times series values that are anomalously large. This makes it robust to sudden noisy but transient spikes in the time series values.
More Details...
#include <dlib/statistics/running_gradient.h>
[top]

# projection_hash

This is a tool for hashing elements of a vector space into the integers. It is intended to represent locality sensitive hashing functions such as the popular random projection hashing method.
More Details...
#include <dlib/lsh.h>
[top]

# put_in_range

This is a simple function that takes a range and a value and returns the given value if it is within the range. If it isn't in the range then it returns the end of range value that is closest.
More Details...
#include <dlib/algs.h>
[top]

# qsort_array

qsort_array is an implementation of the QuickSort algorithm. It will sort anything that has an array like operator[] interface. If the quick sort becomes unstable then it switches to a heap sort. This way sorting is guaranteed to take at most N*log(N) time.
More Details...
#include <dlib/sort.h>
[top]

# quantum_register

This object represents a set of quantum bits. It can be used with the quantum gate object to simulate quantum algorithms.
C++ Example Programs: quantum_computing_ex.cpp
More Details...
#include <dlib/quantum_computing.h>
[top]

# rand

This object represents a pseudorandom number generator.
More Details...
#include <dlib/rand.h>
[top]

# randomly_subsample

This is a set of convenience functions for creating random subsets of data.
More Details...
#include <dlib/statistics.h>
[top]

# random_subset_selector

This object is a tool to help you select a random subset of a large body of data. In particular, it is useful when the body of data is too large to fit into memory.
More Details...
#include <dlib/statistics.h>
[top]

# rect_filter

This object is just a momentum_filter applied to the four corners of a rectangle. It allows you to filter a stream of rectangles, for instance, bounding boxes from an object detector applied to a video stream.
More Details...
#include <dlib/filtering.h>
[top]

# rls_filter

This object is a tool for doing time series prediction using linear recursive least squares. In particular, this object takes a sequence of points from the user and, at each step, attempts to predict the value of the next point.
More Details...
#include <dlib/filtering.h>
[top]

# running_covariance

This object is a simple tool for computing the mean and covariance of a sequence of vectors.
More Details...
#include <dlib/statistics.h>
[top]

# running_cross_covariance

This object is a simple tool for computing the mean and cross-covariance matrices of a sequence of pairs of vectors.
More Details...
#include <dlib/statistics.h>
[top]

# running_gradient

This object is a tool for estimating if a noisy sequence of numbers is trending up or down and by how much. It does this by finding the least squares fit of a line to the data and then allows you to perform a statistical test on the slope of that line.
More Details...
#include <dlib/statistics/running_gradient.h>
[top]

# running_scalar_covariance

This object is a simple tool for computing the covariance of a sequence of scalar values.
More Details...
#include <dlib/statistics.h>
[top]

# running_scalar_covariance_decayed

This object represents something that can compute the running covariance of a stream of real number pairs. It is essentially the same as running_scalar_covariance except that it forgets about data it has seen after a certain period of time. It does this by exponentially decaying old statistics.
More Details...
#include <dlib/statistics.h>
[top]

# running_stats

This object represents something that can compute the running mean, variance, skewness, and kurtosis statistics of a stream of real numbers.
C++ Example Programs: running_stats_ex.cpp, kcentroid_ex.cpp
More Details...
#include <dlib/statistics.h>
[top]

# running_stats_decayed

This object represents something that can compute the running mean and variance of a stream of real numbers. It is similar to running_stats except that it forgets about data it has seen after a certain period of time. It does this by exponentially decaying old statistics.
More Details...
#include <dlib/statistics.h>
[top]

# r_squared

This is a function for computing the R squared coefficient between matching elements of two std::vectors.
More Details...
#include <dlib/statistics.h>
[top]

# set_difference

This function takes two set objects and gives you their difference.
More Details...
#include <dlib/set_utils.h>
[top]

# set_intersection

This function takes two set objects and gives you their intersection.
More Details...
#include <dlib/set_utils.h>
[top]

# set_intersection_size

This function takes two set objects and tells you how many items they have in common.
More Details...
#include <dlib/set_utils.h>
[top]

# set_union

This function takes two set objects and gives you their union.
More Details...
#include <dlib/set_utils.h>
[top]

# split_array

This function is used to efficiently split array like objects into two parts. It uses the global swap() function instead of copying to move elements around, so it works on arrays of non-copyable types.
More Details...
#include <dlib/array.h>
[top]

# square_root

square_root is a function which takes an unsigned long and returns the square root of it or if the root is not an integer then it is rounded up to the next integer.
More Details...
#include <dlib/algs.h>
[top]

# uniform_random_hash

This function uses hashing to generate uniform random values in the range [0,1).
More Details...
#include <dlib/hash.h>