Coverage for algebra/prng.py: 13%

1"""

2 Random Numbers Utilities

3========================

4

5 Random number generator objects:

6

7- :func:`colour.algebra.random_triplet_generator`

8

9 References

10----------

11- :cite:`Laurent2012a` : Laurent. (2012). Reproducibility of python

12 pseudo-random numbers across systems and versions? Retrieved January 20,

13 2015, from

14 http://stackoverflow.com/questions/8786084/\

15 reproducibility-of-python-pseudo-random-numbers-across-systems-and-versions

16"""

17

18 from __future__ import annotations

19

20 import typing

21

22 import numpy as np

23

24 if typing.TYPE_CHECKING:

25 from colour.hints import ArrayLike, NDArrayFloat

26

27 from colour.utilities import as_float_array, tstack

28

29 __author__ = "Colour Developers"

30 __copyright__ = "Copyright 2013 Colour Developers"

31 __license__ = "BSD-3-Clause - https://opensource.org/licenses/BSD-3-Clause"

32 __maintainer__ = "Colour Developers"

33 __email__ = "colour-developers@colour-science.org"

34 __status__ = "Production"

35

36 __all__ = [

37 "RANDOM_STATE",

38 "random_triplet_generator",

39]

40

41 RANDOM_STATE = np.random.RandomState()

42

43

44 def random_triplet_generator(

45 size: int,

46 limits: ArrayLike = ([0, 1], [0, 1], [0, 1]),

47 random_state: np.random.RandomState = RANDOM_STATE,

48) -> NDArrayFloat:

49 """

50 Generate random triplets using a pseudo-random number generator.

51

52 Generate an array of random triplets with values constrained within

53 specified limits for each dimension. The triplets are generated using

54 a Mersenne Twister pseudo-random number generator.

55

56 Parameters

57 ----------

58 size

59 Number of random triplets to generate.

60 limits

61 Random value limits for each axis of the triplets, specified as a

62 sequence of [min, max] pairs. Default limits are [0, 1] for each

63 axis.

64 random_state

65 Mersenne Twister pseudo-random number generator instance used for

66 generating random values.

67

68 Returns

69 -------

70 :class:`numpy.ndarray`

71 Array of shape (size, 3) containing the generated random triplets.

72

73 Notes

74 -----

75 - The test is assuming that :func:`np.random.RandomState` definition

76 will return the same sequence no matter which *OS* or *Python*

77 version is used. There is however no formal promise about the

78 *prng* sequence reproducibility of either *Python* or *Numpy*

79 implementations, see :cite:`Laurent2012a`.

80

81 Examples

82 --------

83 >>> from pprint import pprint

84 >>> prng = np.random.RandomState(4)

85 >>> random_triplet_generator(10, random_state=prng)

86 ... # doctest: +ELLIPSIS

87 array([[ 0.9670298..., 0.7793829..., 0.4361466...],

88 [ 0.5472322..., 0.1976850..., 0.9489773...],

89 [ 0.9726843..., 0.8629932..., 0.7863059...],

90 [ 0.7148159..., 0.9834006..., 0.8662893...],

91 [ 0.6977288..., 0.1638422..., 0.1731654...],

92 [ 0.2160895..., 0.5973339..., 0.0749485...],

93 [ 0.9762744..., 0.0089861..., 0.6007427...],

94 [ 0.0062302..., 0.3865712..., 0.1679721...],

95 [ 0.2529823..., 0.0441600..., 0.7333801...],

96 [ 0.4347915..., 0.9566529..., 0.4084438...]])

97 """

98

99 limit_x, limit_y, limit_z = as_float_array(limits)

100

101 return tstack(

102 [

103 random_state.uniform(limit_x[0], limit_x[1], size=size),

104 random_state.uniform(limit_y[0], limit_y[1], size=size),

105 random_state.uniform(limit_z[0], limit_z[1], size=size),

106 ]

107 )