@comment{ $Source: e:\\cvsroot/ARM/Source/pre_math.mss,v $ } @comment{ $Revision: 1.31 $ $Date: 2005/05/15 06:35:40 $ $Author: Randy $ } @Part(predefmath, Root="ada.mss") @Comment{$Date: 2005/05/15 06:35:40 $} @LabeledClause{The Numerics Packages} @begin{Intro} The library package Numerics is the parent of several child units that provide facilities for mathematical computation. One child, the generic package Generic_Elementary_Functions, is defined in @RefSecNum{Elementary Functions}, together with nongeneric equivalents; two others, the package Float_Random and the generic package Discrete_Random, are defined in @RefSecNum{Random Number Generation}. Additional (optional) children are defined in @RefSec{Numerics}. @end{Intro} @begin{StaticSem} @ChgRef{Version=[1], Kind=[Deleted]} @ChgDeleted[Version=[1],Text=<@ @;@comment{Empty paragraph to hang junk paragraph number from original RM}>] @begin{Example} @ChgRef{Version=[2],Kind=[Revised],ARef=[AI95-00388-01]} @key[package] Ada.Numerics @key[is]@ChildUnit{Parent=[Ada],Child=[Numerics]} @key[pragma] Pure(Numerics); @AdaDefn{Argument_Error} : @key[exception]; @AdaDefn{Pi} : @key[constant] := 3.14159_26535_89793_23846_26433_83279_50288_41971_69399_37511;@Chg{Version=[2],New=[ @pi : @key[constant] := Pi;],Old=[]} @AdaDefn{e} : @key[constant] := 2.71828_18284_59045_23536_02874_71352_66249_77572_47093_69996; @key[end] Ada.Numerics; @end{Example} The Argument_Error exception is raised by a subprogram in a child unit of Numerics to signal that one or more of the actual subprogram parameters are outside the domain of the corresponding mathematical function. @end{StaticSem} @begin{ImplPerm} The implementation may specify the values of Pi and e to a larger number of significant digits. @begin{Reason} 51 digits seem more than adequate for all present computers; converted to binary, the values given above are accurate to more than 160 bits. Nevertheless, the permission allows implementations to accommodate unforeseen hardware advances. @end{Reason} @end{ImplPerm} @begin{Extend83} @Defn{extensions to Ada 83} Numerics and its children were not predefined in Ada 83. @end{Extend83} @begin{Extend95} @ChgRef{Version=[2],Kind=[AddedNormal],ARef=[AI95-00388-01]} @ChgAdded{Version=[2],Text=[@Defn{extensions to Ada 95} The alternative declaration of @pi is new.]} @end{Extend95} @LabeledSubClause{Elementary Functions} @begin{Intro} Implementation-defined approximations to the mathematical functions known as the @lquotes@;elementary functions@rquotes@; are provided by the subprograms in Numerics.@!Generic_@!Elementary_@!Functions. Nongeneric equivalents of this generic package for each of the predefined floating point types are also provided as children of Numerics. @ImplDef{The accuracy actually achieved by the elementary functions.} @end{Intro} @begin{StaticSem} @Leading@;The generic library package Numerics.Generic_Elementary_Functions has the following declaration: @begin{Example} @key{generic} @key{type} Float_Type @key{is} @key{digits} <>; @ChildUnit{Parent=[Ada.Numerics],Child=[Generic_@!Elementary_@!Functions]} @key{package} Ada.Numerics.Generic_Elementary_Functions @key{is} @key[pragma] Pure(Generic_Elementary_Functions); @key{function} @AdaSubDefn{Sqrt} (X : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Log} (X : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Log} (X, Base : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Exp} (X : Float_Type'Base) @key{return} Float_Type'Base; @key{function} "**" (Left, Right : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Sin} (X : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Sin} (X, Cycle : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Cos} (X : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Cos} (X, Cycle : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Tan} (X : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Tan} (X, Cycle : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Cot} (X : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Cot} (X, Cycle : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Arcsin} (X : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Arcsin} (X, Cycle : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Arccos} (X : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Arccos} (X, Cycle : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Arctan} (Y : Float_Type'Base; X : Float_Type'Base := 1.0) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Arctan} (Y : Float_Type'Base; X : Float_Type'Base := 1.0; Cycle : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Arccot} (X : Float_Type'Base; Y : Float_Type'Base := 1.0) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Arccot} (X : Float_Type'Base; Y : Float_Type'Base := 1.0; Cycle : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Sinh} (X : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Cosh} (X : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Tanh} (X : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Coth} (X : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Arcsinh} (X : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Arccosh} (X : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Arctanh} (X : Float_Type'Base) @key{return} Float_Type'Base; @key{function} @AdaSubDefn{Arccoth} (X : Float_Type'Base) @key{return} Float_Type'Base; @key{end} Ada.Numerics.Generic_Elementary_Functions; @end{Example} @ChgRef{Version=[1],Kind=[Revised],Ref=[8652/0020],ARef=[AI95-00126-01]} @ChildUnit{Parent=[Ada.Numerics],Child=[Elementary_@!Functions]} The library package Numerics.Elementary_Functions @Chg{New=[is declared pure and ],Old=[]}defines the same subprograms as Numerics.@!Generic_@!Elementary_@!Functions, except that the predefined type Float is systematically substituted for Float_Type'Base throughout. Nongeneric equivalents of Numerics.@!Generic_@!Elementary_@!Functions for each of the other predefined floating point types are defined similarly, with the names Numerics.@!Short_@!Elementary_@!Functions, Numerics.@!Long_@!Elementary_@!Functions, etc. @begin{Reason} The nongeneric equivalents are provided to allow the programmer to construct simple mathematical applications without being required to understand and use generics. @end{Reason} The functions have their usual mathematical meanings. When the Base parameter is specified, the Log function computes the logarithm to the given base; otherwise, it computes the natural logarithm. When the Cycle parameter is specified, the parameter X of the forward trigonometric functions (Sin, Cos, Tan, and Cot) and the results of the inverse trigonometric functions (Arcsin, Arccos, Arctan, and Arccot) are measured in units such that a full cycle of revolution has the given value; otherwise, they are measured in radians. @Leading@;The computed results of the mathematically multivalued functions are rendered single-valued by the following conventions, which are meant to imply the principal branch: @begin{Itemize} The results of the Sqrt and Arccosh functions and that of the exponentiation operator are nonnegative. The result of the Arcsin function is in the quadrant containing the point (1.0, @i[x]), where @i[x] is the value of the parameter X. This quadrant is I or IV; thus, the range of the Arcsin function is approximately -@Pi/2.0 to @Pi/2.0 (-@R[Cycle]/4.0 to @R[Cycle]/4.0, if the parameter Cycle is specified). The result of the Arccos function is in the quadrant containing the point (@i{x}, 1.0), where @i[x] is the value of the parameter X. This quadrant is I or II; thus, the Arccos function ranges from 0.0 to approximately @Pi (@R[Cycle]/2.0, if the parameter Cycle is specified). The results of the Arctan and Arccot functions are in the quadrant containing the point (@i[x], @i[y]), where @i[x] and @i[y] are the values of the parameters X and Y, respectively. This may be any quadrant (I through IV) when the parameter X (resp., Y) of Arctan (resp., Arccot) is specified, but it is restricted to quadrants I and IV (resp., I and II) when that parameter is omitted. Thus, the range when that parameter is specified is approximately -@Pi to @Pi (-@R[Cycle]/2.0 to @R[Cycle]/2.0, if the parameter Cycle is specified); when omitted, the range of Arctan (resp., Arccot) is that of Arcsin (resp., Arccos), as given above. When the point (@i[x], @i[y]) lies on the negative x-axis, the result approximates @begin{Itemize} @Pi (resp., -@Pi) when the sign of the parameter Y is positive (resp., negative), if Float_Type'Signed_Zeros is True; @Pi, if Float_Type'Signed_Zeros is False. @end{Itemize} @end{Itemize} (In the case of the inverse trigonometric functions, in which a result lying on or near one of the axes may not be exactly representable, the approximation inherent in computing the result may place it in an adjacent quadrant, close to but on the wrong side of the axis.) @end{StaticSem} @begin{RunTime} @Leading@;The exception Numerics.Argument_Error is raised, signaling a parameter value outside the domain of the corresponding mathematical function, in the following cases: @begin{Itemize} by any forward or inverse trigonometric function with specified cycle, when the value of the parameter Cycle is zero or negative; by the Log function with specified base, when the value of the parameter Base is zero, one, or negative; by the Sqrt and Log functions, when the value of the parameter X is negative; by the exponentiation operator, when the value of the left operand is negative or when both operands have the value zero; by the Arcsin, Arccos, and Arctanh functions, when the absolute value of the parameter X exceeds one; by the Arctan and Arccot functions, when the parameters X and Y both have the value zero; by the Arccosh function, when the value of the parameter X is less than one; and by the Arccoth function, when the absolute value of the parameter X is less than one. @end{Itemize} @Leading@IndexCheck{Division_Check} @Defn2{Term=[Constraint_Error],Sec=(raised by failure of run-time check)} The exception Constraint_Error is raised, signaling a pole of the mathematical function (analogous to dividing by zero), in the following cases, provided that Float_Type'Machine_Overflows is True: @begin{Itemize} by the Log, Cot, and Coth functions, when the value of the parameter X is zero; by the exponentiation operator, when the value of the left operand is zero and the value of the exponent is negative; by the Tan function with specified cycle, when the value of the parameter X is an odd multiple of the quarter cycle; by the Cot function with specified cycle, when the value of the parameter X is zero or a multiple of the half cycle; and by the Arctanh and Arccoth functions, when the absolute value of the parameter X is one. @end{Itemize} @Defn2{Term=[Constraint_Error],Sec=(raised by failure of run-time check)} @redundant[Constraint_Error can also be raised when a finite result overflows (see @RefSecNum{Accuracy Requirements for the Elementary Functions}); this may occur for parameter values sufficiently @i{near} poles, and, in the case of some of the functions, for parameter values with sufficiently large magnitudes.]@PDefn{unspecified} When Float_Type'Machine_Overflows is False, the result at poles is unspecified. @begin{Reason} The purpose of raising Constraint_Error (rather than Numerics.Argument_Error) at the poles of a function, when Float_Type'Machine_Overflows is True, is to provide continuous behavior as the actual parameters of the function approach the pole and finally reach it. @end{Reason} @begin{Discussion} It is anticipated that an Ada binding to IEC 559:1989 will be developed in the future. As part of such a binding, the Machine_Overflows attribute of a conformant floating point type will be specified to yield False, which will permit both the predefined arithmetic operations and implementations of the elementary functions to deliver signed infinities (and set the overflow flag defined by the binding) instead of raising Constraint_Error in overflow situations, when traps are disabled. Similarly, it is appropriate for the elementary functions to deliver signed infinities (and set the zero-divide flag defined by the binding) instead of raising Constraint_Error at poles, when traps are disabled. Finally, such a binding should also specify the behavior of the elementary functions, when sensible, given parameters with infinite values. @end{Discussion} When one parameter of a function with multiple parameters represents a pole and another is outside the function's domain, the latter takes precedence (i.e., Numerics.Argument_Error is raised). @end{RunTime} @begin{ImplReq} In the implementation of Numerics.Generic_Elementary_Functions, the range of intermediate values allowed during the calculation of a final result shall not be affected by any range constraint of the subtype Float_Type. @begin{ImplNote} Implementations of Numerics.Generic_Elementary_Functions written in Ada should therefore avoid declaring local variables of subtype Float_Type; the subtype Float_Type'Base should be used instead. @end{ImplNote} @Leading@Defn2{Term=[prescribed result], Sec=[for the evaluation of an elementary function]} In the following cases, evaluation of an elementary function shall yield the @i{prescribed result}, provided that the preceding rules do not call for an exception to be raised: @begin{Itemize} When the parameter X has the value zero, the Sqrt, Sin, Arcsin, Tan, Sinh, Arcsinh, Tanh, and Arctanh functions yield a result of zero, and the Exp, Cos, and Cosh functions yield a result of one. When the parameter X has the value one, the Sqrt function yields a result of one, and the Log, Arccos, and Arccosh functions yield a result of zero. When the parameter Y has the value zero and the parameter X has a positive value, the Arctan and Arccot functions yield a result of zero. The results of the Sin, Cos, Tan, and Cot functions with specified cycle are exact when the mathematical result is zero; those of the first two are also exact when the mathematical result is @PorM 1.0. Exponentiation by a zero exponent yields the value one. Exponentiation by a unit exponent yields the value of the left operand. Exponentiation of the value one yields the value one. Exponentiation of the value zero yields the value zero. @end{Itemize} Other accuracy requirements for the elementary functions, which apply only in implementations conforming to the Numerics Annex, and then only in the @lquotes@;strict@rquotes@; mode defined there (see @RefSecNum{Numeric Performance Requirements}), are given in @RefSecNum{Accuracy Requirements for the Elementary Functions}. @Leading@;When Float_Type'Signed_Zeros is True, the sign of a zero result shall be as follows: @begin{itemize} A prescribed zero result delivered @i{at the origin} by one of the odd functions (Sin, Arcsin, Sinh, Arcsinh, Tan, Arctan or Arccot as a function of Y when X is fixed and positive, Tanh, and Arctanh) has the sign of the parameter X (Y, in the case of Arctan or Arccot). A prescribed zero result delivered by one of the odd functions @i{away from the origin}, or by some other elementary function, has an implementation-defined sign. @ImplDef{The sign of a zero result from some of the operators or functions in Numerics.Generic_Elementary_Functions, when Float_Type'Signed_Zeros is True.} @redundant[A zero result that is not a prescribed result (i.e., one that results from rounding or underflow) has the correct mathematical sign.] @begin{Reason} This is a consequence of the rules specified in IEC 559:1989 as they apply to underflow situations with traps disabled. @end{Reason} @end{itemize} @end{ImplReq} @begin{ImplPerm} The nongeneric equivalent packages may, but need not, be actual instantiations of the generic package for the appropriate predefined type. @end{ImplPerm} @begin{DiffWord83} @Leading@;The semantics of Numerics.Generic_Elementary_Functions differs from Generic_Elementary_Functions as defined in ISO/IEC DIS 11430 (for Ada 83) in the following ways: @begin{itemize} The generic package is a child unit of the package defining the Argument_Error exception. DIS 11430 specified names for the nongeneric equivalents, if provided. Here, those nongeneric equivalents are required. Implementations are not allowed to impose an optional restriction that the generic actual parameter associated with Float_Type be unconstrained. (In view of the ability to declare variables of subtype Float_Type'Base in implementations of Numerics.Generic_Elementary_Functions, this flexibility is no longer needed.) The sign of a prescribed zero result at the origin of the odd functions is specified, when Float_Type'Signed_Zeros is True. This conforms with recommendations of Kahan and other numerical analysts. The dependence of Arctan and Arccot on the sign of a parameter value of zero is tied to the value of Float_Type'Signed_Zeros. Sqrt is prescribed to yield a result of one when its parameter has the value one. This guarantee makes it easier to achieve certain prescribed results of the complex elementary functions (see @RefSec{Complex Elementary Functions}). Conformance to accuracy requirements is conditional. @end{itemize} @end{DiffWord83} @begin{DiffWord95} @ChgRef{Version=[2],Kind=[AddedNormal],Ref=[8652/0020],ARef=[AI95-00126-01]} @ChgAdded{Version=[2],Text=[@b Explicitly stated that the nongeneric equivalents of Generic_Elementary_Functions are pure.]} @end{DiffWord95} @LabeledSubClause{Random Number Generation} @begin{Intro} @redundant[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. @Defn{random number} For brevity, pseudo-random values of any of these types are called @i{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 @lquotes@;next@rquotes@; 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.] @begin{Discussion} These facilities support a variety of requirements ranging from repeatable sequences (for debugging) to unique sequences in each execution of a program. @end{Discussion} @end{Intro} @begin{StaticSem} @Leading@;The library package Numerics.Float_Random has the following declaration: @begin{Example} @key[package] Ada.Numerics.Float_Random @key[is]@ChildUnit{Parent=[Ada.Numerics],Child=[Float_@!Random]} -- @RI{Basic facilities} @key[type] @AdaTypeDefn{Generator} @key[is] @key[limited] @key[private]; @key[subtype] @AdaDefn{Uniformly_Distributed} @key[is] Float @key[range] 0.0 .. 1.0; @key[function] @AdaSubDefn{Random} (Gen : Generator) @key[return] Uniformly_Distributed; @key[procedure] @AdaSubDefn{Reset} (Gen : @key[in] Generator; Initiator : @key[in] Integer); @key[procedure] @AdaSubDefn{Reset} (Gen : @key[in] Generator); -- @RI{Advanced facilities} @key[type] @AdaTypeDefn{State} @key[is] @key[private]; @key[procedure] @AdaSubDefn{Save} (Gen : @key[in] Generator; To_State : @key[out] State); @key[procedure] @AdaSubDefn{Reset} (Gen : @key[in] Generator; From_State : @key[in] State); @AdaDefn{Max_Image_Width} : @key[constant] := @RI{implementation-defined integer value}; @key[function] @AdaSubDefn{Image} (Of_State : State) @key[return] String; @key[function] @AdaSubDefn{Value} (Coded_State : String) @key[return] State; @key[private] ... -- @RI{not specified by the language} @key[end] Ada.Numerics.Float_Random; @end{Example} @ChgRef{Version=[2],Kind=[Added],ARef=[AI95-00360-01]} @ChgAdded{Version=[2],Text=[The type Generator needs finalization (see @RefSecNum{User-Defined Assignment and Finalization}).]} The generic library package Numerics.Discrete_Random has the following declaration: @begin{Example} @ChildUnit{Parent=[Ada.Numerics],Child=[Discrete_@!Random]} @key[generic] @key[type] Result_Subtype @key[is] (<>); @key[package] Ada.Numerics.Discrete_Random @key[is] -- @RI{Basic facilities} @key[type] @AdaTypeDefn{Generator} @key[is] @key[limited] @key[private]; @key[function] @AdaSubDefn{Random} (Gen : Generator) @key[return] Result_Subtype; @key[procedure] @AdaSubDefn{Reset} (Gen : @key[in] Generator; Initiator : @key[in] Integer); @key[procedure] @AdaSubDefn{Reset} (Gen : @key[in] Generator); -- @RI{Advanced facilities} @key[type] @AdaTypeDefn{State} @key[is] @key[private]; @key[procedure] @AdaSubDefn{Save} (Gen : @key[in] Generator; To_State : @key[out] State); @key[procedure] @AdaSubDefn{Reset} (Gen : @key[in] Generator; From_State : @key[in] State); @AdaDefn{Max_Image_Width} : @key[constant] := @RI{implementation-defined integer value}; @key[function] @AdaSubDefn{Image} (Of_State : State) @key[return] String; @key[function] @AdaSubDefn{Value} (Coded_State : String) @key[return] State; @key[private] ... -- @RI{not specified by the language} @key[end] Ada.Numerics.Discrete_Random; @end{Example} @ImplDef{The value of Numerics.Float_Random.Max_Image_Width.} @ImplDef{The value of Numerics.Discrete_Random.Max_Image_Width.} @begin{ImplNote} @ChgRef{Version=[1],Kind=[Revised],Ref=[8652/0097],ARef=[AI95-00115-01]} @Leading@; The following is a possible implementation of the private part of @Chg{New=[Numerics.Float_Random], Old=[each package]} (assuming the presence of @lquotes@;@key[with] Ada.Finalization;@rquotes@; as a context clause): @begin{example} @key[type] State @key[is] ...; @key[type] Access_State @key[is] @key[access] State; @key[type] Generator @key[is] @key[new] Finalization.Limited_Controlled @key[with] @key[record] S : Access_State := @key[new] State'(...); @key[end] @key[record]; @key[procedure] Finalize (G : @key[in] @key[out] Generator); @end{Example} @ChgRef{Version=[1],Kind=[Added],Ref=[8652/0097],ARef=[AI95-00115-01]} @ChgRef{Version=[2],Kind=[RevisedAdded],ARef=[AI95-00344-01]} @ChgAdded{Version=[1],Text=[@Chg{Version=[2],New=[], Old=[Unfortunately, ]}Numerics.Discrete_Random.Generator @Chg{Version=[2],New=[also can],Old=[cannot]} be implemented this way@Chg{Version=[2],New=[],Old=[, as Numerics.Discrete_Random can be instantiated at any nesting depth. However, Generator could have a component of a controlled type, as long as that type is declared in some other (non-generic) package. One possible solution would be to implement Numerics.@!Discrete_@!Random in terms of Numerics.@!Float_@!Random, using a component of Numerics.@!Float_@!Random.Generator to implement Numerics.@!Float_@!Random.@!Generator]}.]} Clearly some level of indirection is required in the implementation of a Generator, since the parameter mode is @key(in) for all operations on a Generator. For this reason, Numerics.Float_Random and Numerics.Discrete_Random cannot be declared pure. @end{ImplNote} @ChgRef{Version=[2],Kind=[Added],ARef=[AI95-00360-01]} @ChgAdded{Version=[2],Text=[The type Generator needs finalization (see @RefSecNum{User-Defined Assignment and Finalization}) in every instantiation of Numerics.Discrete_Random.]} 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. @PDefn{unspecified} 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. @begin{Discussion} The repeatability provided by the implicit initialization may be exploited for testing or debugging purposes. @end{Discussion} 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. @Trailing@;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. @begin{DescribeCode} @begin{Example} @key[function] Random (Gen : Generator) @key[return] Uniformly_Distributed; @key[function] Random (Gen : Generator) @key[return] Result_Subtype; @end{Example} @Trailing@;Obtains the @lquotes@;next@rquotes@; 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. @ChgImplDef{Version=[2],Kind=[Deleted],Text=[@ChgDeleted{Version=[2],Text=[The algorithms for random number generation.]}]} @begin{Discussion} @ChgRef{Version=[2],Kind=[Added]} @ChgAdded{Version=[2],Text=[The algorithm is the subject of a documentation requirement, so we don't separately summarize this implementation-defined item.]}]} @end{Discussion} @begin{Reason} The requirement for a level of indirection in accessing the internal state of a generator arises from the desire to make Random a function, rather than a procedure. @end{Reason} @begin{Example} @key[procedure] Reset (Gen : @key[in] Generator; Initiator : @key[in] Integer); @key[procedure] Reset (Gen : @key[in] Generator); @end{Example} @Trailing@PDefn{unspecified} 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). @Defn2{Term=[Time-dependent Reset procedure],Sec=(of the random number generator)} The latter form of the procedure is known as the @i{time-dependent Reset procedure}. @begin{ImplNote} The time-dependent Reset procedure can be implemented by mapping the current time and date as determined by the system clock into a state, but other implementations are possible. For example, a white-noise generator or a radioactive source can be used to generate time-dependent states. @end{ImplNote} @begin{Example} @key[procedure] Save (Gen : @key[in] Generator; To_State : @key[out] State); @key[procedure] Reset (Gen : @key[in] Generator; From_State : @key[in] State); @end{Example} @Trailing@;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. @begin{Example} @key[function] Image (Of_State : State) @key[return] String; @key[function] Value (Coded_State : String) @key[return] State; @end{Example} 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. @ImplDef{The string representation of a random number generator's state.} @end{DescribeCode} @end{StaticSem} @begin{RunTime} @IndexCheck{Range_Check} @Defn2{Term=[Constraint_Error],Sec=(raised by failure of run-time check)} Instantiation of Numerics.Discrete_Random with a subtype having a null range raises Constraint_Error. @ChgRef{Version=[1],Kind=[Deleted],Ref=[8652/0050],ARef=[AI95-00089]} @ChgDeleted{Version=[1],Text=[@IndexCheck{Range_Check} @Defn2{Term=[Constraint_Error],Sec=(raised by failure of run-time check)} Invoking Value with a string that is not the image of any generator state raises Constraint_Error.]} @end{RunTime} @begin{Bounded} @ChgRef{Version=[1],Kind=[Added],Ref=[8652/0050],ARef=[AI95-00089]} @ChgAdded{Version=[1],Text=[It is a bounded error to invoke Value with a string that is not the image of any generator state. @Defn2{Term=[Program_Error],Sec=(raised by failure of run-time check)} @Defn2{Term=[Constraint_Error],Sec=(raised by failure of run-time check)} 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.]} @end{Bounded} @begin{ImplReq} 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 @lquotes@;strict@rquotes@; mode defined there (see @RefSecNum{Numeric Performance Requirements}), are given in @RefSecNum{Performance Requirements for Random Number Generation}. @end{ImplReq} @begin{DocReq} 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. @ChgDocReq{Version=[2],Kind=[AddedNormal],Text=[@ChgAdded{Version=[2],Text=[The algorithm used for random number generation, including a description of its period.]}]} 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. @ChgImplDef{Version=[2],Kind=[Deleted],Text=[@ChgDeleted{Version=[2],Text=[The minimum time interval between calls to the time-dependent Reset procedure that are guaranteed to initiate different random number sequences.]}]} @ChgDocReq{Version=[2],Kind=[AddedNormal],Text=[@ChgAdded{Version=[2],Text=[The minimum time interval between calls to the time-dependent Reset procedure that is guaranteed to initiate different random number sequences.]}]} @end{DocReq} @begin{ImplAdvice} Any storage associated with an object of type Generator should be reclaimed on exit from the scope of the object. @ChgImplAdvice{Version=[2],Kind=[Added],Text=[@ChgAdded{Version=[2],Text=[Any storage associated with an object of type Generator of the random number packages should be reclaimed on exit from the scope of the object.]}]} @begin{Ramification} A level of indirection is implicit in the semantics of the operations, given that they all take parameters of mode @key(in). This implies that the full type of Generator probably should be a controlled type, with appropriate finalization to reclaim any heap-allocated storage. @end{Ramification} If the generator period is sufficiently long in relation to the number of distinct initiator values, then each possible value of Initiator passed to Reset should initiate a sequence of random numbers that does not, in a practical sense, overlap the sequence initiated by any other value. If this is not possible, then the mapping between initiator values and generator states should be a rapidly varying function of the initiator value. @ChgImplAdvice{Version=[2],Kind=[AddedNormal],Text=[@ChgAdded{Version=[2],Text=[Each value of Initiator passed to Reset for the random number packages should initiate a distinct sequence of random numbers, or, if that is not possible, be at least a rapidly varying function of the initiator value.]}]} @end{ImplAdvice} @begin{Notes} If two or more tasks are to share the same generator, then the tasks have to synchronize their access to the generator as for any shared variable (see @RefSecNum(Shared Variables)). Within a given implementation, a repeatable random number sequence can be obtained by relying on the implicit initialization of generators or by explicitly initializing a generator with a repeatable initiator value. Different sequences of random numbers can be obtained from a given generator in different program executions by explicitly initializing the generator to a time-dependent state. A given implementation of the Random function in Numerics.Float_Random may or may not be capable of delivering the values 0.0 or 1.0. Portable applications should assume that these values, or values sufficiently close to them to behave indistinguishably from them, can occur. If a sequence of random integers from some fixed range is needed, the application should use the Random function in an appropriate instantiation of Numerics.Discrete_Random, rather than transforming the result of the Random function in Numerics.Float_Random. However, some applications with unusual requirements, such as for a sequence of random integers each drawn from a different range, will find it more convenient to transform the result of the floating point Random function. For @R[M] @geq 1, the expression @begin{Example} Integer(Float(M) * Random(G)) mod M @end{Example} @NoPrefix@;transforms the result of Random(G) to an integer uniformly distributed over the range 0 .. @R[M]-1; it is valid even if Random delivers 0.0 or 1.0. Each value of the result range is possible, provided that M is not too large. Exponentially distributed (floating point) random numbers with mean and standard deviation 1.0 can be obtained by the transformation @begin{Example} -Log(Random(G) + Float'Model_Small)) @end{Example} @NoPrefix@;where Log comes from Numerics.Elementary_Functions (see @RefSecNum{Elementary Functions}); in this expression, the addition of Float'Model_Small avoids the exception that would be raised were Log to be given the value zero, without affecting the result (in most implementations) when Random returns a nonzero value. @end{Notes} @begin{Examples} @Leading@Keepnext@i{Example of a program that plays a simulated dice game:} @begin{Example}@Trailing @key[with] Ada.Numerics.Discrete_Random; @key[procedure] Dice_Game @key[is]@Softpage @key[subtype] Die @key[is] Integer @key[range] 1 .. 6; @key[subtype] Dice @key[is] Integer @key[range] 2*Die'First .. 2*Die'Last; @key[package] Random_Die @key[is] @key[new] Ada.Numerics.Discrete_Random (Die); @key[use] Random_Die; G : Generator; D : Dice;@Softpage @key[begin]@Softpage Reset (G); -- @RI{Start the generator in a unique state in each run} @key[loop] -- @RI{Roll a pair of dice; sum and process the results} D := Random(G) + Random(G); ... @key[end] @key[loop];@Softpage @key[end] Dice_Game; @end{Example} @Leading@Keepnext@i{Example of a program that simulates coin tosses:} @begin{Example}@Trailing @key[with] Ada.Numerics.Discrete_Random; @key[procedure] Flip_A_Coin @key[is]@Softpage @key[type] Coin @key[is] (Heads, Tails); @key[package] Random_Coin @key[is] @key[new] Ada.Numerics.Discrete_Random (Coin); @key[use] Random_Coin; G : Generator;@Softpage @key[begin]@Softpage Reset (G); -- @RI{Start the generator in a unique state in each run} @key[loop] -- @RI{Toss a coin and process the result} @key[case] Random(G) @key[is] @key[when] Heads => ... @key[when] Tails => ... @key[end] @key[case]; ... @key[end] @key[loop];@Softpage @key[end] Flip_A_Coin; @end{Example} @Leading@Keepnext@i{Example of a parallel simulation of a physical system, with a separate generator of event probabilities in each task:} @begin{Example} @key[with] Ada.Numerics.Float_Random; @key[procedure] Parallel_Simulation @key[is]@Softpage @key[use] Ada.Numerics.Float_Random; @key[task] @key[type] Worker @key[is] @key[entry] Initialize_Generator (Initiator : @key[in] Integer); ... @key[end] Worker; W : @key[array] (1 .. 10) @key[of] Worker;@Softpage @key[task] @key[body] Worker @key[is] G : Generator; Probability_Of_Event : Uniformly_Distributed; @key[begin]@Softpage @key[accept] Initialize_Generator (Initiator : @key[in] Integer) @key[do] Reset (G, Initiator); @key[end] Initialize_Generator; @key[loop] ... Probability_Of_Event := Random(G); ... @key[end] @key[loop]; @key[end] Worker;@Softpage @key[begin]@Softpage -- @RI{Initialize the generators in the Worker tasks to different states} @key[for] I @key[in] W'Range @key[loop] W(I).Initialize_Generator (I); @key[end] @key[loop]; ... -- @RI{Wait for the Worker tasks to terminate}@Softpage @key[end] Parallel_Simulation; @end{Example} @end{Examples} @begin{Notes} @i{Notes on the last example:} Although each Worker task initializes its generator to a different state, those states will be the same in every execution of the program. The generator states can be initialized uniquely in each program execution by instantiating Ada.Numerics.Discrete_Random for the type Integer in the main procedure, resetting the generator obtained from that instance to a time-dependent state, and then using random integers obtained from that generator to initialize the generators in each Worker task. @end{Notes} @begin{Incompatible95} @ChgRef{Version=[2],Kind=[AddedNormal],ARef=[AI95-00360-01]} @ChgAdded{Version=[2],Text=[@Defn{incompatibilities with Ada 95} Type Generator in Numerics.Float_Random and in an instance of Numerics.Discrete_Random is defined to need finalization. If the restriction No_Nested_Finalization (see @RefSecNum{Tasking Restrictions}) applies to the partition, and Generator does not have a controlled part, it will not be allowed in local objects in Ada 2006 whereas it would be allowed in Ada 95. Such code is not portable, as another Ada compiler may have a controlled part in Generator, and thus would be illegal.]} @end{Incompatible95} @begin{DiffWord95} @ChgRef{Version=[2],Kind=[AddedNormal],Ref=[8652/0050],ARef=[AI95-00089-01]} @ChgAdded{Version=[2],Text=[@b Made the passing of an incorrect Image of a generator a bounded error, as it may not be practical to check for problems (if a generator consists of several related values).]} @end{DiffWord95}