Fortuna 0.16.0

Fast & Flexible Random Value Generator

Fortuna

Fast & Flexible Random Value Generator, or Adventures in Non-determinism

Copyright © 2018 Broken aka Robert Sharp

More than just a high performance random number generator...
Fortuna can help you build dynamic rarefied treasure tables and more.

Suggested Installation Method:

• Open your favorite Unix terminal and type pip install Fortuna

Primary Functions

Note: All ranges are inclusive unless stated otherwise.

Fortuna.random_range(lo: int, hi: int) -> int
Input order is ignored.
Returns a random integer in range (lo..hi) inclusive.
Flat uniform distribution.

Fortuna.random_below(num: int) -> int
Returns a random integer in range (0..num-1) for positive values of num.
Returns a random integer in range (num+1..0) for negative values of num.
Returns 0 for values of num in range (-1..1)
Flat uniform distribution.

Fortuna.d(sides: int) -> int
Returns a random integer in the range (1, sides)
Represents a single die roll.
Flat uniform distribution.

Fortuna.dice(rolls: int, sides: int) -> int
Returns a random integer in range (rolls..(sides * rolls))
Return value represents the sum of multiple rolls of the same dice.
Geometric distribution based on number and size of the dice rolled.
Complexity scales with the number of rolls.

Fortuna.plus_or_minus(num: int) -> int
Negative or positive input will produce an equivalent distribution.
Returns random integer in the range (-num, num)
Flat uniform distribution.

Fortuna.plus_or_minus_linear(num: int) -> int
Negative or positive input will produce an equivalent distribution.
Returns random integer in the range (-num, num)
Zero peak geometric distribution, triangle.

Fortuna.plus_or_minus_curve(num: int) -> int
Negative or positive input will produce an equivalent distributions.
Returns random integer in the range (-num, num)
Zero peak gaussian distribution, bell curve: Mean = 0, Variance = num / pi

Fortuna.percent_true(num: int) -> bool
Always returns False if num is 0 or less, always returns True if num is 100 or more.
Any value of num in range (1..99) will produce True or False.
Returns a random Bool based on the probability of True as a percentage.

Fortuna.random_value(arr: sequence) -> value
Returns a random value from a sequence (list or tuple), uniform distribution, non-destructive.
Up to 4x faster than random.choice().

Fast Base Cases :: rand() % N

Fortuna.fast_rand_below(num: int) -> int
Returns a random integer in range (0..num-1) for positive values of num.
Flat uniform distribution, not guaranteed to produce un-biased distributions on all platforms.
For testing purposes only.

Fortuna.fast_d(sides: int) -> int
Returns a random integer in range (1..sides) for positive values of num.
Flat uniform distribution, not guaranteed to produce un-biased distributions on all platforms.
For testing purposes only.

Fortuna.fast_dice(rolls: int, sides: int) -> int
Returns a random integer in range (rolls..(sides * rolls))
Return value represents the sum of multiple rolls of the same dice.
Geometric distribution based on number and size of the dice rolled.
Not guaranteed to produce un-biased distributions on all platforms.
For testing purposes only.

Class Abstractions

Mostly: The Quantum Monty

A set of strategies for producing random values from a sequence where the probability
of each value is based on it's position in the sequence. For example: the mostly front monty
produces random values where the beginning of the sequence is geometrically more common than the back.

• Constructor takes a copy of a sequence (list or tuple) of arbitrary values.
• Sequence length must be greater than three, best if ten or more.
• Values can be any Python object that can be passed around... string, int, list, function etc.
• Performance scales by some tiny fraction of the length of the sequence. Method scaling may very slightly.

some_sequence = ["Alpha", "Beta", "Delta", "Eta", "Gamma", "Kappa", "Zeta"]
random_monty = Fortuna.Mostly(some_sequence)

random_monty.mostly_front() -> value
Returns a random value, mostly from the front of the list (geometric)

random_monty.mostly_middle() -> value
Returns a random value, mostly from the middle of the list (geometric)

random_monty.mostly_back() -> value
Returns a random value, mostly from the back of the list (geometric)

