KissBitGenerator#

class scikitplot.random.KissBitGenerator(seed: Optional[Union[int, KissSeedSequence]]=None, int bit_width: int = None)[source]#

NumPy-compatible BitGenerator using KISS algorithm with complete serialization.

Parameters:
seed{None, int, SeedSequence, KissSeedSequence}, optional, default=None

Random seed or seed sequence: - int: Direct seed value - SeedSequence: Use its generated state - None: Use OS entropy via secrets.token_bytes()

bit_widthint, default=None

Generator bit width (32 or 64) - 32: Uses Kiss32Random (faster, period ~2^121) - 64: Uses Kiss64Random (slower, period ~2^250)

Attributes:
lockthreading.RLock

Lock for thread-safe access (NumPy protocol requirement)

seed_seqKissSeedSequence

seed_seq: object

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

KissGenerator

High-level generator using this BitGenerator

KissRandomState

Inherites from KissGenerator

default_rng

Convenience function to create generator

numpy.random.BitGenerator

NumPy’s BitGenerator base class

Notes

The bit_width parameter determines internal generator: - 32: Uses Kiss32Random (faster, period ~2^121) - 64: Uses Kiss64Random (slower, period ~2^250) - NumPy BitGenerator protocol compatible - Thread-safe via lock - Complete pickle/JSON support

For NumPy compatibility, random_raw() always returns uint64 values regardless of internal bit width.

Examples

>>> bg = KissBitGenerator(42)
>>> bg.random_raw()
>>>
>>> # NOTE: Due to C API differences, use KissGenerator instead
>>> # of wrapping in numpy.random.Generator
>>> gen = KissGenerator(bg)
>>> gen.random(10)
>>>
>>> # Serialization
>>> import pickle
>>> restored = pickle.loads(pickle.dumps(bg))
capsule#

Get PyCapsule for NumPy C API (protocol requirement).

classmethod deserialize(cls, data)#

Deserialize from dict.

Parameters:
datadict

Serialized state

Returns:
KissBitGenerator

Restored instance

Examples

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

Alias for deserialize().

get_params(self, deep=True)#

Get parameters (sklearn-style).

Parameters:
deepbool, default=True

If True, include nested params

Returns:
dict

Parameters

Examples

>>> bg = KissBitGenerator(42)
>>> params = bg.get_params()
get_state(self)#

Get state dictionary.

Returns:
dict

Complete state

Examples

>>> bg = KissBitGenerator(42)
>>> state = bg.get_state()
>>> print("seed_sequence" in state)
True
lock#

!! processed by numpydoc !!

random_raw(self, size=None, output=True)#

Generate random uint64 values.

Parameters:
sizeint, tuple of ints, or None

Output shape

outputbool, default=True

If True, return values. If False, just advance state.

Returns:
int or ndarray

Random uint64 values

Examples

>>> bg = KissBitGenerator(seed=42)
>>> bg.random_raw()  # Single value
<class 'int'>

>>> bg.random_raw(10)  # 10 values
>>> bg.random_raw((3, 4))  # 3x4 array
seed_seq#

object

Type:

seed_seq

serialize(self)#

Serialize to JSON-compatible dict.

Returns:
dict

JSON-serializable state

Examples

>>> import json
>>> bg = KissBitGenerator(42)
>>> data = bg.serialize()
>>> json_str = json.dumps(data)
set_params(self, **params)#

Set parameters (sklearn-style).

Parameters:
**paramsdict

Parameters to set

Returns:
self

Examples

>>> bg = KissBitGenerator(42)
>>> bg.set_params(seed=123)
set_state(self, state)#

Set state from dictionary.

Parameters:
statedict

State from get_state()

Examples

>>> bg1 = KissBitGenerator(42)
>>> state = bg1.get_state()
>>> bg2 = KissBitGenerator(0)
>>> bg2.set_state(state)
spawn(self, int n_children: int) → list['KissBitGenerator']#

Create independent child BitGenerators (NumPy protocol).

Parameters:
n_childrenint

Number of children to spawn

Returns:
list of KissBitGenerator

Independent bit generators

Raises:
ValueError

If n_children < 1

Parameters:

n_children (int)

Return type:

list[KissBitGenerator]

Notes

This is REQUIRED by NumPy’s BitGenerator protocol. Each child is statistically independent.

Examples

>>> bg = KissBitGenerator(42)
>>> children = bg.spawn(3)
>>> print(len(children))
3
>>> # Use in parallel workers
state#

dict

Get state dict (NumPy protocol).

Type:

KissBitGenerator.state

to_dict(self)#

Alias for serialize().