Coverage for colour/algebra/prng.py: 100%

1""" 

2Random Numbers Utilities 

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

4 

5Random number generator objects: 

6 

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

8 

9References 

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/\ 

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

16""" 

17 

18from __future__ import annotations 

19 

20import typing 

21 

22import numpy as np 

23 

24if typing.TYPE_CHECKING: 

25 from colour.hints import ArrayLike, NDArrayFloat 

26 

27from 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 

41RANDOM_STATE = np.random.RandomState() 

42 

43 

44def 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 )