KissGenerator#

class scikitplot.random.KissGenerator(bit_generator=None)[source]#

High-level random number generator using KISS algorithm.

Provides NumPy-compatible interface for common distributions with complete serialization support. For advanced distributions, wrap KissBitGenerator in numpy.random.Generator.

Parameters:
bit_generator{None, int, KissBitGenerator}, optional

BitGenerator or seed value

Attributes:
bit_generatorKissBitGenerator

Gets the bit generator instance used by the generator

See also

Kiss32Random

32-bit version for smaller datasets

Kiss64Random

64-bit version for larger datasets

KissRandom

Factory function for auto-detecting

KissSeedSequence

Seed sequence for initialization

KissBitGenerator

NumPy-compatible bit generator

KissRandomState

Inherites from KissGenerator

default_rng

Convenience function to create generator

numpy.random.Generator

NumPy’s Generator class

Notes

This is the recommended high-level API for most users. Provides methods similar to numpy.random.Generator.

References

Examples

>>> gen = KissGenerator(42)
>>> gen.random(5)
>>> gen.integers(0, 100, 10)
>>> gen.normal(0, 1, 1000)
>>>
>>> # Context manager
>>> with KissGenerator(42) as gen:
...     data = gen.random(1000)
>>>
>>> # Serialization
>>> import pickle
>>> restored = pickle.loads(pickle.dumps(gen))
bit_generator#

Gets the bit generator instance used by the generator

Returns:
bit_generatorKissBitGenerator

The bit generator instance used by the generator

Examples

>>> gen = KissGenerator(42)
>>> bg = gen.get_bit_generator()
>>> print(type(bg))
<class 'KissBitGenerator'>
choice(self, a, size=None, replace=True, p=None)#

Random sample from array.

Parameters:
aint or array_like

If int, random sample from np.arange(a)

sizeint or tuple, optional

Output shape

replacebool, default=True

Whether to sample with replacement

parray_like, optional

Probabilities for each element

Returns:
scalar or ndarray

Random samples

Examples

>>> gen = KissGenerator(42)
>>> gen.choice(10, size=5)
array([...])
classmethod deserialize(cls, data)#

Deserialize a KissGenerator from a JSON-compatible dict.

Parameters:
datadict

Serialized generator state.

Returns:
KissGenerator

Fully restored generator instance.

Raises:
TypeError

If types are invalid.

KeyError

If required fields are missing.

ValueError

If state is incompatible or unsupported.

Examples

>>> import json
>>> gen = KissGenerator(42)
>>> json_str = json.dumps(gen.serialize())
>>> data = json.loads(json_str)
>>> restored = KissGenerator.deserialize(data)
classmethod from_dict(cls, data)#

Alias for deserialize().

get_bit_generator(self)#

Get underlying bit generator.

Returns:
KissBitGenerator

The bit generator

Examples

>>> gen = KissGenerator(42)
>>> bg = gen.get_bit_generator()
>>> print(type(bg))
<class 'KissBitGenerator'>
get_params(self, deep=True)#

Get parameters (sklearn-style).

Parameters:
deepbool, default=True

If True, include nested params

Returns:
dict

Parameters

Examples

>>> gen = KissGenerator(42)
>>> params = gen.get_params()
get_state(self)#

Get state dictionary.

Returns:
dict

Complete state

Examples

>>> gen = KissGenerator(42)
>>> state = gen.get_state()
>>> print("bit_generator_state" in state)
True
integers(self, low, high=None, size=None, dtype=np.int64, endpoint=False)#

Random integers in [low, high) or [low, high].

Parameters:
lowint

Lowest value (inclusive)

highint, optional

Highest value (exclusive unless endpoint=True)

sizeint or tuple, optional

Output shape

dtypedtype, default=np.int64

Data type

endpointbool, default=False

If True, sample from [low, high] instead of [low, high)

Returns:
int or ndarray

Random integers

Examples

>>> gen = KissGenerator(42)
>>> gen.integers(0, 10, size=5)
array([...])
normal(self, loc=0.0, scale=1.0, size=None)#

Normal distribution (Box-Muller transform).

Parameters:
locfloat, default=0.0

