BurstCompile FloatMode, FloatPrecision, Compile Async

[Radu392]

Hello, so I was trying to look up some in depth info about the burst attributes, but I can’t find anything clear enough.

Example:

[BurstCompile(FloatMode = FloatMode.Fast,FloatPrecision = FloatPrecision.Low,CompileSynchronously = true)]

What exactly do all these parameters do? I know that FloatMode.Fast is obviously faster than standard for example, but I’m looking for in depth information. How much faster? How much precision is exactly sacrificed? If FloatPrecision represents float precision (as in number of decimals), then what does the float mode Fast sacrifice in order to get that extra speed compared to FloatMode.Default? Even then, is FloadMode.Default actually slower or faster than FloatMode.Fast?

FloatMode:

Specifically, I want to know more about FloatMode.Default, .Fast, .Deterministic and .Strict. Is Strict faster than Fast? What exactly does Strict mean? Is default deterministic? If so, what’s the difference between default and deterministic?

Float precision:

I assume a High precision float would have more decimals than a Low one. If that’s not the case, what exactly does it do? If it is the case, how much precision is exactly lost/gained for every step in number of decimals?

Compile synchronously:

The documentation says ‘Gets or sets whether or not to burst compile the code immediately on first use, or in the background over time’. Why would you want to compile it in the background over time? Does that mean that compilation is being done even, say, 10 minutes after program start if set to false? Why would anyone want to set that to false?

[tertle]

The documents are actually pretty detailed on this. Not sure what you’re reading.

https://docs.unity3d.com/Packages/com.unity.burst@latest/

FloatPrecision
The accuracy is defined by the following enumeration:

public enum FloatPrecision
{
///

/// Use the default target floating point precision - .
///

Standard = 0,
///

/// Compute with an accuracy of 1 ULP - highly accurate, but increased runtime as a result, should not be required for most purposes.
///

High = 1,
///

/// Compute with an accuracy of 3.5 ULP - considered acceptable accuracy for most tasks.
///

Medium = 2,
///

/// Reserved for future.
///

Low = 3,
}

Currently, the implementation is only providing the following accuracy:

• FloatPrecision.Standard is equivalent to FloatPrecision.Medium providing an accuracy of 3.5 ULP. This is the default value.
• FloatPrecision.High is providing an accuracy of 1.0 ULP
• FloatPrecision.Medium is providing an accuracy of 3.5 ULP
• FloatPrecision.Low has currently the same accuracy than Medium but it will provide lower accuracy in the future

Using the FloatPrecision.Standard accuracy should be largely enough for most games.

An ULP (unit in the last place or unit of least precision) is the spacing between floating-point numbers, i.e., the value the least significant digit represents if it is 1.

We expect to support more ULP accuracy for FloatPrecision.Low for a future version of Burst

Note: The FloatPrecision Enum was named Accuracy in early versions of the Burst API.

Compiler floating point math mode
The compiler floating point math mode is defined by the following enumeration:

///

/// Represents the floating point optimization mode for compilation.
///

public enum FloatMode
{
///

/// Use the default target floating point mode - .
///

Default = 0,
///

/// No floating point optimizations are performed.
///

Strict = 1,
///

/// Reserved for future.
///

Deterministic = 2,
///

/// Allows algebraically equivalent optimizations (which can alter the results of calculations), it implies :
/// optimizations can assume results and arguments contain no NaNs or +/- Infinity and treat sign of zero as insignificant.
/// optimizations can use reciprocals - 1/x * y , instead of y/x.
/// optimizations can use fused instructions, e.g. madd.
///

Fast = 3,
}

• FloatMode.Default is defaulting to FloatMode.Strict
• FloatMode.Strict: The compiler is not performing any re-arrangement of the calculation and will be careful at respecting special floating point values (denormals, NaN…). This is the default value.
• FloatMode.Fast: The compiler can perform instructions re-arrangement and/or using dedicated/less precise hardware SIMD instructions.
• FloatMode.Deterministic: Reserved for future, when Burst will provide support for deterministic mode

Typically, some hardware can support Multiply and Add (e.g mad a * b + c) into a single instruction. Using the Fast calculation can allow these optimizations. The reordering of these instructions can lead to a lower accuracy.

Using the FloatMode.Fast compiler floating point math mode can be used for many scenarios where the exact order of the calculation and the uniform handling of NaN values are not strictly required.

Synchronous compilation
By default, the Burst compiler in the editor will compile the jobs asynchronously.

You can change this behavior by setting CompileSynchronously = true for the [BurstCompile] attribute:

[BurstCompile(CompileSynchronously = true)]
public struct MyJob : IJob
{
// …
}

Seems to answer all your questions.

[tim_jones]

As @tertle said, our docs are quite detailed about FloatPrecision and FloatMode:
https://docs.unity3d.com/Packages/com.unity.burst@latest

To expand a bit on CompileSynchronously:

• This is only relevant for play mode in the editor (i.e. it’s ignored when building a standalone player).
• If CompileSynchronously=false (the default), then while Burst is compiling your code in the background, your code will be run using Mono. You would want to set CompileSynchronously=true when you’re doing profiling, or are writing deterministic code where you don’t want it to ever run on Mono.

Lee actually covered this stuff in his Unite talk - here are links to the relevant time codes:

• FloatMode / FloatPrecision -
  https://www.youtube.com/watch?v=Tzn-nX9hK1o

• CompileSynchronously -
  https://www.youtube.com/watch?v=Tzn-nX9hK1o

[Radu392]

Hmm I did check that page, but I somehow managed to miss that information. I should probably stop doing this kind of stuff so late at night.

Anyway, thanks for the links! Also, good to know that CompileAsync is editor mode only.