# A.5.2 Random Number Generation

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

Facilities for the generation of pseudo-random floating point numbers are provided in the package Numerics.Float_Random; the generic package Numerics.Discrete_Random provides similar facilities for the generation of pseudo-random integers and pseudo-random values of enumeration types. For brevity, pseudo-random values of any of these types are called random numbers.

Some of the facilities provided are basic to all applications of random numbers. These include a limited private type each of whose objects serves as the generator of a (possibly distinct) sequence of random numbers; a function to obtain the next random number from a given sequence of random numbers (that is, from its generator); and subprograms to initialize or reinitialize a given generator to a time-dependent state or a state denoted by a single integer.

Other facilities are provided specifically for advanced applications. These include subprograms to save and restore the state of a given generator; a private type whose objects can be used to hold the saved state of a generator; and subprograms to obtain a string representation of a given generator state, or, given such a string representation, the corresponding state.

## Static Semantics

The library package Numerics.Float_Random has the following declaration:

```package Ada.Numerics.Float_Random is
```

```    -- Basic facilities
```

```    type Generator is limited private;
```

```    subtype Uniformly_Distributed is Float range 0.0 .. 1.0;
function Random (Gen : Generator) return Uniformly_Distributed;
```

```    procedure Reset (Gen       : in Generator;
Initiator : in Integer);
procedure Reset (Gen       : in Generator);
```

```    -- Advanced facilities
```

```    type State is private;
```

```    procedure Save  (Gen        : in  Generator;
To_State   : out State);
procedure Reset (Gen        : in  Generator;
From_State : in  State);
```

```    Max_Image_Width : constant := implementation-defined integer value;
```

```    function Image (Of_State    : State)  return String;
function Value (Coded_State : String) return State;
```

```private
... -- not specified by the language
```

The generic library package Numerics.Discrete_Random has the following declaration:

```generic
type Result_Subtype is (<>);
```

```    -- Basic facilities
```

```    type Generator is limited private;
```

```    function Random (Gen : Generator) return Result_Subtype;
```

```    procedure Reset (Gen       : in Generator;
Initiator : in Integer);
procedure Reset (Gen       : in Generator);
```

```    -- Advanced facilities
```

```    type State is private;
```

```    procedure Save  (Gen        : in  Generator;
To_State   : out State);
procedure Reset (Gen        : in  Generator;
From_State : in  State);
```

```    Max_Image_Width : constant := implementation-defined integer value;
```

```    function Image (Of_State    : State)  return String;
function Value (Coded_State : String) return State;
```

```private
... -- not specified by the language
```

An object of the limited private type Generator is associated with a sequence of random numbers. Each generator has a hidden (internal) state, which the operations on generators use to determine the position in the associated sequence. All generators are implicitly initialized to an unspecified state that does not vary from one program execution to another; they may also be explicitly initialized, or reinitialized, to a time-dependent state, to a previously saved state, or to a state uniquely denoted by an integer value.

An object of the private type State can be used to hold the internal state of a generator. Such objects are only needed if the application is designed to save and restore generator states or to examine or manufacture them.

The operations on generators affect the state and therefore the future values of the associated sequence. The semantics of the operations on generators and states are defined below.

```function Random (Gen : Generator) return Uniformly_Distributed;
function Random (Gen : Generator) return Result_Subtype;
```

Obtains the next random number from the given generator, relative to its current state, according to an implementation-defined algorithm. The result of the function in Numerics.Float_Random is delivered as a value of the subtype Uniformly_Distributed, which is a subtype of the predefined type Float having a range of 0.0 .. 1.0. The result of the function in an instantiation of Numerics.Discrete_Random is delivered as a value of the generic formal subtype Result_Subtype.

```procedure Reset (Gen       : in Generator;
Initiator : in Integer);
procedure Reset (Gen       : in Generator);
```

Sets the state of the specified generator to one that is an unspecified function of the value of the parameter Initiator (or to a time-dependent state, if only a generator parameter is specified). The latter form of the procedure is known as the time-dependent Reset procedure.

```procedure Save  (Gen        : in  Generator;
To_State   : out State);
procedure Reset (Gen        : in  Generator;
From_State : in  State);
```

Save obtains the current state of a generator. Reset gives a generator the specified state. A generator that is reset to a state previously obtained by invoking Save is restored to the state it had when Save was invoked.

```function Image (Of_State    : State)  return String;
function Value (Coded_State : String) return State;
```

Image provides a representation of a state coded (in an implementation-defined way) as a string whose length is bounded by the value of Max_Image_Width. Value is the inverse of Image: Value(Image(S)) = S for each state S that can be obtained from a generator by invoking Save.

## Dynamic Semantics

Instantiation of Numerics.Discrete_Random with a subtype having a null range raises Constraint_Error.

This paragraph was deleted.

## Bounded (Run-Time) Errors

It is a bounded error to invoke Value with a string that is not the image of any generator state. If the error is detected, Constraint_Error or Program_Error is raised. Otherwise, a call to Reset with the resulting state will produce a generator such that calls to Random with this generator will produce a sequence of values of the appropriate subtype, but which might not be random in character. That is, the sequence of values might not fulfill the implementation requirements of this subclause.

## Implementation Requirements

A sufficiently long sequence of random numbers obtained by successive calls to Random is approximately uniformly distributed over the range of the result subtype.

The Random function in an instantiation of Numerics.Discrete_Random is guaranteed to yield each value in its result subtype in a finite number of calls, provided that the number of such values does not exceed 2 15.

Other performance requirements for the random number generator, which apply only in implementations conforming to the Numerics Annex, and then only in the strict mode defined there (see G.2), are given in G.2.5.

## Documentation Requirements

No one algorithm for random number generation is best for all applications. To enable the user to determine the suitability of the random number generators for the intended application, the implementation shall describe the algorithm used and shall give its period, if known exactly, or a lower bound on the period, if the exact period is unknown. Periods that are so long that the periodicity is unobservable in practice can be described in such terms, without giving a numerical bound.

The implementation also shall document the minimum time interval between calls to the time-dependent Reset procedure that are guaranteed to initiate different sequences, and it shall document the nature of the strings that Value will accept without raising Constraint_Error.