Mean

scalefloat, default=1.0

Standard deviation

sizeint or tuple, optional

Output shape

Returns:
float or ndarray

Normal samples

Examples

>>> gen = KissGenerator(42)
>>> gen.normal(0, 1, size=1000)
array([...])
permutation(self, x, axis=0)#

Randomly permute sequence or return permuted range.

Parameters:
xint or array-like

If int, permute np.arange(x). If array-like, permute copy of array.

axisint, default=0

Axis to permute along

Returns:
ndarray

Permuted sequence

See also

shuffle

In-place shuffle (destructive)

choice

Random sampling

Notes

Unlike shuffle(), this returns a permuted copy without modifying the input.

Examples

>>> gen = KissGenerator()
>>> gen.permutation(10)  # Permuted [0, 1, ..., 9]
array([3, 7, 1, 9, 2, 5, 8, 0, 6, 4])
>>>
>>> # Permute array (returns copy)
>>> arr = np.array([1, 2, 3, 4])
>>> gen.permutation(arr)
array([3, 1, 4, 2])
>>> arr  # Original unchanged
array([1, 2, 3, 4])
random(self, size=None, dtype=np.float64, out=None)#

Random floats in [0, 1).

Parameters:
sizeint or tuple, optional

Output shape

dtypedtype, default=np.float64

Output data type

outndarray, optional

Output array

Returns:
float or ndarray

Random values

Examples

>>> gen = KissGenerator(42)
>>> gen.random(5)
array([...])
serialize(self)#

Serialize to JSON-compatible dict.

Returns:
dict

JSON-serializable state

Examples

>>> import json
>>> gen = KissGenerator(42)
>>> data = gen.serialize()
>>> json_str = json.dumps(data)
set_bit_generator(self, bit_generator)#

Set new bit generator.

Parameters:
bit_generatorKissBitGenerator

New bit generator

Raises:
TypeError

If not KissBitGenerator

Examples

>>> gen = KissGenerator(42)
>>> new_bg = KissBitGenerator(123)
>>> gen.set_bit_generator(new_bg)
set_params(self, **params)#

Set parameters (sklearn-style).

Parameters:
**paramsdict

Parameters to set

Returns:
self

Examples

>>> gen = KissGenerator(42)
>>> gen.set_params(bit_generator={"seed": 123})
set_state(self, state)#

Set state from dictionary.

Parameters:
statedict

State from get_state()

Examples

>>> gen1 = KissGenerator(42)
>>> state = gen1.get_state()
>>> gen2 = KissGenerator(0)
>>> gen2.set_state(state)
shuffle(self, x)#

Shuffle array in-place (Fisher-Yates algorithm).

Parameters:
xndarray

Array to shuffle

Examples

>>> gen = KissGenerator(42)
>>> arr = np.arange(10)
>>> gen.shuffle(arr)
>>> print(arr)  # shuffled
spawn(self, n_children)#

Create independent child Generators.

Parameters:
n_childrenint

Number of children to spawn

Returns:
list of KissGenerator

Independent generators

Raises:
ValueError

If n_children < 1

See also

KissSeedSequence.spawn

Low-level seed sequence spawning

Notes

Uses seed sequence spawning to ensure statistical independence. Each child generator has its own independent random stream.

Useful for parallel computation where each worker needs an independent RNG.

Examples

>>> gen = KissGenerator()
>>> children = gen.spawn(4)
>>> print(len(children))
3

Use in parallel computation

>>> from concurrent.futures import ThreadPoolExecutor
>>> def worker(gen):
...     return gen.random(100).mean()
>>>
>>> with ThreadPoolExecutor() as executor:
...     results = list(executor.map(worker, children))
to_dict(self)#

Alias for serialize().

uniform(self, low=0.0, high=1.0, size=None)#

Uniform distribution in [low, high).

Parameters:
lowfloat, default=0.0

Lower bound (inclusive)

highfloat, default=1.0

Upper bound (exclusive)

sizeint or tuple, optional

Output shape

Returns:
float or ndarray

Uniform samples

Examples

>>> gen = KissGenerator(42)
>>> gen.uniform(0, 10, size=5)
array([...])