pymath

█ OVERVIEW

This library ➕ enhances Pine Script's built-in types (`float`, `int`, `array<float>`, `array<int>`) with mathematical methods, mirroring 🪞 many functions from Python's `math` module. Import this library to overload or add to built-in capabilities, enabling calls like `myFloat.sin()` or `myIntArray.gcd()`.

█ CONCEPTS

This library wraps Pine's built-in `math.*` functions and implements others where necessary, expanding the mathematical toolkit available within Pine Script. It provides a more object-oriented approach to mathematical operations on core data types.

█ HOW TO USE

 • Import the library: import kaigouthro/pymath/1
 • Call methods directly on variables: myFloat.sin() , myIntArray.gcd()

 • For raw integer literals, you MUST use parentheses: `(1234).factorial()`.

█ FEATURES

 • **Infinity Handling:** Includes `isinf()` and `isfinite()` for robust checks. Uses `POS_INF_PROXY` to represent infinity.
 • **Comprehensive Math Functions:** Implements a wide range of methods, including trigonometric, logarithmic, hyperbolic, and array operations.
 • **Object-Oriented Approach:** Allows direct method calls on `int`, `float`, and arrays for cleaner code.
 • **Improved Accuracy:** Some functions (e.g., `remainder()`) offer improved accuracy compared to default Pine behavior.
 • **Helper Functions:** Internal helper functions optimize calculations and handle edge cases.

█ NOTES

This library improves upon Pine Script's built-in `math` functions by adding new ones and refining existing implementations. It handles edge cases such as infinity, NaN, and zero values, enhancing the reliability of your Pine scripts. For Speed, it wraps and uses built-ins, as thy are fastest.

█ EXAMPLES

//@version=6
indicator("My Indicator") 

// Import the library
import kaigouthro/pymath/1

// Create some Vars
float myFloat = 3.14159
int myInt = 10
array<int> myIntArray = array.from(1, 2, 3, 4, 5)

// Now you can...
plot( myFloat.sin()   )          // Use sin() method on a float, using built in wrapper
plot( (myInt).factorial() )    // Factorial of an integer (note parentheses)
plot( myIntArray.gcd()   )     // GCD of an integer array

method isinf(self)
  isinf: Checks if this float is positive or negative infinity using a proxy value.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) [STALE?] value to check.
  Returns: (bool) `true` if the absolute value of `self` is greater than or equal to the infinity proxy, `false` otherwise.

method isfinite(self)
  isfinite: Checks if this float is finite (not NaN and not infinity).
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The value to check.
  Returns: (bool) `true` if `self` is not `na` and not infinity (as defined by `isinf()`), `false` otherwise.

method fmod(self, divisor)
  fmod: Returns the C-library style floating-point remainder of `self / divisor` (result has the sign of `self`).
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) Dividend `x`.
    divisor (float): (float) Divisor `y`. Cannot be zero or `na`.
  Returns: (float) The remainder `x - n*y` where n is `trunc(x/y)`, or `na` if divisor is 0, `na`, or inputs are infinite in a way that prevents calculation.

method factorial(self)
  factorial: Calculates the factorial of this non-negative integer.
  Namespace types: series int, simple int, input int, const int
  Parameters:
    self (int): (int) The integer `n`. Must be non-negative.
  Returns: (float) `n!` as a float, or `na` if `n` is negative or overflow occurs (based on `isinf`).

method isqrt(self)
  isqrt: Calculates the integer square root of this non-negative integer (floor of the exact square root).
  Namespace types: series int, simple int, input int, const int
  Parameters:
    self (int): (int) The non-negative integer `n`.
  Returns: (int) The greatest integer `a` such that a² <= n, or `na` if `n` is negative.

method comb(self, k)
  comb: Calculates the number of ways to choose `k` items from `self` items without repetition and without order (Binomial Coefficient).
  Namespace types: series int, simple int, input int, const int
  Parameters:
    self (int): (int) Total number of items `n`. Must be non-negative.
    k (int): (int) Number of items to choose. Must be non-negative.
  Returns: (float) The binomial coefficient nCk, or `na` if inputs are invalid (n<0 or k<0), `k > n`, or overflow occurs.

