Math

Usage

use Math;

or

import Math;

Support for frequently used mathematical constants and functions.

It includes wrappers for many of the constants and 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.

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.

Automatically Available Symbols

Note

These symbols can also be accessed using Math. as their qualified access prefix.

Roots

cbrt sqrt

Rounding

ceil floor round trunc

Computations Involving Complex Numbers

conj phase riemProj

Infinity and NaN

inf nan isFinite isInf isNan

Comparison Functions

max min isClose

Sign Functions

sgn signbit

Remaining Functions

abs mod

Non-Automatically Available Symbols

Constants

e log2E log10E ln2 ln10 pi halfPi quarterPi reciprPi twiceReciprPi twiceReciprSqrtPi sqrt2 reciprSqrt2

Trigonometric Functions

acos asin atan atan2 cos sin tan

Hyperbolic Functions

acosh asinh atanh cosh sinh tanh

Log Functions

ln log log10 log1p logBasePow2 log2

Exponential Functions

exp exp2 expm1 ldExp

Rounding

divCeil divCeilPos divFloor divFloorPos nearbyint rint

Gamma Functions

gamma lnGamma

Error Functions

erf erfc

Algorithms

gcd

Bessel Functions

j0 j1 jn y0 y1 yn

Optimization Functions

fma

Automatically Included Constant and Function Definitions

proc abs(x: int(?w))

Returns the absolute value of the integer argument.

Return type:

The type of x.

proc abs(x: uint(?w))

Returns the absolute value of the unsigned integer argument.

Return type:

The type of x.

proc abs(param x: integral) param

Returns the absolute value of the integer param argument x.

proc abs(x: real(64)) : real(64)

Returns the magnitude of the real argument x.

proc abs(param x: real(64)) param : real(64)

Return the absolute value of a param real(64) as a param

proc abs(x: real(32)) : real(32)

Returns the magnitude of the real argument x.

proc abs(param x: real(32)) param : real(32)

Return the absolute value of a param real(32) as a param

proc abs(x: imag(64)) : real(64)

Returns the real magnitude of the imaginary argument x.

proc abs(param x: imag(64)) param : real(64)

Return the real magnitude of a param imaginary argument x as a param

proc abs(x: imag(32)) : real(32)

Returns the real magnitude of the imaginary argument x.

proc abs(param x: imag(32)) param : real(32)

Return the real magnitude of a param imaginary argument x as a param

proc abs(x: complex(128)) : real(64)

Returns the magnitude (often called modulus) of complex x.

In concert with the related phase (a.k.a. argument) of x, it can be used to recompute x.

proc abs(param x: complex(128)) param : real(64)

Returns the magnitude of a param complex(128).

proc abs(x: complex(64)) : real(32)

Returns the magnitude (often called modulus) of complex x.

In concert with the related phase (a.k.a. argument) of x, it can be used to recompute x.

proc abs(param x: complex(64)) param : real(32)

Returns the magnitude of a param complex(64).

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

Returns the complex conjugate of the complex argument x.

Return type:

A complex number of the same type as x.

proc conj(x: imag(?w))

Returns the complex conjugate of the imaginary argument x.

Return type:

An imaginary number of the same type as x.

proc conj(x: int(?w))

Returns the argument x.

Return type:

A number that is not complex or imaginary of the same type as x.

proc conj(x: uint(?w))
proc conj(x: real(?w))
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 inf param : 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 max(x, y)  where !isArray(x) && !isArray(y) && !(isNumeric(_desync(x.type)) && isNumeric(_desync(y.type)))

Returns the maximum value of two arguments using the > operator for comparison. If one of the arguments is Math.nan, the result is also nan.

Return type:

The type of x.

proc max(x, y, z ...?k)

Returns the maximum value of 3 or more arguments using the above call.

proc max(param x: numeric, param y: numeric) param  where !(isComplex(x) || isComplex(y))

Returns the maximum of 2 param int, uint, real, or imag values as a param.

proc min(x, y)  where !isArray(x) && !isArray(y) && !(isNumeric(_desync(x.type)) && isNumeric(_desync(y.type)))

Returns the minimum value of two arguments using the < operator for comparison.

If one of the arguments is Math.nan, the result is also nan.

Return type:

The type of x.

proc min(x, y, z ...?k)

