yade.math module

This python module exposes all C++ math functions for Real and Complex type to python. In fact it sort of duplicates import math, import cmath or import mpmath. This module has four purposes:

  1. to reliably test all C++ math functions of arbitrary precision Real and Complex types against mpmath.
  2. to test Eigen NumTraits
  3. to test CGAL NumTraits
  4. To allow writing python math code in a way that mirrors C++ math code in yade. As a bonus it will be faster than mpmath because mpmath is a purely python library (which was one of the main difficulties when writing lib/high-precision/ToFromPythonConverter.hpp)

If another math function is needed it should be added to following files:

  1. lib/high-precision/MathFunctions.hpp
  2. py/high-precision/_math.cpp
  3. py/tests/testMath.py
yade._math.CGAL_Is_finite((float)x) → bool

CGAL’s function Is_finite, as described in CGAL algebraic foundations exposed to python for testing of CGAL numerical traits.

Returns:bool indicating if the Real argument is finite.
yade._math.CGAL_Is_valid((float)x) → bool

CGAL’s function Is_valid, as described in CGAL algebraic foundations exposed to python for testing of CGAL numerical traits.

Returns:bool indicating if the Real argument is valid. Checks are performed against NaN and Inf.
yade._math.CGAL_Kth_root((int)arg1, (float)x) → float

CGAL’s function Kth_root, as described in CGAL algebraic foundations exposed to python for testing of CGAL numerical traits.

Returns:Real the k-th root of argument.
yade._math.CGAL_Sgn((float)x) → int

CGAL’s function Sgn, as described in CGAL algebraic foundations exposed to python for testing of CGAL numerical traits.

Returns:sign of the argument, can be -1, 0 or 1. Not very useful in python. In C++ it is useful to obtain a sign of an expression with exact accuracy, CGAL starts using MPFR internally for this when the approximate interval contains zero inside it.
yade._math.CGAL_Sqrt((float)x) → float

CGAL’s function Sqrt, as described in CGAL algebraic foundations exposed to python for testing of CGAL numerical traits.

Returns:Real the square root of argument.
yade._math.CGAL_Square((float)x) → float

CGAL’s function Square, as described in CGAL algebraic foundations exposed to python for testing of CGAL numerical traits.

Returns:Real the argument squared.
yade._math.CGAL_To_interval((float)x) → tuple

CGAL’s function To_interval, as described in CGAL algebraic foundations exposed to python for testing of CGAL numerical traits.

Returns:(double,double) tuple inside which the high-precision Real argument resides.
yade._math.CGAL_simpleTest() → float

Tests a simple CGAL calculation. Distance between plane and point, uses CGAL’s sqrt and pow.

Returns:3.0
yade._math.Catalan([(int)Precision=53]) → float
Returns:Real The catalan constant, exposed to python for testing of eigen numerical traits.
yade._math.Euler([(int)Precision=53]) → float
Returns:Real The Euler–Mascheroni constant, exposed to python for testing of eigen numerical traits.
yade._math.Log2([(int)Precision=53]) → float
Returns:Real natural logarithm of 2, exposed to python for testing of eigen numerical traits.
yade._math.Pi([(int)Precision=53]) → float
Returns:Real The π constant, exposed to python for testing of eigen numerical traits.
class yade._math.Var

The Var class is used to test to/from python converters for arbitrary precision Real

cpl

one Complex variable to test reading from and writing to it.

val

one Real variable for testing.

