Module fixedpoint

Deterministic, no_std-compatible mathematical primitives for Substrate’s fixed-point numeric tower ([FixedU64], [FixedU128], [FixedI64], [FixedI128]).

All arithmetic is implemented without floating-point instructions, making every operation fully deterministic and suitable for on-chain execution where bit-identical results across heterogeneous validator hardware are required.

Type System

Three layered abstractions bridge raw integers and fixed-point values:

Trait	Role
FixedForInteger	Associates each primitive integer with its natural fixed-point counterpart
IntegerToFixed	Round-trip to_fixed / from_fixed with saturation at type boundaries
FixedSignedCast	Lifts unsigned types into signed arithmetic space for operations that require negative intermediates, then projects the result back

Operations

Function	Description
fixed_sqrt	Square root - real domain; returns None for negatives
complex_sqrt	Square root - complex domain; imaginary output for x<0
fixed_exp	Natural exponential e^x
fixed_ln	Natural logarithm ln(x), defined for x > 0
fixed_pow	General power x^p - integer and fractional exponents

Operations are exposed through the FixedOp and FixedComplexOp trait facades, so generic code can be written against a single trait bound and work across all four fixed-point types without specialisation.

Design Notes

• No panics. All public entry-points return Option<T> so that undefined inputs (negative logarithm, zero base with negative exponent, etc.) are expressed as None rather than a runtime abort.
• Saturating internal arithmetic. Intermediate overflow clamps to the type’s representable range rather than wrapping or panicking.
• Convergence guarantees. Every iterative algorithm is hard-capped at MAX_ITERATIONS and also checks for stagnation, so no function can loop indefinitely regardless of input.

Planned Extensions

Trigonometric, hyperbolic, special (gamma, erf), and additional root / power functions are outlined in the PLANNED EXTENSIONS section at the bottom of this file. New operations should implement the corresponding method on FixedOp (or a new companion trait) and follow the same Option-returning, saturation-safe conventions established here.

Macros

impl_fixed_convert_signed 🔒

Implements IntegerToFixed conversion for all signed integer types in the list.

impl_fixed_convert_unsigned 🔒

Implements IntegerToFixed conversion for all unsigned integer types in the list.

int_best_fixed 🔒

Macro to conveniently implement FixedForInteger for multiple integer types at once.

Structs

Complex

A simple, generic complex number representation.

Constants

MAX_ITERATIONS 🔒

Maximum allowed number of iterations for iterative numerical methods.

Traits

FixedComplexOp

Interface for complex-valued fixed-point operations.

FixedForInteger

Trait mapping primitive integer types to an appropriate fixed-point type.

FixedOp

Unified interface for core fixed-point mathematical operations.

FixedPointInfo

Provides precision metadata for fixed-point types used in numerical series computations.

FixedSignedCast

A bridge that allows any [FixedPointNumber] type - including unsigned ones - to perform arithmetic in a signed intermediate space, then project the result back to the original type.

IntegerToFixed

Trait for converting a numeric type to and from its associated fixed-point type.

Functions

complex_sqrt 🔒

Computes the principal square root of a fixed-point number, returning a Complex result.

dynamic_max_iterations 🔒

Computes an adaptive iteration count for series expansions based on the magnitude of x and the precision of the fixed-point type.

fixed_exp 🔒

Computes e^x for a fixed-point number using argument reduction and a Taylor series expansion.

fixed_ln 🔒

Computes the natural logarithm ln(x) for a fixed-point number.

fixed_pi 🔒

fixed_pow 🔒

Computes x^p for fixed-point numbers.

fixed_powi 🔒

Raises a fixed-point number x to an integer power n using binary exponentiation.

fixed_powi_positive 🔒

Core binary exponentiation for non-negative integer powers.

fixed_sqrt 🔒

Computes the square root of a fixed-point number [FixedPointNumber] x.

fixed_sqrt_newton 🔒

Approximates the square root of a fixed-point number using the Newton-Raphson method.

fixed_to_i128 🔒

Extracts the exact integer value of a fixed-point number as i128, returning None if the value has a non-zero fractional component.

ln_near_one 🔒

Computes ln(y) for a fixed-point value y near 1 using the arctanh series identity:

range_reduce_sqrt 🔒

Reduces a fixed-point value y toward 1 by repeatedly taking its square root, returning the reduced value and the number of reductions applied.

to_u32_floor 🔒

Extracts the integer part of a fixed-point number as a u32, truncating the fractional component toward zero.

ulp 🔒

Returns the smallest positive increment representable by the fixed-point generic [FixedPointNumber].