Returns the minimum value of 3 or more arguments using the above call.

proc min(param x: numeric, param y: numeric) param  where !(isComplex(x) || isComplex(y))

Returns the minimum of 2 param int, uint, real, or imag values as a param.

proc mod(param x: integral, param y: integral) param

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

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

Note

This does not have the same behavior as the Modulus Operators (%) when y is negative.

proc mod(x: integral, y: 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 conditionals will be evaluated at run time.

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

Note

This does not have the same behavior as the Modulus Operators (%) when y is negative.

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

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

proc mod(x: real(64), y: real(64)) : real(64)

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

proc nan param : real(64)

Returns a value for which isNan will return true.

proc phase(x: complex(?w)) : real(w/2)

Returns the phase (often called argument) of complex x, an angle (in radians).

In concert with the related abs, the magnitude (a.k.a. modulus) of x, it can be used to recompute x.

Return type:

real(w/2) when x has a type of complex(w).

proc riemProj(x: complex(?w)) : complex(w)

Returns the projection of x on a Riemann sphere.

proc round(x: real(64)) : real(64)

Returns the nearest integral value of the argument x, returning that value which is larger than x in absolute value for the half-way case.

proc round(x: real(32)) : real(32)

Returns the nearest integral value of the argument x, returning that value which is larger than x in absolute value for the half-way case.

proc sgn(x: int(?w)) : int(8)

Warning

sgn is unstable and may change its name and return type in the future

Returns the signum function of the integer argument x: 1 if positive, -1 if negative, 0 if zero.

proc sgn(x: uint(?w)) : uint(8)

Warning

sgn is unstable and may change its name and return type in the future

Returns the signum function of the unsigned integer argument x: 1 if positive, -1 if negative, 0 if zero.

proc sgn(param x: integral) param

Warning

sgn is unstable and may change its name and return type in the future

Returns the signum function of the integer param argument x: 1 if positive, -1 if negative, 0 if zero.

proc sgn(x: real(?w)) : int(8)

Warning

sgn is unstable and may change its name and return type in the future

Returns the signum function of the real argument x: 1 if positive, -1 if negative, 0 if zero.

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(param x: real(64)) param : 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(param x: real(32)) param : real(32)

Returns the square root of the argument x.

It is an error if x is less than zero.

proc sqrt(x: complex(64)) : complex(64)

Returns the square root of the argument x.

proc sqrt(param x: complex(64)) param : complex(64)

Returns the square root of the argument x.

proc sqrt(x: complex(128)) : complex(128)

Returns the square root of the argument x.

proc sqrt(param x: complex(128)) param : complex(128)

Returns the square root 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.

proc isClose(x, y, relTol = 1e-5, absTol = 0.0) : bool

Returns true if x and y are approximately equal, else returns false.

relTol specifies the relative tolerance for differences between x and y, while absTol specifies the absolute tolerance. Both must be positive when specified.

x and y must be either real, imag, or complex.

proc signbit(x: real(32)) : bool

Warning

signbit is unstable and may change its name in the future

Returns true if the sign of x is negative, else returns false. It detects the sign bit of zeroes, infinities, and nans

proc signbit(x: real(64)) : bool

Warning

signbit is unstable and may change its name in the future

Returns true if the sign of x is negative, else returns false. It detects the sign bit of zeroes, infinities, and nans

Constant and Function Definitions for Math

param e = 2.7182818284590452354

e - exp(1) or the base of the natural logarithm

param log2E = 1.4426950408889634074

log2(e)

param log10E = 0.43429448190325182765

log10(e)

param ln2 = 0.69314718055994530942

ln(2) (natural logarithm)

param ln10 = 2.30258509299404568402

ln(10) (natural logarithm)

param pi = 3.14159265358979323846

pi - the circumference/the diameter of a circle

param halfPi = 1.57079632679489661923

Warning

‘halfPi’ is unstable due to questions about its utility. If you are seeing negative performance impacts from using ‘pi/2’ instead of this ‘param’, please let us know!

pi/2

param quarterPi = 0.78539816339744830962

Warning

‘quarterPi’ is unstable due to questions about its utility. If you are seeing negative performance impacts from using ‘pi/4’ instead of this ‘param’, please let us know!

pi/4

param reciprPi = 0.31830988618379067154

Warning

‘reciprPi’ is unstable due to questions about its utility. If you are seeing negative performance impacts from using ‘1/pi’ instead of this ‘param’, please let us know!

1/pi

param twiceReciprPi = 0.63661977236758134308

Warning

‘twiceReciprPi’ is unstable due to questions about its utility. If you are seeing negative performance impacts from using ‘2/pi’ instead of this ‘param’, please let us know!

2/pi

param twiceReciprSqrtPi = 1.12837916709551257390

Warning

‘twiceReciprSqrtPi’ is unstable due to questions about its utility. If you are using this symbol, please let us know!

2/sqrt(pi)

param sqrt2 = 1.41421356237309504880

Warning

‘sqrt2’ is unstable due to questions about its utility. If you are using this symbol, please let us know!

sqrt(2)

param reciprSqrt2 = 0.70710678118654752440

Warning

‘reciprSqrt2’ is unstable due to questions about its utility. If you are using this symbol, please let us know!

1/sqrt(2)

config param useNewImaginaryTrig = false

Enables the new return types for some of the trigonometric and hyperbolic functions that operate on imag

Functions Affected: - proc cos(imag): real - proc cosh(imag): real - proc sin(imag): imag - proc sinh(imag): imag - proc tan(imag): imag - proc tanh(imag): imag - proc asin(imag): imag - proc atanh(imag): imag

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

Returns the arc cosine of the argument x.

proc acos(x: complex(128)) : complex(128)

Returns the arc cosine of the argument x.

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

Returns the inverse hyperbolic cosine of the argument x.

proc acosh(x: complex(128)) : complex(128)

Returns the inverse hyperbolic cosine of the argument x.

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

Returns the arc sine of the argument x.

proc asin(x: complex(128)) : complex(128)

Returns the arc sine of the argument x.

proc asin(x: imag(32)) : imag(32)  where useNewImaginaryTrig

Returns the arc sine of the argument x. Uses the formula asin(i*x) == i*asinh(x).

proc asin(x: imag(64)) : imag(64)  where useNewImaginaryTrig

Returns the arc sine of the argument x. Uses the formula asin(i*x) == i*asinh(x).

proc asin(x: imag) : complex  where !useNewImaginaryTrig

Warning

The overload of ‘asin’ that takes an ‘imag’ argument and returns a ‘complex’ is deprecated and will be removed in the future. To opt-in to the new behavior, compile with -suseNewImaginaryTrig=true.

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

Returns the inverse hyperbolic sine of the argument x.

proc asinh(x: complex(128)) : complex(128)

Returns the inverse hyperbolic sine of the argument x.

proc atan(x: real(64)) : real(64)

Returns the arc tangent of the argument x. The result lies in the inclusive range [-pi/2,+pi/2].

proc atan(x: real(32)) : real(32)

Returns the arc tangent of the argument x. The result lies in the inclusive range [-pi/2,+pi/2].

proc atan(x: complex(64)) : complex(64)

Returns the arc tangent of the argument x. The result lies in the inclusive range [-pi/2,+pi/2].

proc atan(x: complex(128)) : complex(128)

Returns the arc tangent of the argument x. The result lies in the inclusive range [-pi/2,+pi/2].

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

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

This is the arc (or inverse) tangent of y / x which lies in the inclusive range [-pi,+pi] where 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 ratio of the two arguments.

This is the arc (or inverse) tangent of y / x which lies in the inclusive range [-pi,+pi] where 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(x: complex(64)) : complex(64)

Returns the inverse hyperbolic tangent of the argument x.

proc atanh(x: complex(128)) : complex(128)

Returns the inverse hyperbolic tangent of the argument x.

proc atanh(x: imag(32)) : imag(32)  where useNewImaginaryTrig

Returns the inverse hyperbolic tangent of the argument x. Uses the formula atanh(i*x) == i*atan(x).

proc atanh(x: imag(64)) : imag(64)  where useNewImaginaryTrig

Returns the inverse hyperbolic tangent of the argument x. Uses the formula atanh(i*x) == i*atan(x).

proc atanh(x: imag) : complex  where !useNewImaginaryTrig

Warning

The overload of ‘atanh’ that takes an ‘imag’ argument and returns a ‘complex’ is deprecated and will be removed in the future. To opt-in to the new behavior, compile with -suseNewImaginaryTrig=true.

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

Returns the cosine of the argument x.

proc cos(x: complex(128)) : complex(128)

Returns the cosine of the argument x.

proc cos(x: imag(32)) : real(32)  where useNewImaginaryTrig

Returns the cosine of the argument x. Uses the formula cos(i*x) == cosh(x).

proc cos(x: imag(64)) : real(64)  where useNewImaginaryTrig

Returns the cosine of the argument x. Uses the formula cos(i*x) == cosh(x).

proc cos(x: imag) : complex  where !useNewImaginaryTrig

Warning

The overload of ‘cos’ that takes an ‘imag’ argument and returns a ‘complex’ is deprecated and will be removed in the future. To opt-in to the new behavior, compile with -suseNewImaginaryTrig=true.

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

Returns the hyperbolic cosine of the argument x.

proc cosh(x: complex(128)) : complex(128)

Returns the hyperbolic cosine of the argument x.

proc cosh(x: imag(32)) : real(32)  where useNewImaginaryTrig

Returns the hyperbolic cosine of the argument x. Uses the formula cosh(i*x) == cos(x).

proc cosh(x: imag(64)) : real(64)  where useNewImaginaryTrig

Returns the hyperbolic cosine of the argument x. Uses the formula cosh(i*x) == cos(x).

proc cosh(x: imag) : complex  where !useNewImaginaryTrig

Warning

The overload of ‘cosh’ that takes an ‘imag’ argument and returns a ‘complex’ is deprecated and will be removed in the future. To opt-in to the new behavior, compile with -suseNewImaginaryTrig=true.

proc divCeil(param x: integral, param y: integral) param

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

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

proc divCeil(x: integral, y: integral)

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

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

proc divCeilPos(x: integral, y: integral)

Warning

divCeilPos is unstable due to questions about its utility. If you find this function valuable, please let us know!

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 x: integral, param y: integral) param

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

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

