Math¶

Usage

use Math;

This module provides mathematical constants and functions.

Note

All Chapel programs automatically use this module by default. An explicit use statement is not necessary.

It includes wrappers for many of the constants in functions in the C Math library, which is part of the C Language Standard (ISO/IEC 9899) as described in Section 7.12. Please consult that standard for an authoritative description of the expected properties of those constants and routines.

In general, where the C math library provides a double and a float version of a function, the float version has a suffix 'f'. In the Chapel interface, the suffix is dropped, and the type of the operand determines which version is called -- according to the usual function overloading and resolution rules. Normally, the result has the same precision as the argument(s). Please consult the C standard for specifics.

Rounding -- The rounding mode for floating-point addition (subtraction) is implementation-defined.

Error Handling -- At present, Chapel does not provide control over error handling in the Math module. The default behavior is as if the macro math_errhandling is set to 0: Given erroneous input at run-time, all math functions will return an implementation-defined value; no exception will be generated.

param e = 2.71828¶: e - exp(1) or the base of the natural logarithm

param log2_e = 1.4427¶: log2(e)

param log10_e = 0.434294¶: log10(e)

param ln_2 = 0.693147¶: log(2) (natural logarithm)

param ln_10 = 2.30259¶: log(10) (natural logarithm)

param pi = 3.14159¶: pi - the circumference/the diameter of a circle

param half_pi = 1.5708¶: pi/2

param quarter_pi = 0.785398¶: pi/4

param recipr_pi = 0.31831¶: 1/pi

param twice_recipr_pi = 0.63662¶: 2/pi

param twice_recipr_sqrt_pi = 1.12838¶: 2/sqrt(pi)

param sqrt_2 = 1.41421¶: sqrt(2)

param recipr_sqrt_2 = 0.707107¶: 1/sqrt(2)

proc abs(i: int(?w))¶

Returns the absolute value of the integer argument.

Return type:	The type of i.

proc abs(i: uint(?w))

Returns the absolute value of the unsigned integer argument.

Return type:	The type of i.

proc abs(param i: integral) param: Returns the absolute value of the integer param argument i.

proc abs(r: real(64)): real(64): Returns the magnitude of the real argument r.

proc abs(x: real(32)): real(32): Returns the magnitude of the real argument x.

proc abs(im: imag(64)): real(64): Returns the real magnitude of the imaginary argument im.

proc abs(im: imag(32)): real(32): Returns the real magnitude of the imaginary argument im.

proc abs(z: complex(?w)): real(w/2)

Returns the real magnitude of the complex argument z.

Return type:	The type of the real component of the argument (== w/2).

proc carg(z: complex(?w)): real(w/2)¶: Returns the real phase angle of complex argument z.

proc acos(x: real(64)): real(64)¶

Returns the arc cosine of the argument x.

It is an error if x is less than -1 or greater than 1.

proc acos(x: real(32)): real(32)

Returns the arc cosine of the argument x.

It is an error if x is less than -1 or greater than 1.

proc acos(z: complex(64)): complex(64): Returns the arc cosine of the argument z.

proc acos(z: complex(128)): complex(128): Returns the arc cosine of the argument z.

proc acosh(x: real(64)): real(64)¶

Returns the inverse hyperbolic cosine of the argument x.

It is an error if x is less than 1.

proc acosh(x: real(32)): real(32)

Returns the inverse hyperbolic cosine of the argument x.

It is an error if x is less than 1.

proc acosh(z: complex(64)): complex(64): Returns the inverse hyperbolic cosine of the argument z.

proc acosh(z: complex(128)): complex(128): Returns the inverse hyperbolic cosine of the argument z.

proc asin(x: real(64)): real(64)¶

Returns the arc sine of the argument x.

It is an error if x is less than -1 or greater than 1.

proc asin(x: real(32)): real(32)

Returns the arc sine of the argument x.

It is an error if x is less than -1 or greater than 1.

proc asin(z: complex(64)): complex(64): Returns the arc sine of the argument z.

proc asin(z: complex(128)): complex(128): Returns the arc sine of the argument z.

proc asinh(x: real(64)): real(64)¶: Returns the inverse hyperbolic sine of the argument x.

proc asinh(x: real(32)): real(32): Returns the inverse hyperbolic sine of the argument x.

proc asinh(z: complex(64)): complex(64): Returns the inverse hyperbolic sine of the argument z.

