Module functions 

Scalar Numerical Functions Module

This module provides a collection of traits and error types for common mathematical functions operating on scalar numerical values. These functions are designed to be generic over different floating-point and complex number types, including support for arbitrary-precision numbers via the rug library (when the “rug” feature is enabled).

Core Concepts

• Function Traits: Each mathematical operation (e.g., Exp, Ln, Sin, Pow, etc.) is defined by a trait. These traits typically offer two methods:

  • try_xxx(): A fallible method that performs comprehensive validation of inputs and outputs, returning a Result.
  • xxx(): An infallible method that aims for performance, especially in release builds. In debug builds, it usually calls try_xxx().unwrap().

• Error Handling: Errors are structured using the FunctionErrors enum, which distinguishes between input validation failures and output validation failures. Each function trait usually has an associated error type (e.g., ExpErrors, LogarithmRealErrors, etc.) that is a type alias for FunctionErrors specialized with function-specific input error enums (e.g., ExpInputErrors, LogarithmRealInputErrors, etc.).

• Validation: Input and output values are typically validated using policies defined in the validation module (as implementation of the ValidationPolicy trait from the try_create crate), with StrictFinitePolicy being commonly used to ensure values are not NaN, Infinity, or subnormal.

Provided Functions

The module re-exports traits and error types for various categories of functions:

• Basic Operations:
  • Abs: Absolute value.
  • NegAssign: In-place negation.
  • Reciprocal: Reciprocal (1/x).
  • Pow: Power function (base^exponent).
  • Sqrt: Square root.
• Exponential and Logarithmic:
  • Exp: Exponential function (e^x).
  • Ln: Natural logarithm.
  • Log2: Base-2 logarithm.
  • Log10: Base-10 logarithm.
• Trigonometric:
  • Sin, Cos, Tan: Basic trigonometric functions.
  • ASin, ACos, ATan: Inverse trigonometric functions.
  • ATan2: Four-quadrant inverse tangent.
• Hyperbolic:
  • SinH, CosH, TanH: Hyperbolic functions.
  • ASinH, ACosH, ATanH: Inverse hyperbolic functions.
• Complex Number Operations:
  • Arg: Argument (phase) of a complex number.
  • Conjugate: Complex conjugate.
• Comparison:
  • Max, Min: Maximum and minimum of two numbers.
• Real Number Specific:
  • Rounding: Ceiling, floor, rounding operations.
  • Sign: Sign manipulation and checking.
  • Clamp, Classify, ExpM1, Hypot, Ln1p, TotalCmp: Specialized real number operations.

Each function is organized into its own submodule (e.g., abs, exp) and its public interface is re-exported here.

Enums

ACosComplexInputErrors

Errors that can occur during the input validation phase when computing the inverse cosine of a complex number.

ACosHInputErrors

Errors that can occur during the computation of the inverse hyperbolic cosine.

ACosRealInputErrors

Errors that can occur during the input validation phase when computing the inverse cosine of a real number.

ASinComplexInputErrors

Errors that can occur during the input validation phase when computing the inverse sine of a complex number.

ASinHInputErrors

Errors that can occur during the computation of the inverse hyperbolic sine.

ASinRealInputErrors

Errors that can occur during the input validation phase when computing the inverse sine of a real number.

ATan2InputErrors

Errors that can occur during the input validation phase when attempting to compute the 2-argument arctangent (atan2).

ATanComplexInputErrors

Errors that can occur during the input validation phase when attempting to compute the arctangent of a complex number.

ATanHInputErrors

Errors that can occur during the computation of the inverse hyperbolic tangent.

ATanRealInputErrors

Errors that can occur during the input validation phase when computing the inverse tangent of a real number.

AbsInputErrors

Errors that can occur during the input validation phase when attempting to compute the absolute value of a number.

ArgInputErrors

Errors that can occur specifically during the input validation phase or due to special input values when attempting to compute the argument (principal value) of a complex number.

CosHInputErrors

Errors that can occur during the computation of the hyperbolic cosine.

CosInputErrors

Errors that can occur during the input validation phase when computing the cosine of a real or complex number.

ExpInputErrors

Errors that can occur during the input validation phase when attempting to compute the exponential of a number.

FunctionErrors

A generic error type for fallible numerical function computations.

LogarithmComplexInputErrors

Errors that can occur when computing the logarithm of a complex number.

LogarithmRealInputErrors

Errors that can occur when computing the logarithm of a real number.

PowComplexBaseRealExponentErrors

Errors that can occur when computing base^exponent where the base is complex and the exponent is real.

PowComplexBaseRealExponentInputErrors

Errors that can occur during input validation when computing base^exponent where the base is a complex number and the exponent is a real number.

PowIntExponentInputErrors

Errors that can occur during input validation when computing base^exponent where the exponent is an integer type.

PowRealBaseRealExponentErrors

Errors that can occur when computing base^exponent where both base and exponent are real numbers.

PowRealBaseRealExponentInputErrors

Errors that can occur during input validation when computing base^exponent where both the base and exponent are real numbers.

ReciprocalInputErrors

Errors that can occur during the input validation phase or due to special input values when attempting to compute the reciprocal of a number.

SinHInputErrors

Errors that can occur during the computation of the hyperbolic sine.

SinInputErrors

Errors that can occur during the input validation phase when computing the sine of a real or complex number.

SqrtComplexInputErrors

Errors that can occur during the input validation phase when computing the square root of a complex number.

SqrtRealInputErrors

Errors that can occur during the input validation phase when attempting to compute the square root of a real number.

TanComplexInputErrors

Errors that can occur during the input validation phase when computing the tangent of a complex number.

TanHComplexInputErrors

Errors that can occur when computing the hyperbolic tangent of a complex number.

TanHRealInputErrors

Errors that can occur when computing the hyperbolic tangent of a real number.

TanRealInputErrors

Errors that can occur during the input validation phase when computing the tangent of a real number.

Traits

ACos

Trait for computing the inverse cosine of a number.

ACosH

Trait for computing the inverse hyperbolic cosine of a number.

ASin

Trait for computing the inverse sine of a number.

ASinH

Trait for computing the inverse hyperbolic sine of a number.

ATan

Trait for computing the inverse tangent of a number.

ATan2

Trait for computing the 2-argument arctangent of two numbers, y (self) and x (denominator).

ATanH

Trait for computing the inverse hyperbolic tangent of a number.

Abs

This trait provides the interface for the function used to compute the absolute value (also known as modulus or magnitude) of a number, which can be real or complex.

Arg

Trait for computing the argument (principal value) of a complex number.

Arithmetic

A convenience trait that aggregates the standard arithmetic operations.

Clamp

Trait for clamping a value between minimum and maximum bounds.

Classify

Trait for classifying floating-point values into categories.

ComplexScalarConstructors

Trait for constructing complex scalar types from their raw components.

ComplexScalarGetParts

Trait for accessing the real and imaginary components of a complex scalar.

ComplexScalarMutateParts

Provides methods for in-place mutation of the components of a complex scalar.

ComplexScalarSetParts

Trait for setting the real and imaginary components of a complex scalar.

Conjugate

Trait for computing the complex conjugate of a number.

Cos

Trait for computing the cosine of a number.

CosH

Trait for computing the hyperbolic cosine of a number.

Exp

A trait for computing the exponential function (e^x).

ExpM1

Trait for computing exp(x) - 1 with high precision for small values.

HyperbolicFunctions

A convenience trait that aggregates the standard hyperbolic functions and their inverses.

Hypot

Trait for computing the Euclidean distance (hypotenuse) between two values.

Ln

Trait for computing the natural logarithm (base e) of a number.

Ln1p

Trait for computing ln(1 + x) with high precision for small values.

Log2

Trait for computing the base-2 logarithm of a number.

Log10

Trait for computing the base-10 logarithm of a number.

LogarithmFunctions

A convenience trait that aggregates the standard logarithm functions.