random_monty.mostly_first() -> value
Returns a random value, mostly from the very front of the list (gaussian)

random_monty.mostly_center() -> value
Returns a random value, mostly from the very center of the list (gaussian)

random_monty.mostly_last() -> value
Returns a random value, mostly from the very back of the list (gaussian)

random_monty() -> value
Returns a random value, Quantum Monty Algorithm (complex)

Random Cycle: The Truffle Shuffle

Returns a random value from the sequence. Produces a uniform distribution with no consecutive duplicates and relatively few nearly consecutive duplicates. Longer sequences will naturally push duplicates even further apart. This behavior gives rise to output sequences that seem much less mechanical than other random_value sequences.

• Constructor takes a copy of a sequence (list or tuple) of arbitrary values.
• Sequence length must be greater than three, best if ten or more.
• Values can be any Python object that can be passed around... string, int, list, function etc.
• Features continuous smart micro-shuffling: The Truffle Shuffle.
• Performance scales by some small fraction of the length of the sequence.

some_sequence = ["Alpha", "Beta", "Delta", "Eta", "Gamma", "Kappa", "Zeta"]
random_cycle = Fortuna.RandomCycle(some_sequence)
random_cycle() -> value

Weighted Choice: Custom Rarity

Two strategies for selecting random values from a sequence where rarity counts.
Both produce a custom distribution of values based on the weights of the values.

• Constructor takes a copy of a sequence of weighted value pairs... [(weight, value), ... ]
• The sequence must not be empty, and each pair must have a weight and a value.
• Weights must be integers. A future release may allow weights to be floats.
• Values can be any Python object that can be passed around... string, int, list, function etc.
• Performance scales by some fraction of the length of the sequence.

The following examples produce equivalent distributions with comparable performance. The choice to use one over the other is purely about which strategy suits you or the data best. Relative weights are easier to understand at a glance, while RPG Treasure Tables map rather nicely to cumulative weights. Cumulative weights are slightly easier for humans to get wrong, because math. Relative weights can be compared directly while cumulative weights can not. The tables below have been constructed to have the exact same probabilities for each corresponding value.

Cumulative Weight Strategy:

Note: Logic dictates Cumulative Weights must be unique!

cumulative_weighted_table = (
    (7, "Apple"),
    (11, "Banana"),
    (13, "Cherry"),
    (23, "Grape"),
    (26, "Lime"),
    (30, "Orange"),
)
cumulative_weighted_choice = Fortuna.CumulativeWeightedChoice(cumulative_weighted_table)
cumulative_weighted_choice() -> value

Relative Weight Strategy:

relative_weighted_table = (
    (7, "Apple"),
    (4, "Banana"),
    (2, "Cherry"),
    (10, "Grape"),
    (3, "Lime"),
    (4, "Orange"),
)
relative_weighted_choice = Fortuna.RelativeWeightedChoice(relative_weighted_table)
relative_weighted_choice() -> value

MultiCat

MultiCat is an abstraction layer to enable random selection from a sequence inside an OrderedDict by passing an optional category key. MultiCat uses RandomCycle() to produce a uniform distribution cycle of values within each cat sequence. If no key is provided - MultiCat uses Mostly.mostly_front() to choose a random key for you, where keys at the beginning of the key list are more common than keys at the back. This makes the top of the data structure geometrically more common than the bottom.

Cats love to be on top.

multi_cat = MultiCat(
    OrderedDict({
        "Cat_A": ("A1", "A2", "A3", "A4", "A5"),
        "Cat_B": ("B1", "B2", "B3", "B4", "B5"),
        "Cat_C": ("C1", "C2", "C3", "C4", "C5")
    })
)
multi_cat("Cat_A") -> random value from "Cat_A" sequence: uniform distribution
multi_cat("Cat_B") -> random value from "Cat_B" sequence: uniform distribution
multi_cat("Cat_C") -> random value from "Cat_C" sequence: uniform distribution
multi_cat() -> random value: uniform distribution, from a random sequence: linear descending distribution