proc asinh(z: complex(128)): complex(128): Returns the inverse hyperbolic sine of the argument z.

proc atan(x: real(64)): real(64)¶: Returns the arc tangent of the argument x.

proc atan(x: real(32)): real(32): Returns the arc tangent of the argument x.

proc atan(z: complex(64)): complex(64): Returns the arc tangent of the argument z.

proc atan(z: complex(128)): complex(128): Returns the arc tangent of the argument z.

proc atan2(y: real(64), x: real(64)): real(64)¶

Returns the arc tangent of the ratio of the two arguments.

This is equivalent to the arc tangent of y / x except that the signs of y and x are used to determine the quadrant of the result.

proc atan2(y: real(32), x: real(32)): real(32)

Returns the arc tangent of the two arguments.

This is equivalent to the arc tangent of y / x except that the signs of y and x are used to determine the quadrant of the result.

proc atanh(x: real(64)): real(64)¶

Returns the inverse hyperbolic tangent of the argument x.

It is an error if x is less than -1 or greater than 1.

proc atanh(x: real(32)): real(32)

Returns the inverse hyperbolic tangent of the argument x.

It is an error if x is less than -1 or greater than 1.

proc atanh(z: complex(64)): complex(64): Returns the inverse hyperbolic tangent of the argument z.

proc atanh(z: complex(128)): complex(128): Returns the inverse hyperbolic tangent of the argument z.

proc cbrt(x: real(64)): real(64)¶: Returns the cube root of the argument x.

proc cbrt(x: real(32)): real(32): Returns the cube root of the argument x.

proc ceil(x: real(64)): real(64)¶: Returns the value of the argument x rounded up to the nearest integer.

proc ceil(x: real(32)): real(32): Returns the value of the argument x rounded up to the nearest integer.

proc conjg(z: complex(?w)): complex(w)¶

Returns the complex conjugate of the argument z.

Return type:	A complex number of the same type as z.

proc cproj(z: complex(?w)): real(w/2)¶: Returns the projection of z on a Riemann sphere.

proc cos(x: real(64)): real(64)¶: Returns the cosine of the argument x.

proc cos(x: real(32)): real(32): Returns the cosine of the argument x.

proc cos(z: complex(64)): complex(64): Returns the cosine of the argument z.

proc cos(z: complex(128)): complex(128): Returns the cosine of the argument z.

proc cosh(x: real(64)): real(64)¶: Returns the hyperbolic cosine of the argument x.

proc cosh(x: real(32)): real(32): Returns the hyperbolic cosine of the argument x.

proc cosh(z: complex(64)): complex(64): Returns the hyperbolic cosine of the argument z.

proc cosh(z: complex(128)): complex(128): Returns the hyperbolic cosine of the argument z.

proc divceil(param m: integral, param n: integral) param¶

Returns ceil(m/n), i.e., the fraction m/n rounded up to the nearest integer.

If the arguments are of unsigned type, then fewer conditionals will be evaluated at run time.

proc divceil(m: integral, n: integral)

Returns ceil(m/n), i.e., the fraction m/n rounded up to the nearest integer.

If the arguments are of unsigned type, then fewer conditionals will be evaluated at run time.

proc divceilpos(m: integral, n: integral)¶: A variant of divceil that performs no runtime checks. The user must ensure that both arguments are strictly positive (not 0) and are of a signed integer type (not uint).

proc divfloor(param m: integral, param n: integral) param¶

Returns floor(m/n), i.e., the fraction m/n rounded down to the nearest integer.

If the arguments are of unsigned type, then fewer conditionals will be evaluated at run time.

proc divfloor(m: integral, n: integral)

Returns floor(m/n), i.e., the fraction m/n rounded down to the nearest integer.

If the arguments are of unsigned type, then fewer conditionals will be evaluated at run time.

proc divfloorpos(m: integral, n: integral)¶: A variant of divfloor that performs no runtime checks. The user must ensure that both arguments are strictly positive (not 0) and are of a signed integer type (not uint).

proc erf(x: real(64)): real(64)¶: Returns the error function of the argument x.

proc erf(x: real(32)): real(32): Returns the error function of the argument x.

proc erfc(x: real(64)): real(64)¶: Returns the complementary error function of the argument. This is equivalent to 1.0 - erf(x).

proc erfc(x: real(32)): real(32): Returns the complementary error function of the argument. This is equivalent to 1.0 - erf(x).

