# Fortuna
##### Fast & Flexible Random Value Generator, or Adventures in Non-determinism
Copyright (c) 2018 Robert Sharp aka Broken \
\
\
More than just a high performance random number generator... \
Fortuna can help you build rarefied treasure tables and more. \
Examples coming soon.

#### 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(int A, int B) -> int` \
Inputs must be in range (-1,000,000,000..1,000,000,000). \
Input order is ignored. \
Returns a random integer in range (A..B), uniform distribution. \
Ten to fifteen times faster than random.randrange() or random.randint().

`Fortuna.d(int sides) -> int` \
Input must be in range (1..1,000,000,000). \
Returns a random integer in the range (1, sides), uniform distribution. \
Represents a single die roll.

`Fortuna.dice(int rolls, int sides) -> int` \
Rolls must be in range (1..1,000,000). \
Sides must be in range (1..1,000,000,000). \
Maximum output (rolls * sides) must be in range (1..2,000,000,000). \
Returns a random integer in range (rolls..(sides * rolls))
Returns a geometric distribution based on number and size of the dice rolled. \
Represents the sum of multiple die rolls. \
Complexity scales with the number of dice rolls.

`Fortuna.plus_or_minus(int N) -> int` \
Input must be in range (-1,000,000,000..1,000,000,000). \
Negative or positive input will produce an equivalent distribution. \
Returns random integer in the range (-N, N), inclusive uniform distribution.

`Fortuna.plus_or_minus_linear(int N) -> int` \
Input must be in range (-1,000,000,000..1,000,000,000). \
Negative or positive input will produce an equivalent distribution. \
Returns random integer in the range (-N, N), inclusive zero peak geometric distribution.

`Fortuna.plus_or_minus_curve(int N) -> int` \
Input must be in range (-1,000,000,000..1,000,000,000). \
Negative or positive input will produce an equivalent distribution. \
Returns random integer in the range (-N, N), inclusive zero peak gaussian distribution.

`Fortuna.percent_true(int N) -> bool` \
Input range: (0..100). \
N=zero always returns False, N=100 always returns True. \
Any value of N in range (1..99) will produce True or False.
Returns a random Bool based on N: the probability of True as a percentage.

`Fortuna.random_value(list) -> value` \
Input sequence length must be in range (1..1,000,000,000). \
Returns a random value from a sequence (list or tuple), uniform distribution, non-destructive. \
Replaces random.choice(). Up to 4x faster.

## Class Abstractions

