mrunbelievable92 / maxmath

A supplementary SIMD math library to Unity.Mathematics, extending it to all C# numeric types while adding many new types and functions. Written entirely with hardware intrinsics, using Unity.Burst.

MaxMath

A C# SIMD math library for use with Unity only, supplementary to Unity.Mathematics using Unity.Burst.

It adds (s)byte, (u)short and (u)long SIMD vectors and matrices to the ones already provided by Unity.Mathematics. Almost all functions present in Unity.Mathematics have been transcribed to work with the new vector and matrix types in addition to many useful functions having been added.

Note:

• C Sharp Dev Tools (conditionally compiled runtime checks) is required. Unit tests for this library are included in this repository.
• This library utilizes Avx2 as often as possible. Optimized fallback procedures for Sse4 and Sse2 are included, aswell as a managed C# implementation. There are currently no plans for supporting ARM or other instruction sets in the future, although Burst/LLVM is generally good at vectorizing some of the code for them.
• The "float8" type does not support deterministic compilation across all platforms with Unity.Burst. Split up the vector into two "float4" vectors via the properties "myfloat8.v4_0" and "myfloat8.v4_4" to take advantage of deterministic compilation instead.

How To Use This Library

New Types

Integer

(S)Byte

(U)Short

(U)Int

(U)Long

Floating Point

Float

Half

Quarter (8-bit 1.3.4.-3 IEEE 754 floating point)

Random Number Generators

XOR-Shift

New Functions

Miscellaneous

Arithmetic

Bitwise Operations

Vector Operations

Interpolation and Geometry

Type Conversion

What Kind Of Performance To Expect

Highlights

• Division and modulo operations of (s)byte and (u)short vectors by other vectors are implemented as either a long division algorithm ((s)byte32, (s)byte16 and (s)byte8 if not compiling for Avx2) or reciprocal multiplication after converting the vectors to float vectors (up to (s)byte8, all (u)short vectors) - it is very fast and, of course, 100% accurate!

• This library uses Wojciech Mula's SIMD population count algorithm. You can count the amount of set bits of a contiguous block of memory very efficiently using either the (s)byte32 (Avx2) or (s)byte16 (Ssse3) type

Notes

• It is recommended, just like with Unity.Mathematics, to use vector types that use up an entire SIMD register (128 and 256 bits, respectively). LLVM has a very hard time optimizing code which does not follow this recommendation

How To Install This Library

Disclaimer: I firmly believe in open source - being able to copy/modify/understand other people's code is great :) I also want people to be able to step through code with a debugger. For these reasons I usually don't distribute DLLs.

• Download the package and unzip it into your "LocalPackages" folder, which is located at the root folder of your Unity project (where your "Assets" folder resides at).
• Start up Unity. Usually Unity detects new packages and will generate .meta files for you.
• In case that doesn't work, open up the package manager from within Unity and click on the '+' symbol at the upper left corner of the window, further clicking on "Add package from disk..." - "Add package from git URL" should also work.

• Locate the library's "package.json" file
• DONE!

maxmath's Issues

bool8, bool16 Not Blittable

When attempting to send bool8 and/or bool16 to a static burst compiled method, I get a burst error that these types are not blittable due to the "asArray" field. Removing the field did fix the issue. Are you aware of this? Is this desired?

"Add from git URL" does not work

When I read "should work" I knew it wouldn't work. :)

Here's the output when trying to add the package from git URL:

