pyxfem.core.nbkalgebra2d module
Created march 2026 @author: nchevaug
2D Algebraic Kernel for High-Performance Numba JIT Compilation.
Philosophy & Architecture: This module provides fundamental 2D vector and symmetric tensor operations specifically tailored for Numba’s nopython mode (@njit).
To achieve maximum performance and avoid the massive overhead of heap allocations inside hot loops (e.g., cell or vertex iterations), this module STRICTLY avoids NumPy arrays for small local variables. Instead, it relies entirely on Python Tuple of floats.
Why Tuples? When compiled with Numba and LLVM, homogenous tuples of primitive types (like Tuple[float, float]) are not treated as standard Python objects. They are lowered directly into C-style structs passed by value, which the LLVM backend maps directly into the processor’s hardware registers. This guarantees zero-allocation overhead, completely bypasses the Python garbage collector, and allows aggressive compiler optimizations like loop unrolling and SIMD vectorization (enhanced by fastmath=True).
Storage Convention: - Vectors (Vec2) are stored as 2-tuples: (x, y) - Symmetric 2x2 Matrices (Sy22) are stored as 3-tuples: (A00, A01, A11).
This exploits the symmetry ($A_{01} = A_{10}$) to save register space and reduce floating-point operations.
- pyxfem.core.nbkalgebra2d.sy22_add(A: Tuple[float64, float64, float64], B: Tuple[float64, float64, float64]) Tuple[float64, float64, float64][source]
Adds two symmetric 2x2 matrices. Math: $A + B$
- pyxfem.core.nbkalgebra2d.sy22_mv(A: Tuple[float64, float64, float64], x: Tuple[float64, float64]) Tuple[float64, float64][source]
Performs a matrix-vector multiplication for a symmetric 2x2 matrix. Math: $A x$ Note: The matrix is implicitly reconstructed from its components $(A_{00}, A_{01}, A_{11})$.
- pyxfem.core.nbkalgebra2d.sy22_r(alpha: float64, x: Tuple[float64, float64]) Tuple[float64, float64, float64][source]
Computes the symmetric rank-1 update (dyadic product). Math: $alpha (x otimes x)$
- pyxfem.core.nbkalgebra2d.sy22_r2(alpha: float64, x: Tuple[float64, float64], y: Tuple[float64, float64]) Tuple[float64, float64, float64][source]
Computes the scalar-penalized symmetric rank-2 update. Math: $alpha (x otimes y + y otimes x)$
- pyxfem.core.nbkalgebra2d.sy22_smv(A: Tuple[float64, float64, float64], b: Tuple[float64, float64]) Tuple[float64, float64][source]
Solves the linear system $A x = b$ for a symmetric 2x2 matrix using explicit Cramer’s rule inversion. Math: $x = A^{-1} b$
- pyxfem.core.nbkalgebra2d.sy22_trace(A: Tuple[float64, float64, float64]) float64[source]
Computes the trace of a symmetric 2x2 matrix. Math: $text{Tr}(A) = A_{00} + A_{11}$
- pyxfem.core.nbkalgebra2d.vec2_add(a: Tuple[float64, float64], b: Tuple[float64, float64]) Tuple[float64, float64][source]
Adds two 2D vectors. Math: $a + b$
- pyxfem.core.nbkalgebra2d.vec2_add3(a: Tuple[float64, float64], b: Tuple[float64, float64], c: Tuple[float64, float64]) Tuple[float64, float64][source]
Adds three 2D vectors. Math: $a + b + c$
- pyxfem.core.nbkalgebra2d.vec2_dot(a: Tuple[float64, float64], b: Tuple[float64, float64]) float64[source]
Computes the dot product of two 2D vectors. Math: $a cdot b = a_0 b_0 + a_1 b_1$
- pyxfem.core.nbkalgebra2d.vec2_norm(a: Tuple[float64, float64]) float64[source]
Computes the Euclidean (L2) norm of a 2D vector. Math: $|a| = sqrt{a_0^2 + a_1^2}$
- pyxfem.core.nbkalgebra2d.vec2_scal(alpha: float64, x: Tuple[float64, float64]) Tuple[float64, float64][source]
Multiplies a 2D vector by a scalar. Math: $alpha x$