Ada Conformity Assessment Authority |
Home |
Conformity Assessment | Test Suite |
ARG | Ada Standard |

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

{*AI95-00434-01*}
{*AI12-0241-1*}
**with** Ada.Numerics.Generic_Complex_Types;

**generic**

**with** **package** Complex_Types **is**

**new** Ada.Numerics.Generic_Complex_Types (<>);

**use** Complex_Types;

**package** Ada.Numerics.Generic_Complex_Elementary_Functions **is**

**with**** pragma** Pure, Nonblocking **is**(Generic_Complex_Elementary_Functions);

{*8652/0020*}
{*AI95-00126-01*}
The library package Numerics.Complex_Elementary_Functions
is declared pure and defines the same subprograms as Numerics.Generic_Complex_Elementary_Functions,
except that the predefined type Float is systematically substituted for
Real'Base, and the Complex and Imaginary types exported by Numerics.Complex_Types
are systematically substituted for Complex and Imaginary, throughout.
Nongeneric equivalents of Numerics.Generic_Complex_Elementary_Functions
corresponding to each of the other predefined floating point types are
defined similarly, with the names Numerics.Short_Complex_Elementary_Functions,
Numerics.Long_Complex_Elementary_Functions, etc.

The overloading of the Exp function for the pure-imaginary
type is provided to give the user an alternate way to compose a complex
value from a given modulus and argument. In addition to Compose_From_Polar(Rho,
Theta) (see G.1.1), the programmer may write
Rho * Exp(i * Theta).

The imaginary (resp., real) component of the parameter
X of the forward hyperbolic (resp., trigonometric) functions and of the
Exp function (and the parameter X, itself, in the case of the overloading
of the Exp function for the pure-imaginary type) represents an angle
measured in radians, as does the imaginary (resp., real) component of
the result of the Log and inverse hyperbolic (resp., trigonometric) functions.

The functions have
their usual mathematical meanings. However, the arbitrariness inherent
in the placement of branch cuts, across which some of the complex elementary
functions exhibit discontinuities, is eliminated by the following conventions:

The imaginary component of the result of the Sqrt
and Log functions is discontinuous as the parameter X crosses the negative
real axis.

The result of the exponentiation operator when
the left operand is of complex type is discontinuous as that operand
crosses the negative real axis.

{*AI95-00185-01*}
The imaginary component of the result of the Arcsin, Arccos, and Arctanh
functions is discontinuous as the parameter X crosses the real axis to
the left of –1.0 or the right of 1.0.

{*AI95-00185-01*}
The real component of the result of the Arctan and Arcsinh functions
is discontinuous as the parameter X crosses the imaginary axis below
–*i* or above *i*.

{*AI95-00185-01*}
The real component of the result of the Arccot function is discontinuous
as the parameter X crosses the imaginary axis below –*i*
or above *i*.

The imaginary component of the Arccosh function
is discontinuous as the parameter X crosses the real axis to the left
of 1.0.

The imaginary component of the result of the Arccoth
function is discontinuous as the parameter X crosses the real axis between
–1.0 and 1.0.

A branch cut should not intersect the real
axis at a place where the corresponding real function is well-defined
(in other words, the complex function should be an extension of the corresponding
real function).

Because all the functions in question are
analytic, to ensure power series validity for the principal value, the
branch cuts should be invariant by complex conjugation.

For odd functions, to ensure that the principal
value remains an odd function, the branch cuts should be invariant by
reflection in the origin.

{*AI95-00185-01*}
The computed results of the mathematically multivalued functions are
rendered single-valued by the following conventions, which are meant
to imply that the principal branch is an analytic continuation of the
corresponding real-valued function in Numerics.Generic_Elementary_Functions.
(For Arctan and Arccot, the single-argument function in question is that
obtained from the two-argument version by fixing the second argument
to be its default value.)

The real component of the result of the Sqrt and
Arccosh functions is nonnegative.

The same convention applies to the imaginary component
of the result of the Log function as applies to the result of the natural-cycle
version of the Argument function of Numerics.Generic_Complex_Types (see
G.1.1).

The range of the real (resp., imaginary) component
of the result of the Arcsin and Arctan (resp., Arcsinh and Arctanh) functions
is approximately –π/2.0 to π/2.0.

The real (resp., imaginary) component of the result
of the Arccos and Arccot (resp., Arccoth) functions ranges from 0.0 to
approximately π.

The range of the imaginary component of the result
of the Arccosh function is approximately –π to π.

In addition, the exponentiation operator inherits
the single-valuedness of the Log function.

The exception Numerics.Argument_Error is raised by
the exponentiation operator, signaling a parameter value outside the
domain of the corresponding mathematical function, when the value of
the left operand is zero and the real component of the exponent (or the
exponent itself, when it is of real type) is zero.

The exception Constraint_Error
is raised, signaling a pole of the mathematical function (analogous to
dividing by zero), in the following cases, provided that Complex_Types.Real'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 real component of the exponent (or
the exponent itself, when it is of real type) is negative;

