## Documentation

### Overview ¶

Package quat provides the quaternion numeric type and functions.

For a good treatment of uses and behaviors of quaternions, see the interactive videos by Ben Eater and Grant Sanderson here https://eater.net/quaternions.

Example (Rotate)

Rotate a cube 120° around the diagonal vector [1, 1, 1].

Code:

```package main

import (
"fmt"
"math"

"gonum.org/v1/gonum/floats/scalar"
"gonum.org/v1/gonum/num/quat"
)

// point is a 3-dimensional point/vector.
type point struct {
x, y, z float64
}

// raise raises the dimensionality of a point to a quaternion.
func raise(p point) quat.Number {
return quat.Number{Imag: p.x, Jmag: p.y, Kmag: p.z}
}

// rotate performs the quaternion rotation of p by the given quaternion
// and scaling by the scale factor.
func rotate(p point, by quat.Number, scale float64) point {
// Ensure the modulus of by is correctly scaled.
if len := quat.Abs(by); len != scale {
by = quat.Scale(math.Sqrt(scale)/len, by)
}

// Perform the rotation/scaling.
pp := quat.Mul(quat.Mul(by, raise(p)), quat.Conj(by))

// Extract the point.
return point{x: pp.Imag, y: pp.Jmag, z: pp.Kmag}
}

// Rotate a cube 120° around the diagonal vector [1, 1, 1].
func main() {
alpha := 2 * math.Pi / 3
q := raise(point{1, 1, 1})
scale := 1.0

q = quat.Scale(math.Sin(alpha/2)/quat.Abs(q), q)
q.Real += math.Cos(alpha / 2)

for i, p := range []point{
{x: 0, y: 0, z: 0},
{x: 0, y: 0, z: 1},
{x: 0, y: 1, z: 0},
{x: 0, y: 1, z: 1},
{x: 1, y: 0, z: 0},
{x: 1, y: 0, z: 1},
{x: 1, y: 1, z: 0},
{x: 1, y: 1, z: 1},
} {
pp := rotate(p, q, scale)

// Clean up floating point error for clarity.
pp.x = scalar.Round(pp.x, 2)
pp.y = scalar.Round(pp.y, 2)
pp.z = scalar.Round(pp.z, 2)

fmt.Printf("%d %+v -> %+v\n", i, p, pp)
}

}
```
```
0 {x:0 y:0 z:0} -> {x:0 y:0 z:0}
1 {x:0 y:0 z:1} -> {x:1 y:0 z:0}
2 {x:0 y:1 z:0} -> {x:0 y:0 z:1}
3 {x:0 y:1 z:1} -> {x:1 y:0 z:1}
4 {x:1 y:0 z:0} -> {x:0 y:1 z:0}
5 {x:1 y:0 z:1} -> {x:1 y:1 z:0}
6 {x:1 y:1 z:0} -> {x:0 y:1 z:1}
7 {x:1 y:1 z:1} -> {x:1 y:1 z:1}
```

### Constants ¶

This section is empty.

### Variables ¶

This section is empty.

### Functions ¶

#### func Abs¶

`func Abs(q Number) float64`

Abs returns the absolute value (also called the modulus) of q.

#### func IsInf¶

`func IsInf(q Number) bool`

IsInf returns true if any of real(q), imag(q), jmag(q), or kmag(q) is an infinity.

#### func IsNaN¶

`func IsNaN(q Number) bool`

IsNaN returns true if any of real(q), imag(q), jmag(q), or kmag(q) is NaN and none are an infinity.

### Types ¶

#### type Number¶

```type Number struct {
Real, Imag, Jmag, Kmag float64
}```

Number is a float64 precision quaternion.

#### func Acos¶

`func Acos(q Number) Number`

Acos returns the inverse cosine of q.

#### func Acosh¶

`func Acosh(q Number) Number`

Acosh returns the inverse hyperbolic cosine of q.

`func Add(x, y Number) Number`

Add returns the sum of x and y.

#### func Asin¶

`func Asin(q Number) Number`

Asin returns the inverse sine of q.

#### func Asinh¶

`func Asinh(q Number) Number`

Asinh returns the inverse hyperbolic sine of q.

#### func Atan¶

`func Atan(q Number) Number`

Atan returns the inverse tangent of q.

#### func Atanh¶

`func Atanh(q Number) Number`

Atanh returns the inverse hyperbolic tangent of q.

#### func Conj¶

`func Conj(q Number) Number`

Conj returns the quaternion conjugate of q.

#### func Cos¶

`func Cos(q Number) Number`

Cos returns the cosine of q.

#### func Cosh¶

`func Cosh(q Number) Number`

Cosh returns the hyperbolic cosine of q.

#### func Exp¶

`func Exp(q Number) Number`

Exp returns e**q, the base-e exponential of q.

#### func Inf¶

`func Inf() Number`

Inf returns a quaternion infinity, quaternion(+Inf, +Inf, +Inf, +Inf).

#### func Inv¶

`func Inv(q Number) Number`

Inv returns the quaternion inverse of q.

#### func Log¶

`func Log(q Number) Number`

Log returns the natural logarithm of q.

#### func Mul¶

`func Mul(x, y Number) Number`

Mul returns the Hamiltonian product of x and y.

#### func NaN¶

`func NaN() Number`

NaN returns a quaternion ``not-a-number'' value.

#### func Parse¶

`func Parse(s string) (Number, error)`

Parse converts the string s to a Number. The string may be parenthesized and has the format [±]N±Ni±Nj±Nk. The order of the components is not strict.

#### func Pow¶

`func Pow(q, r Number) Number`

Pow return q**r, the base-q exponential of r. For generalized compatibility with math.Pow:

```Pow(0, ±0) returns 1+0i+0j+0k
Pow(0, c) for real(c)<0 returns Inf+0i+0j+0k if imag(c), jmag(c), kmag(c) are zero,
otherwise Inf+Inf i+Inf j+Inf k.
```

#### func Scale¶

`func Scale(f float64, q Number) Number`

Scale returns q scaled by f.

#### func Sin¶

`func Sin(q Number) Number`

Sin returns the sine of q.

#### func Sinh¶

`func Sinh(q Number) Number`

Sinh returns the hyperbolic sine of q.

#### func Sqrt¶

`func Sqrt(q Number) Number`

Sqrt returns the square root of q.

#### func Sub¶

`func Sub(x, y Number) Number`

Sub returns the difference of x and y, x-y.

#### func Tan¶

`func Tan(q Number) Number`

Tan returns the tangent of q.

#### func Tanh¶

`func Tanh(q Number) Number`

Tanh returns the hyperbolic tangent of q.

#### func (Number) Format¶

`func (q Number) Format(fs fmt.State, c rune)`

Format implements fmt.Formatter.