Module fixed 

Functions for handling fixed-point arithmetic.

This module provides constants and functions that enforce a fixed-point precision strategy, ensuring consistent precision and scaling across various types and calculations.

Raw Value Requirements

When constructing value types like Price or Quantity using from_raw, the raw value must be a valid multiple of the scale factor for the given precision. Valid raw values should ideally come from:

• Accessing the .raw field of an existing value (e.g., price.raw)
• Using the fixed-point conversion functions in this module
• Values from Nautilus-produced Arrow data

Raw values that are not valid multiples will cause a panic on construction in debug builds, and may result in incorrect values in release builds.

Legacy Catalog Data and Floating-Point Errors

Data written to catalogs using V2 wranglers before 16th December 2025 may contain raw values with floating-point precision errors. This occurred because the wranglers used:

int(value * FIXED_SCALAR)  # Introduces floating-point errors

instead of the correct precision-aware approach:

round(value * 10^precision) * scale  # Correct

Raw Value Correction

To handle legacy data with floating-point errors, the Arrow decode path uses correction functions (correct_raw_i64, correct_raw_i128, etc.) to round raw values to the nearest valid multiple. This ensures backward compatibility with existing catalogs.

Note: This correction adds a small amount of overhead during decoding. In a future version, once catalogs have been repaired or migrated, this correction will become opt-in.

Constants

FIXED_PRECISION

The maximum fixed-point precision.

FIXED_SCALAR

The scalar value corresponding to the maximum precision (10^16).

FIXED_SIZE_BINARY

The data type name for the Arrow fixed-size binary representation.

MAX_FLOAT_PRECISION

The maximum precision that can be safely used with f64-based constructors.

PRECISION_BYTES

The width in bytes for fixed-point value types in high-precision mode (128-bit).

PRECISION_DIFF_SCALAR

The scalar representing the difference between high-precision and standard-precision modes.

Statics

HIGH_PRECISION_MODE

Indicates if high-precision mode is enabled.

Functions

bankers_round

Rounds a mantissa by removing excess decimal digits using banker’s rounding (half to even).

check_fixed_precision

Checks if a given precision value is within the allowed fixed-point precision range.

check_fixed_raw_i64

Checks that a raw signed fixed-point value (64-bit) has no spurious bits.

check_fixed_raw_i128

Checks that a raw signed fixed-point value has no spurious bits beyond the precision scale.

check_fixed_raw_u64

Checks that a raw unsigned fixed-point value (64-bit) has no spurious bits.

check_fixed_raw_u128

Checks that a raw unsigned fixed-point value has no spurious bits beyond the precision scale.

correct_price_raw

Rounds a raw price value to the nearest valid multiple of the scale for the given precision.

correct_quantity_raw

Rounds a raw quantity value to the nearest valid multiple of the scale for the given precision.

correct_raw_i64

Rounds a raw i64 value to the nearest valid multiple of the scale for the given precision.

correct_raw_i128

Rounds a raw i128 value to the nearest valid multiple of the scale for the given precision.

correct_raw_u64

Rounds a raw u64 value to the nearest valid multiple of the scale for the given precision.

correct_raw_u128

Rounds a raw u128 value to the nearest valid multiple of the scale for the given precision.

f64_to_fixed_i64

Converts an f64 value to a raw fixed-point i64 representation with a specified precision.

f64_to_fixed_i128

Converts an f64 value to a raw fixed-point i128 representation with a specified precision.

f64_to_fixed_u64

Converts an f64 value to a raw fixed-point u64 representation with a specified precision.

f64_to_fixed_u128

Converts an f64 value to a raw fixed-point u128 representation with a specified precision.

fixed_i64_to_f64

Converts a raw fixed-point i64 value back to an f64 value.

fixed_i128_to_f64

Converts a raw fixed-point i128 value back to an f64 value.

fixed_u64_to_f64

Converts a raw fixed-point u64 value back to an f64 value.

fixed_u128_to_f64

Converts a raw fixed-point u128 value back to an f64 value.

mantissa_exponent_to_fixed_i128

Converts a mantissa/exponent pair to a raw fixed-point i128 value at the given precision.

raw_scales_match

Returns true when two precisions encode their raw values at the same scale.