proc exp(x: real(64)): real(64)¶: Returns the value of the Napierian e raised to the power of the argument x.

proc exp(x: real(32)): real(32): Returns the value of the Napierian e raised to the power of the argument.

proc exp(z: complex(64)): complex(64): Returns the value of the Napierian e raised to the power of the argument.

proc exp(z: complex(128)): complex(128): Returns the value of the Napierian e raised to the power of the argument.

proc exp2(x: real(64)): real(64)¶: Returns the value of 2 raised to the power of the argument x.

proc exp2(x: real(32)): real(32): Returns the value of 2 raised to the power of the argument x.

proc expm1(x: real(64)): real(64)¶: Returns one less than the value of the Napierian e raised to the power of the argument x.

proc expm1(x: real(32)): real(32): Returns one less than the value of the Napierian e raised to the power of the argument x.

proc floor(x: real(64)): real(64)¶: Returns the value of the argument x rounded down to the nearest integer.

proc floor(x: real(32)): real(32): Returns the value of the argument x rounded down to the nearest integer.

proc INFINITY: real(64)¶: Returns a value for which isinf will return true.

proc isfinite(x: real(64)): bool¶: Returns true if the argument x is a representation of a finite value; false otherwise.

proc isfinite(x: real(32)): bool: Returns true if the argument x is a representation of a finite value; false otherwise.

proc isinf(x: real(64)): bool¶: Returns true if the argument x is a representation of infinity; false otherwise.

proc isinf(x: real(32)): bool: Returns true if the argument x is a representation of infinity; false otherwise.

proc isnan(x: real(64)): bool¶: Returns true if the argument x does not represent a valid number; false otherwise.

proc isnan(x: real(32)): bool: Returns true if the argument x does not represent a valid number; false otherwise.

proc ldexp(x: real(64), n: int(32)): real(64)¶: Multiply by an integer power of 2. Returns x * 2**n.

proc ldexp(x: real(32), n: int(32)): real(32)

proc lgamma(x: real(64)): real(64)¶: Returns the natural logarithm of the absolute value of the gamma function of the argument x.

proc lgamma(x: real(32)): real(32): Returns the natural logarithm of the absolute value of the gamma function of the argument x.

proc log(x: real(64)): real(64)¶

Returns the natural logarithm of the argument x.

It is an error if x is less than or equal to zero.

proc log(x: real(32)): real(32)

Returns the natural logarithm of the argument x.

It is an error if x is less than or equal to zero.

proc log(z: complex(64)): complex(64): Returns the natural logarithm of the argument z.

proc log(z: complex(128)): complex(128): Returns the natural logarithm of the argument z.

proc log10(x: real(64)): real(64)¶

Returns the base 10 logarithm of the argument x.

It is an error if x is less than or equal to zero.

proc log10(x: real(32)): real(32)

Returns the base 10 logarithm of the argument x.

It is an error if x is less than or equal to zero.

proc log1p(x: real(64)): real(64)¶

Returns the natural logarithm of x + 1.

It is an error if x is less than or equal to -1.

proc log1p(x: real(32)): real(32)

Returns the natural logarithm of x + 1.

It is an error if x is less than or equal to -1.

proc logBasePow2(in val: int(?w), baseLog2)¶

Returns the log to the base 2**baseLog2 of the given in value. If baseLog2 is 1, then returns the log to the base 2; if baseLog2 is 2, then returns the log to the base 4, etc. Any fractional part is discarded.

Return type:	int

proc logBasePow2(in val: uint(?w), baseLog2)

Returns the log to the base 2**baseLog2 of the given in value. If baseLog2 is 1, then returns the log to the base 2; if baseLog2 is 2, then returns the log to the base 4, etc. Any fractional part is discarded.

Return type:	int

proc log2(x: real(64)): real(64)¶

Returns the base 2 logarithm of the argument x.

It is an error if x is less than or equal to zero.

proc log2(x: real(32)): real(32)

Returns the base 2 logarithm of the argument x.

It is an error if x is less than or equal to zero.

proc log2(in val: int(?w))

Returns the base 2 logarithm of the argument x.

Return type:	int(64)

It is an error if x is less than or equal to zero.

proc log2(in val: uint(?w))

Returns the base 2 logarithm of the argument x.

Return type:	int(64)

It is an error if x is less than or equal to zero.

