Skip to content

dx_generator

Caution

The dx_generator subpackage is not recommended for cryptographic applications.
It is intended for statistical simulations or machine learning tasks only.

DX and DX32

The DX() API is the recommended fast 32-bit DX generator in this package. It fixes the modulus parameter at \(2^{31} - 1\) to accelerate modular reduction.

The DX32() API provides a more general 32-bit DX generator family with broader parameter choices. Use DX() when speed and the default recommended configuration are preferred, and use DX32() when more flexible parameter selection is needed.

Provides an interface for generating _DX32Generator and _DXGenerator objects from dx_id values.

Provides an end-user interface for generating _DX32Generator and _DXGenerator objects based on dx_id values. It also allows users to access the internal table of dx_id values and their parameters, as well as retrieve the maximum allowed dx_id.

DX() is the recommended faster 32-bit DX generator. It uses parameter sets with fixed modulus pp = 2^31 - 1 and dispatches to the optimized Mersenne modular reduction implementation.

DX32() is the general 32-bit DX generator. It corresponds to the previously released create_dx() API and supports the general DX parameter table.

Both APIs produce 32-bit random integers, but they differ in how the modulus parameter pp is handled.

The internal parameter tables are organized such that each dx_id corresponds to a unique set of parameters. The dx_id values are assigned in ascending order based on the log10(period) value of the parameters.

Examples:

>>> from nextrngbook.dx_generator import DX
>>> DX()
_DXGenerator(
    bb=522882, pp=2147483647, kk=6, ss=2, log10_period=56.0
)

>>> from nextrngbook.dx_generator import DX32
>>> DX32()
_DX32Generator(
    bb=32643, pp=2147483587, kk=7, ss=1, log10_period=65.30000305175781
)

>>> from nextrngbook import dx_generator
>>> dx_id_table = dx_generator.get_dx_id_table()
>>> print(dx_id_table)
{0: {'kk': '3', 'ss': '1', 'bb': '523697', 'pp': '2147483647', 'log10(period)': '28.0'}, 
 1: {'kk': '3', 'ss': '1', 'bb': '523703', 'pp': '2147483647', 'log10(period)': '28.0'},
 ...}
>>> max_dx_id = dx_generator.get_dx_max_id()
>>> print(max_dx_id)
14601

Functions:

  • DX(dx_id, seed=None) - Returns a _DXGenerator object generated from the internal parameters with modulus pp = 2^31 - 1.
  • get_dx_id_table() - Returns the internal table of dx_id values and their associated parameters for DX().

  • get_dx_max_id() - Returns the maximum allowed dx_id value for DX().

  • DX32(dx_id, seed=None) - Returns a _DX32Generator object generated from the internal parameters.

  • get_dx32_id_table() - Returns the internal table of dx_id values and their associated parameters for DX32().
  • get_dx32_max_id() - Returns the maximum allowed dx_id value for DX32().

Type Aliases:

  • SeedType - Type alias for valid seed input types. Can be None, int, NDArray[np.integer], SeedSequence, or a sequence of integers.

DX(dx_id, seed)

Example dx_id values

dx_id k s B p log₁₀(period)
0 3 1 523697 2147483647 28.0
556 4 2 523345 2147483647 37.3
1030 6 2 523867 2147483647 56
2500 13 1 1046957 2147483647 121.3
5000 24 2 518514 2147483647 224
10000 47 2 646323 2147483647 438.6
14769 20897 2 1028880 2147483647 195009.3

Since DX with \(k=2\) showed relatively poor performance in the Crush tests, they are currently excluded from the provided parameter set.

Returns a _DXGenerator object generated from the internal parameters.

Retrieves the corresponding parameters from the internal table based on the given dx_id, and then returns the corresponding _DXGenerator object based on these parameters.

This function is a specialized fast interface for DX generators with modulus pp = 2^31 - 1 so that the optimized Mersenne modular reduction path can be used.

If dx_id is None, a valid dx_id will be randomly selected based on the current time.

If dx_id exceeds the maximum allowed value, it is mapped to a fixed value within the valid range, with the specific mapping depending on the given dx_id. Regardless of whether dx_id is within the valid range or has been mapped, the function will always return the generated object with the same parameter settings for the same dx_id on every call.

The maximum allowed dx_id value can be retrieved using the function get_dx_max_id. To inspect the full table of dx_id values and their corresponding parameters, use the function get_dx_id_table.

Parameters:

Name Type Description Default
dx_id Union[float, int, None]

A non-negative integer representing the identifier used to retrieve the corresponding parameters from the internal table.

 None
seed SeedType

A value used to initialize the random number generator. If None, fresh and unpredictable entropy will be retrieved from the OS. If an int or array-like of integers is provided, it will be passed to SeedSequence to set the initial state of the BitGenerator. Alternatively, a SeedSequence instance can also be used directly. This function uses the same seeding mechanism as NumPy's random system.

 None

