A.5.1 Elementary Functions
Implementation-defined approximations to the mathematical
functions known as the “elementary functions” 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.
Implementation defined: The accuracy
actually achieved by the elementary functions.
Static Semantics
The generic library
package Numerics.Generic_Elementary_Functions has the following declaration:
generic
type Float_Type
is digits <>;
package Ada.Numerics.Generic_Elementary_Functions
is
pragma Pure(Generic_Elementary_Functions);
function Sqrt (X : Float_Type'Base)
return Float_Type'Base;
function Log (X : Float_Type'Base)
return Float_Type'Base;
function Log (X, Base : Float_Type'Base)
return Float_Type'Base;
function Exp (X : Float_Type'Base)
return Float_Type'Base;
function "**" (Left, Right : Float_Type'Base)
return Float_Type'Base;
function Sin (X : Float_Type'Base)
return Float_Type'Base;
function Sin (X, Cycle : Float_Type'Base)
return Float_Type'Base;
function Cos (X : Float_Type'Base)
return Float_Type'Base;
function Cos (X, Cycle : Float_Type'Base)
return Float_Type'Base;
function Tan (X : Float_Type'Base)
return Float_Type'Base;
function Tan (X, Cycle : Float_Type'Base)
return Float_Type'Base;
function Cot (X : Float_Type'Base)
return Float_Type'Base;
function Cot (X, Cycle : Float_Type'Base)
return Float_Type'Base;
function Arcsin (X : Float_Type'Base)
return Float_Type'Base;
function Arcsin (X, Cycle : Float_Type'Base)
return Float_Type'Base;
function Arccos (X : Float_Type'Base)
return Float_Type'Base;
function Arccos (X, Cycle : Float_Type'Base)
return Float_Type'Base;
function Arctan (Y : Float_Type'Base;
X : Float_Type'Base := 1.0)
return Float_Type'Base;
function Arctan (Y : Float_Type'Base;
X : Float_Type'Base := 1.0;
Cycle : Float_Type'Base)
return Float_Type'Base;
function Arccot (X : Float_Type'Base;
Y : Float_Type'Base := 1.0)
return Float_Type'Base;
function Arccot (X : Float_Type'Base;
Y : Float_Type'Base := 1.0;
Cycle : Float_Type'Base)
return Float_Type'Base;
function Sinh (X : Float_Type'Base)
return Float_Type'Base;
function Cosh (X : Float_Type'Base)
return Float_Type'Base;
function Tanh (X : Float_Type'Base)
return Float_Type'Base;
function Coth (X : Float_Type'Base)
return Float_Type'Base;
function Arcsinh (X : Float_Type'Base)
return Float_Type'Base;
function Arccosh (X : Float_Type'Base)
return Float_Type'Base;
function Arctanh (X : Float_Type'Base)
return Float_Type'Base;
function Arccoth (X : Float_Type'Base)
return Float_Type'Base;
end Ada.Numerics.Generic_Elementary_Functions;
{
8652/0020}
{
AI95-00126-01}
The library package Numerics.Elementary_Functions
is declared pure and 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.
Reason: The nongeneric equivalents are
provided to allow the programmer to construct simple mathematical applications
without being required to understand and use generics.
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.
The computed results
of the mathematically multivalued functions are rendered single-valued
by the following conventions, which are meant to imply the principal
branch:
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, x), where x is the value of
the parameter X. This quadrant is I or IV; thus, the range of the Arcsin
function is approximately –π/2.0 to π/2.0 (–Cycle/4.0
to Cycle/4.0, if the parameter Cycle is specified).
The result of the Arccos function is in the quadrant
containing the point (x, 1.0), where x is the value of
the parameter X. This quadrant is I or II; thus, the Arccos function
ranges from 0.0 to approximately π (Cycle/2.0,
if the parameter Cycle is specified).
The results of the Arctan and Arccot functions
are in the quadrant containing the point (x, y), where
x and 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 –π to
π (–Cycle/2.0 to 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 (x, y) lies on the negative x-axis, the result
approximates
π (resp., –π) when the sign
of the parameter Y is positive (resp., negative), if Float_Type'Signed_Zeros
is True;
π, if Float_Type'Signed_Zeros is False.
(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.)
Dynamic Semantics
The exception Numerics.Argument_Error
is raised, signaling a parameter value outside the domain of the corresponding
mathematical function, in the following cases:
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.
{Division_Check
[partial]} {check,
language-defined (Division_Check)} {Constraint_Error
(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:
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.
{Constraint_Error
(raised by failure of run-time check)} [Constraint_Error
can also be raised when a finite result overflows (see
G.2.4);
this may occur for parameter values sufficiently
near poles, and,
in the case of some of the functions, for parameter values with sufficiently
large magnitudes.]
{unspecified [partial]}
When Float_Type'Machine_Overflows is False, the
result at poles is unspecified.
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.
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.
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).
Implementation Requirements
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.
Implementation Note: 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.
{prescribed
result (for the evaluation of an elementary function)} In
the following cases, evaluation of an elementary function shall yield
the
prescribed result, provided that the preceding rules do not
call for an exception to be raised:
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
± 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.
Other accuracy requirements for the elementary functions,
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.4.
When Float_Type'Signed_Zeros
is True, the sign of a zero result shall be as follows:
A prescribed zero result delivered 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 away from the origin, or by some other elementary
function, has an implementation-defined sign.
Implementation defined: 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.
[A zero result that is not a prescribed result
(i.e., one that results from rounding or underflow) has the correct mathematical
sign.]
Reason: This is a consequence of the
rules specified in IEC 559:1989 as they apply to underflow situations
with traps disabled.
Implementation Permissions
The nongeneric equivalent packages may, but need
not, be actual instantiations of the generic package for the appropriate
predefined type.
Wording Changes from Ada 83
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:
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
G.1.2, “
Complex
Elementary Functions”).
Conformance to accuracy requirements is conditional.
Wording Changes from Ada 95
{
8652/0020}
{
AI95-00126-01}
Corrigendum: Explicitly stated that the nongeneric equivalents
of Generic_Elementary_Functions are pure.
Sponsored by Ada-Europe