proc divFloor(x: integral, y: integral)

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

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

proc divFloorPos(x: integral, y: integral)

Warning

divFloorPos is unstable due to questions about its utility. If you find this function valuable, please let us know!

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)

Warning

‘erf’ is unstable and may be renamed or moved to a different module in the future

Returns the error function of the argument x. This is equivalent to 2/sqrt(pi) * the integral of exp(-t**2)dt from 0 to x.

proc erf(x: real(32)) : real(32)

Warning

‘erf’ is unstable and may be renamed or moved to a different module in the future

Returns the error function of the argument x. This is equivalent to 2/sqrt(pi) * the integral of exp(-t**2)dt from 0 to x.

proc erfc(x: real(64)) : real(64)

Warning

‘erfc’ is unstable and may be renamed or moved to a different module in the future

Returns the complementary error function of the argument x. This is equivalent to 1.0 - erf(x).

proc erfc(x: real(32)) : real(32)

Warning

‘erfc’ is unstable and may be renamed or moved to a different module in the future

Returns the complementary error function of the argument x. 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 x.

proc exp(x: complex(64)) : complex(64)

Returns the value of the Napierian e raised to the power of the argument x.

proc exp(x: complex(128)) : complex(128)

Returns the value of the Napierian e raised to the power of the argument x.

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 gamma(x: real(64)) : real(64)