method perm(self, k)
  perm: Calculates the number of ways to choose `k` items from `self` items without repetition and with order (Permutations).
  Namespace types: series int, simple int, input int, const int
  Parameters:
    self (int): (int) Total number of items `n`. Must be non-negative.
    k (simple int): (simple int = na) Number of items to choose. Must be non-negative. Defaults to `n` if `na`.
  Returns: (float) The number of permutations nPk, or `na` if inputs are invalid (n<0 or k<0), `k > n`, or overflow occurs.

method log2(self)
  log2: Returns the base-2 logarithm of this float. Input must be positive. Wraps `math.log(self) / math.log(2.0)`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number. Must be positive.
  Returns: (float) The base-2 logarithm, or `na` if input <= 0.

method trunc(self)
  trunc: Returns this float with the fractional part removed (truncates towards zero).
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number.
  Returns: (int) The integer part, or `na` if input is `na` or infinite.

method abs(self)
  abs: Returns the absolute value of this float. Wraps `math.abs()`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number.
  Returns: (float) The absolute value, or `na` if input is `na`.

method acos(self)
  acos: Returns the arccosine of this float, in radians. Wraps `math.acos()`. Input must be between -1 and 1.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number. Must be between -1 and 1.
  Returns: (float) Angle in radians [0, pi], or `na` if input is outside [-1, 1] or `na`.

method asin(self)
  asin: Returns the arcsine of this float, in radians. Wraps `math.asin()`. Input must be between -1 and 1.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number. Must be between -1 and 1.
  Returns: (float) Angle in radians [-pi/2, pi/2], or `na` if input is outside [-1, 1] or `na`.

method atan(self)
  atan: Returns the arctangent of this float, in radians. Wraps `math.atan()`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number.
  Returns: (float) Angle in radians [-pi/2, pi/2], or `na` if input is `na`.

method ceil(self)
  ceil: Returns the ceiling of this float (smallest integer >= self). Wraps `math.ceil()`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number.
  Returns: (int) The ceiling value, or `na` if input is `na` or infinite.

method cos(self)
  cos: Returns the cosine of this float (angle in radians). Wraps `math.cos()`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The angle in radians.
  Returns: (float) The cosine, or `na` if input is `na`.

method degrees(self)
  degrees: Converts this float from radians to degrees. Wraps `math.todegrees()`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The angle in radians.
  Returns: (float) The angle in degrees, or `na` if input is `na`.

method exp(self)
  exp: Returns e raised to the power of this float. Wraps `math.exp()`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The exponent.
  Returns: (float) `e**self`, or `na` if input is `na`.

method floor(self)
  floor: Returns the floor of this float (largest integer <= self). Wraps `math.floor()`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number.
  Returns: (int) The floor value, or `na` if input is `na` or infinite.

method log(self)
  log: Returns the natural logarithm (base e) of this float. Wraps `math.log()`. Input must be positive.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number. Must be positive.
  Returns: (float) The natural logarithm, or `na` if input <= 0 or `na`.

method log10(self)
  log10: Returns the base-10 logarithm of this float. Wraps `math.log10()`. Input must be positive.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number. Must be positive.
  Returns: (float) The base-10 logarithm, or `na` if input <= 0 or `na`.

method pow(self, exponent)
  pow: Returns this float raised to the power of `exponent`. Wraps `math.pow()`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The base.
    exponent (float): (float) The exponent.
  Returns: (float) `self**exponent`, or `na` if inputs are `na` or lead to undefined results.

method radians(self)
  radians: Converts this float from degrees to radians. Wraps `math.toradians()`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The angle in degrees.
  Returns: (float) The angle in radians, or `na` if input is `na`.

method round(self)
  round: Returns the nearest integer to this float. Wraps `math.round()`. Ties are rounded away from zero.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number.
  Returns: (int) The rounded integer, or `na` if input is `na` or infinite.

method sign(self)
  sign: Returns the sign of this float (-1, 0, or 1). Wraps `math.sign()`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number.
  Returns: (int) -1 if negative, 0 if zero, 1 if positive, `na` if input is `na`.

method sin(self)
  sin: Returns the sine of this float (angle in radians). Wraps `math.sin()`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The angle in radians.
  Returns: (float) The sine, or `na` if input is `na`.

method sqrt(self)
  sqrt: Returns the square root of this float. Wraps `math.sqrt()`. Input must be non-negative.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number. Must be non-negative.
  Returns: (float) The square root, or `na` if input < 0 or `na`.

method tan(self)
  tan: Returns the tangent of this float (angle in radians). Wraps `math.tan()`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The angle in radians.
  Returns: (float) The tangent, or `na` if input is `na`.

method acosh(self)
  acosh: Returns the inverse hyperbolic cosine of this float. Input must be >= 1.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number. Must be >= 1.
  Returns: (float) The inverse hyperbolic cosine, or `na` if input < 1 or `na`.

method asinh(self)
  asinh: Returns the inverse hyperbolic sine of this float.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number.
  Returns: (float) The inverse hyperbolic sine, or `na` if input is `na`.

method atanh(self)
  atanh: Returns the inverse hyperbolic tangent of this float. Input must be between -1 and 1 (exclusive).
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number. Must be between -1 and 1 (exclusive).
  Returns: (float) The inverse hyperbolic tangent, or `na` if input is outside (-1, 1) or `na`.

method cosh(self)
  cosh: Returns the hyperbolic cosine of this float.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number.
  Returns: (float) The hyperbolic cosine, or `na` if input is `na`.

method sinh(self)
  sinh: Returns the hyperbolic sine of this float.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number.
  Returns: (float) The hyperbolic sine, or `na` if input is `na`.

method tanh(self)
  tanh: Returns the hyperbolic tangent of this float.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The input number.
  Returns: (float) The hyperbolic tangent, or `na` if input is `na`.

method atan2(self, dx)
  atan2: Returns the angle in radians between the positive x-axis and the point (dx, self). Wraps `math.atan2()`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The y-coordinate `y`.
    dx (float): (float) The x-coordinate `x`.
  Returns: (float) The angle in radians [-pi, pi], result of `math.atan2(self, dx)`. Returns `na` if inputs are `na`. Note: `math.atan2(0, 0)` returns 0 in Pine.
Optimization: Use built-in math.atan2()

method cbrt(self)
  cbrt: Returns the cube root of this float.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The value to find the cube root of.
  Returns: (float) The real cube root. Handles negative inputs correctly, or `na` if input is `na`.

method exp2(self)
  exp2: Returns 2 raised to the power of this float. Calculated as `2.0.pow(self)`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The exponent.
  Returns: (float) `2**self`, or `na` if input is `na` or results in non-finite value.

method expm1(self)
  expm1: Returns `e**self - 1`. Calculated as `self.exp() - 1.0`. May offer better precision for small `self` in some environments, but Pine provides no guarantee over `self.exp() - 1.0`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The exponent.
  Returns: (float) `e**self - 1`, or `na` if input is `na` or `self.exp()` is `na`.

method log1p(self)
  log1p: Returns the natural logarithm of (1 + self). Calculated as `(1.0 + self).log()`. Pine provides no specific precision guarantee for self near zero.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) Value to add to 1. `1 + self` must be positive.
  Returns: (float) Natural log of `1 + self`, or `na` if input is `na` or `1 + self <= 0`.

method modf(self)
  modf: Returns the fractional and integer parts of this float as a tuple `[fractional, integer]`. Both parts have the sign of `self`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The number `x` to split.
  Returns: ([float, float]) A tuple containing `[fractional_part, integer_part]`, or `[na, na]` if `x` is `na` or non-finite.

method remainder(self, divisor)
  remainder: Returns the IEEE 754 style remainder of `self` with respect to `divisor`. Result `r` satisfies `abs(r) <= 0.5 * abs(divisor)`. Uses round-half-to-even.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) Dividend `x`.
    divisor (float): (float) Divisor `y`. Cannot be zero or `na`.
  Returns: (float) The IEEE 754 remainder, or `na` if divisor is 0, `na`, or inputs are non-finite in a way that prevents calculation.

method copysign(self, signSource)
  copysign: Returns a float with the magnitude (absolute value) of `self` but the sign of `signSource`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) Value providing the magnitude `x`.
    signSource (float): (float) Value providing the sign `y`.
  Returns: (float) `abs(x)` with the sign of `y`, or `na` if either input is `na`.

method frexp(self)
  frexp: Returns the mantissa (m) and exponent (e) of this float `x` as `[m, e]`, such that `x = m * 2^e` and `0.5 <= abs(m) < 1` (unless `x` is 0).
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) The number `x` to decompose.
  Returns: ([float, int]) A tuple `[mantissa, exponent]`, or `[0.0, 0]` if `x` is 0, or `[na, na]` if `x` is non-finite or `na`.

method isclose(self, other, rel_tol, abs_tol)
  isclose: Checks if this float `a` and `other` float `b` are close within relative and absolute tolerances.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) First value `a`.
    other (float): (float) Second value `b`.
    rel_tol (simple float): (simple float = 1e-9) Relative tolerance. Must be non-negative and less than 1.0.
    abs_tol (simple float): (simple float = 0.0) Absolute tolerance. Must be non-negative.
  Returns: (bool) `true` if `abs(a - b) <= max(rel_tol * max(abs(a), abs(b)), abs_tol)`. Handles `na`/`inf` appropriately. Returns `na` if tolerances are invalid.

method ldexp(self, exponent)
  ldexp: Returns `self * (2**exponent)`. Inverse of `frexp`.
  Namespace types: series float, simple float, input float, const float
  Parameters:
    self (float): (float) Mantissa part `x`.
    exponent (int): (int) Exponent part `i`.
  Returns: (float) The result of `x * pow(2, i)`, or `na` if inputs are `na` or result is non-finite.

method gcd(self)
  gcd: Calculates the Greatest Common Divisor (GCD) of all integers in this array.
  Namespace types: array<int>
  Parameters:
    self (array<int>): (array<int>) An array of integers.
  Returns: (int) The largest positive integer that divides all non-zero elements, 0 if all elements are 0 or array is empty. Returns `na` if any element is `na`.

method lcm(self)
  lcm: Calculates the Least Common Multiple (LCM) of all integers in this array.
  Namespace types: array<int>
  Parameters:
    self (array<int>): (array<int>) An array of integers.
  Returns: (int) The smallest positive integer that is a multiple of all non-zero elements, 0 if any element is 0, 1 if array is empty. Returns `na` on potential overflow or if any element is `na`.

method dist(self, other)
  dist: Returns the Euclidean distance between this point `p` and another point `q` (given as arrays of coordinates).
  Namespace types: array<float>
  Parameters:
    self (array<float>): (array<float>) Coordinates of the first point `p`.
    other (array<float>): (array<float>) Coordinates of the second point `q`. Must have the same size as `p`.
  Returns: (float) The Euclidean distance, or `na` if arrays have different sizes, are empty, or contain `na`/non-finite values.

method fsum(self)
  fsum: Returns an accurate floating-point sum of values in this array. Uses built-in `array.sum()`. Note: Pine Script does not guarantee the same level of precision tracking as Python's `math.fsum`.
  Namespace types: array<float>
  Parameters:
    self (array<float>): (array<float>) The array of floats to sum.
  Returns: (float) The sum of the array elements. Returns 0.0 for an empty array. Returns `na` if any element is `na`.

method hypot(self)
  hypot: Returns the Euclidean norm (distance from origin) for this point given by coordinates in the array. `sqrt(sum(x*x for x in coordinates))`.
  Namespace types: array<float>
  Parameters:
    self (array<float>): (array<float>) Array of coordinates defining the point.
  Returns: (float) The Euclidean norm, or 0.0 if the array is empty. Returns `na` if any element is `na` or non-finite.

method prod(self, start)
  prod: Calculates the product of all elements in this array.
  Namespace types: array<float>
  Parameters:
    self (array<float>): (array<float>) The array of values to multiply.
    start (simple float): (simple float = 1.0) The starting value for the product (returned if the array is empty).
  Returns: (float) The product of array elements * start. Returns `na` if any element is `na`.

method sumprod(self, other)
  sumprod: Returns the sum of products of values from this array `p` and another array `q` (dot product).
  Namespace types: array<float>
  Parameters:
    self (array<float>): (array<float>) First array of values `p`.
    other (array<float>): (array<float>) Second array of values `q`. Must have the same size as `p`.
  Returns: (float) The sum of `p * q` for all i, or `na` if arrays have different sizes or contain `na`/non-finite values. Returns 0.0 for empty arrays.