[Package Manager Window] Cannot perform upm operation: Unable to add package [https://github.com/MrUnbelievable92/MaxMath]:
  Package name 'https://github.com/MrUnbelievable92/MaxMath' is invalid. [InvalidParameter].
UnityEditor.EditorApplication:Internal_CallUpdateFunctions ()

Next thing: when I clone the project and try to add that locally, it still won't resolve the C# DevTools package. ;)

---

The actually working "how to install" is this:

• Clone or download C# DevTools: https://github.com/MrUnbelievable92/C-Sharp-Dev-Tools
• Unity PM: "Add Package from Disk" => locate DevTools' package.json
• Clone or download MaxMath: https://github.com/MrUnbelievable92/MaxMath
• Unity PM: "Add Package from Disk" => locate MaxMath' package.json

(Backlink) Extreme memory usage with MaxMath in Rider

Link to Youtrack issue

No action needed.
I thought I'll post this here for reference in case another Rider user runs into this high memory usage issue. For the time being I removed MaxMath from my project. Specifically the file Impl.cs seems to be where Rider analysis got stuck.

Can't add package from git URL because no .meta files

All the files in the repo are ignored because they don't have .meta files, and Unity won't generate .meta files for files in immutable folders (such as Packages).

Use of DEBUG Symbol

DEBUG define symbol is always active in the Unity Editor which is leading to Assertions being active... slowing performance and cluttering the Burst Inspector with many branches. I'm not sure what the best remedy for this is. Maybe using ENABLE_UNITY_COLLECTIONS_CHECKS instead so at least Burst can get rid of them.

maxmath.cbrt returns NaN for an input value of 0

As per the title of the issue, maxmath.cbrt() returns NaN for an input of 0. This is the case for the method both Bursted and non-Bursted.

I also wanted your opinion on an issue with the explicit fnmadd_ps instructions. Is it wise to use these instructions directly rather than let Burst handle using fused instructions automatically when using FloatMode.Fast (which it does do, though differently it seems)? For my use case, I need to use FloatMode.Strict and the explicit use of fused instructions sort of goes against that. Maybe it would be worth having a separate fastcbrt() method.

Edit:
Looking further into the fused instruction issue, it seems using the fused instructions directly leads to less optimal code than without? Could you take a closer look at this?

Random8() always returns 255

I noticed something odd about Random8 when using the "parameterless" constructor. It always outputs 255 because the internal State remains 0. Interestingly, the Assert in NextState() isn't triggered either, probably because it's a Unit test assertion and not a Debug.Assert() (which, honestly, I would avoid using in Burst compiled code but rather check for Burst Safety Checks = On).

Because of the ctor default value - and because you cannot implement a truly parameterless ctor in a struct - I believe that using a single parameter with a default value in a struct ctor leads to the code actually calling the internal parameterless ctor of the struct when no input value is supplied. It does NOT call the ctor with a default value parameter!

Coincidentally, I cannot "step into" the new Random8() line at all, this only works when supplying a parameter ie new Random8(1).

Random8 works fine when using any value in the constructor, including the default: 0b0111_1001

Here's the code I've tested it with (outside Jobs, not Burst compiled):

var rand = new MaxMath.Random8();
for (int i = 0; i < 10; i++)
{
	Debug.Log(rand.State);
	Debug.Log(rand.NextByte());
	var color = rand.NextByte4();
	Debug.Log(color);
}

Using Unity 2022.1.14f1 with Burst 1.7.4, Mathematics 1.2.6, MaxMath 2.3.0.

Missing static factory methods like var foo = byte4(x,y,z,w)

This is a silly issue but I'm used to using unity mathematics convention of doing
float4 foo = float4(bar)
instead of
float4 foo = new float4(bar)
and when I massively search and replace float4 by byte4, it doesn't compile and I have to use new byte4()

eg
public static float4 float4(float x, float y, float z, float w) { return new float4(x, y, z, w); }

Inns

This was due to the GUID of devtools being wrong in the math assembly definition, I could fix it easily by adding the dev tools depency.

It would probably be more reliable with the use guids checkbox set to off in assembly definitions

MaxMath Causes Much Longer Compile Times

I used Needles Compilation Visualizer to track compilation time in our project, I was hoping this could be addressed as it really cuts into productivity.

NextGreater Appears to be Broken

This functionality should be very useful, but NextGreater doesn't seem to work for me (Bursted code or not). Not much else to say about it, but here are some screenshots: