Module: Math

This module provides wrappers for <cmath> (math.h) numerical constants and routines. Its symbols are provided by default; an explicit ‘use’ statement is not necessary.

The C Math library 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.

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(x: complex(?w))

Returns the real magnitude of the complex argument x.

Return type:The type of the real component of the argument (== w/2).
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 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 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 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 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 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 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(a: complex(?w)): complex(w)

Returns the complex conjugate of the argument a.

Return type:The type of a.
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 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 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 condititionals 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 condititionals 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 condititionals 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 condititionals 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 Napierien e raised to the power of the argument x.

proc exp(x: real(32)): real(32)

Returns the value of the Napierien 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 Napierien e raised to the power of the argument x.

proc expm1(x: real(32)): real(32)

Returns one less than the value of the Napierien 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 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 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(x,y) = x - y * floor(x / y).

proc mod(m: integral, n: integral)

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

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

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 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 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 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 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 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.

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)