Returns:

Type Description
_DXGenerator

A _DXGenerator object using a parameter set from the fast DX table.

Raises:

Type Description
ValueError

If dx_id is not an integer-valued number.
ValueError

If dx_id is negative.

Examples:

>>> from nextrngbook.dx_generator import DX
>>> DX()
_DXGenerator(
    bb=1073738158, pp=2147483647, kk=20897, ss=2, log10_period=195009.296875
)
>>> DX(dx_id=300)
_DXGenerator(
    bb=17301504, pp=2147483647, kk=24, ss=1, log10_period=224.0
)

To ensure reproducibility for the RNG

  1. The seed should be provided with a fixed value (non-None).
  2. The dx_id should be fixed by explicitly providing a specific integer value, such as 270. Do not rely on the default dx_id=None if exact reproducibility is required.

Caution

If multiple dx_id values exceeding the valid range are provided, they might be mapped to the same internal dx_id. This could lead to the misconception that different, independent RNGs are being used, while in fact they are the same. A warning will be issued to inform the user about this mapping. Care should be taken when applying such mappings across multiple threads or processes, as they may introduce high correlations among results.

The fast reduction used in DX() is designed for speed. It maps intermediate values into the range \([0, 2^{31}-1]\), but it is not the same as the fully general modular reduction used by the general DX generator definition. For applications that require the general DX formulation, use DX32() instead.

get_dx_max_id()

Returns the maximum allowed dx_id value for DX().

get_dx_id_table()

Returns the internal parameter table for DX().

The DX() table contains parameter sets for the faster DX generator with fixed pp = 2^31 - 1.

Returns:

Type Description
dict

A dictionary mapping each dx_id to its corresponding fast DX
dict

parameter set.

DX32(dx_id, seed)

Example dx_id values

dx_id k s B p log₁₀(period)
0 2 1 32693 2147483249 18.7
556 3 2 32736 2147483579 28
1030 5 1 32711 2147483497 46.7
2000 8 1 32743 2147483269 74.7
3000 13 2 32754 2147481143 121.3
4000 1301 2 1046381 2147472413 12140.8
4194 50873 2 1016882 2146123787 474729.3

Returns a _DX32Generator object generated from the internal parameters.

Retrieves the corresponding parameters from the internal table based on the given dx_id, and then returns the corresponding _DX32Generator object based on these parameters.

If dx_id is None, a valid dx_id will be randomly selected based on the current time.

If dx_id exceeds the maximum allowed value, it is mapped to a fixed value within the valid range, with the specific mapping depending on the given dx_id. Regardless of whether dx_id is within the valid range or has been mapped, the function will always return the generated object with the same parameter settings for the same dx_id on every call.

The maximum allowed dx_id value can be retrieved using the function get_dx32_max_id. To inspect the full table of dx_id values and their corresponding parameters, use the function get_dx32_id_table.

Parameters:

Name Type Description Default
dx_id Union[float, int, None]

A non-negative integer representing the identifier used to retrieve the corresponding parameters from the internal table.

 None
seed SeedType

A value used to initialize the random number generator. If None, fresh and unpredictable entropy will be retrieved from the OS. If an int or array-like of integers is provided, it will be passed to SeedSequence to set the initial state of the BitGenerator. Alternatively, a SeedSequence instance can also be used directly. This function uses the same seeding mechanism as NumPy's random system.

 None

Returns:

Type Description
_DX32Generator

A _DX32Generator object using a parameter set from the general DX32
_DX32Generator

table.

Raises:

Type Description
ValueError

If dx_id is not an integer-valued number.
ValueError

If dx_id is negative.

Examples:

>>> DX32()
_DX32Generator(
    bb=1016882, pp=2146123787, kk=50873, ss=2, log10_period=474729.3125
)
>>> DX32(dx_id=4000)
_DX32Generator(
    bb=1046381, pp=2147472413, kk=1301, ss=2, log10_period=12140.7998046875
)

To ensure reproducibility for the RNG

  1. The seed should be provided with a fixed value (non-None).
  2. The dx_id should be fixed by explicitly providing a specific integer value, such as 270. Do not rely on the default dx_id=None if exact reproducibility is required.

Caution

If multiple dx_id values exceeding the valid range are provided, they might be mapped to the same internal dx_id. This could lead to the misconception that different, independent RNGs are being used, while in fact they are the same. A warning will be issued to inform the user about this mapping. Care should be taken when applying such mappings across multiple threads or processes, as they may introduce high correlations among results.

get_dx32_max_id()

Returns the maximum allowed dx_id value for DX32().

get_dx32_id_table()

Returns the internal table of dx_id values for DX32().

The DX32() table contains the general 32-bit DX generator parameter sets. This corresponds to the parameter table used by the original create_dx() API.

Returns:

Type Description
dict

A dictionary mapping each dx_id to its corresponding general DX32
dict

parameter set.