math(3)

NAME

MATH − mathematics library

FORMAT

with MATH;
with COMPLEX;

DESCRIPTION

The VADS mathematics library provides mathematical constants and functions. The library consists of two packages: MATH and COMPLEX. The library resides in the VADS library verdixlib. Since this library is placed on the path when a library is created with MKLIB, no changes to the path are required to use the math library

The MATH package provides mathematical constants, exponential, logarithmic, circular trigonometric, inverse circular trigonometric, hyperbolic trigonometric, polar conversion, and Bessel functions.

The COMPLEX package provides functions for complex value arithmetic using generic floating types and functions for composition and decomposition of complex data types.

The actual Ada specifications for these packages can be found in the following files in verdixlib.

math_spec.a
complex_spec.a
complex_arith.a

The following mathematical notations have been used below to describe the contents of the packages.

pi ratio of a circle’s circumference to its radius

e natural or Naperian logarithm base

gamma Euler’s constant

phi golden ratio, a/b such that a/b = b/(a-b)

log_n(m) base n logarithm of m (n = 2, e, 10)

sin(m) circular sine

cos(m) circular cosine

tan(m) circular tangent

sinh(m) hyperbolic sine

cosh(m) hyperbolic cosine

tanh(m) hyperbolic tangent

Arcsin(m) principle inverse circular sine

Arccos(m) principle inverse circular cosine

Arctan(m) principle inverse circular tangent

+,-,*,/,**,|m| arithmetic operators for addition, subtraction, multiplication, division, exponentiation, and absolute value

m**(1/n) the nth root of m (n = 2, 3, 4)

MATH FUNCTIONS

The package defines two exceptions: DOMAIN_ERROR and RANGE_ERROR. DOMAIN_ERROR may be raised when the argument(s) passed in were not in the domain of the function. RANGE_ERROR may be raised when the value that should be returned is not representable. Exceptions are raised only by the functions that are documented below as doing so.

This version of the MATH library uses the functions in the unix(3m) library. These functions provide the same accuracy and indication of error as those in that library.

The following functions are defined. (All functions, except log_gamma, take and return only values of the predefined types FLOAT and SHORT_FLOAT.)

EXP(X) returns e**x − RANGE_ERROR is raised if correct value would overflow.

NAT_LOG(X) returns log_e(x) − DOMAIN_ERROR is raised if x is zero or negative.

COM_LOG10(X)
returns log_10(x)

BIN_LOG(X) returns log_2(x) − COMAIN_ERROR is raised if x is zero or negative.

X**Y returns x**y − DOMAIN_ERROR is raised if the first argument is negative and the second is non-integer, or if the first argument is zero and the second is less than or equal to zero. RANGE_ERRO is raised if the correct value would overflow.

SQRT(X) returns x**(1/2) − DOMAIN_ERROR is raised if x is negative.

ABS(X) returns |x|

FLOOR(X) returns the largest integer value not greater than x

CEIL(X) returns the smallest integer value not less than x

LOG_GAMMA(x)
returns a structure of a type GAMMA_COMPONENTS that contains the elements LOG_OF_GAMMA and SIGN. LOG_OF_GAMMA is of type FLOAT and returns log_e(gamma(|x|)). SIGN returns the sign of gamma(x) as an enumeration value of a type SIGN_GAMMA whose possible values are POSITIVE and NEGATIVE. DOMAIN_ERROR is raised if x is a negative integer.

CALC_GAMMA(X)
returns gamma(x) calculated by the algorithm given in gamma(3m) in the UNIX manual − DOMAIN_ERROR is raised if x is a negative integer.

RADIUS(X,Y) returns (x**2 + y**2)**(1/2) avoiding unwarranted overflows

ANGLE(X,Y) returns Arctan(x/y) − The range of this function is -pi .. +pi.

SIN(X) returns sin(x)

COS(X) returns cos(x)

TAN(X) returns tan(x) − RANGE_ERROR is raised for singular points, and values returned for x > 2**31 will most likely be incorrect.

SINH(X) returns sinh(x) − A large value with the correct sign is returned if the correct value would overflow.

COSH(X) returns cosh(x) − A large value with the correct sign is returned if the correct value would overflow.

TANH(X) returns tanh(x)

ARCSIN(X) returns Arcsin(x) − DOMAIN_ERROR is raised if x is greater than 1. The range of this function is -pi/2 .. +pi/2.

ARCCOS(X) returns Arccos(x) − DOMAIN_ERROR is raised if x is greater than 1. The range of this function is 0 .. +pi.

ARCTAN(X) returns Arctan(x) − The range of this function is -pi/2 .. +pi/2.

J0(X), J1(X), JN(N,X), Y0(X), Y1(X), YN(N,X) These functions calculate Bessel functions of the first and second kinds for FLOAT values for x and INTEGER values for N. DOMAIN_ERROR is raised by Y0, Y1, and YN when x is negative.

MATH CONSTANTS

The constant values are specified to 35 digits (116 bits) or the maximum accuracy in the referenced sources, if less. All constant values have been checked in at least two sources to at least 20 significant digits. In general, except for 1/pi and 1/e, simple multiples such as 2.0*pi and inverses such as 1.0/gamma, have not been included. Multiples and inverses may be declared in source code from these constants without incurring an increase in execution time; the VADS compiler performs these operations to full accuracy during compilation. Names are selected to minimize conflict with likely variable names, be descriptive, and make length proportional to expected frequency of use.

The following constants are defined in the MATH package.

PI := pi

BASE_E := e

INV_PI := 1/pi

INV_E := 1/e

PI_SQ := pi**2

SQRT_2 := 2**(1/2)

SQRT_3 := 3**(1/2)

SQRT_5 := 5**(1/2)

SQRT_7 := 7**(1/2)