### Mostly: The Quantum Monty
- Constructor takes a sequence (list or tuple) of arbitrary values.
- Sequence length must be in range (3..1,000,000,000).
- Values can be any Python object that can be passed around... string, int, list, function etc.
- Provides a variety of methods for choosing a random value based on position in the sequence.
- Performance scales by some tiny fraction of the length of the sequence.
<pre>
some_sequence = ["Alpha", "Beta", "Delta", "Eta", "Gamma", "Kappa", "Zeta"]
random_monty = Fortuna.Mostly(some_sequence)
</pre>
`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 overlapped probability waves)

### Random Cycle: The Truffle Shuffle
- Constructor takes a sequence (list or tuple) of arbitrary values.
- Sequence length must be in range (3..1,000,000,000).
- 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.
<pre>
some_sequence = ["Alpha", "Beta", "Delta", "Eta", "Gamma", "Kappa", "Zeta"]
random_cycle = Fortuna.RandomCycle(some_sequence)
random_cycle() -> value
</pre>
Returns a random value from the sequence. Produces uniform distributions with no consecutive duplicates 
and relatively few nearby duplicates. This behavior gives rise to output sequences 
that seem much less mechanical when compared to output from other random_value algorithms.

### Weighted Choice: Custom Rarity
- Constructors take a 2d sequence (list or tuple) of weighted values... `[(weight, value), ... ]`
- Sequence length must be in range (1..1,000,000,000).
- 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.
- Returns a random value and produces custom distributions based on weighting.
- 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 nicely to cumulative weights.
Cumulative weights are slightly easier for humans to get wrong. Relative weights can be compared directly
while cumulative weights can not.

#### Cumulative Weight Strategy:
Note: Logic dictates Cumulative Weights must be unique!
<pre>
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
</pre>

#### Relative Weight Strategy:
<pre>
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
</pre>


## Fortuna 0.15 Sample Distribution and Performance Test Suite
<pre>
$ /usr/local/bin/python3.7 .../site-packages/fortuna_extras/fortuna_tests.py
Running 100,000 cycles of each...


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

Base Case:
random.randrange(10) x 100000: 108.72 ms
 0: 10.12%
 1: 9.95%
 2: 9.94%
 3: 10.05%
 4: 10.07%
 5: 10.12%
 6: 9.9%
 7: 10.13%
 8: 9.92%
 9: 9.79%

Fortuna.random_range(0, 9) x 100000: 9.77 ms
 0: 9.97%
 1: 9.92%
 2: 10.1%
 3: 9.98%
 4: 10.07%
 5: 10.16%
 6: 9.97%
 7: 9.95%
 8: 10.06%
 9: 9.82%

Base Case:
random.randint(1, 10) x 100000: 134.45 ms
 1: 9.77%
 2: 10.13%
 3: 10.07%
 4: 10.02%
 5: 10.01%
 6: 10.11%
 7: 10.05%
 8: 9.96%
 9: 10.01%
 10: 9.87%

Fortuna.d(10) x 100000: 9.73 ms
 1: 10.17%
 2: 9.9%
 3: 9.87%
 4: 10.12%
 5: 10.21%
 6: 9.94%
 7: 9.99%
 8: 9.81%
 9: 9.96%
 10: 10.04%

Fortuna.plus_or_minus(5) x 100000: 10.12 ms
 -5: 8.96%
 -4: 9.3%
 -3: 9.15%
 -2: 9.06%
 -1: 9.08%
 0: 8.95%
 1: 9.02%
 2: 9.14%
 3: 8.96%
 4: 9.09%
 5: 9.29%

Fortuna.plus_or_minus_linear(5) x 100000: 13.23 ms
 -5: 2.74%
 -4: 5.59%
 -3: 8.35%
 -2: 11.14%
 -1: 13.95%
 0: 16.58%
 1: 13.95%
 2: 11.02%
 3: 8.31%
 4: 5.62%
 5: 2.74%

Fortuna.plus_or_minus_curve(5) x 100000: 14.44 ms
 -5: 0.21%
 -4: 1.17%
 -3: 4.36%
 -2: 11.56%
 -1: 20.57%
 0: 24.56%
 1: 20.23%
 2: 11.49%
 3: 4.44%
 4: 1.21%
 5: 0.21%


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

Fortuna.percent_true(25) x 100000: 14.27 ms
 False: 74.8%
 True: 25.2%


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

Base Case:
random.choice(some_list) x 100000: 91.07 ms
 Alpha: 14.3%
 Beta: 14.38%
 Delta: 14.1%
 Eta: 14.26%
 Gamma: 14.38%
 Kappa: 14.3%
 Zeta: 14.28%

Fortuna.random_value(some_list) x 100000: 21.11 ms
 Alpha: 14.34%
 Beta: 14.22%
 Delta: 14.23%
 Eta: 14.2%
 Gamma: 14.34%
 Kappa: 14.51%
 Zeta: 14.16%

monty = Mostly(some_list)
monty.mostly_front() x 100000: 36.36 ms
 Alpha: 24.89%
 Beta: 21.63%
 Delta: 17.86%
 Eta: 14.27%
 Gamma: 10.72%
 Kappa: 7.12%
 Zeta: 3.51%

monty.mostly_middle() x 100000: 25.21 ms
 Alpha: 6.13%
 Beta: 12.43%
 Delta: 18.91%
 Eta: 25.16%
 Gamma: 18.73%
 Kappa: 12.48%
 Zeta: 6.17%

monty.mostly_back() x 100000: 29.88 ms
 Alpha: 3.54%
 Beta: 7.01%
 Delta: 10.88%
 Eta: 14.35%
 Gamma: 17.82%
 Kappa: 21.51%
 Zeta: 24.89%

monty.mostly_first() x 100000: 35.76 ms
 Alpha: 34.01%
 Beta: 30.16%
 Delta: 19.97%
 Eta: 10.35%
 Gamma: 4.0%
 Kappa: 1.23%
 Zeta: 0.28%

monty.mostly_center() x 100000: 41.09 ms
 Alpha: 0.43%
 Beta: 5.33%
 Delta: 24.53%
 Eta: 39.73%
 Gamma: 24.21%
 Kappa: 5.33%
 Zeta: 0.43%

monty.mostly_last() x 100000: 47.15 ms
 Alpha: 0.25%
 Beta: 1.24%
 Delta: 4.09%
 Eta: 10.08%
 Gamma: 19.88%
 Kappa: 29.87%
 Zeta: 34.6%

monty() x 100000: 62.39 ms
 Alpha: 11.0%
 Beta: 12.8%
 Delta: 16.54%
 Eta: 19.63%
 Gamma: 16.26%
 Kappa: 12.94%
 Zeta: 10.83%

truffle_shuffle = RandomCycle(some_list)
truffle_shuffle() x 100000: 93.79 ms
 Alpha: 14.26%
 Beta: 14.31%
 Delta: 14.18%
 Eta: 14.32%
 Gamma: 14.32%
 Kappa: 14.28%
 Zeta: 14.34%


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

cumulative_weighted_choice() x 100000: 31.05 ms
 Apple: 23.23%
 Banana: 13.54%
 Cherry: 6.65%
 Grape: 33.09%
 Lime: 10.1%
 Orange: 13.39%

relative_weighted_choice() x 100000: 29.28 ms
 Apple: 23.18%
 Banana: 13.41%
 Cherry: 6.7%
 Grape: 33.31%
 Lime: 9.95%
 Orange: 13.45%


Multi Dice: 
-------------------------------------------------------------------------

Base Case:
randrange_dice(10, 10) x 100000: 1065.73 ms

Base Case:
floor_dice(10, 10) x 100000: 292.35 ms

Fortuna.dice(10, 10) x 100000: 42.95 ms


-------------------------------------------------------------------------
Total Test Time: 2.56 sec


Process finished with exit code 0
</pre>

## Update History

#### Fortuna 0.15.2
_Fixed: Linux installation failure._
_Added: complete source files to distribution (.cpp .hpp .pyx)._
_The distribution_timer in fortuna_tests.py now requires kwarg: call_sig="..." and no longer attempts to discover the function's name automatically._

#### Fortuna 0.15.1 - internal only
_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
_Minor performance tweaks._ \ 
_Readme updated, added some details._

#### Fortuna 0.14.1
_Readme updated, fixed some typos._

#### Fortuna 0.14.0
_Fortuna now requires Python 3.7_ \
_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_


## 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:

The above copyright notice and this permission notice 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.
