Crate octonion 

octonion

Minimal, dependency-free, no_std octonion algebra for Rust.

This crate provides Octonion (an 8D hypercomplex number over f64) with basic arithmetic, conjugation, norms, and inversion.

Quick start

use octonion::Octonion;

let x = Octonion::new(1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0);

// Basis elements square to -1.
assert_eq!(Octonion::E1 * Octonion::E1, -Octonion::ONE);

// Non-commutativity.
assert_eq!(Octonion::E1 * Octonion::E2, Octonion::E3);
assert_eq!(Octonion::E2 * Octonion::E1, -Octonion::E3);

// Conjugation, norm, inverse.
let _conj = x.conj();
let _norm_sq = x.norm_sqr();
let _inv = x.try_inverse().unwrap();

Notes

• Octonion multiplication is non-associative. If you need explicit grouping, enable alloc (on by default) and use Paren or OctoExpr.
• If an octonion lies in the quaternion subalgebra (its e₄..e₇ coefficients are exactly zero), you can call Octonion::as_quaternion to get a QuaternionView that supports associative multiplication.

SIMD helpers

The octonion::simd module includes a direct coefficient expansion simd::mul_direct (often easier for the compiler to auto-vectorize than the default implementation).

On x86_64 with avx, simd::mul_simd_avx is available (currently a thin wrapper around mul_direct).

Features

• alloc (default): enables Paren, OctoExpr, and simd::mul_batch.
• alloc (default): enables Paren, OctoExpr, and simd::mul_batch.
• e8: enables octonion::e8::IntegralOctonion (Cayley integers / E8 lattice).

To use this crate without allocation support:

octonion = { version = "0.1", default-features = false }

Examples and benches

• Colorized display demo: cargo run --example display_demo
• Benchmarks: cargo bench

Quick Start

use octonion::Octonion;

// Create an octonion from coefficients
let x = Octonion::new(1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0);

// Use basis elements
let e1 = Octonion::E1;
let e2 = Octonion::E2;

// Basis elements square to -1
assert_eq!(e1 * e1, -Octonion::ONE);

// Octonion multiplication is non-commutative
assert_eq!(e1 * e2, Octonion::E3);
assert_eq!(e2 * e1, -Octonion::E3);

// Conjugation, norm, and inverse
let conj = x.conj();
let norm_sq = x.norm_sqr();
let inv = x.try_inverse().unwrap();

Mathematical Background

The octonions are an 8-dimensional normed division algebra over the reals. They extend the quaternions in the same way that the quaternions extend the complex numbers. An octonion can be written as:

x = a₀ + a₁e₁ + a₂e₂ + a₃e₃ + a₄e₄ + a₅e₅ + a₆e₆ + a₇e₇

where a₀ through a₇ are real numbers and e₁ through e₇ are the imaginary basis units.

Properties

• Non-commutative: xy ≠ yx in general
• Non-associative: (xy)z ≠ x(yz) in general
• Alternative: x(xy) = x²y and (xy)y = xy² (weaker than associativity)
• Normed: |xy| = |x||y| (the norm is multiplicative)
• Division algebra: Every non-zero octonion has a multiplicative inverse

Cayley-Dickson Construction

This crate implements octonion multiplication using the Cayley-Dickson construction, which represents an octonion as a pair of quaternions (a, b):

(a, b)(c, d) = (ac - d*b, da + bc*)

where * denotes quaternion conjugation.

Features

• no_std compatible
• Zero dependencies
• No unsafe code
• Compile-time constructors via const fn

Re-exports

pub use simd::mul_direct;

pub use simd::mul_simd_avx;

Modules

e8

Integral Octonions (Cayley integers) over the E8 lattice.

simd

SIMD-accelerated octonion multiplication.

Macros

octo_eval

Evaluates an octonion expression with explicit parenthesization.

octo_group

Evaluates an octonion expression with keyword-based grouping.

Structs

Octonion

An octonion over f64, represented in the standard basis.

Paren

A builder for explicitly parenthesized octonion expressions.

QuaternionView

A view into an Octonion that is known to have zero coefficients for e₄ through e₇.

Enums

OctoExpr

An unevaluated octonion expression tree.