Pysamplespace 1.0.4

Description:

pysamplespace 1.0.4

SampleSpace: Cross-Platform Tools for Generating Random Numbers

SampleSpace is a cross-platform library for describing and sampling from
random distributions.
While SampleSpace is primarily intended for creating
procedurally-generated content, it is also useful for Monte-Carlo
simulations, unit testing, and anywhere that flexible, repeatable random
numbers are required.
Platforms
SampleSpace supports the following platforms:

Python — pysamplespace
C++ — In development
C# — In development

SampleSpace guarantees that the value of random sequences is consistent
and serialized states are compatible across each platform implementation.
Installation
Installation is simple using pip:

$ pip install pysamplespace

SampleSpace's only dependency is
xxHash, though it optionally
offers additional functionality if
PyYAML is installed.
Usage
All documentation is available at on Read the Docs.
SampleSpace provides the following submodules:

samplespace.repeatablerandom — Repeatable Random Sequences
samplespace.distributions — Serializable Probability Distributions
samplespace.algorithms — General Sampling Algorithms
samplespace.pyyaml_support — YAML serialization support

Repeatable Random Sequences
samplespace.repeatablerandom allows for generating repeatable,
deterministic random sequences. It is compatible with the built-in
random module as a
drop-in replacement.
A key feature of RepeatableRandomSequence is its ability to get, serialize, and restore internal
state. This is especially useful when generating procedural content from a fixed seed.
A RepeatableRandomSequence can also be used for unit testing by replacing the built-in random module.
Because each random sequence is deterministic and repeatable for a given seed, expected values can be
recorded and compared against within unit tests.
RepeatableRandomSequence produces high-quality pseudo-random values. See
Randomness Test Results for
results from randomness tests.
import samplespace

rrs = samplespace.RepeatableRandomSequence(seed=1234)

samples = [rrs.randrange(30) for _ in range(10)]
print(samples)
# Will always print:
# [21, 13, 28, 19, 16, 29, 28, 24, 29, 25]

# Generate some random values to advance the state
[rrs.random() for _ in range(90)]

# Save the state for later recall
# State can be serialzied to a dict and serialized as JSON
state = rrs.getstate()
state_as_dict = state.as_dict()
state_as_json = json.dumps(state_as_dict)
print(state_as_json)
# Prints {"seed": 12345, "hash_input": "gxzNfDj4Ypc=", "index": 100}

print(rrs.random())
# Will print 0.5940559149714152

# Generate some more values
[rrs.random() for _ in range(100)]

# Return the sequence to the saved state. The next value will match
# the value following when the state was saved.
new_state_as_dict = json.loads(state_as_json)
new_state = samplespace.repeatablerandom.RepeatableRandomSequenceState.from_dict(new_state_as_dict)
rrs.setstate(new_state)
print(rrs.random())
# Will also print 0.5940559149714152

Distributions
samplespace.distributions implements a number of useful probability distributions.
Each distribution can be sampled using any random number generator providing at least the same
functionality as the random module; this includes samplespace.repeatablerandom.
The classes in this module are primarily intended for storing information on random distributions
in configuration files using Distribution.as_dict()/distribution_from_dict()
or Distribution.as_list()/distribution_from_list().
Distributions can be serialized to strings:
from samplespace.distributions import Pareto, DiscreteUniform, UniformCategorical

pareto = Pareto(2.5)
print('Pareto as dict:', pareto.as_dict()) # {'distribution': 'pareto', 'alpha': 2.5}
print('Pareto as list:', pareto.as_list()) # ['pareto', 2.5]

discrete = DiscreteUniform(3, 8)
print('Discrete uniform as dict:', discrete.as_dict()) # {'distribution': 'discreteuniform', 'min_val': 3, 'max_val': 8}
print('Discrete uniform as list:', discrete.as_list()) # ['discreteuniform', 3, 8]

cat = UniformCategorical(['string', 4, {'a':'dict'}])
print('Uniform categorical as dict:', cat.as_dict()) # {'distribution': 'uniformcategorical', 'population': ['string', 4, {'a': 'dict'}]}
print('Uniform categorical as list:', cat.as_list()) # ['uniformcategorical', ['string', 4, {'a': 'dict'}]]

Distributions can be specified in configuration files:
from samplespace import distributions, RepeatableRandomSequence

city_config = {
"building_distribution": {
"distribution": "weightedcategorical",
"items": [
["house", 0.2],
["store", 0.4],
["tree", 0.8],
["ground", 5.0]
]
}
}

rrs = RepeatableRandomSequence()
building_dist = distributions.distribution_from_dict(city_config['building_distribution'])

buildings = [[building_dist.sample(rrs) for col in range(20)] for row in range(5)]

for row in buildings:
for building_type in row:
if building_type == 'house':
print('H', end='')
elif building_type == 'store':
print('S', end='')
elif building_type == 'tree':
print('T', end='')
else:
print('.', end='')
print()

Algorithms
samplespace.algorithms implements several general-purpose sampling algorithms
such as binary roulette wheel sampling and alias tables.
PyYAML Support
SampleSpace provides optional support for PyYAML,
which can be enabled via the samplespace.pyyaml_support submodule.
Repeatable Random Sequences:
import yaml
from samplespace import RepeatableRandomSequence
import samplespace.pyyaml_support
samplespace.pyyaml_support.enable_yaml_support()

rrs = RepeatableRandomSequence(seed=678)
[rrs.randrange(10) for _ in range(5)]

# Serialize the sequence as YAML
as_yaml = yaml.dump(rrs) # '!samplespace.rrs\nhash_input: s1enBV+SSXk=\nindex: 5\nseed: 678\n'

rrs_from_yaml = yaml.load(as_yaml, Loader=yaml.FullLoader)

Distributions:
import yaml
from samplespace import distributions
import samplespace.pyyaml_support
samplespace.pyyaml_support.enable_yaml_support()

gamma = distributions.Gamma(5.0, 3.0)
gamma_as_yaml = yaml.dump(gamma) # '!samplespace.distribution\nalpha: 5.0\nbeta: 3.0\ndistribution: gamma\n'

dist_from_yaml = yaml.load(gamma_as_yaml, Loader=yaml.FullLoader)

Copyright and License
SampleSpace was created by Coriander V. Pines
and is available under the
BSD 3-Clause License.
The source is available on GitLab.