yade.math module

This python module exposes all C++ math functions for Real and Complex types to python. In fact it sort of duplicates import math, import cmath or import mpmath. Also it facilitates migration of old python scripts to high precision calculations.

This module has following purposes:

  1. To reliably test all C++ math functions of arbitrary precision Real and Complex types against mpmath.
  2. To act as a “migration helper” for python scripts which call python mathematical functions that do not work well with mpmath. As an example see math.linspace below and this merge request
  3. 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)
  4. To test Eigen NumTraits
  5. To test CGAL NumTraits

If another C++ 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
  4. py/tests/testMathHelper.py

If another python math function does not work well with mpmath it should be added below, and original calls to this function should call this function instead, e.g. numpy.linspace(…) is replaced with yade.math.linspace(…).

yade.math.linspace(a, b, num)[source]

This function calls numpy.linspace(…) or mpmath.linspace(…), because numpy.linspace function does not work with mpmath.

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.