Documentation

Eig3x3.Basic

Eig3x3.Basic — types and the 3×3 vector/matrix vocabulary #

Core types (Vec3, Eigval3, Mat3, SymmMat3, Decomposition), the public Float arithmetic vocabulary, typeclass instances for arithmetic notation, and scoped unicode notation.

Usage #

Importing this module activates every typeclass instance (Add, Mul, HSMul, Inv, …), so arithmetic on Vec3 and Mat3 works immediately through Lean's core syntax. The Unicode operator glyphs are opt-in:

open scoped Eig3x3

Notation and Operators #

A Mathlib-consistent operator layer for vector/matrix algebra on Float, with no Mathlib dependency. Precedences follow Lean core and Mathlib:

NotationOperationDeclarationConvention source
a + badditioninfixl:65Lean core (HAdd.hAdd)
a - bsubtractioninfixl:65Lean core (HSub.hSub)
-anegationprefixLean core (Neg.neg)
a * bmultiplication/actioninfixl:70Lean core (HMul.hMul)
a / sscalar divisioninfixl:70Lean core (HDiv.hDiv)
u ⊗ᵥ vvector outer productinfixl:70(new; subscript family of ⬝ᵥ)
u ⬝ᵥ vvector dot productinfixl:72Mathlib Matrix.dotProduct
A ⬝ₘ Bmatrix Frobenius dotinfixl:72(family extension of ⬝ᵥ)
s • vscalar multiplicationinfixr:73Lean core (HSMul.hSMul)
u ⨯₃ vcross productinfixl:74Mathlib crossProduct
x ^ⁿ npower (by fast Nat)infixr:80(new; family of ^)
A ⊙ BHadamard productinfixl:100Mathlib Matrix.hadamard
|x|absolute valuedelimitedMathlib |a| for abs
‖v‖normdelimitedMathlib Norm.norm
‖v‖²squared normdelimited(Mathlib writes ‖x‖ ^ 2)
Aᵀtransposepostfix:maxMathlib Matrix.transpose
A⁻¹inversepostfix:maxLean core (Inv.inv)

Binding strength: + - (65) < * / (70) < ⬝ᵥ ⬝ₘ (72) < (73) < ⨯₃ (74) < ^ⁿ (80) < (100); the postfixes and ⁻¹ (1024) bind tightest.

Useful consequences:

Important: ⬝ᵥ (72) binds tighter than * (70), so M * v ⬝ᵥ w parses as M * (v ⬝ᵥ w) — write (M * v) ⬝ᵥ w instead.

structure Eig3x3.Vec3 :

Vector over Float in real (ℝ³) space.

  • x : Float

    X coordinate (first component).

  • y : Float

    Y coordinate (second component).

  • z : Float

    Z coordinate (third component).