Fortuna 0.16.0 Sample Distribution and Performance Tests

Testbed: MacOS 10.13.6, Python3.7, Skylake 2.7 GHz Intel Core i7, 16GB RAM, 1TB PCIe SSD

$ python3.7 .../fortuna_extras/fortuna_tests.py

Running 1,000,000 cycles of each...


Random Numbers
-------------------------------------------------------------------------

Base Case:
random.randint(1, 10) x 1000000: 1260.64 ms
 1: 9.96%
 2: 10.0%
 3: 9.93%
 4: 10.01%
 5: 9.99%
 6: 9.95%
 7: 10.03%
 8: 10.06%
 9: 10.03%
 10: 10.04%

Fortuna.random_range(1, 10) x 1000000: 80.27 ms
 1: 10.03%
 2: 9.93%
 3: 9.98%
 4: 10.03%
 5: 9.98%
 6: 9.99%
 7: 10.0%
 8: 10.02%
 9: 10.02%
 10: 10.02%

Base Case:
random.randrange(10) x 1000000: 906.21 ms
 0: 10.0%
 1: 10.0%
 2: 10.03%
 3: 9.96%
 4: 10.02%
 5: 10.04%
 6: 10.01%
 7: 9.96%
 8: 10.0%
 9: 9.98%

Fortuna.random_below(10) x 1000000: 79.21 ms
 0: 9.99%
 1: 9.96%
 2: 9.96%
 3: 10.02%
 4: 10.06%
 5: 10.0%
 6: 10.05%
 7: 10.01%
 8: 9.97%
 9: 9.98%

Fast Base Case:
Fortuna.fast_rand_below(10) x 1000000: 52.27 ms
 0: 9.98%
 1: 10.07%
 2: 10.01%
 3: 10.03%
 4: 9.99%
 5: 10.02%
 6: 9.95%
 7: 9.99%
 8: 9.95%
 9: 10.01%

Fortuna.d(10) x 1000000: 77.1 ms
 1: 10.0%
 2: 9.99%
 3: 10.01%
 4: 9.98%
 5: 10.03%
 6: 9.97%
 7: 10.0%
 8: 10.02%
 9: 10.02%
 10: 9.99%

Fast Base Case:
Fortuna.fast_d(10) x 1000000: 52.64 ms
 1: 10.01%
 2: 9.97%
 3: 9.99%
 4: 9.97%
 5: 10.0%
 6: 10.08%
 7: 10.04%
 8: 9.94%
 9: 10.0%
 10: 10.0%

Fortuna.dice(1, 10) x 1000000: 81.16 ms
 1: 10.04%
 2: 9.99%
 3: 10.01%
 4: 10.0%
 5: 10.03%
 6: 9.98%
 7: 10.04%
 8: 9.97%
 9: 9.99%
 10: 9.95%

Fast Base Case:
Fortuna.fast_dice(1, 10) x 1000000: 54.92 ms
 1: 10.0%
 2: 10.01%
 3: 9.98%
 4: 9.96%
 5: 9.98%
 6: 10.01%
 7: 10.0%
 8: 10.04%
 9: 10.02%
 10: 10.01%

Fortuna.plus_or_minus(5) x 1000000: 75.34 ms
 -5: 9.09%
 -4: 9.11%
 -3: 9.11%
 -2: 9.07%
 -1: 9.08%
 0: 9.11%
 1: 9.1%
 2: 9.09%
 3: 9.09%
 4: 9.04%
 5: 9.11%

Fortuna.plus_or_minus_linear(5) x 1000000: 99.3 ms
 -5: 2.78%
 -4: 5.58%
 -3: 8.32%
 -2: 11.1%
 -1: 13.92%
 0: 16.72%
 1: 13.86%
 2: 11.05%
 3: 8.36%
 4: 5.56%
 5: 2.76%

Fortuna.plus_or_minus_curve(5) x 1000000: 123.71 ms
 -5: 0.22%
 -4: 1.16%
 -3: 4.42%
 -2: 11.53%
 -1: 20.33%
 0: 24.63%
 1: 20.45%
 2: 11.5%
 3: 4.4%
 4: 1.15%
 5: 0.21%


