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.
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.
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)
x to the power of a fractional y aren’t supported.Unity.Mathematics.math.fmod(x, y)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.
Consistent floating point results are particularly important for deterministic simulations, networkingThe Unity system that enables multiplayer gaming across a computer network. More info
See in Glossary, or any scenario where cross-platform reproducibility is critical.
When FloatMode.Deterministic is enabled:
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:
FloatMode.Deterministic into Burst-compiled code that is, determinism may be broken.