Documentation

Unity Engine

User Manual

Script Reference

Unity Engine

Float precision and determinism

Read time 3 minutesLast updated 13 days ago
You can use the relevant APIs to configure the degree of accuracy and determinism in Burst's floating point number calculations. This is important in contexts when either a certain level of precision or cross-platform reproducibility are required.

Float precision

Use the 
FloatPrecision
 enumeration to define Burst's floating precision accuracy.
Float precision is measured in ulp (unit in the last place or unit of least precision). This is the space between floating-point numbers: the value the least significant digit represents if it's 1. 
Unity.Burst.FloatPrecision
provides the following accuracy:
  • FloatPrecision.Standard
    : Default value, which is the same as 
    FloatPrecision.Medium
    . This provides an accuracy of 3.5 ulp.
  • FloatPrecision.High
    : Provides an accuracy of 1.0 ulp.
  • FloatPrecision.Medium
    : Provides an accuracy of 3.5 ulp.
  • FloatPrecision.Low
    : Has an accuracy defined per function, and functions might specify a restricted range of valid inputs.
Note
In previous versions of the Burst API, the 
FloatPrecision
enum was named 
Accuracy
.

Low float precision

If you use the 
FloatPrecision.Low
 mode, the following functions have a precision of 350.0 ulp. All other functions inherit the ulp from 
FloatPrecision.Medium
.
  • Unity.Mathematics.math.sin(x)
  • Unity.Mathematics.math.cos(x)
  • Unity.Mathematics.math.exp(x)
  • Unity.Mathematics.math.exp2(x)
  • Unity.Mathematics.math.exp10(x)
  • Unity.Mathematics.math.log(x)
  • Unity.Mathematics.math.log2(x)
  • Unity.Mathematics.math.log10(x)
  • Unity.Mathematics.math.pow(x, y)
    • Negative 
      x
      to the power of a fractional 
      y
      aren't supported.
  • Unity.Mathematics.math.fmod(x, y)

Float math mode

Use the 
FloatMode
 enumeration to define Burst's floating point math mode. It provides the following modes:
  • FloatMode.Default
    : Defaults to 
    FloatMode.Strict
    mode.
  • FloatMode.Strict
    : Burst doesn't perform any re-arrangement of the calculation and respects special floating point values such as denormals and 
    NaN
    (Not a Number) values. This is the default value.
  • FloatMode.Fast
    : Burst can perform instruction re-arrangement and use dedicated or less precise hardware SIMD instructions.
  • FloatMode.Deterministic
    : Ensure that floating point calculation in Burst are deterministic, i.e., consistent across all supported platforms. Only supported on 64-bit architectures.
For hardware that can support Multiply and Add (e.g mad 
a * b + c
) into a single instruction, you can use 
FloatMode.Fast
to enable this optimization. However, the reordering of these instructions might lead to a lower accuracy.
Use 
FloatMode.Fast
for scenarios where the exact order of the calculation and the uniform handling of NaN values aren't required.
Use 
FloatMode.Deterministic
when your application requires floating point calculations to produce consistent results across different platforms and hardware.

Float determinism

Consistent floating point results are particularly important for deterministic simulations, networking, or any scenario where cross-platform reproducibility is critical.
When 
FloatMode.Deterministic
is enabled:
  • Burst uses deterministic implementations of math functions.
  • Burst disables certain floating-point optimizations that can introduce platform-specific differences.
  • Subnormal (denormal) floating-point numbers are flushed to zero on all platforms, eliminating inconsistencies due to subnormal handling.
Disabling some optimizations may negatively impact the performance of floating point calculations. The actual performance impact will depend on your specific use case.
NaN
values in IEEE 754 are encoded with all exponent bits set to one and a non-zero significand. 
FloatMode.Deterministic
does not guarantee bitwise-identical 
NaN
representations. If a calculation results in a 
NaN
, all platforms will produce a 
NaN
, but the exact bit pattern of the 
NaN
may vary across platforms.
Use of hardware-specific intrinsics or platform-specific instructions can still cause differences across platforms and may break determinism if not avoided.
Keep in mind that 
FloatMode.Deterministic
only applies to Burst-compiled code. Determinism can still be compromised by several factors, such as:
  • If the input to Burst-compiled code includes floating-point calculations, this may introduce non-determinism.
  • If you pass a function pointer from code that is not set to use 
    FloatMode.Deterministic
    into Burst-compiled code that is, determinism may be broken.

Additional resources