Information technology — Programming languages — Generic package of complex elementary functions for Ada
Technologies de l'information — Langages de programmation — Paquetage générique de fonctions élémentaires complexes pour Ada
Standards Content (sample)
Information technology - Programming
languages - Generic package of complex
elementary functions for Ada
- Langages de programmation -
Technologies de /‘information
Paquetage g&Grique de fonctions Mmentaires complexes pour Ada
---------------------- Page: 1 ----------------------
1 Scope.. ..........................................
2 Normative references ................................. 1
3 Subprograms provided. ............................... 1
Instantiations ...................................... 2
5 Implementations .................................... 3
6 Exceptions ........................................
7 Arguments outside the range of safe numbers. 5
8 Method of specification of functions. ..................... 5
9 Branch cut and domain definitions ...................... 5
10 Range definitions ................................... 5
11 Accuracy requirements ............................... 6
12 Overflow .......................................... 7
Underflow ......................................... 8
Specifications of the functions .......................... 9
14.1 SQRT - Square root. ........................... 9
14.2 LOG - Natural logarithm ........................ 10
14.3 EXP - Exponential function, complex argument ....... 10
14.4 EXP - ..... 11
Exponential function, imaginary argument.
@ ISO/IEC 1998
All rights reserved. Unless otherwise specified, no part of this publication may be
reproduced or utilized in any form or by any means, electronic or mechanical, includingphotocopying and microfilm, without permission in writing from the publisher.
ISO/IEC Copyright Office l Case postale 56 l CH-1211 Geneve 20 l Switzerland
Printed in Switzerland
---------------------- Page: 2 ----------------------
14.5 - Exponentiation operator, complex to complex
14.6 Exponentiation operator, complex to real power
14.7 Exponentiation operator, real to complex power
14.8 SIN - Trigonometric sine function
14.9 cos - Trigonometric cosine function
14.10 TAN - Trigonometric tangent function
14.11 COT - Trigonometric cotangent function
Inverse trigonometric sine function
14.13 ARCCOS- Inverse trigonometric cosine function
14.14 ARCTAN - Inverse trigonometric tangent function
14.15 ARCCOT- Inverse trigonometric cotangent function
14.16 SINH - Hyperbolic sine function
14.17 COSH - Hyperbolic cosine function
14.18 TANH- Hyperbolic tangent function
Hyperbolic cotangent function .............. 23
14.20 ARCSINH - Inverse hyperbolic sine function
Inverse hyperbolic cosine function ........ 24
14.22 ARCTANH - Inverse hyperbolic tangent function
14.23 ARCCOTH- Inverse hyperbolic cotangent function
A Ada specification for GENERIC-COMPLEX-ELEMENTARY-FUNCTIONS
B Rationale .........................................
B.1 Introduction and motivation.
B.3 Packaging considerations
B.4 Choice of functions
B.5 Handling of exceptions
B.6 Matters of style
B.7 Method of expressing accuracy requirements
B.l Result rectangle for a subprogram satisfying a maximum relative
component error requirement . . . . . . . . . . . . . . . . . . . . . . . . . . .B.2 Result rectangle for a subprogram satisfying a maximum relative
box error requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .B.3 Result circle for a subprogram satisfying a maximum relative vec-
tor error requirement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. . .
---------------------- Page: 3 ----------------------
IS0 (the International Organization for Standardization) and IEC (the In-
ternational Electrotechnical Commission) form the specialized system for
worldwide standardization. National bodies that are members of IS0 or IEC
participate in the development of International Standards through technical
committees established by the respective organization to deal with particular
fields of technical activity. IS0 and IEC technical committees collaborate
in fields of mutual interest. Other international organizations, governmental
and non-governmental, in liaison with IS0 and IEC, also take part in the
In the field of information technology, IS0 and IEC have established a
joint technical committee, ISO/IEC JTC 1. Draft International Standards
adopted by the joint technical committee are circulated to national bodies
for voting. Publication as an International Standard requires approval by at
least 75% of the national bodies casting a vote.
International Standard ISO/IEC 13814 was prepared by Joint Technical
Committee ISO/IEC JTC 1, Inf ormation technology, Subcommittee 22, Pro-
gramming languages, their environments and system software interfaces.
Annex A forms an integral part of this International Standard. Annexes B
and C are for information only.
---------------------- Page: 4 ----------------------
@ ISO/IEC ISO/IEC 13814:1998(E)
The generic package described here is intended to provide the basic complex
mathematical routines from which portable, reusable applications can be
built. This International Standard serves a broad class of applications with
reasonable ease of use, while demanding implementations that are of high
quality, capable of validation, and also practical given the state of the art.
The specification included in this International Standard is presented as a
compilable Ada specification in Annex A, with explanatory text in numbered
clauses in the main body of text. The explanatory text is normative, with
the exception of the following items:
notes (under the heading Notes associated with some of the functions);
- notes (labeled as such) presented at the end of any numbered clause.
The word “may” as used in this International Standard consistently means
“is allowed to” (or “are allowed to ”). It is used only to express permission,
as in the commonly occurring phrase “an implementation may ”; other words
(such as “can ,” “could” or “might ”) are used to express ability, possibility,
capacity or consequentiality.
---------------------- Page: 5 ----------------------
INTERNATIONAL STANDARD 0 ISO/IEC
Informat ion technology -
Programming languages -
Generic package of complex elementary functions for Ada
This International Standard defines the specification of a generic package of complex elementary functions called
GENERIC-COMPLEX-ELEMENTARY-FUNCTIONS. It does not provide the body of the package.
This International Standard specifies certain basic complex mathematical routines from which portable, reusable
applications can be built. This International St)andard serves a broad class of applications with reasonable ease of use,
while demanding implementations that are of high quality, capable of validation, and also practical given the state ofthe art.
This International Standard is applicable to programming environments conforming to ISO/IEC 8652:1987 and isrelevant to the revised standard ISO/IEC 8652:1995.
2 Normative references
The following standards contain provisions which, through reference in this text, constitute provisions of this Interna-
tional Standard. At the time of publication, the editions indicated were valid. All standards are subject to revision,
and parties to agreements based on this International Standard are encouraged to investigate the possibility of applying
the most recent editions of the standards indicated below. Members of IEC and IS0 maintain registers of currentlyvalid International Standards.
ISO/IEC 8652, Information technology - Programming languages - Ada.
ISO/IEC 11430, Information technology - Programming languages - Generic package of elementary functions forAda.
ISO/IEC 11729, Information technology - Programming languages - Generic package of primitive functions for Ada.Generic packages of real and complex type
ISO/IEC 13813, Information technology - Programming languages -
declarations and basic operations for Ada (including vector and matrix types).
3 Subprograms provided
The following twenty mathematical functions are provided:
SQRT LOG EXP
SIN cos TAN COT
ARCSIN ARCCOS ARCTAN ARCCOT
SINH COSH TANH COTH
ARCSINH ARCCOSH ARCTANH ARCCOTH
These are the square root (SQRT), logarithm (LOG) and exponential (EXP) function and the exponentiation operator
(**); the trigonometric functions for sine (SIN), cosine (COS), tangent (TAN) and cotangent (COT) and their inverses---------------------- Page: 6 ----------------------
and the hyperbolic functions for sine (SINH), cosine (COSH), tangent (TANH),
(ARCSIN, ARCCOS, ARCTAN and ARCCOT);
and cotangent (COT@ together with their inverses (ARCSINH, ARCCOSH, ARCTANH, and ARCCOTH). These are the same
functions by the same names that are in the package GENERIC-ELEMENTARY-FUNCTIONS definied in ISO/IEC 11430.
Several variations are provided for the exponentiation operator and the exponential function. All functions have one or
more formal parameters oftype COMPLEX or IMAGINARY and return a value oftype COMPLEX. COMPLEX and IMAGINARY
are generic formal parameters of the generic package GENERIC-COMPLEX-ELEMENTARY-FUNCTIONS.4 Instantiations
This International Standard describes a generic package, GENERIC-COMPLEX-ELEMENTARY-FUNCTIONS, which the user
must instantiate to obtain a computational capability. The generic package has three required generic formal parame-
ters and many generic formal subprograms with defaults. At instantiation, the user must specify, as the generic actualparameters to be associated with REAL, COMPLEX and IMAGINARY respectively,
a floating-point type,
b) a private composite type containing real and imaginary components of the type specified by a), (Within this
International Standard, the real and imaginary components of the composite type are referred to simply as compo-nents.)
a private type of the same base type as a) that is interpreted as the pure imaginary form of b).
Types suitable for b) and c) are exported by the package obtained by instantiating, with the type specified by a) as
its generic actual parameter, the generic package GENERIC-COMPLEX-TYPES defined in ISO/IEC 13813. (Instantiation
of the package GENERIC-COMPLEX-TYPES is not a prerequisite for using GENERIC-COMPLEX-ELEMENTARY-FUNCTIONS;
it is merely an option that the user might find convenient to pursue.) In addition the user may specify the many
subprogram generic formal parameters as generic actual parameters, or for convenience, all these subprograms areexported by the instantiation of GENERIC-COMPLEX-TYPES described above.
Depending on the implementation, the user may or may not be allowed to specify a generic actual type having a range
constraint for the first generic actual parameter (see clause 5). The generic actual parameters for the subprograms
can be omitted if functions having names and profiles matching those of the corresponding generic formal parameters
are visible at the place of the instantiation. An instantiation of GENERIC-COMPLEX-TYPES, as described above, canoptionally be used to obtain subprograms that satisfy these requirements.
In addition to the body of the generic package itself, implementers may provide (non-generic) library packages that can
be used just like instantiations of the generic package in which the first generic actual parameter is a predefined floating-
point type and the remainder are related to the first in appropriate ways. In particular, the name of a package serving
as a replacement for an instantiation of GENERIC-COMPLEX-ELEMENTARY-FUNCTIONS for the predefined type FLOAT
shall be COMPLEX-ELEMENTARY-FUNCTIONS with REAL replaced by FLOAT in the profiles of the functions that it exports.
Similarly, the names of packages serving as replacements for instantiations of GENERIC-COMPLEX-ELEMENTARY-FUNC-TIONS for the predefined types LONG-FLOAT, SHORT-FLOAT, etc.,
shall be LONG-COMPLEX-ELEMENTARY-FUNCTIONS,
SHORT_COMPLEX,ELEMENTARY_FUNCTIONS, etc., respectively and REAL shall be systematically replaced in the profiles
of the functions that they export by LONG-FLOAT, SHORT-FLOAT, etc. Implementers are responsible for ensuring that
a composite type called COMPLEX containing a pair of components of types FLOAT, LONG-FLOAT, SHORT-FLOAT, etc.,
respectively, are available. For example, each of the non-generic library packages could be prefixed by an appropriatecontext clause, such as:
package COMPLEX-ELEMENTARY-FUNCTIONS is . . .
The packages COMPLEX-TYPES, LONG-COMPLEX-TYPES, etc., described in ISO/IEC 13813, are not a prerequisite for
implementation, yet are an option the implementer might find convenient to pursue.---------------------- Page: 7 ----------------------
Portable implementations of GENERIC-COMPLEX-ELEMENTARY-FUNCTIONS are strongly encouraged. However, implemen-
tations are not required to be portable. In particular, an implementation of this International Standard in Ada may usemachine-code insertions or other machine-dependent
pragma INTERFACE or other pragmas, unchecked conversion,
techniques as desired. On the other hand, to the extent that generic packages (e.g. GENERIC-ELEMENTARY-FUNCTIONS
defined in ISO/IEC 11430 and GENERIC-PRIMITIVE-FUNCTIONS defined in ISO/TEC 11729) become widely ‘available,
portable implementations of GENERIC-COMPLEX-ELEMENTARY-FUNCTIONS should not be particularly difficult to con-
struct In particular, it is possible to achieve the accuracy required by this International Standard, when specified, byappropriate use ofthe package GENERIC-ELEMENTARY-FUNCTIONS.
An implementation is allowed to limit the precision it supports (by stating an assumed maximum value for
SYSTEM. MAX-DIGITS), since portable implementations would not, in general, be possible otherwise. An implemen-
tation is also allowed to make other reasonable assumptions about the environment in which it is to be used, but
only when necessary in order to match algorithms to hardware characteristics in an economical manner. All suchBy convention, an implementation of GENERIC-COMPLEX-ELE-
limits and assumptions shall be clearly documented.
MENTARY-FUNCTIONS is said not to conform to this International Standard in any environment in which its limits or
assumptions are not satisfied, and this International Standard does not define its behavior in that environment. Ineffect, this convention delimits the portability of implementations.
An implementation is allowed to impose a restriction that the generic actual parameter associated with REAL shall
not have a range constraint that reduces the range of allowable values. If it does impose this restriction, then the
restriction shall be documented, and the effects of violating the restriction shall be one of the following:
a) Compilation of a unit containing an instantiation of GENERIC-COMPLEX-ELEMENTARY-FUNCTIONS is rejected.
b) CONSTRAINT-ERROR or PROGRAM-ERROR is raised during the elaboration of an instantiation of GENERIC-COM-PLEX-ELEMENTARY-FUNCTIONS.
Conversely, if an implementation does not impose the restriction, then it must not allow such a range constraint,
when included with the user ’s actual type, to interfere with the internal computations of the functions; that is, if the
components of the argument and the result are within the range of the type, then the implementation shall return theresult and shall not raise an exception (such as CONSTRAINT-ERROR).
Any of the restrictions discussed above may in fact be inherited from implementations of the packages GENERIC-EL-
EMENTARY-FUNCTIONS defined in ISO/IEC 11430, GENERIC~PRIMITIVEJ'UNCTIONS defined in ISO/IEC 11729 and
GENERIC-COMPLEX-TYPES defined in ISO/IEC 13813, if used. The dependence of an implementation on such inheritedrestrictions should be documented.
An implementation shall function properly in a tasking environment. Apart from the obvious restriction that an
implementation of GENERIC-COMPLEX-ELEMENTARY-FUNCTIONS shall avoid declaring variables that are global to theNothing in this International Standard requires the
functions, no special constraints are imposed on implementations.
use of such global variables.
Some hardware and their accompanying Ada implementations have the capability of representing and discriminatingof preserving the sign of an infinitesimal quantity
between positively and negatively signed zeros as a means, e.g.,
that has underflowed to zero. This International Standard allows implementations of GENERIC-COMPLEX-ELEMENTA-
RY-FUNCTIONS to exploit that capability, when available, so as to exhibit continuity in the results of some functionsAt the same time, it accommodates implementations in which that capability is
as certain limits are approached.
unavailable. Because a definition of what comprises the capability of representing and distinguishing signed zeros is
beyond the scope of this International Standard, implementations are allowed the freedom not to exploit the capability,
even when available. An implementation shall exercise its choice consistently, either exploiting signed-zero behavior
everywhere or nowhere in this package. The signs of zero results prescribed by this International Standard apply only
to implementations that exploit signed zeros; an implementation that does not exploit signed zeros may give any sign
to a zero result. In addition an implementation shall document its behavior with respect to signed zeros. In this
International Standard, unless otherwise qualified, zero means any of (410.0, 310.0) and one means either of (I. 0,*o.o).
---------------------- Page: 8 ----------------------
The ARGUMENT-ERROR exception is raised by a function in the generic package when an argument of the function violates
one or more of the conditions given in the function ’s domain definition (see clause 9). Note that these conditions are
related only to the mathematical definition of the function and are therefore implementation independent.
The ARGUMENT-ERRORexception is declared as a renaming of the exception of the same name declared in the package EL-
EMENTARY FUNCTIONS EXCEPTIONS defined in ISO/IEC 11430. This exception distinguishes neither between different
kinds of argument errors, nor between different functions, nor between different instantiations of GENERIC-COMPLEX-EL-
EMENTARY-FUNCTIONS, nor between instantiations of GENERIC-COMPLEX-ELEMENTARY-FUNCTIONS and those of GENER-IC-ELEMENTARY-FUNCTIONS.
Besides ARGUMENT-ERROR, the only exceptions allowed during a call to a function in GENERIC-COMPLEX-ELEMENTA-RY-FUNCTIONS are predefined exceptions, as follows:
a) Virtually any predefined exception is possible during the evaluation of an argument of a function in GENER-
IC-COMPLEX-ELEMENTARY-FUNCTIONS. For example, NUMERIC-ERROR, CONSTRAINT-ERROR or even PROGRAM-ERROR
could be raised if an argument has an undefined value; and CONSTRAINT-ERROR will be raised when the value of an
argument (or component of an argument) lies outside the range of the user ’s generic actual type REAL. Additionally
STORAGE-ERROR could be raised, e.g. if insufficient storage is available to perform the call. All these exceptions are
raised before the body of the function is entered and therefore have no bearing on implementations of GENERIC-COM-PLEX-ELEMENTARY-FUNCTIONS.
b) Also, CONSTRAINT-ERROR will be raised when a function in GENERIC-COMPLEX-ELEMENTARY-FUNCTIONS attempts
to construct a complex return value with a component outside the range of the user ’s generic actual type associated
with REAL. The exception raised for this reason shall be propagated to the caller of the function.
c) Whenever the arguments of a function are such that a component of a result permitted by the accuracy require-
ments would exceed REAL’ SAFE-LARGE in absolute value, as formalized below in clause 12, an implementation may
raise, and shall then propagate to the caller, the exception specified by Ada for signaling overflow.
d) Whenever the arguments of a function are such that the corresponding mathematical function is infinite (i.e.,
has an infinite component), an implementation shall raise and propagate to the caller the exception specified byAda for signaling division by zero.
Once execution of a function has begun, an implementation may propagate STORAGE-ERROR to the caller of the
function, but only to signal the unexpected exhaustion of storage. Similarly, once execution of a function has begun,
an implementation may propagate PROGRAM-ERROR to the caller of the function, but only to signal errors made bythe user of GENERIC_COMPLEX-ELEMENTARY-FUNCTIONS.
No exception is allowed during a call to a function in GENERIC-COMPLEX-ELEMENTARY-FUNCTIONS except those per-
mitted by the foregoing rules. In particular, for arguments for which all components of results satisfying the accuracy
requirements remain less than or equal to REAL ’SAFE-LARGE in absolute value in both real and imaginary parts, a
function shall locally handle an overflow occurring during the computation of an intermediate result, if such an overflow
is possible, and shall not propagate an exception signaling that overflow to the caller of the function.
The only exceptions allowed during an instantiation of GENERIC-COMPLEX-ELEMENTARY-FUNCTIONS, including the ex-
ecution of the optional sequence of statements in the body of the instance, are CONSTRAINT-ERROR, STORAGE-ERROR
and PROGRAM-ERROR, and then only for the following reasons. The raising of CONSTRAINT-ERROR during instantiation
is only allowed when the implementation imposes the restriction that the generic actual type associated with REAL
shall not have a range constraint, and the user violates that restriction (it may, in fact, be an inescapable consequence
of the violation). The raising of PROGRAM-ERROR during instantiation is only allowed for the purpose of signaling errors
made by the user violating some restriction or limitation of the implementation. The raising of STORAGE-ERROR during
instantiation is only allowed for the purpose of signaling the exhaustion of storage.
NOTE - In ISO/IEC 8652:1995, the exception specified for signaling overflow is CONSTRAINT-ERROR.---------------------- Page: 9 ----------------------
7 Arguments outside the range of safe numbers
The ISO/IEC 8652:198 ’7 fails to define the result safe interval of any basic or predefined operation of a real subtype
when the absolute value of one of its operands exceeds the largest safe number of the operand subtype. (The failure
to define a result in this case occurs because no safe interval is defined for the operand in question.) In order to
avoid imposing requirements that would, consequently, be more stringent than those of Ada itself, this International
Standard likewise does not define the result of a contained function when the absolute value of a component of one
of its arguments exceeds REAL' SAFE-LARGE. All of the accuracy requirements and other provisions of the following
clauses are understood to be implicitly qualified by the assumption that both components of function arguments areless than or equal to REAL' SAFE-LARGE in absolute value.
8 Method of specification of functions
One of the functions has three overloaded forms. For each form of each function covered by this International Standard,
the function is specified by its parameter and result type profile, a defining equation, the applicable branch cuts, the
domain of its argument(s), its range, and the accuracy required of its implementation. The meaning of, and conventionsapplicable to, these specifications are described below.
This is meant to convey the required behavior of
The specification of each function has a heading called Definition.
the function. The definition is not necessarily an appropriate implementation for the function. The definition is one
of the mathematically correct definitions of the function but algebraic simplifications or transformations may not be
correct. Transformations may cause the sign of the result to be wrong or cause a gratuitous singularity. The definition
is based on exact computation whereas an implementation must take into account the accuracy requirements.9 Branch cut and domain definitions
The specification of each function covered by this International Standard includes headings of Branch cut and Domain.
The branch cuts or slits are specified to warn the user of discontinuity in the function or one of its derivatives. Under
the heading Domain, a characterization of the argument values is given for which the function is mathematically
defined. The portion of the complex plane over which the function is defined is expressed by inequalities or other
conditions which the arguments must satisfy to be valid. The phrase “mathematically unbounded” in a domain
definition indicates that all representable values of the argument are valid, i.e., that the domain is the entire complex
plane. Whenever the arguments fail to satisfy all the conditions, the implementation shall raise ARGUMENT-ERROR. The
implementation shall not raise ARGUMENT-ERROR if all the domain conditions are satisfied.
Inability to deliver a result for valid arguments because the result overflows, for example, shall not raise ARGUMENT-ER-
ROR, but shall be treated in the same way that Ada defines for its predefined floating-point operations (see clause12)
10 Range definitions
The usual mathematical meaning of the “range” of a function is the set of values into which the function maps the
values in its domain. Many of the functions covered by this International Standard are mathematically multivalued,
in the sense that a given argument value can be mapped by the function into many different result values. By means
of range restrictions, this International Standard imposes a uniqueness requirement on the results of multivaluedfunctions, thereby reducing them to single-valued functions.
The range of each function is shown under the heading Range in the specifications. The range definition is expressed
by inequalities or other conditions that shall be satisfied by the components of the returned result. An implementation
shall not exceed a limit of a range component when that limit is a safe number of REAL (like 0.0 or 1.0). On the other
hand, when a range component limit is not a safe number of REAL (like 7r), an implementation is allowed to exceed
the range component limit, but it is not allowed to exceed the safe number of REAL next beyond the range component
limit in the direction away from the interior of the range component; this is in general the best that can be expected---------------------- Page: 10 ----------------------
from a portable implementation. Effectively, therefore, range definitions have the added effect of imposing accuracy
requirements on implementations above and beyond those presented under the heading Accwucy in the specifications(see clause 11).
The phrase “mathematically unbounded” in a range definition indicates that the range of values of the function is notbounded by its mathematical definition.
11 Accuracy requirements
Because they are implemented on digital computers with only finite precision, the functions provided in this generic
package can, at best, only approximate the corresponding mathematically defined functions.
The accuracy requirements contained in this International Standard define the latitude that implementations are
allowed in approximating the intended precise mathematical result with floating-point computations. Accuracy re-
quirements of two kinds are stated under the heading Accuracy in the specifications. Additionally, range definitions
stated under the heading Range impose requirements that constrain the values implementations may yield, so the
range definitions are another source of accuracy requirements (the precise meaning of a range limit that is not a safe
number of REAL, as an accuracy requirement , is discussed above in clause 10). Every result yielded by a function is
subject to all of the function ’s applicable accuracy requirements, except in the one case described in clause 13, below.
In that case, the result will satisfy a small absolute error requirement in lieu of the other accuracy requirements definedfor the function.
requirement used under the heading Accuracy in the specifications is a separate boundThe first kind of accuracy
components of the computed value of the function, which shall hold
on the relative error in the (except as provided
by the rules in clauses 12 and 13) for all arguments satisfying the conditions in the domai...