Random Truth
-------------------------------------------------------------------------

Fortuna.percent_true(25) x 1000000: 71.83 ms
 False: 75.07%
 True: 24.93%


Random Values from a Sequence
-------------------------------------------------------------------------

Base Case:
random.choice(some_list) x 1000000: 754.13 ms
 Alpha: 14.28%
 Beta: 14.33%
 Delta: 14.27%
 Eta: 14.38%
 Gamma: 14.2%
 Kappa: 14.26%
 Zeta: 14.28%

Fortuna.random_value(some_list) x 1000000: 73.56 ms
 Alpha: 14.28%
 Beta: 14.34%
 Delta: 14.31%
 Eta: 14.27%
 Gamma: 14.26%
 Kappa: 14.28%
 Zeta: 14.26%

mostly.mostly_front() x 1000000: 212.46 ms
 Alpha: 24.97%
 Beta: 21.48%
 Delta: 17.89%
 Eta: 14.27%
 Gamma: 10.71%
 Kappa: 7.12%
 Zeta: 3.54%

mostly.mostly_middle() x 1000000: 164.4 ms
 Alpha: 6.26%
 Beta: 12.5%
 Delta: 18.72%
 Eta: 24.96%
 Gamma: 18.83%
 Kappa: 12.5%
 Zeta: 6.23%

mostly.mostly_back() x 1000000: 211.88 ms
 Alpha: 3.56%
 Beta: 7.13%
 Delta: 10.71%
 Eta: 14.36%
 Gamma: 17.9%
 Kappa: 21.37%
 Zeta: 24.97%

mostly.mostly_first() x 1000000: 254.71 ms
 Alpha: 34.22%
 Beta: 30.0%
 Delta: 20.04%
 Eta: 10.26%
 Gamma: 4.0%
 Kappa: 1.21%
 Zeta: 0.27%

mostly.mostly_center() x 1000000: 199.73 ms
 Alpha: 0.44%
 Beta: 5.38%
 Delta: 24.25%
 Eta: 39.93%
 Gamma: 24.2%
 Kappa: 5.37%
 Zeta: 0.43%

mostly.mostly_last() x 1000000: 254.69 ms
 Alpha: 0.27%
 Beta: 1.2%
 Delta: 4.04%
 Eta: 10.25%
 Gamma: 20.02%
 Kappa: 29.95%
 Zeta: 34.28%

mostly() x 1000000: 347.38 ms
 Alpha: 10.86%
 Beta: 12.92%
 Delta: 16.36%
 Eta: 19.83%
 Gamma: 16.34%
 Kappa: 12.86%
 Zeta: 10.85%

random_cycle() x 1000000: 574.2 ms
 Alpha: 14.27%
 Beta: 14.27%
 Delta: 14.32%
 Eta: 14.28%
 Gamma: 14.29%
 Kappa: 14.29%
 Zeta: 14.28%


Random Values by Weighted Table
-------------------------------------------------------------------------

Base Case:
random.choices(pop, cum_weights=cum_weights) x 1000000: 1897.3 ms
 Apple: 23.3%
 Banana: 13.28%
 Cherry: 6.67%
 Grape: 33.34%
 Lime: 9.99%
 Orange: 13.42%

Base Case:
random.choices(pop, weights) x 1000000: 2275.09 ms
 Apple: 23.23%
 Banana: 13.32%
 Cherry: 6.65%
 Grape: 33.4%
 Lime: 10.03%
 Orange: 13.38%

cumulative_choice() x 1000000: 239.87 ms
 Apple: 23.33%
 Banana: 13.34%
 Cherry: 6.68%
 Grape: 33.28%
 Lime: 10.0%
 Orange: 13.37%

relative_choice() x 1000000: 240.85 ms
 Apple: 23.37%
 Banana: 13.31%
 Cherry: 6.68%
 Grape: 33.3%
 Lime: 10.0%
 Orange: 13.34%


