# Unity Mathematics APIs

> Use the collection of SIMD-friendly, Burst-compilable math APIs in the Unity.Mathematics namespace to access common mathematical operations, including trigonometric and logarithmic functions, random number generation, and working with vectors, matrices, and quaternions.

The APIs in the `Unity.Mathematics` namespace are a [Burst-compilable](/engine/6000.5/manual/scripting/compilation-and-code-reload/script-compilation/burst.md) C# math library that provides vector types and math functions that have a shader-like syntax, similar to [Single Instruction, Multiple Data (SIMD)](https://en.wikipedia.org/wiki/Single_instruction,_multiple_data) or [High-Level Shading Language (HLSL)](https://docs.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl).

Unity Mathematics offers a [Burst-compilable](/engine/6000.5/manual/scripting/compilation-and-code-reload/script-compilation/burst.md) alternative to Unity's standard [Unity Engine math APIs](/engine/6000.5/manual/scripting/programming-math/unity-engine-math.md). Unity Mathematics implements vector and matrix types such as [`float3`](/engine/6000.5/script-reference/unity/mathematics/float3.md), [`quaternion`](/engine/6000.5/script-reference/unity/mathematics/quaternion.md), [`float3×3`](/engine/6000.5/script-reference/unity/mathematics/float3x3.md), and [`float4×4`](/engine/6000.5/script-reference/unity/mathematics/float4x4.md). It also includes elementary functions such as min, max, fabs, sin, cos, sqrt, normalize, dot, and cross.

To use Unity Mathematics, add `using Unity.Mathematics` to your code.

Prefer Unity Mathematics APIs over Unity Engine math APIs in Burst-compiled code. For code that isn't Burst compiled, prefer Unity Engine math APIs.

## Naming convention

In C# `int` and `float` are built-in types. The Burst compiler extends this set of built-in types to also include vectors, matrices, and quaternions. The Burst compiler already has implementations of these types, and can use them to generate better code than for custom types.

To signify that these types are built-in, their type names are in all lower case. The operators on these built-in types in [`Unity.Mathematics.math`](/engine/6000.5/script-reference/unity/mathematics/math.md) are intrinsics and are always in lower case. This convention has the added benefit of making the library highly compatible with shader code and makes porting or sharing code between the two easier.

## 4×4 matrices

To create a 4×4 transformation matrix, use the constructors in [`float4x4`](/engine/6000.5/script-reference/unity/mathematics/float4x4.md) to assign one value to all elements of the matrix, or individually set all 16 elements directly:

```lang-cs
// Unity Mathematics example
void Build4x4UnityMathematics()
{
   var c0 = new float4(1.0f, 0.0f, 0.0f, 0.0f);
   var c1 = new float4(0.0f, 1.0f, 0.0f, 0.0f);
   var c2 = new float4(0.0f, 0.0f, 1.0f, 0.0f);
   var c3 = new float4(0.0f, 0.0f, 0.0f, 1.0f);
   var m = new float4x4(c0, c1, c2, c3);
}
```

### Multiplying a 4×4 matrix

The `Unity.Mathematics` and `UnityEngine` APIs define the `*` operator differently. The `*` operator for [`float4x4`](/engine/6000.5/script-reference/unity/mathematics/float4x4.md) implements componentwise multiplication. If you multiply a `float4x4` of all 1s with 0.5 on the diagonal, you get back the half identity because the upper and lower triangles of the matrix are multiplied by the respective zero entries from `f4x4_HalfIdentity`:

```lang-cs
// Unity Mathematics example
void OperatorMultiply4x4UnityMathematics()
{
   float4x4 result = f4x4_Ones * f4x4_HalfIdentity;
   // result:
   // 0.5, 0.0, 0.0, 0.0,
   // 0.0, 0.5, 0.0, 0.0,
   // 0.0, 0.0, 0.5, 0.0,
   // 0.0, 0.0, 0.0, 0.5
}
```

### Multiplying a 4×4 matrix and a 4D vector

Use the [`math.mul`](/engine/6000.5/script-reference/unity/mathematics/math/mul.md) method to multiply a 4×4 matrix and a 4D vector. If you supply a `float4x4` as the first parameter and a `float4` as the second, it performs a 4×4 matrix multiplication with a 4×1 column vector, which returns a 4×1 column vector as a `float4`.

`math.mul` can also multiply a 1×4 row vector by a 4×4 matrix to produce a 1×4 row vector by taking a `float4` as the first parameter and a `float4×4` as the second. Unity Mathematics stores the row vector in a `float4` and it isn't treated as a separate type.

```lang-cs
// Unity Mathematics example
void Multiply4x4AndVector4UnityMathematics()
{
   float4 result1 = math.mul(f4x4, f4); // 4x4 * 4x1 = 4x1
   float4 result2 = math.mul(f4, f4x4); // 1x4 * 4x4 = 1x4
}
```

## Vector multiplication

To multiply vectors, use the `*` operator:

```lang-cs
// Unity Mathematics example
void ComponentwiseVectorMultiplyUnityMathematics()
{
   var v0 = new float4(2.0f, 4.0f, 6.0f, 8.0f);
   var v1 = new float4(1.0f, -1.0f, 1.0f, -1.0f);
   var result = v0 * v1;
   // result == new float4(2.0f, -4.0f, 6.0f, -8.0f).
}
```

This is a common way of writing [SIMD](https://en.wikipedia.org/wiki/Single_instruction,_multiple_data) code, which applies a single instruction to multiple data elements. Other operators such as addition, subtraction, and division work in the same way.

## Quaternion multiplication

To rotate a quaternion, use the [`AxisAngle`](/engine/6000.5/script-reference/unity/mathematics/quaternion/axisangle.md) method. You need to specify the axis of rotation and the angle of rotation, in that order. All are in radians rather than degrees. `math.mul` multiplies the quaternion, just as with matrices and vectors.

```lang-cs
// Unity Mathematics example
void QuaternionMultiplicationUnityMathematics()
{
   var axis = new float3(0.0f, 1.0f, 0.0f);
   var q = quaternion.AxisAngle(axis,math.radians(45.0f));
   var orientation = quaternion.Euler(
       math.radians(45.0f),
       math.radians(90.0f),
       math.radians(180.0f));
   var result = math.mul(q, orientation);
}
```

## Random numbers

To generate random numbers, you must create and manage the random number generator state yourself with the [`Random`](https://docs.unity3d.com/Packages/com.unity.mathematics@latest/index.html?subfolder=/api/Unity.Mathematics.Random.html) struct. You can control the random number generator state explicitly, which is useful if you're using parallel code, or if you want to make sure that one source of random numbers is seeded differently than another source. You can also have as many `Random` instances as you like.

Once you set up the state, use [`NextFloat`](/engine/6000.5/script-reference/unity/mathematics/random/nextfloat.md) to get random floats. By default it returns random numbers between `[0, 1)`, exclusive:

```lang-cs
// Unity Mathematics example
void RandomNumberUnityMathematics()
{
   // Choose some non-zero seed and set up the random number generator state.
   uint seed = 1;
   Unity.Mathematics.Random rng = new Unity.Mathematics.Random(seed);

   // [0, 1) exclusive
   float randomFloat1 = rng.NextFloat();

   // [-5, 5) exclusive
   float randomFloat2 = rng.NextFloat(-5.0f, 5.0f);
}
```

## Additional resources

* [Math coding with the Mathf API](/engine/6000.5/manual/scripting/programming-math/unity-engine-math/class-mathf.md)
* [Burst compiler](https://docs.unity3d.com/Packages/com.unity.burst@latest)