Max

A trait for finding the maximum of two values.

Min

A trait for finding the minimum of two values.

MulAddRef

Trait for fused multiply-add operations.

NegAssign

Compound negation and assignment.

Pow

A trait for computing the power of a number (base^exponent).

PowIntExponent

An aggregate trait for types that can be raised to the power of any primitive integer.

Reciprocal

A trait for computing the reciprocal (1/x) of a number.

Rounding

Provides methods for rounding floating-point numbers.

Sign

Provides methods for sign manipulation and checking.

Sin

Trait for computing the sine of a number.

SinH

Trait for computing the hyperbolic sine of a number.

Sqrt

A trait for computing the principal square root of a number.

Tan

Trait for computing the tangent of a number.

TanH

Trait for computing the hyperbolic tangent of a number.

TotalCmp

Trait for total ordering comparison of floating-point values.

TrigonometricFunctions

A convenience trait that aggregates the standard trigonometric functions and their inverses.

Type Aliases

ACosComplexErrors

A type alias for FunctionErrors, specialized for errors during inverse cosine computation on a complex number.

ACosHErrors

Errors that can occur when computing the inverse hyperbolic cosine of a real or complex number.

ACosRealErrors

A type alias for FunctionErrors, specialized for errors during inverse cosine computation on a real number.

ASinComplexErrors

A type alias for FunctionErrors, specialized for errors during inverse sine computation on a complex number.

ASinHErrors

Errors that can occur when computing the inverse hyperbolic sine of a real or complex number.

ASinRealErrors

A type alias for FunctionErrors, specialized for errors during inverse sine computation on a real number.

ATan2Errors

A type alias for FunctionErrors, specialized for errors that can occur during the computation of the 2-argument arctangent (atan2).

ATanComplexErrors

A type alias for FunctionErrors, specialized for errors during inverse tangent computation on a complex number.

ATanHErrors

Errors that can occur when computing the inverse hyperbolic tangent of a real or complex number.

ATanRealErrors

A type alias for FunctionErrors, specialized for errors during inverse tangent computation on a real number.

AbsComplexErrors

A type alias for FunctionErrors, specialized for errors that can occur during the computation of the absolute value (or modulus) of a complex number.

AbsRealErrors

A type alias for FunctionErrors, specialized for errors that can occur during the computation of the absolute value of a real number.

ArgErrors

A type alias for FunctionErrors, specialized for errors that can occur during the computation of the argument (principal value) of a complex number.

CosErrors

A type alias for FunctionErrors, specialized for errors during cosine computation on a real or complex number.

CosHErrors

Errors that can occur when computing the hyperbolic cosine of a real or complex number.

ExpErrors

Errors that can occur during the computation of the exponential of a real or complex number.

LogarithmComplexErrors

Errors that can occur when computing the logarithm of a complex number.

LogarithmRealErrors

Errors that can occur when computing the logarithm of a real number.

PowIntExponentErrors

A type alias for FunctionErrors, specialized for errors that can occur when computing base^exponent where the exponent is an integer type.

ReciprocalErrors

A type alias for FunctionErrors, specialized for errors that can occur during the computation of the reciprocal of a scalar number.

SinErrors

A type alias for FunctionErrors, specialized for errors during sine computation on a real or complex number.

SinHErrors

Errors that can occur when computing the hyperbolic sine of a real or complex number.

SqrtComplexErrors

A type alias for FunctionErrors, specialized for errors that can occur during the computation of the square root of a complex number.

SqrtRealErrors

A type alias for FunctionErrors, specialized for errors that can occur during the computation of the square root of a real number.

TanComplexErrors

A type alias for FunctionErrors, specialized for errors during tangent computation on a complex number.

TanHComplexErrors

Errors that can occur when computing the hyperbolic tangent of a complex number.

TanHRealErrors

Errors that can occur when computing the hyperbolic tangent of a real number.

TanRealErrors

A type alias for FunctionErrors, specialized for errors during tangent computation on a real number.