SQRT_10 := 10**(1/2)

SQRT_PI := pi**(1/2)

CBRT_2 := 2**(1/3)

CBRT_3 := 3**(1/3)

CBRT_4 := 4**(1/3)

CBRT_10 := 10**(1/3)

FOURTH_RT_2
:= 2**(1/4)

FOURTH_RT_10
:= 10**(1/4)

PI_TO_E := pi**e

EXP_SQ := e**2

EXP_E := e**e

EXP_INV_E := e**(1/e)

EXP_NEG_E := e**(-e)

EXP_NEG_INV_E
:= e**(-1/e)

EXP_PI := e**pi

EXP_HALF_PI
:= e**(pi/2)

EXP_4TH_PI := e**(pi/4)

EXP_NEG_PI := e**(-pi)

EXP_NEG_HALF_PI
:= e**(-pi/2)

EXP_NEG_4TH_PI
:= e**(-pi/4)

NAT_LOG_2 := log_e(2)

NAT_LOG_3 := log_e(3)

NAT_LOG_10 := log_e(10)

NAT_LOG_E := log_e(e)

NAT_LOG_PI := log_e(pi)

COM_LOG_2 := log_10(2)

COM_LOG_3 := log_10(3)

COM_LOG_10
:= log_10(10)

COM_LOG_E := log_10(e)

COM_LOG_PI
:= log_10(pi)

BIN_LOG_2 := log_2(2)

BIN_LOG_3 := log_2(3)

BIN_LOG_10 := log_2(10)

BIN_LOG_E := log_2(e)

BIN_LOG_PI := log_2(pi)

GOLDEN_RATIO
:= phi

NAT_LOG_PHI
:= log_e(phi)

GAMMA := gamma

NAT_LOG_GAMMA
:= log_e(gamma)

COM_LOG_GAMMA
:= log_10(gamma)

EXP_GAMMA := e**gamma

EXP_NEG_GAMMA
:= e**(-gamma)

SIN_1 := sin(1)

COS_1 := cos(1)

TAN_1 := tan(1)

SINH_1 := sinh(1)

COSH_1 := cosh(1)

TANH_1 := tanh(1)

COMPLEX

The COMPLEX arithmetic package provides a private COMPLEX data type based on generic floating types REAL and ARG (argument, the angle from the real-axis of a complex value). The constant I, of type COMPLEX, is defined as private, and is equal to the imaginary unit, the square root of minus one.

The following functions are defined by the COMPLEX package.

function CMPLX ( X : REAL ) return COMPLEX;
-- Cartesian construction, generate a complex value that has a real
-- component of X and an imaginary component of zero
function CMPLX ( X,Y : REAL ) return COMPLEX;
-- Cartesian construction, generate a complex value that has a real
-- component of X and an imaginary component of Y
function CMPLX_POLAR ( R : REAL; A : ARG ) return COMPLEX;
function CMPLX_POLAR ( A : ARG; R : REAL ) return COMPLEX;
-- Polar construction, generate a complex value that has an
-- argument(angle) A and a radius of R
function "ABS" ( X : COMPLEX ) return REAL;
function MODULUS ( X : COMPLEX ) return REAL;
-- Absolute value or "modulus", return distance from origin,
-- sqrt( x**2 + y**2 ) for Cartesian form, radius for polar form
function ARGUMENT ( X : COMPLEX ) return ARG;
-- Argument value, Atan( y/x ) for Cartesian form, argument (angle)
-- for polar form
function "+" ( X   : COMPLEX; Y : REAL )    return COMPLEX;
function "-" ( X   : COMPLEX; Y : REAL )    return COMPLEX;
function "*" ( X   : COMPLEX; Y : REAL )    return COMPLEX;
function "/" ( X   : COMPLEX; Y : REAL )    return COMPLEX;
function "+" ( X   : REAL; Y    : COMPLEX ) return COMPLEX;
function "-" ( X   : REAL; Y    : COMPLEX ) return COMPLEX;
function "*" ( X   : REAL; Y    : COMPLEX ) return COMPLEX;
function "/" ( X   : REAL; Y    : COMPLEX ) return COMPLEX;
function "+" ( X   : COMPLEX )              return COMPLEX;
function "-" ( X   : COMPLEX )              return COMPLEX;
function "+" ( X,Y : COMPLEX )              return COMPLEX;
function "-" ( X,Y : COMPLEX )              return COMPLEX;
function "*" ( X,Y : COMPLEX )              return COMPLEX;
function "/" ( X,Y : COMPLEX )              return COMPLEX;

The following generic formal parameter floating data types must be specified in a COMPLEX generic instantiation.

type REAL is digits <>;

type ARG is digits <>;

If the data types for REAL and ARG are the same, the CMPLX_POLAR functions cannot be called, as the overloading ambiguity is impossible to resolve (see RM 12.3(22)).

The following generic formal functions on the types REAL and ARG must be defined for a COMPLEX generic instantiation.

with function "+"    ( U,V : REAL ) return REAL is <>;

with function "-"    ( U,V : REAL ) return REAL is <>;

with function "*"    ( U,V : REAL ) return REAL is <>;

with function "/"    ( U,V : REAL ) return REAL is <>;

with function "+"    ( U   : REAL ) return REAL is <>;

with function "-"    ( U   : REAL ) return REAL is <>;

with function SIN    ( X   : ARG )   return REAL is <>;

with function COS    ( X   : ARG )   return REAL is <>;

with function RADIUS ( X,Y : REAL ) return REAL is <>;

with function ANGLE ( Y,X : REAL ) return ARG is <>;

The definition of these functions can either be implicit or explicit. Note that if REAL and ARG are both SHORT_FLOAT or FLOAT, then the MATH package contains the properly defined functions.

Museum