Module functions

Expand description

§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.

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
Classify
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
HyperbolicFunctions: A convenience trait that aggregates the standard hyperbolic functions and their inverses.
Hypot
Ln: Trait for computing the natural logarithm (base e) of a number.
Ln1p
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
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.