yade._math.abs((complex)x) → float
return:the Real absolute value of the Complex argument. Depending on compilation options wraps ::boost::multiprecision::abs(…) or std::abs(…) function.
abs( (float)x) → float :
return:the Real absolute value of the Real argument. Depending on compilation options wraps ::boost::multiprecision::abs(…) or std::abs(…) function.
yade._math.acos((float)x) → float
Returns:Real the arcus cosine of the argument. Depending on compilation options wraps ::boost::multiprecision::acos(…) or std::acos(…) function.
yade._math.acosh((float)x) → float
Returns:Real the hyperbolic arcus cosine of the argument. Depending on compilation options wraps ::boost::multiprecision::acosh(…) or std::acosh(…) function.
yade._math.asin((float)x) → float
Returns:Real the arcus sine of the argument. Depending on compilation options wraps ::boost::multiprecision::asin(…) or std::asin(…) function.
yade._math.asinh((float)x) → float
Returns:Real the hyperbolic arcus sine of the argument. Depending on compilation options wraps ::boost::multiprecision::asinh(…) or std::asinh(…) function.
yade._math.atan((float)x) → float
Returns:Real the arcus tangent of the argument. Depending on compilation options wraps ::boost::multiprecision::atan(…) or std::atan(…) function.
yade._math.atan2((float)x, (float)y) → float
Returns:Real the arc tangent of y/x using the signs of the arguments x and y to determine the correct quadrant. Depending on compilation options wraps ::boost::multiprecision::atan2(…) or std::atan2(…) function.
yade._math.atanh((float)x) → float
Returns:Real the hyperbolic arcus tangent of the argument. Depending on compilation options wraps ::boost::multiprecision::atanh(…) or std::atanh(…) function.
yade._math.cbrt((float)x) → float
Returns:Real cubic root of the argument. Depending on compilation options wraps ::boost::multiprecision::cbrt(…) or std::cbrt(…) function.
yade._math.ceil((float)x) → float
Returns:Real Computes the smallest integer value not less than arg. Depending on compilation options wraps ::boost::multiprecision::ceil(…) or std::ceil(…) function.
yade._math.conj((complex)x) → complex
Returns:the complex conjugation a Complex argument. Depending on compilation options wraps ::boost::multiprecision::conj(…) or std::conj(…) function.
yade._math.cos((complex)x) → complex
return:Complex the cosine of the Complex argument in radians. Depending on compilation options wraps ::boost::multiprecision::cos(…) or std::cos(…) function.
cos( (float)x) → float :
return:Real the cosine of the Real argument in radians. Depending on compilation options wraps ::boost::multiprecision::cos(…) or std::cos(…) function.
yade._math.cosh((complex)x) → complex
return:Complex the hyperbolic cosine of the Complex argument in radians. Depending on compilation options wraps ::boost::multiprecision::cosh(…) or std::cosh(…) function.
cosh( (float)x) → float :
return:Real the hyperbolic cosine of the Real argument in radians. Depending on compilation options wraps ::boost::multiprecision::cosh(…) or std::cosh(…) function.
yade._math.dummy_precision() → float
Returns:similar to the function epsilon, but assumes that last 10% of bits contain the numerical error only. This is sometimes used by Eigen when calling isEqualFuzzy to determine if values differ a lot or if they are vaguely close to each other.
yade._math.epsilon([(int)Precision=53]) → float
return:Real returns the difference between 1.0 and the next representable value of the Real type. Wraps std::numeric_limits<Real>::epsilon() function.
epsilon( (float)x) → float :
return:Real returns the difference between 1.0 and the next representable value of the Real type. Wraps std::numeric_limits<Real>::epsilon() function.
yade._math.erf((float)x) → float
Returns:Real Computes the error function of argument. Depending on compilation options wraps ::boost::multiprecision::erf(…) or std::erf(…) function.
yade._math.erfc((float)x) → float
Returns:Real Computes the complementary error function of argument, that is 1.0-erf(arg). Depending on compilation options wraps ::boost::multiprecision::erfc(…) or std::erfc(…) function.
yade._math.exp((complex)x) → complex
return:the base e exponential of a Complex argument. Depending on compilation options wraps ::boost::multiprecision::exp(…) or std::exp(…) function.
exp( (float)x) → float :
return:the base e exponential of a Real argument. Depending on compilation options wraps ::boost::multiprecision::exp(…) or std::exp(…) function.
yade._math.exp2((float)x) → float
Returns:the base 2 exponential of a Real argument. Depending on compilation options wraps ::boost::multiprecision::exp2(…) or std::exp2(…) function.
yade._math.expm1((float)x) → float
Returns:the base e exponential of a Real argument minus 1.0. Depending on compilation options wraps ::boost::multiprecision::expm1(…) or std::expm1(…) function.
yade._math.fabs((float)x) → float
Returns:the Real absolute value of the argument. Depending on compilation options wraps ::boost::multiprecision::abs(…) or std::abs(…) function.
yade._math.floor((float)x) → float
Returns:Real Computes the largest integer value not greater than arg. Depending on compilation options wraps ::boost::multiprecision::floor(…) or std::floor(…) function.
yade._math.fma((float)x, (float)y, (float)z) → float
Returns:Real - computes (x*y) + z as if to infinite precision and rounded only once to fit the result type. Depending on compilation options wraps ::boost::multiprecision::fma(…) or std::fma(…) function.
yade._math.fmod((float)x, (float)y) → float
Returns:Real the floating-point remainder of the division operation x/y of the arguments x and y. Depending on compilation options wraps ::boost::multiprecision::fmod(…) or std::fmod(…) function.
yade._math.frexp((float)x) → tuple
Returns:tuple of (Real,int), decomposes given floating point Real argument into a normalized fraction and an integral power of two. Depending on compilation options wraps ::boost::multiprecision::frexp(…) or std::frexp(…) function.
yade._math.getEigenFlags() → dict
Returns:A python dictionary listing flags for all types, see: https://eigen.tuxfamily.org/dox/group__flags.html
yade._math.getEigenStorageOrders() → dict
Returns:A python dictionary listing options for all types, see: https://eigen.tuxfamily.org/dox/group__TopicStorageOrders.html
yade._math.highest([(int)Precision=53]) → float
Returns:Real returns the largest finite value of the Real type. Wraps std::numeric_limits<Real>::max() function.
yade._math.hypot((float)x, (float)y) → float
Returns:Real the square root of the sum of the squares of x and y, without undue overflow or underflow at intermediate stages of the computation. Depending on compilation options wraps ::boost::multiprecision::hypot(…) or std::hypot(…) function.
yade._math.ilogb((float)x) → float
Returns:Real extracts the value of the unbiased exponent from the floating-point argument arg, and returns it as a signed integer value. Depending on compilation options wraps ::boost::multiprecision::ilogb(…) or std::ilogb(…) function.
yade._math.imag((complex)x) → float
Returns:the imag part of a Complex argument. Depending on compilation options wraps ::boost::multiprecision::imag(…) or std::imag(…) function.
yade._math.isApprox((float)a, (float)b, (float)eps) → bool
Returns:bool, True if a is approximately equal b with provided eps, see also here
yade._math.isApproxOrLessThan((float)a, (float)b, (float)eps) → bool
Returns:bool, True if a is approximately less than or equal b with provided eps, see also here
yade._math.isEqualFuzzy((float)arg1, (float)arg2, (float)arg3) → bool
Returns:bool, True if the absolute difference between two numbers is smaller than std::numeric_limits<Real>::epsilon()
yade._math.isMuchSmallerThan((float)a, (float)b, (float)eps) → bool
Returns:bool, True if a is less than b with provided eps, see also here
yade._math.isfinite((float)x) → bool
Returns:bool indicating if the Real argument is Inf. Depending on compilation options wraps ::boost::multiprecision::isfinite(…) or std::isfinite(…) function.
yade._math.isinf((float)x) → bool
Returns:bool indicating if the Real argument is Inf. Depending on compilation options wraps ::boost::multiprecision::isinf(…) or std::isinf(…) function.
yade._math.isnan((float)x) → bool
Returns:bool indicating if the Real argument is NaN. Depending on compilation options wraps ::boost::multiprecision::isnan(…) or std::isnan(…) function.
yade._math.ldexp((float)x, (int)y) → float
Returns:Multiplies a floating point value x by the number 2 raised to the exp power. Depending on compilation options wraps ::boost::multiprecision::ldexp(…) or std::ldexp(…) function.
yade._math.lgamma((float)x) → float
Returns:Real Computes the natural logarithm of the absolute value of the gamma function of arg. Depending on compilation options wraps ::boost::multiprecision::lgamma(…) or std::lgamma(…) function.
yade._math.log((complex)x) → complex
return:the Complex natural (base e) logarithm of a complex value z with a branch cut along the negative real axis. Depending on compilation options wraps ::boost::multiprecision::log(…) or std::log(…) function.
log( (float)x) → float :
return:the Real natural (base e) logarithm of a real value. Depending on compilation options wraps ::boost::multiprecision::log(…) or std::log(…) function.
yade._math.log10((float)x) → float
Returns:the Real decimal (base 10) logarithm of a real value. Depending on compilation options wraps ::boost::multiprecision::log10(…) or std::log10(…) function.
yade._math.log1p((float)x) → float
Returns:the Real natural (base e) logarithm of 1+argument. Depending on compilation options wraps ::boost::multiprecision::log1p(…) or std::log1p(…) function.
yade._math.log2((float)x) → float
Returns:the Real binary (base 2) logarithm of a real value. Depending on compilation options wraps ::boost::multiprecision::log2(…) or std::log2(…) function.
yade._math.logb((float)x) → float
Returns:Extracts the value of the unbiased radix-independent exponent from the floating-point argument arg, and returns it as a floating-point value. Depending on compilation options wraps ::boost::multiprecision::logb(…) or std::logb(…) function.
yade._math.lowest([(int)Precision=53]) → float
Returns:Real returns the lowest (negative) finite value of the Real type. Wraps std::numeric_limits<Real>::lowest() function.
yade._math.max((float)x, (float)y) → float
Returns:Real larger of the two arguments. Depending on compilation options wraps ::boost::multiprecision::max(…) or std::max(…) function.
yade._math.min((float)x, (float)y) → float
Returns:Real smaller of the two arguments. Depending on compilation options wraps ::boost::multiprecision::min(…) or std::min(…) function.
yade._math.modf((float)x) → tuple
Returns:tuple of (Real,Real), decomposes given floating point Real into integral and fractional parts, each having the same type and sign as x. Depending on compilation options wraps ::boost::multiprecision::modf(…) or std::modf(…) function.
yade._math.pow((float)x, (float)y) → float
Returns:Real the value of base raised to the power exp. Depending on compilation options wraps ::boost::multiprecision::pow(…) or std::pow(…) function.
yade._math.random() → float
return:Real a symmetric random number in interval (-1,1). Used by Eigen.
random( (float)a, (float)b) → float :
return:Real a random number in interval (a,b). Used by Eigen.
yade._math.real((complex)x) → float
Returns:the real part of a Complex argument. Depending on compilation options wraps ::boost::multiprecision::real(…) or std::real(…) function.
yade._math.remainder((float)x, (float)y) → float
Returns:Real the IEEE remainder of the floating point division operation x/y. Depending on compilation options wraps ::boost::multiprecision::remainder(…) or std::remainder(…) function.
yade._math.remquo((float)x, (float)y) → tuple
Returns:tuple of (Real,long), the floating-point remainder of the division operation x/y as the std::remainder() function does. Additionally, the sign and at least the three of the last bits of x/y are returned, sufficient to determine the octant of the result within a period. Depending on compilation options wraps ::boost::multiprecision::remquo(…) or std::remquo(…) function.
yade._math.rint((float)x) → float
Returns:Rounds the floating-point argument arg to an integer value (in floating-point format), using the current rounding mode. Depending on compilation options wraps ::boost::multiprecision::rint(…) or std::rint(…) function.
yade._math.round((float)x) → float
Returns:Real the nearest integer value to arg (in floating-point format), rounding halfway cases away from zero, regardless of the current rounding mode.. Depending on compilation options wraps ::boost::multiprecision::round(…) or std::round(…) function.
yade._math.sgn((float)x) → int
Returns:int the sign of the argument: -1, 0 or 1.
yade._math.sign((float)x) → int
Returns:int the sign of the argument: -1, 0 or 1.
yade._math.sin((complex)x) → complex
return:Complex the sine of the Complex argument in radians. Depending on compilation options wraps ::boost::multiprecision::sin(…) or std::sin(…) function.
sin( (float)x) → float :
return:Real the sine of the Real argument in radians. Depending on compilation options wraps ::boost::multiprecision::sin(…) or std::sin(…) function.
yade._math.sinh((complex)x) → complex
return:Complex the hyperbolic sine of the Complex argument in radians. Depending on compilation options wraps ::boost::multiprecision::sinh(…) or std::sinh(…) function.
sinh( (float)x) → float :
return:Real the hyperbolic sine of the Real argument in radians. Depending on compilation options wraps ::boost::multiprecision::sinh(…) or std::sinh(…) function.
yade._math.smallest_positive() → float
Returns:Real the smallest number greater than zero. Wraps std::numeric_limits<Real>::min()
yade._math.sqrt((float)x) → float
Returns:Real square root of the argument. Depending on compilation options wraps ::boost::multiprecision::sqrt(…) or std::sqrt(…) function.
yade._math.tan((complex)x) → complex
return:Complex the tangent of the Complex argument in radians. Depending on compilation options wraps ::boost::multiprecision::tan(…) or std::tan(…) function.
tan( (float)x) → float :
return:Real the tangent of the Real argument in radians. Depending on compilation options wraps ::boost::multiprecision::tan(…) or std::tan(…) function.
yade._math.tanh((complex)x) → complex
return:Complex the hyperbolic tangent of the Complex argument in radians. Depending on compilation options wraps ::boost::multiprecision::tanh(…) or std::tanh(…) function.
tanh( (float)x) → float :
return:Real the hyperbolic tangent of the Real argument in radians. Depending on compilation options wraps ::boost::multiprecision::tanh(…) or std::tanh(…) function.
yade._math.testArray() → None

This function tests call to std::vector::data(…) function in order to extract the array.

yade._math.tgamma((float)x) → float
Returns:Real Computes the gamma function of arg. Depending on compilation options wraps ::boost::multiprecision::tgamma(…) or std::tgamma(…) function.
yade._math.toDouble((float)x) → float
Returns:float converts Real type to double and returns a native python float.
yade._math.toInt((float)x) → int
Returns:int converts Real type to int and returns a native python int.
yade._math.toLong((float)x) → int
Returns:int converts Real type to long int and returns a native python int.
yade._math.toLongDouble((float)x) → float
Returns:float converts Real type to long double and returns a native python float.
yade._math.trunc((float)x) → float
Returns:Real the nearest integer not greater in magnitude than arg. Depending on compilation options wraps ::boost::multiprecision::trunc(…) or std::trunc(…) function.