by the Arctan and Arccot functions, when the value
of the parameter X is ± *i*;

by the Arctanh and Arccoth functions, when the
value of the parameter X is ± 1.0.

[Constraint_Error can also be raised when a finite
result overflows (see G.2.6); this may occur
for parameter values sufficiently *near* poles, and, in the case
of some of the functions, for parameter values having components of sufficiently
large magnitude.] When Complex_Types.Real'Machine_Overflows
is False, the result at poles is unspecified.

In the implementation of Numerics.Generic_Complex_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
Complex_Types.Real.

In
the following cases, evaluation of a complex elementary function shall
yield the *prescribed result* (or a result having the prescribed
component), 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, Arctan, Sinh, Arcsinh, Tanh, and Arctanh functions
yield a result of zero; the Exp, Cos, and Cosh functions yield a result
of one; the Arccos and Arccot functions yield a real result; and the
Arccoth function yields an imaginary result.

When the parameter X has the value one, the Sqrt
function yields a result of one; the Log, Arccos, and Arccosh functions
yield a result of zero; and the Arcsin function yields a real result.

When the parameter X has the value –1.0,
the Sqrt function yields the result

{*AI95-00434-01*}
When the parameter X has the value –1.0, the Log function yields
an imaginary result; and the Arcsin and Arccos functions yield a real
result.

When the parameter X has the value ± *i*,
the Log function yields an imaginary result.

Exponentiation by a zero exponent yields the value
one. Exponentiation by a unit exponent yields the value of the left operand
(as a complex value). Exponentiation of the value one yields the value
one. Exponentiation of the value zero yields the value zero.

Other accuracy requirements for the complex elementary
functions, which apply only in the strict mode, are given in G.2.6.

The sign of a zero result or zero result component
yielded by a complex elementary function is implementation defined when
Complex_Types.Real'Signed_Zeros is True.

{*AI12-0444-1*}
The nongeneric equivalent packages can may,
but need not, be actual instantiations of the generic package
with the appropriate predefined nongeneric equivalent of Numerics.Generic_Complex_Types,
though that is not required; if they are, then the latter shall
have been obtained by actual instantiation of Numerics.Generic_Complex_Types.

The exponentiation operator may be implemented in
terms of the Exp and Log functions. Because this implementation yields
poor accuracy in some parts of the domain, no accuracy requirement is
imposed on complex exponentiation.

The implementation of the Exp
function of a complex parameter X is allowed to raise the exception Constraint_Error,
signaling overflow, when the real component of X exceeds an unspecified
threshold that is approximately log(Complex_Types.Real'Safe_Last).
This permission recognizes the impracticality of avoiding overflow in
the marginal case that the exponential of the real component of X exceeds
the safe range of Complex_Types.Real but both components of the final
result do not. Similarly, the Sin and Cos (resp., Sinh and Cosh) functions
are allowed to raise the exception Constraint_Error, signaling overflow,
when the absolute value of the imaginary (resp., real) component of the
parameter X exceeds an unspecified threshold that is approximately log(Complex_Types.Real'Safe_Last)
+ log(2.0). This permission recognizes the impracticality
of avoiding overflow in the marginal case that the hyperbolic sine or
cosine of the imaginary (resp., real) component of X exceeds the safe
range of Complex_Types.Real but both components of the final result do
not.

Implementations in which Complex_Types.Real'Signed_Zeros
is True should attempt to provide a rational treatment of the signs of
zero results and result components. For example, many of the complex
elementary functions have components that are odd functions of one of
the parameter components; in these cases, the result component should
have the sign of the parameter component at the origin. Other complex
elementary functions have zero components whose sign is opposite that
of a parameter component at the origin, or is always positive or always
negative.

The semantics
of Numerics.Generic_Complex_Elementary_Functions differs from Generic_Complex_Elementary_Functions
as defined in ISO/IEC CD 13814 (for Ada 83) in the following ways:

The generic package is a child unit of the
package defining the Argument_Error exception.

The proposed Generic_Complex_Elementary_Functions
standard (for Ada 83) specified names for the nongeneric equivalents,
if provided. Here, those nongeneric equivalents are required.

The generic package imports an instance of
Numerics.Generic_Complex_Types rather than a long list of individual
types and operations exported by such an instance.

The dependence of the imaginary component
of the Sqrt and Log functions on the sign of a zero parameter component
is tied to the value of Complex_Types.Real'Signed_Zeros.

Conformance to accuracy requirements is conditional.

{*8652/0020*}
{*AI95-00126-01*}
**Corrigendum:** Explicitly stated that the nongeneric equivalents
of Generic_Complex_Elementary_Functions are pure.

{*AI95-00185-01*}
Corrected various inconsistencies in the definition of the branch cuts.

Ada 2005 and 2012 Editions sponsored in part by **Ada-Europe**