Puid.Entropy (puid v2.3.2)

Entropy related calculations

The implementation is based on mathematical approximations to the solution of what is often referred to as the Birthday Problem.

Summary

Functions

Entropy bits necessary to generate total number of puids with risk risk of repeat.

Entropy bits for a binary of length len comprised of chars characters.

Same as Puid.Entropy.bits_for_len/2 but either returns bits or raises a Puid.Error

Entropy bits per chars character.

Same as bits_per_char/1 but either returns bits or raises a Puid.Error

Length needed for a string generated from chars to have entropy bits.

Same as Puid.Entropy.len_for_bits/2 but either returns len or raises a Puid.Error

Risk of repeat in total number of events with bits bits entropy.

Approximate total number of puids which can be generated using bits bits entropy at a risk risk of repeat.

Functions

bits(total, risk)

@spec bits(non_neg_integer(), non_neg_integer()) :: float()

Entropy bits necessary to generate total number of puids with risk risk of repeat.

The total number of possible puids is 2<sup>bits</sup>. Risk is expressed as a 1 in risk chance, so the probability of a repeat is 1/risk.

Example

iex> Puid.Entropy.bits(10.0e6, 1.0e12)
85.37013046707142

bits_for_len(chars, len)

@spec bits_for_len(Puid.Chars.puid_chars(), non_neg_integer()) ::
  {:ok, non_neg_integer()} | Puid.Error.t()

Entropy bits for a binary of length len comprised of chars characters.

chars must be valid as per Chars.charlist/1.

Example

iex> Puid.Entropy.bits_for_len(:alphanum, 14)
{:ok, 83}

iex> Puid.Entropy.bits_for_len(~c'dingosky', 14)
{:ok, 42}

bits_for_len!(chars, len)

@spec bits_for_len!(Puid.Chars.puid_chars(), non_neg_integer()) :: non_neg_integer()

Same as Puid.Entropy.bits_for_len/2 but either returns bits or raises a Puid.Error

Example

iex> Puid.Entropy.bits_for_len!(:alphanum, 14)
83

iex> Puid.Entropy.bits_for_len!("dingosky", 14)
42

bits_per_char(chars)

@spec bits_per_char(Puid.Chars.puid_chars()) :: {:ok, float()} | Puid.Error.t()

Entropy bits per chars character.

chars must be valid as per Chars.charlist/1.

Example

iex> Puid.Entropy.bits_per_char(:alphanum)
{:ok, 5.954196310386875}

iex> Puid.Entropy.bits_per_char("dingosky")
{:ok, 3.0}

bits_per_char!(chars)

@spec bits_per_char!(Puid.Chars.puid_chars()) :: float()

Same as bits_per_char/1 but either returns bits or raises a Puid.Error

Example

iex> Puid.Entropy.bits_per_char!(:alphanum)
5.954196310386875

Puid.Entropy.bits_per_char!("dingosky")
3.0

len_for_bits(chars, bits)

@spec len_for_bits(Puid.Chars.puid_chars(), non_neg_integer()) ::
  {:ok, non_neg_integer()} | Puid.Error.t()

Length needed for a string generated from chars to have entropy bits.

chars must be valid as per Chars.charlist/1.

Example

iex> Puid.Entropy.len_for_bits(:alphanum, 128)
{:ok, 22}

iex> Puid.Entropy.len_for_bits("dingosky", 128)
{:ok, 43}

len_for_bits!(chars, bits)

Same as Puid.Entropy.len_for_bits/2 but either returns len or raises a Puid.Error

Example

iex> Puid.Entropy.len_for_bits!(:alphanum, 128)
22

iex> Puid.Entropy.len_for_bits!(~c'dingosky', 128)
43

risk(bits, total)

@spec risk(bits :: float(), total :: float()) :: integer()

Risk of repeat in total number of events with bits bits entropy.

The total number of possible puids is 2<sup>bits</sup>. Risk is expressed as a 1 in risk chance, so the probability of a repeat is 1/risk.

Due to approximations used in the entropy calculation this value is also approximate; the approximation is conservative, however, so the calculated risk will not be exceed for the specified total.

Example

iex> bits = 96
iex> total = 1.0e7
iex> Puid.Entropy.risk(bits, total)
1501199875790165
iex> 1.0 / 1501199875790165
6.661338147750941e-16

total(bits, risk)

@spec total(bits :: float(), risk :: float()) :: integer()

Approximate total number of puids which can be generated using bits bits entropy at a risk risk of repeat.

The total number of possible puids is 2<sup>bits</sup>. Risk is expressed as a 1 in risk chance, so the probability of a repeat is 1/risk.

Due to approximations used in the entropy calculation this value is also approximate; the approximation is conservative, however, so the calculated total will not exceed the specified risk.

Example

iex> bits = 64
iex> risk = 1.0e9
iex> Puid.Entropy.total(bits, risk)
192077