Returns the gamma function of the argument x.

proc gamma(x: real(32)) : real(32)

Returns the gamma function of the argument x.

proc ldExp(x: real(64), exp: int(32)) : real(64)

Returns the value of the argument x multiplied by 2 raised to the argument exp power, i.e., x * 2**exp.

proc ldExp(x: real(32), exp: int(32)) : real(32)

Returns the value of the argument x multiplied by 2 raised to the argument exp power, i.e., x * 2**exp.

proc lnGamma(x: real(64)) : real(64)

Returns the natural logarithm of the absolute value of the gamma function of the argument x.

proc lnGamma(x: real(32)) : real(32)

Returns the natural logarithm of the absolute value of the gamma function of the argument x.

proc ln(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 ln(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 ln(x: complex(64)) : complex(64)

Returns the natural logarithm of the argument x.

proc ln(x: complex(128)) : complex(128)

Returns the natural logarithm 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(x: complex(64)) : complex(64)

Returns the natural logarithm of the argument x.

proc log(x: complex(128)) : complex(128)

Returns the natural logarithm of the argument x.

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(x: int(?w), exp)

Warning

‘logBasePow2’ is unstable due to questions about its utility. If you rely on this function, please let us know!

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

Return type:

int

proc logBasePow2(x: uint(?w), exp)

Warning

‘logBasePow2’ is unstable due to questions about its utility. If you rely on this function, please let us know!

Returns the log to the base 2**exp of the given x value. If exp is 1, then returns the log to the base 2; if exp 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(x: int(?w))

Warning

The version of ‘log2’ that takes an int argument is unstable

Returns the base 2 logarithm of the argument x, rounded down.

Return type:

int

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

proc log2(x: uint(?w))

Warning

The version of ‘log2’ that takes an uint argument is unstable

Returns the base 2 logarithm of the argument x, rounded down.

Return type:

int

It is an error if x is equal to zero.

proc nearbyint(x: real(64)) : real(64)

Warning

nearbyint is unstable while we design more thorough rounding support

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)

Warning

nearbyint is unstable while we design more thorough rounding support

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)