Random Values by Key: MultiCat
-------------------------------------------------------------------------

multi_cat('Cat_A') x 1000000: 687.75 ms
 A1: 20.02%
 A2: 20.0%
 A3: 20.0%
 A4: 20.01%
 A5: 19.97%

multi_cat('Cat_B') x 1000000: 701.81 ms
 B1: 20.01%
 B2: 20.0%
 B3: 20.01%
 B4: 19.98%
 B5: 20.01%

multi_cat('Cat_C') x 1000000: 728.2 ms
 C1: 19.98%
 C2: 20.02%
 C3: 19.99%
 C4: 20.01%
 C5: 20.0%

multi_cat() x 1000000: 875.01 ms
 A1: 10.0%
 A2: 9.99%
 A3: 10.0%
 A4: 10.0%
 A5: 10.02%
 B1: 6.67%
 B2: 6.68%
 B3: 6.67%
 B4: 6.68%
 B5: 6.67%
 C1: 3.32%
 C2: 3.32%
 C3: 3.32%
 C4: 3.32%
 C5: 3.32%


Multi Dice: 10d10
-------------------------------------------------------------------------

Base Case:
randrange_dice(10, 10) x 1000000: 9713.09 ms

Base Case:
floor_dice(10, 10) x 1000000: 2680.88 ms

Fortuna.dice(10, 10) x 1000000: 376.32 ms

Fast Base Case:
Fortuna.fast_dice(10, 10) x 1000000: 117.33 ms


-------------------------------------------------------------------------
Total Test Time: 30.88 sec


Process finished with exit code 0

Change Log

Fortuna 0.16.0
Pushed distribution_timer to the .pyx layer.
Changed default number of iterations of tests to 1 million, up form 1 hundred thousand.
Reordered tests to better match documentation. Added Fortuna.fast_d.
Added Fortuna.fast_dice.
Added Fortuna.fast_rand_below.

Fortuna 0.15.10
Internal Development Cycle

Fortuna 0.15.9
Added Base Cases for random.choices
Added Base Case for randint_dice

Fortuna 0.15.8
Clarified MultiCat Test

Fortuna 0.15.7
Fixed minor typos.

Fortuna 0.15.6
Fixed minor typos.
Simplified MultiCat example.

Fortuna 0.15.5
Added MultiCat test.
Fixed some minor typos in docs.

Fortuna 0.15.4
Performance optimization for both WeightedChoice() variants.
Cython update provides small performance enhancement across the board.
Compilation now leverages Python3 all the way down.
MultiCat pushed to the .pyx layer for better performance.

Fortuna 0.15.3
Reworked the MultiCat example to include several randomizing strategies working in concert.
Added Multi Dice 10d10 performance tests.
Updated sudo code in documentation to be more pythonic.

Fortuna 0.15.2
Fixed: Linux installation failure.
Added: complete source files to the distribution (.cpp .hpp .pyx).

Fortuna 0.15.1
Updated & simplified distribution_timer in fortuna_tests.py
Readme updated, fixed some typos.
Known issue preventing successful installation on some linux platforms.

Fortuna 0.15.0
Performance tweaks. \ Readme updated, added some details.

Fortuna 0.14.1
Readme updated, fixed some typos.

Fortuna 0.14.0
Fixed a bug where the analytic continuation algorithm caused a rare issue during compilation on some platforms.

Fortuna 0.13.3
Fixed Test Bug: percent sign was missing in output distributions.
Readme updated: added update history, fixed some typos.

Fortuna 0.13.2
Readme updated for even more clarity.

Fortuna 0.13.1
Readme updated for clarity.

Fortuna 0.13.0
Minor Bug Fixes.
Readme updated for aesthetics.
Added Tests: .../fortuna_extras/fortuna_tests.py

Fortuna 0.12.0
Internal test for future update.

Fortuna 0.11.0
Initial Release: Public Beta

Fortuna 0.10.0
Module name changed from Dice to Fortuna

Legal Stuff

Fortuna :: Copyright (c) 2018 Robert Sharp aka Broken

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

This readme file shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.