Instances For
    Equations
    • One or more equations did not get rendered due to their size.
    Instances For
      @[instance_reducible]
      Equations
      structure Eig3x3.Mat3 :

      General 3×3 matrix over Float, stored by columns. The primary matrix this library produces is the eigenvector matrix Q, whose columns are eigenvectors, matching conventional mathematics and NumPy/SciPy/PyTorch.

      • c₀ : Vec3

        Column 0 vector.

      • c₁ : Vec3

        Column 1 vector.

      • c₂ : Vec3

        Column 2 vector.

      Instances For
        @[instance_reducible]
        Equations
        Equations
        • One or more equations did not get rendered due to their size.
        Instances For

          Symmetric 3×3 matrix stored as its six independent entries.

          Meant to be used as an input parameter type, not for matrix math. Coerces one-way to Mat3 for matrix operations.

          • a₀₀ : Float

            Diagonal entry A₀₀.

          • a₁₁ : Float

            Diagonal entry A₁₁.

          • a₂₂ : Float

            Diagonal entry A₂₂.

          • a₀₁ : Float

            Off-diagonal entry A₀₁ = A₁₀.

          • a₀₂ : Float

            Off-diagonal entry A₀₂ = A₂₀.

          • a₁₂ : Float

            Off-diagonal entry A₁₂ = A₂₁.

          Instances For
            Equations
            • One or more equations did not get rendered due to their size.
            Instances For
              structure Eig3x3.Eigval3 :

              Ordered eigenvalues l₀l₁l₂.

              Not meant to be used directly. A distinct return type so eigenvalue ordering guarantees required by Eberly's algorithm [Ebe14] are carried by the type. Coerces to Vec3 for vector operations. Coercion is one-way, and ordering guarantees do not hold after coercion.

              • l₀ : Float

                Smallest eigenvalue.

              • l₁ : Float

                Middle eigenvalue.

              • l₂ : Float

                Largest eigenvalue.

              Instances For
                Equations
                • One or more equations did not get rendered due to their size.
                Instances For

                  Full eigendecomposition: A = QΛQᵀ = Σᵢ λᵢ cᵢcᵢᵀ.

                  • eigvals : Eigval3

                    Eigenvalues in increasing order: l₀l₁l₂.

                  • eigvecs : Mat3

                    Eigenvector matrix Q; column cᵢ is a unit eigenvector for lᵢ. Right-handed: Q.det = 1.

                  Instances For
                    Equations
                    • One or more equations did not get rendered due to their size.
                    Instances For

                      Vec3 operations #

                      @[inline]

                      Vector addition u + v.

                      Equations
                      Instances For
                        @[inline]

                        Vector negation -v.

                        Equations
                        Instances For
                          @[inline]

                          Vector subtraction u - v.

                          Equations
                          Instances For
                            @[inline]
                            def Eig3x3.Vec3.scale (v : Vec3) (s : Float) :

                            Scalar multiplication s • v.

                            Equations
                            Instances For
                              @[inline]
                              def Eig3x3.Vec3.div (v : Vec3) (s : Float) :

                              Scalar division v / s.

                              Equations
                              Instances For
                                @[inline]

                                Vector dot product u ⬝ᵥ v.

                                Equations
                                Instances For
                                  @[inline]

                                  Vector cross product u ⨯₃ v in ℝ³.

                                  Equations
                                  Instances For
                                    @[inline]

                                    Squared Euclidean norm ‖u‖² = u.x² + u.y² + u.z².

                                    Equations
                                    Instances For
                                      @[inline]

                                      Euclidean norm ‖u‖ = √(‖u‖²).

                                      Equations
                                      Instances For
                                        @[inline]

                                        Outer product of two vectors, producing the rank-1 matrix u vᵀ. Exposed as ⊗ᵥ. The columns are u scaled by the entries of v, matching Mat3's column-major layout.

                                        Equations
                                        Instances For
                                          @[inline]

                                          Componentwise product, exposed as via the Hadamard class. Vec3 deliberately has no Mul instance: the vector products of this library are ⬝ᵥ and ⨯₃, and is the single entrywise spelling.

                                          Equations
                                          Instances For
                                            @[inline]
                                            def Eig3x3.Vec3.map (f : FloatFloat) (v : Vec3) :

                                            Componentwise map — workhorse for eigenvalue post-processing (clipping, shifting, reciprocals).

                                            Equations
                                            Instances For
                                              @[inline]
                                              def Eig3x3.Vec3.map2 (f : FloatFloatFloat) (u v : Vec3) :

                                              Componentwise zip.

                                              Equations
                                              Instances For
                                                @[inline]

                                                Componentwise absolute value of a vector |v|.

                                                Equations
                                                Instances For
                                                  @[inline]

                                                  Convert ordered eigenvalues Eigval3 to an unconstrained Vec3.

                                                  Equations
                                                  Instances For
                                                    @[instance_reducible]

                                                    One-way coercion: ordered eigenvalues are a vector, but an arbitrary vector is not ordered eigenvalues.

                                                    Equations

                                                    Mat3 operations #

                                                    @[inline]

                                                    Rows become columns: nine field moves, no arithmetic.

                                                    Equations
                                                    Instances For
                                                      @[inline]
                                                      def Eig3x3.Mat3.mulVec (M : Mat3) (v : Vec3) :

                                                      M·v: linear combination of the columns.

                                                      Equations
                                                      Instances For
                                                        @[inline]

                                                        Mᵀ·v without materializing the transpose: dot with each column.

                                                        Equations
                                                        Instances For
                                                          @[inline]

                                                          M·N: column j of the product is M applied to column j of N.

                                                          Equations
                                                          Instances For
                                                            @[inline]
                                                            def Eig3x3.Mat3.scale (M : Mat3) (s : Float) :

                                                            Scalar multiplication of a matrix s • M.

                                                            Equations
                                                            Instances For
                                                              @[inline]
                                                              def Eig3x3.Mat3.div (M : Mat3) (s : Float) :

                                                              Scalar division of a matrix M / s.

                                                              Equations
                                                              Instances For
                                                                @[inline]

                                                                Matrix addition M + N.

                                                                Equations
                                                                Instances For
                                                                  @[inline]

                                                                  Matrix negation -M.

                                                                  Equations
                                                                  Instances For
                                                                    @[inline]

                                                                    Matrix subtraction M - N.

                                                                    Equations
                                                                    Instances For
                                                                      @[inline]

                                                                      Componentwise (Hadamard) product, exposed as .

                                                                      Equations
                                                                      Instances For
                                                                        @[inline]

                                                                        Componentwise absolute value.

                                                                        Equations
                                                                        Instances For
                                                                          @[inline]

                                                                          Matrix Frobenius inner product ∑ᵢⱼ Mᵢⱼ Nᵢⱼ = tr(MᵀN).

                                                                          Equations
                                                                          Instances For
                                                                            @[inline]

                                                                            Squared Frobenius norm: sum of squares of all entries.

                                                                            Equations
                                                                            Instances For
                                                                              @[inline]

                                                                              Frobenius norm: square root of sum of squares of all entries. (Not the operator norm; chosen because it is exactly computable with nine multiplications.)

                                                                              Equations
                                                                              Instances For
                                                                                @[inline]

                                                                                det M: the triple product (c₀ × c₁) ⬝ c₂ of the columns.

                                                                                Equations
                                                                                Instances For
                                                                                  @[inline]

                                                                                  tr M: sum of the diagonal entries.

                                                                                  Equations
                                                                                  Instances For

                                                                                    The identity matrix.

                                                                                    Equations
                                                                                    • Eig3x3.Mat3.id = { c₀ := { x := 1.0, y := 0.0, z := 0.0 }, c₁ := { x := 0.0, y := 1.0, z := 0.0 }, c₂ := { x := 0.0, y := 0.0, z := 1.0 } }
                                                                                    Instances For
                                                                                      @[inline]
                                                                                      def Eig3x3.Mat3.ofRows (r₀ r₁ r₂ : Vec3) :

                                                                                      Row-minded constructor: build from three rows.

                                                                                      Equations
                                                                                      Instances For

                                                                                        Invert a 3×3 matrix via cofactor cross products: M⁻¹ = (1/det M) adj(M), with adj(M) computed from cross products of the rows. Totalized like the rest of the Float vocabulary: a singular M yields inf/NaN entries rather than an error.

                                                                                        Equations
                                                                                        • One or more equations did not get rendered due to their size.
                                                                                        Instances For

                                                                                          Convert a symmetric matrix representation SymmMat3 to a full Mat3.

                                                                                          Equations
                                                                                          Instances For
                                                                                            @[instance_reducible]

                                                                                            One-way coercion: a symmetric matrix is a matrix, but an arbitrary matrix is not symmetric.

                                                                                            Equations

                                                                                            Fast natural-number powers (^ⁿ) #

                                                                                            class Eig3x3.PowNat (α : Type) :

                                                                                            Fast natural-number power, exposed as x ^ⁿ n.

                                                                                            • powNat : αNatα

                                                                                              Exponentiate x to natural power n.

                                                                                            Instances

                                                                                              Power by repeated multiplication — adequate for the small exponents (e.g. 2 or 3) that appear in characteristic-polynomial computations, and computationally cheaper than Lean's C-accelerated pow call.

                                                                                              Equations
                                                                                              Instances For
                                                                                                @[instance_reducible]

                                                                                                Conditioning for Float: repeated multiplication below 8, core's C-accelerated Float.pow above 8.

                                                                                                Equations
                                                                                                partial def Eig3x3.Mat3.powSq (M : Mat3) (n : Nat) :

                                                                                                Conditioning for Mat3: exponentiation by squaring, ⌈log₂ n⌉ matrix products instead of n, with M ^ⁿ 0 = Mat3.id.

                                                                                                @[instance_reducible]
                                                                                                Equations
                                                                                                @[instance_reducible]

                                                                                                Flexible compatibility with core's ^.

                                                                                                Equations

                                                                                                Custom typeclasses behind the delimited/Hadamard notation #

                                                                                                class Eig3x3.Abs (α : Type) :

                                                                                                Absolute value behind a typeclass, so the same bars work on Float (magnitude), Vec3 (componentwise), and Mat3 (componentwise).

                                                                                                • abs : αα

                                                                                                  Absolute value / componentwise magnitude.

                                                                                                Instances
                                                                                                  @[instance_reducible]
                                                                                                  Equations
                                                                                                  @[instance_reducible]
                                                                                                  Equations
                                                                                                  @[instance_reducible]
                                                                                                  Equations
                                                                                                  class Eig3x3.Norm (α : Type) :

                                                                                                  Euclidean norm for vectors, Frobenius norm for matrices.

                                                                                                  • norm : αFloat

                                                                                                    Euclidean (vector) or Frobenius (matrix) norm.

                                                                                                  Instances
                                                                                                    @[instance_reducible]
                                                                                                    Equations
                                                                                                    @[instance_reducible]
                                                                                                    Equations
                                                                                                    class Eig3x3.NormSq (α : Type) :

                                                                                                    Squared norm: Euclidean for vectors, Frobenius for matrices.

                                                                                                    • normSq : αFloat

                                                                                                      Squared norm.

                                                                                                    Instances
                                                                                                      @[instance_reducible]
                                                                                                      Equations
                                                                                                      @[instance_reducible]
                                                                                                      Equations
                                                                                                      class Eig3x3.Hadamard (α : Type) :

                                                                                                      Hadamard (componentwise) product.

                                                                                                      • hadamard : ααα

                                                                                                        Componentwise (Hadamard) product.

                                                                                                      Instances
                                                                                                        @[instance_reducible]
                                                                                                        Equations
                                                                                                        @[instance_reducible]
                                                                                                        Equations

                                                                                                        Arithmetic instances (global: these are this package's own types) #

                                                                                                        @[instance_reducible]
                                                                                                        Equations
                                                                                                        @[instance_reducible]
                                                                                                        Equations
                                                                                                        @[instance_reducible]
                                                                                                        Equations
                                                                                                        @[instance_reducible]
                                                                                                        Equations
                                                                                                        @[instance_reducible]
                                                                                                        Equations
                                                                                                        @[instance_reducible]
                                                                                                        Equations
                                                                                                        @[instance_reducible]
                                                                                                        Equations
                                                                                                        @[instance_reducible]
                                                                                                        Equations
                                                                                                        @[instance_reducible]

                                                                                                        Row-vector times matrix product vᵀ M without materializing the transpose.

                                                                                                        Equations
                                                                                                        @[instance_reducible]
                                                                                                        Equations
                                                                                                        @[instance_reducible]

                                                                                                        Matrix inverse through Lean core's Inv class, so M⁻¹ just works.

                                                                                                        Equations

                                                                                                        Scoped operators (open scoped Eig3x3 to activate) #

                                                                                                        Outer product producing the rank-1 matrix u vᵀ. Type \otimes then \_v.

                                                                                                        Equations
                                                                                                        Instances For

                                                                                                          Vector dot product. Type \cdot then \_v (or \dot\_v).

                                                                                                          Equations
                                                                                                          Instances For

                                                                                                            Matrix Frobenius inner product. Type \cdot\_m.

                                                                                                            Equations
                                                                                                            Instances For

                                                                                                              Cross product (⨯₃, U+2A2F). Type \crossproduct\_3.

                                                                                                              Equations
                                                                                                              Instances For

                                                                                                                Absolute value bars, whitespace-sensitive: the bars must hug the argument (|v|, never | v |), so the leading bar will not be mistaken for | in match, which is always followed by a space.

                                                                                                                Equations
                                                                                                                • One or more equations did not get rendered due to their size.
                                                                                                                Instances For

                                                                                                                  Fast natural-number exponent operator. Right-associative. Type ^\^n.

                                                                                                                  Equations
                                                                                                                  Instances For

                                                                                                                    Norm: Euclidean on Vec3, Frobenius on Mat3. Type \Vert.

                                                                                                                    Equations
                                                                                                                    • One or more equations did not get rendered due to their size.
                                                                                                                    Instances For

                                                                                                                      Squared norm. Write it tight: ‖v‖², no space before the ².

                                                                                                                      Equations
                                                                                                                      • One or more equations did not get rendered due to their size.
                                                                                                                      Instances For

                                                                                                                        Hadamard (componentwise) product. Type \odot.

                                                                                                                        Equations
                                                                                                                        Instances For

                                                                                                                          Transpose. Type \^T.

                                                                                                                          Equations
                                                                                                                          Instances For

                                                                                                                            Internal pipeline helpers (package-private) #