Warning

rint is unstable while we design more thorough rounding support

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)

Warning

rint is unstable while we design more thorough rounding support

Returns the rounded integral value of the argument x determined by the current rounding direction. rint may raise the “inexact” floating-point exception.

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

Returns the sine of the argument x.

proc sin(x: complex(128)) : complex(128)

Returns the sine of the argument x.

proc sin(x: imag(32)) : imag(32)  where useNewImaginaryTrig

Returns the sine of the argument x. Uses the formula sin(i*x) == i*sinh(x).

proc sin(x: imag(64)) : imag(64)  where useNewImaginaryTrig

Returns the sine of the argument x. Uses the formula sin(i*x) == i*sinh(x).

proc sin(x: imag) : complex  where !useNewImaginaryTrig

Warning

The overload of ‘sin’ that takes an ‘imag’ argument and returns a ‘complex’ is deprecated and will be removed in the future. To opt-in to the new behavior, compile with -suseNewImaginaryTrig=true.

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

Returns the hyperbolic sine of the argument x.

proc sinh(x: complex(128)) : complex(128)

Returns the hyperbolic sine of the argument x.

proc sinh(x: imag(32)) : imag(32)  where useNewImaginaryTrig

Returns the hyperbolic sine of the argument x. Uses the formula sinh(i*x) == i*sin(x).

proc sinh(x: imag(64)) : imag(64)  where useNewImaginaryTrig

Returns the hyperbolic sine of the argument x. Uses the formula sinh(i*x) == i*sin(x).

proc sinh(x: imag) : complex  where !useNewImaginaryTrig

Warning

The overload of ‘sinh’ that takes an ‘imag’ argument and returns a ‘complex’ is deprecated and will be removed in the future. To opt-in to the new behavior, compile with -suseNewImaginaryTrig=true.

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

Returns the tangent of the argument x.

proc tan(x: complex(128)) : complex(128)

Returns the tangent of the argument x.

proc tan(x: imag(32)) : imag(32)  where useNewImaginaryTrig

Returns the tangent of the argument x. Uses the formula tan(i*x) == i*tanh(x).

proc tan(x: imag(64)) : imag(64)  where useNewImaginaryTrig

Returns the tangent of the argument x. Uses the formula tan(i*x) == i*tanh(x).

proc tan(x: imag) : complex  where !useNewImaginaryTrig

Warning

The overload of ‘tan’ that takes an ‘imag’ argument and returns a ‘complex’ is deprecated and will be removed in the future. To opt-in to the new behavior, compile with -suseNewImaginaryTrig=true.

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

Returns the hyperbolic tangent of the argument x.

proc tanh(x: complex(128)) : complex(128)

Returns the hyperbolic tangent of the argument x.

proc tanh(x: imag(32)) : imag(32)  where useNewImaginaryTrig

Returns the hyperbolic tangent of the argument x. Uses the formula tanh(i*x) == i*tan(x).

proc tanh(x: imag(64)) : imag(64)  where useNewImaginaryTrig

Returns the hyperbolic tangent of the argument x. Uses the formula tanh(i*x) == i*tan(x).

proc tanh(x: imag) : complex  where !useNewImaginaryTrig

Warning

The overload of ‘tanh’ that takes an ‘imag’ argument and returns a ‘complex’ is deprecated and will be removed in the future. To opt-in to the new behavior, compile with -suseNewImaginaryTrig=true.

