Math¶

Combinations¶

Tools to step through combinations of items.

Step through all combinations of size K from a set of N values. For ComboIDs just return the indecies (the specific of the container don’t matter). Other versions will directly wrapper containers.

Note: This file is part of Empirical, https://github.com/devosoft/Empirical
Copyright: Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
Date: 2017

namespace emp

If we are in emscripten, make sure to include the header.

class ComboIDs

Public Functions

ComboIDs(size_t in_max, size_t combo_size)

~ComboIDs()

const emp::vector<size_t> &GetCombo() const

const emp::vector<size_t> &GetMaxCombo() const

size_t GetComboSize() const

size_t GetNumCombos() const

size_t &operator[](const size_t index)

const size_t &operator[](const size_t index) const

const emp::vector<size_t> &Reset()

bool NextCombo()

void ResizeCombos(size_t new_size)

emp::vector<size_t> GetInverseCombo()

ComboIDs &operator++()

ComboIDs &operator++(int)

size_t size()

Private Members

size_t max_count

emp::vector<size_t> cur_combo

emp::vector<size_t> max_combo

size_t num_combos

Private Static Functions

size_t CountCombos(size_t max_count, size_t combo_size)

Constants¶

Commonly used constant values.

Note: This file is part of Empirical, https://github.com/devosoft/Empirical
Copyright: Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
Date: 2015-2017
Note: Status: RELEASE

namespace emp

If we are in emscripten, make sure to include the header.

Functions

template<typename T> constexpr T MaxValue(): Determine the maximum value for any type.

template<typename T> constexpr double InterpolateTable(T &&table, double pos, double tsize): The following function takes a table and a position [0.0, 1.0) and intepolates a value.

Variables

constexpr const double E = 2.71828: e

constexpr const double PHI = 1.61803398874: Golden ratio.

constexpr const double PI = 3.14159265358979: pi

constexpr const double SQRT2 = 1.41421356237310: sqrt(2)

constexpr const uint32_t MAX_BYTE = 255: (2^8 - 1)

constexpr const uint32_t MAX_2BYTE = 65535: (2^16 - 1)

constexpr const uint32_t MAX_WORD = 65535: (2^16 - 1)

constexpr const uint32_t MAX_3BYTE = 16777215: (2^24 - 1)

constexpr const uint32_t MAX_UINT = 4294967295: (2^32 - 1)

constexpr const uint32_t MAX_4BYTE = 4294967295: (2^32 - 1)

constexpr const int32_t MIN_INT = -2147483648: (- 2^31)

constexpr const double log2_chart_1_2[]: Large table to log base-2 results.

constexpr const double pow2_chart_bits[] = {1.4142135623730951, 1.1892071150027210, 1.0905077326652577, 1.0442737824274138, 1.0218971486541166, 1.0108892860517005, 1.0054299011128027, 1.0027112750502025, 1.0013547198921082, 1.0006771306930664, 1.0003385080526823, 1.0001692397053021, 1.0000846162726944, 1.0000423072413958, 1.0000211533969647, 1.0000105766425498, 1.0000052883072919, 1.0000026441501502, 1.0000013220742012, 1.0000006610368821, 1.0000003305183864, 1.0000001652591795, 1.0000000826295863, 1.0000000413147923, 1.0000000206573960, 1.0000000103286979, 1.0000000051643489, 1.0000000025821745, 1.0000000012910872, 1.0000000006455436, 1.0000000003227718, 1.0000000001613858}: Table to provide results of Pow2 for values of bits (0.1, 0.01, 0.001, etc, in binary)

constexpr const double pow2_chart_0_1[]: Table to provide results of Pow2 from 0 to 1.

Information Theory Tools¶

Tools to calculate Information Theory metrics.

Info-theory formulas: H(X) = -SUM(X: p[x] log2 p[x]) H(X|Y) = H(XY) - H(Y) I(X:Y) = H(X) - H(X|Y) H2(p) = -p log2(p) - (1-p)log2(1-p) = H({p, 1-p})

Note: This file is part of Empirical, https://github.com/devosoft/Empirical
Copyright: Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
Date: 2021.
Note: Status: ALPHA

Developer notes:

Input may come as WEIGHTS or as ELEMENTS (or both!). ELEMENTS need to be converted to WEIGHTS for calculations.
Want basic info theory functions, as well as tools (for channels, error-correction, compression, etc.)

namespace emp

If we are in emscripten, make sure to include the header.

Functions

template<typename CONTAINER> double Entropy(const CONTAINER &weights): Convert a vector of weights to probabilities and return the entropy of the system.

template<typename CONTAINER, typename WEIGHT_FUN> double Entropy(const CONTAINER &objs, WEIGHT_FUN fun, double total = 0.0): Calculate the entropy in a container of arbitrary objects. Args are a container, a function to extract the weight of each member, and an (optional) total weight.

constexpr double Entropy2(const double p): Calculate the entropy when their are two possibile states based on one state’s probability.

Math¶

Useful mathematical functions (that are constexpr when possible.)

Note: This file is part of Empirical, https://github.com/devosoft/Empirical
Copyright: Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
Date: 2016-2021.
Note: Status: BETA (though new functions are added frequently)

namespace emp

If we are in emscripten, make sure to include the header.

Functions

constexpr int Mod(int in_val, int mod_val): % is actually remainder; Mod is a proper modulus command that handles negative #’s correctly

double Mod(double in_val, double mod_val): Regular Mod doesn’t work on doubles. Build one that does!

template<typename T> int Sgn(T val): Calculate the sign (i.e., +1, -1, or 0) of a value.

template<typename T> constexpr T Abs(T in): Find the absolute value for any variable.

int FloorDivide(int dividend, int divisor): Divide one integer by another, rounding towards minus infinity.

int RoundedDivide(int dividend, int divisor): Default integer division is truncated, not rounded. Round the division result instead of truncating it. Rounding ties (i.e., result % divisor == 0.5) are rounded up.

size_t RoundedDivide(size_t dividend, size_t divisor): Default integer division is truncated, not rounded. Round the division result instead of truncating it. Rounding ties (i.e., result % divisor == 0.5) will be rounded up.

int UnbiasedDivide(int dividend, int divisor, emp::Random &r): Regular integer division is truncated, not rounded. Round the division result instead of truncating it. Rounding ties (i.e., result % divisor == 0.5) are broken by coin toss.

size_t UnbiasedDivide(size_t dividend, size_t divisor, emp::Random &r): Regular integer division is truncated, not rounded. Round the division result instead of truncating it. Rounding ties (i.e., result % divisor == 0.5) are broken by coin toss.

template<typename TYPE> constexpr TYPE ToRange(const TYPE &value, const TYPE &in_min, const TYPE &in_max): Run both min and max on a value to put it into a desired range.

template<typename T> constexpr T Min(T in1): Min of only one element is that element itself!

template<typename T, typename ...Ts> constexpr T Min(T in1, T in2, Ts... extras): Min of multiple elements is solved recursively.

template<typename T> constexpr T Max(T in1): Max of only one element is that element itself!

template<typename T, typename ...Ts> constexpr T Max(T in1, T in2, Ts... extras): Max of multiple elements is solved recursively.

template<typename T> constexpr const T &MinRef(const T &in1): MinRef works like Min, but never copies any inputs; always treats as references. MinRef of only one element returns reference to that element itself!

template<typename T, typename ...Ts> constexpr const T &MinRef(const T &in1, const T &in2, const Ts&... extras): MinRef of multiple elements returns reference to minimum value.

template<typename T> constexpr const T &MaxRef(const T &in1): MaxRef works like Max, but never copies any inputs; always treats as references. MaxRef of only one element returns reference to that element itself!

template<typename T, typename ...Ts> constexpr const T &MaxRef(const T &in1, const T &in2, const Ts&... extras): MaxRef of multiple elements returns reference to maximum value.

constexpr double Log2(double x): Compile-time log base 2 calculator.

constexpr double Log(double x, double base = 10.0): Compile-time log calculator.

constexpr double Ln(double x): Compile-time natural log calculator.

constexpr double Log10(double x): Compile-time log base 10 calculator.

template<typename T> constexpr T Square(T val): A simple function to square a value.

constexpr double Pow2(double exp): A fast 2^x command.

template<typename TYPE> constexpr TYPE IntPow(TYPE base, TYPE exp): A fast method for calculating exponents for int types.

template<typename T> constexpr T Pow(T base, typename internal::identity<T>::type exp): A fast method for calculating exponents on doubles or integral types. Uses if constexpr to work around compiler bug in Emscripten (issue #296).

constexpr double Exp(double exp): A fast method of calculating e^x.

template<typename TYPE> constexpr int IntLog2(TYPE x): A compile-time int-log calculator (aka, significant bits)

template<typename T> constexpr const T &Min(const T &in1, const T &in2, const T &in3): Return the minimum of three values.

template<typename T> const T &Min(std::initializer_list<const T&> lst): A version of Min that allows a variable number of inputs to be compared.

template<typename T> const T &Max(std::initializer_list<const T&> lst): A version of Max that allows a variable number of inputs to be compared.

uint64_t NextPowerOf2(uint64_t A): Returns the next power of two (in 64-bits) that is strictly greater than A. Returns zero on overflow.

constexpr bool IsPowerOf2(const size_t x): Tests if a number is a power of two.

constexpr int Factorial(int i)

bool Toggle(bool &in_bool): Toggle an input bool.

constexpr bool AllTrue(): Combine bools to AND them all together.

template<typename ...Ts> bool AllTrue(bool result, Ts... OTHER)

constexpr bool AnyTrue(): Combine bools to OR them all together.

template<typename ...Ts> bool AnyTrue(bool result, Ts... OTHER)

template<typename T> constexpr T GCD(const T v1, const T v2): Greatest Common Divisor.

template<typename T> constexpr T LCM(const T v1, const T v2): Least common multiple.

Randomness Utilites¶

Helper functions for emp::Random for common random tasks.

Note: This file is part of Empirical, https://github.com/devosoft/Empirical
Copyright: Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
Date: 2016-2017
Note: Status: RELEASE

namespace emp

If we are in emscripten, make sure to include the header.

Functions

template<typename T> void Shuffle(Random &random, emp::vector<T> &v, size_t max_count): Randomly reorder all of the elements in a vector. If max_count is provided, just make sure that the first max_count entries are randomly drawn from entire vector.

template<typename T> void Shuffle(Random &random, emp::vector<T> &v)

emp::vector<size_t> GetPermutation(Random &random, size_t size): Return an emp::vector<int> numbered 0 through size-1 in a random order.

void Choose(Random &random, size_t N, size_t K, std::vector<size_t> &choices): Choose K positions from N possibilities.

std::vector<size_t> Choose(Random &random, size_t N, size_t K)

BitVector RandomBitVector(Random &random, size_t size, double p = 0.5): Generate a random BitVector of the specified size.

emp::vector<double> RandomDoubleVector(Random &random, size_t size, double min, double max): Generate a random double vector in the specified range.

emp::vector<size_t> RandomUIntVector(Random &random, size_t size, size_t min, size_t max): Generate a random size_t vector in the specified range.

template<typename T> emp::vector<T> RandomVector(Random &random, size_t size, T min, T max): Generate a random vector in the specified type and range.

void RandomizeBitVector(BitVector &bits, Random &random, double p = 0.5): Generate a random BitVector of the specified size.

template<typename T> void RandomizeVector(emp::vector<T> &vals, Random &random, T min, T max): Generate a random vector in the specified type and range.

size_t CountRngTouches(std::function<void(emp::Random&)> routine)

Random Number Generator¶

A versatile and non-patterned pseudo-random-number generator.

Note: This file is part of Empirical, https://github.com/devosoft/Empirical
Copyright: Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
Date: 2015-2021.
Note: Status: RELEASE

namespace emp

If we are in emscripten, make sure to include the header.

class Random: #include <Random.hpp>

struct RandomStdAdaptor

#include <Random.hpp>

This is an adaptor to make Random behave like a proper STL random number generator.

Public Types

typedef int argument_type

typedef int result_type

Public Functions

RandomStdAdaptor(Random &rng)

int operator()(int n)

Public Members

Random &_rng

Range¶

A simple way to track value ranges.

Note: This file is part of Empirical, https://github.com/devosoft/Empirical
Copyright: Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
Date: 2016-2019
Note: Status: BETA

namespace emp

If we are in emscripten, make sure to include the header.

Functions

template<typename T> Range<T> MakeRange(T _l, T _u): Build a new range with auto-detected type.

Range<int> IntRange(int _l, int _u): Build a new range of type int.

Range<double> DRange(double _l, double _u): Build a new range of type double.

template<typename T> class Range

#include <Range.hpp>

A range of values from a lower limit to and upper limit, of any provided type.

Public Functions

Range() = default

Range(T _l, T _u)

T GetLower() const

T GetUpper() const

size_t CalcBin(T value, size_t num_bins) const

Range &operator=(const Range&) = default

bool operator==(const Range &_in) const

bool operator!=(const Range &_in) const

void SetLower(T l)

void SetUpper(T u)

void Set(T _l, T _u)

void SetMaxLower()

void SetMaxUpper()

bool Valid(T value) const: Determine if a provided value is in the range.

T Limit(T _in) const: Force a value into range.

emp::vector<T> Spread(size_t s) const: Produce a vector that spreads values evenly across the range.

Private Members

T lower = std::numeric_limits<T>::min(): Beginning of range, inclusive.

T upper = std::numeric_limits<T>::max(): End of range, inclusive.

Sequence Utilities¶

Functions for analyzing with generic sequence types.

A set of functions for analyzing sequences, including distance metrics (Hamming and Edit/Levenschtein) and alignment.

Note: This file is part of Empirical, https://github.com/devosoft/Empirical
Copyright: Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
Date: 2016-2020.
Note: Status: BETA

namespace emp

If we are in emscripten, make sure to include the header.

Functions

template<typename TYPE> size_t calc_hamming_distance(const TYPE &in1, const TYPE &in2, int offset = 0)

Hamming distance is a simple count of substitutions needed to convert one array to another.

Parameters

in1: The first sequence to compare.
in2: The second sequence to compare.
offset: (optional) Position in the first sequence to start the second sequence.

template<typename TYPE> size_t calc_edit_distance(const TYPE &in1, const TYPE &in2): Edit distance is the minimum number of insertions, deletions and substitutions to convert one array to another.

template<typename TYPE, typename GAP_TYPE> size_t align(TYPE &in1, TYPE &in2, GAP_TYPE gap): Use edit distance to find the minimum number of insertions, deletions and substitutions to convert one array to another, and then insert gaps into the arrays appropriately.

Statistics Tools¶

Functions for calculating various statistics about an ensemble.

Note: This file is part of Empirical, https://github.com/devosoft/Empirical
Copyright: Copyright (C) Michigan State University, MIT Software license; see doc/LICENSE.md
Date: 2016-2019
Note: Status: BETA

namespace emp

If we are in emscripten, make sure to include the header.

Functions

template<typename C> emp::remove_ptr_type<typename C::value_type>::type Sum(C &elements): Calculate sum of the values in a container; if pointers to scalars, convert to scalar type.

template<typename C, typename FUN> auto SumScalarResults(C &elements, FUN &&fun): Sum the RESULTS of scalar values in a container; if pointers to scalars, convert to scalar type.

template<typename C> double ShannonEntropy(C &elements): Calculate Shannon Entropy of the members of the container passed.

template<typename C> emp::sfinae_decoy<double, typename C::value_type> Mean(C &elements): Calculate the mean of the values in a container If values are pointers, they will be automatically de-referenced Values must be numeric.

template<typename C> emp::sfinae_decoy<double, typename C::value_type> Median(C elements)

template<typename C> auto Variance(C &elements): Calculate variance of the members of the container passed Only works on containers with a scalar member type

template<typename C> emp::sfinae_decoy<double, typename C::value_type> StandardDeviation(C &elements): Calculate the standard deviation of the values in a container If values are pointers, they will be automatically de-referenced Values must be numeric.

template<typename C> emp::sfinae_decoy<double, typename C::value_type> StandardError(C &elements): Calculate the standard error of the values in a container If values are pointers, they will be automatically de-referenced Values must be numeric.

template<typename C> std::enable_if<!emp::is_ptr_type<typename C::value_type>::value, int>::type UniqueCount(C &elements): Count the number of unique elements in a container.

template<typename C, typename RET_TYPE, typename ARG_TYPE> RET_TYPE MaxResult(std::function<RET_TYPE(ARG_TYPE)> &fun, C &elements, ): Run the provided function on every member of a container and return the MAXIMUM result.

template<typename C, typename RET_TYPE, typename ARG_TYPE> RET_TYPE MinResult(std::function<RET_TYPE(ARG_TYPE)> &fun, C &elements, ): Run the provided function on every member of a container and return the MINIMUM result.

template<typename C, typename RET_TYPE, typename ARG_TYPE> std::enable_if<std::is_scalar<RET_TYPE>::value, double>::type MeanResult(std::function<RET_TYPE(ARG_TYPE)> &fun, C &elements, ): Run the provided function on every member of a container and return the AVERAGE result. Function must return a scalar (i.e. numeric) type.

template<typename C, typename RET_TYPE, typename ARG_TYPE> emp::vector<RET_TYPE> ApplyFunction(std::function<RET_TYPE(ARG_TYPE)> &fun, C &elements, ): Run the provided function on every member of a container and return a vector of ALL results.