1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170 | ------------------------------------------------------------------------------
-- --
-- GNAT RUN-TIME COMPONENTS --
-- --
-- S Y S T E M . R A N D O M _ N U M B E R S --
-- --
-- S p e c --
-- --
-- Copyright (C) 2007-2023, Free Software Foundation, Inc. --
-- --
-- GNAT is free software; you can redistribute it and/or modify it under --
-- terms of the GNU General Public License as published by the Free Soft- --
-- ware Foundation; either version 3, or (at your option) any later ver- --
-- sion. GNAT is distributed in the hope that it will be useful, but WITH- --
-- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY --
-- or FITNESS FOR A PARTICULAR PURPOSE. --
-- --
-- As a special exception under Section 7 of GPL version 3, you are granted --
-- additional permissions described in the GCC Runtime Library Exception, --
-- version 3.1, as published by the Free Software Foundation. --
-- --
-- You should have received a copy of the GNU General Public License and --
-- a copy of the GCC Runtime Library Exception along with this program; --
-- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
-- <http://www.gnu.org/licenses/>. --
-- --
-- GNAT was originally developed by the GNAT team at New York University. --
-- Extensive contributions were provided by Ada Core Technologies Inc. --
-- --
------------------------------------------------------------------------------
-- Extended pseudo-random number generation
-- This package provides a type representing pseudo-random number generators,
-- and subprograms to extract various uniform distributions of numbers
-- from them. It also provides types for representing initialization values
-- and snapshots of internal generator state, which permit reproducible
-- pseudo-random streams.
-- The generator currently provided by this package has an extremely long
-- period (at least 2**19937-1), and passes the Big Crush test suite, with the
-- exception of the two linear complexity tests. Therefore, it is suitable
-- for simulations, but should not be used as a cryptographic pseudo-random
-- source without additional processing.
-- Note: this package is in the System hierarchy so that it can be directly
-- used by other predefined packages. User access to this package is via
-- the package GNAT.Random_Numbers (file g-rannum.ads), which also extends
-- its capabilities. The interfaces are different so as to include in
-- System.Random_Numbers only the definitions necessary to implement the
-- standard random-number packages Ada.Numerics.Float_Random and
-- Ada.Numerics.Discrete_Random.
-- Note: this package is marked SPARK_Mode Off, because functions Random work
-- by side-effect to change the value of the generator, hence they should not
-- be called from SPARK code.
with Interfaces;
private with Ada.Strings.Text_Buffers;
package System.Random_Numbers with
SPARK_Mode => Off
is
type Generator is limited private;
-- Generator encodes the current state of a random number stream, it is
-- provided as input to produce the next random number, and updated so
-- that it is ready to produce the next one.
type State is private;
-- A non-limited version of a Generator's internal state
function Random (Gen : Generator) return Float;
function Random (Gen : Generator) return Long_Float;
-- Return pseudo-random numbers uniformly distributed on [0.0 .. 1.0)
function Random (Gen : Generator) return Interfaces.Unsigned_32;
function Random (Gen : Generator) return Interfaces.Unsigned_64;
function Random (Gen : Generator) return Interfaces.Unsigned_128;
-- Return pseudo-random numbers uniformly distributed on T'First .. T'Last
-- for builtin integer types.
generic
type Result_Subtype is (<>);
Default_Min : Result_Subtype := Result_Subtype'Val (0);
function Random_Discrete
(Gen : Generator;
Min : Result_Subtype := Default_Min;
Max : Result_Subtype := Result_Subtype'Last) return Result_Subtype;
-- Returns pseudo-random numbers uniformly distributed on Min .. Max
generic
type Result_Subtype is digits <>;
function Random_Float (Gen : Generator) return Result_Subtype;
-- Returns pseudo-random numbers uniformly distributed on [0 .. 1)
type Initialization_Vector is
array (Integer range <>) of Interfaces.Unsigned_32;
-- Provides the most general initialization values for a generator (used
-- in Reset). In general, there is little point in providing more than
-- a certain number of values (currently 624).
procedure Reset (Gen : Generator);
-- Re-initialize the state of Gen from the time of day
procedure Reset (Gen : Generator; Initiator : Initialization_Vector);
procedure Reset (Gen : Generator; Initiator : Interfaces.Integer_32);
procedure Reset (Gen : Generator; Initiator : Interfaces.Unsigned_32);
procedure Reset (Gen : Generator; Initiator : Integer);
-- Re-initialize Gen based on the Initiator in various ways. Identical
-- values of Initiator cause identical sequences of values.
procedure Reset (Gen : Generator; From_State : Generator);
-- Causes the state of Gen to be identical to that of From_State; Gen
-- and From_State will produce identical sequences of values subsequently.
procedure Reset (Gen : Generator; From_State : State);
procedure Save (Gen : Generator; To_State : out State);
-- The sequence
-- Save (Gen2, S); Reset (Gen1, S)
-- has the same effect as Reset (Gen2, Gen1).
procedure Reset (Gen : Generator; From_Image : String);
function Image (Gen : Generator) return String;
-- The call
-- Reset (Gen2, Image (Gen1))
-- has the same effect as Reset (Gen2, Gen1);
Max_Image_Width : constant := 11 * 624;
-- Maximum possible length of result of Image (...)
function Image (Of_State : State) return String;
-- A String representation of Of_State. Identical to the result of
-- Image (Gen), if Of_State has been set with Save (Gen, Of_State).
function Value (Coded_State : String) return State;
-- Inverse of Image on States
private
N : constant := 624;
-- The number of 32-bit integers in the shift register
M : constant := 397;
-- Feedback distance from the current position
subtype State_Val is Interfaces.Unsigned_32;
type State is array (0 .. N - 1) of State_Val with Put_Image => Put_Image;
procedure Put_Image
(S : in out Ada.Strings.Text_Buffers.Root_Buffer_Type'Class; V : State);
type Writable_Access (Self : access Generator) is limited null record;
-- Auxiliary type to make Generator a self-referential type
type Generator is limited record
Writable : Writable_Access (Generator'Access);
-- This self reference allows functions to modify Generator arguments
S : State := [others => 0];
-- The shift register, a circular buffer
I : Integer := N;
-- Current starting position in shift register S (N means uninitialized)
-- Naming exception: I is fine to use here as it is the name used in the
-- original paper describing the Mersenne Twister and in common
-- descriptions of the algorithm.
end record;
end System.Random_Numbers;
|