proc mod(param m: integral, param n: integral) param¶

Computes the mod operator on the two arguments, defined as mod(m,n) = m - n * floor(m / n).

The result is always >= 0 if n > 0. It is an error if n == 0.

proc mod(m: integral, n: integral)

Computes the mod operator on the two arguments, defined as mod(m,n) = m - n * floor(m / n).

If the arguments are of unsigned type, then fewer conditionals will be evaluated at run time.

The result is always >= 0 if n > 0. It is an error if n == 0.

proc mod(x: real(?w), y: real(w)): real(w)

Computes the mod operator on the two numbers, defined as mod(x,y) = x - y * floor(x / y).

The return value has the same type as x.

proc NAN: real(64)¶: Returns a value for which isnan will return true.

proc nearbyint(x: real(64)): real(64)¶: Returns the rounded integral value of the argument x determined by the current rounding direction. nearbyint will not raise the "inexact" floating-point exception.

proc nearbyint(x: real(32)): real(32): Returns the rounded integral value of the argument x determined by the current rounding direction. nearbyint will not raise the "inexact" floating-point exception.

proc rint(x: real(64)): real(64)¶: Returns the rounded integral value of the argument x determined by the current rounding direction. rint may raise the "inexact" floating-point exception.

proc rint(x: real(32)): real(32): Returns the rounded integral value of the argument x determined by the current rounding direction. rint may raise the "inexact" floating-point exception.

proc round(x: real(64)): real(64)¶: Returns the rounded integral value of the argument x.

proc round(x: real(32)): real(32): Returns the rounded integral value of the argument x.

proc sgn(i: int(?w)): int(8)¶: Returns the signum function of the integer argument i: 1 if positive, -1 if negative, 0 if zero.

proc sgn(i: uint(?w)): uint(8): Returns the signum function of the unsigned integer argument i: 1 if positive, -1 if negative, 0 if zero.

proc sgn(param i: integral) param: Returns the signum function of the integer param argument i: 1 if positive, -1 if negative, 0 if zero.

proc sgn(x: real(?w)): int(8): Returns the signum function of the real argument x: 1 if positive, -1 if negative, 0 if zero.

proc sin(x: real(64)): real(64)¶: Returns the sine of the argument x.

proc sin(x: real(32)): real(32): Returns the sine of the argument x.

proc sin(z: complex(64)): complex(64): Returns the sine of the argument z.

proc sin(z: complex(128)): complex(128): Returns the sine of the argument z.

proc sinh(x: real(64)): real(64)¶: Returns the hyperbolic sine of the argument x.

proc sinh(x: real(32)): real(32): Returns the hyperbolic sine of the argument x.

proc sinh(z: complex(64)): complex(64): Returns the hyperbolic sine of the argument z.

proc sinh(z: complex(128)): complex(128): Returns the hyperbolic sine of the argument z.

proc sqrt(x: real(64)): real(64)¶

Returns the square root of the argument x.

It is an error if the x is less than zero.

proc sqrt(x: real(32)): real(32)

Returns the square root of the argument x.

It is an error if x is less than zero.

proc sqrt(z: complex(64)): complex(64): Returns the square root of the argument z.

proc sqrt(z: complex(128)): complex(128): Returns the square root of the argument z.

proc tan(x: real(64)): real(64)¶: Returns the tangent of the argument x.

proc tan(x: real(32)): real(32): Returns the tangent of the argument x.

proc tan(z: complex(64)): complex(64): Returns the tangent of the argument z.

proc tan(z: complex(128)): complex(128): Returns the tangent of the argument z.

proc tanh(x: real(64)): real(64)¶: Returns the hyperbolic tangent of the argument x.

proc tanh(x: real(32)): real(32): Returns the hyperbolic tangent of the argument x.

proc tanh(z: complex(64)): complex(64): Returns the hyperbolic tangent of the argument z.

proc tanh(z: complex(128)): complex(128): Returns the hyperbolic tangent of the argument z.

proc tgamma(x: real(64)): real(64)¶: Returns the absolute value of the gamma function of the argument x.

proc tgamma(x: real(32)): real(32): Returns the absolute value of the gamma function of the argument x.

proc trunc(x: real(64)): real(64)¶: Returns the nearest integral value to the argument x that is not larger than x in absolute value.

proc trunc(x: real(32)): real(32): Returns the nearest integral value to the argument x that is not larger than x in absolute value.