proc gcd(in x: int, in y: int) : int

Returns the greatest common divisor of the integer arguments x and y.

proc gcd(in x: int(32), in y: int(32)) : int(32)

Returns the greatest common divisor of the integer arguments x and y.

proc gcd(in x: int(16), in y: int(16)) : int(16)

Returns the greatest common divisor of the integer arguments x and y.

proc gcd(in x: int(8), in y: int(8)) : int(8)

Returns the greatest common divisor of the integer arguments x and y.

proc gcd(in x: uint(64), in y: uint(64)) : uint(64)

Returns the greatest common divisor of the unsigned integer arguments x and y.

proc gcd(in x: uint(32), in y: uint(32)) : uint(32)

Returns the greatest common divisor of the unsigned integer arguments x and y.

proc gcd(in x: uint(16), in y: uint(16)) : uint(16)

Returns the greatest common divisor of the unsigned integer arguments x and y.

proc gcd(in x: uint(8), in y: uint(8)) : uint(8)

Returns the greatest common divisor of the unsigned integer arguments x and y.

proc j0(x: real(32)) : real(32)

Warning

‘j0’ is unstable and may be renamed or moved to a different module in the future

Returns the Bessel function of the first kind of order 0 of x.

proc j0(x: real(64)) : real(64)

Warning

‘j0’ is unstable and may be renamed or moved to a different module in the future

Returns the Bessel function of the first kind of order 0 of x.

proc j1(x: real(32)) : real(32)

Warning

‘j1’ is unstable and may be renamed or moved to a different module in the future

Returns the Bessel function of the first kind of order 1 of x.

proc j1(x: real(64)) : real(64)

Warning

‘j1’ is unstable and may be renamed or moved to a different module in the future

Returns the Bessel function of the first kind of order 1 of x.

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

Warning

‘jn’ is unstable and may be renamed or moved to a different module in the future

Returns the Bessel function of the first kind of order n of x.

proc jn(n: int, x: real(64)) : real(64)

Warning

‘jn’ is unstable and may be renamed or moved to a different module in the future

Returns the Bessel function of the first kind of order n of x.

proc y0(x: real(32)) : real(32)

Warning

‘y0’ is unstable and may be renamed or moved to a different module in the future

Returns the Bessel function of the second kind of order 0 of x, where x must be greater than 0.

proc y0(x: real(64)) : real(64)

Warning

‘y0’ is unstable and may be renamed or moved to a different module in the future

Returns the Bessel function of the second kind of order 0 of x, where x must be greater than 0.

proc y1(x: real(32)) : real(32)

Warning

‘y1’ is unstable and may be renamed or moved to a different module in the future

Returns the Bessel function of the second kind of order 1 of x, where x must be greater than 0.

proc y1(x: real(64)) : real(64)

Warning

‘y1’ is unstable and may be renamed or moved to a different module in the future

Returns the Bessel function of the second kind of order 1 of x, where x must be greater than 0.

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

Warning

‘yn’ is unstable and may be renamed or moved to a different module in the future

Returns the Bessel function of the second kind of order n of x, where x must be greater than 0.

proc yn(n: int, x: real(64)) : real(64)

Warning

‘yn’ is unstable and may be renamed or moved to a different module in the future

Returns the Bessel function of the second kind of order n of x, where x must be greater than 0.

proc fma(x: real(64), y: real(64), z: real(64)) : real(64)

Warning

The ‘fma()’ procedure was recently added, and may change based on feedback

Performs a fused multiply-add operation that multiplies x and y and adds z to the result. The advantage of fma() over the expression (x*y)+z is that it avoids the additional error introduced by performing two separate floating point operations. It can also be faster on machines that implement the operation as a single instruction.

Note

When compiling with CHPL_TARGET_COMPILER=llvm, this procedure should reliably generate a single hardware instruction on x86 if --specialize is thrown and CHPL_TARGET_CPU is set (provided that the x86 CPU supports hardware FMA).

When compiling with C, this procedure will call out to the fma() routines defined in the C header math.h. Any optimization performed is decided by the C compiler.

proc fma(x: real(32), y: real(32), z: real(32)) : real(32)

Warning

The ‘fma()’ procedure was recently added, and may change based on feedback