Recipes & Applications¶

The ../recipes/ folder contains runnable use-case scripts, Jupyter Notebooks (.ipynb), and an interactive graphical laboratory demonstrating algebrax in real-world scenarios.

Use Cases¶

2D Image Processing¶

• Files: image_processing.py | image_processing.ipynb
• Run: uv run recipes/image_processing.py
• Components: transforms.convolve, StandardSemiring, ArcticSemiring, TropicalSemiring
• Summary: Applies 2D spatial convolution (key_op = add_2d) for linear image filtering (Sobel edge detection, sharpening) and non-linear mathematical morphology (Dilation via Max-Plus, Erosion via Min-Plus). Includes PIL Image support.

Urban Traffic Resilience¶

• Files: traffic_network_resilience.py | traffic_network_resilience.ipynb
• Run: uv run recipes/traffic_network_resilience.py
• Components: semiring.TropicalSemiring, matrix.core.power, analysis.forman_ricci_curvature, probability.markov_steady_state
• Summary: Combines Tropical matrix powers (\(M^k\)) for shortest-path travel latency, Forman-Ricci edge curvature (\(K < 0\)) to identify highway choke points, and Markov steady-state analysis for equilibrium traffic distribution.

Natural Language Parsing¶

• Files: nlp_provenance_parser.py | nlp_provenance_parser.ipynb
• Run: uv run recipes/nlp_provenance_parser.py
• Components: matrix.core.dot, semiring.ProvenanceSemiring, probability.entropy
• Summary: Executes CYK Context-Free Grammar parsing via matrix multiplication (dot), tracks symbolic rule derivation polynomials with ProvenanceSemiring, and audits syntactic ambiguity using Shannon entropy \(H(\text{Trees})\).

Post-Quantum Cryptography¶

• Files: post_quantum_crypto_exchange.py | post_quantum_crypto_exchange.ipynb
• Run: uv run recipes/post_quantum_crypto_exchange.py
• Components: semiring.DigitalSemiring, matrix.core.dot, transforms.z_transform, probability.mutual_information
• Summary: Demonstrates non-commutative matrix key exchange (\(U = A M A, V = B M B\)) over DigitalSemiring, complex Z-transform modulation \(X(z)\) at shared key coordinates, and mutual information verification (\(I(X; Y) = 0\)).

Supply Chain Logistics¶

• Files: supply_chain_optimal_transport.py | supply_chain_optimal_transport.ipynb
• Run: uv run recipes/supply_chain_optimal_transport.py
• Components: trie.AlgebraicTrie, lattice.join, lattice.meet, probability.kl_divergence
• Summary: Stores 3D demand tensors (Warehouse, Region, Season) with subtree contraction via AlgebraicTrie, calculates peak (\(\vee\)) and baseline (\(\wedge\)) capacity bounds with lattice join/meet, and audits allocation mismatch using KL divergence.

Financial Risk & Portfolio¶

• Files: financial_risk_portfolio.py | financial_risk_portfolio.ipynb
• Run: uv run recipes/financial_risk_portfolio.py
• Components: automata.simulate_dfa, analysis.eigen_centrality, semiring.VarianceSemiring, matrix.core.power
• Summary: Simulates automated trade execution state machines (simulate_dfa), computes dominant eigenvector asset centrality (eigen_centrality) on cross-asset correlation matrices, and calculates expected return \(E[X]\) and variance \(\text{Var}(X)\) over multi-step market transition paths.

Extreme Tail Risk & Multivariate Moments¶

• Files: extreme_risk_tail_moments.py | extreme_risk_tail_moments.ipynb
• Run: uv run recipes/extreme_risk_tail_moments.py
• Components: semiring.KurtosisSemiring, semiring.StatisticalMomentSemiring, semiring.MultivariateMomentSemiring, matrix.core.power
• Summary: Evaluates 4th-order Kurtosis (\(\beta_2\)) and Skewness (\(\gamma_1\)) to identify black-swan jump risks under identical Mean/Variance conditions, evaluates 5th-order Hyperskewness (\(\tilde{\mu}_5\)) across 3-hop network cascades, and extracts full \(2 \times 2\) Covariance Matrices \(\boldsymbol{\Sigma}\) and correlation coefficients \(\rho(X_1, X_2)\) via MultivariateMomentSemiring.

Vibration & Structural Analysis¶

• Files: vibration_structural_analysis.py | vibration_structural_analysis.ipynb
• Run: uv run recipes/vibration_structural_analysis.py
• Components: group.compose, group.signature, matrix.academic.determinant, transforms.hilbert
• Summary: Models rotational and reflectional permutation symmetries (compose, signature) across turbine assemblies, evaluates mechanical stiffness determinants (determinant), and extracts instantaneous vibration amplitude envelopes (hilbert) for fatigue detection.

Telecommunications & Fractal Dynamics¶

• Files: telecom_fractal_network.py | telecom_fractal_network.ipynb
• Run: uv run recipes/telecom_fractal_network.py
• Components: transforms.walsh_hadamard, analysis.laplacian, analysis.divergence, metrics.box_counting_dimension
• Summary: Encodes telemetry streams into orthogonal Hadamard spectra (walsh_hadamard) with dual self-inverse reconstruction, evaluates graph Laplacian signal diffusion (laplacian) and net flow divergence (divergence), and measures spatial cell tower coverage dimension (box_counting_dimension).

Quantum Spin-Chain & Convex Optimization¶

• Files: quantum_convex_optimization.py | quantum_convex_optimization.ipynb
• Run: uv run recipes/quantum_convex_optimization.py
• Components: transforms.legendre_fenchel, matrix.core.block_diag, matrix.core.trace, automata.simulate_nfa
• Summary: Computes dual Fenchel-Legendre convex conjugate values (legendre_fenchel) for primal loss functions, constructs block diagonal quantum Hamiltonians (block_diag) with matrix trace invariants (trace), and simulates probabilistic superposition decay (simulate_nfa).

Sensor Network Reliability & Heat Gradient Analysis¶

• Files: sensor_network_reliability.py | sensor_network_reliability.ipynb
• Run: uv run recipes/sensor_network_reliability.py
• Components: semiring.ViterbiSemiring, matrix.core.power, analysis.gaussian_kernel, analysis.gradient, metrics.sparsity
• Summary: Calculates multi-hop maximum transmission success probabilities (\(P_{\max}\)) across lossy wireless links using ViterbiSemiring \((\max, \times)\), computes spatial Gaussian RBF similarity matrices (gaussian_kernel) with sparsity audits, and isolates thermal flux boundaries via discrete scalar field gradients (gradient).

Holographic Bulk-Boundary Duality & Entanglement Entropy¶

• Files: holographic_bulk_boundary.py | holographic_bulk_boundary.ipynb
• Run: uv run recipes/holographic_bulk_boundary.py
• Components: analysis.forman_ricci_curvature, analysis.divergence, trie.AlgebraicTrie, probability.entropy, probability.mutual_information
• Summary: Evaluates discrete negative Forman-Ricci curvature (\(K < 0\)) on hyperbolic bulk graphs (\(\text{AdS}_3\)), proves the discrete Holographic Gauss-Stokes divergence theorem (\(\int_{\text{Bulk}} \text{div}(F) = \oint_{\partial} F\)), contracts MERA tensor network scale trees (AlgebraicTrie), and calculates Ryu-Takayanagi boundary entanglement entropy \(S(A) = \frac{\text{Area}(\gamma_A)}{4 G_N}\).

Optical Holography Simulation & Wavefront Reconstruction¶

• Files: optical_holography_simulation.py | optical_holography_simulation.ipynb
• Run: uv run recipes/optical_holography_simulation.py
• Components: transforms.dft, transforms.idft, probability.entropy
• Summary: Simulates physical optical interference patterns \(I(x) = |O(x) + R(x)|^2\) between object and reference plane waves, reconstructs virtual object wavefronts via reference illumination (\(R \cdot I\)), evaluates angular frequency diffraction spectra using dft and idft, and audits Michelson fringe visibility (\(V = 98\%\)) and Shannon entropy.

Topological Data Analysis (TDA) & Persistent Homology¶

• Files: topological_data_analysis.py | topological_data_analysis.ipynb
• Run: uv run recipes/topological_data_analysis.py
• Components: semiring.BooleanSemiring, matrix.power, analysis.forman_ricci_curvature, matrix.academic.determinant
• Summary: Evaluates transitive closure matrices over BooleanSemiring \((\lor, \land)\) to extract connected component equivalence classes and zeroth Betti numbers \(b_0(\epsilon)\) across Vietoris-Rips point-cloud filtrations, isolates topological inter-cluster bridges via negative Forman-Ricci edge curvature (\(K < 0\)), and audits boundary operator Laplacians via determinant singularities.

Control Theory & State-Space Systems¶

• Files: control_theory_state_space.py | control_theory_state_space.ipynb
• Run: uv run recipes/control_theory_state_space.py
• Components: matrix.core.power, transforms.z_transform, matrix.academic.determinant
• Summary: Computes multi-step discrete state transition trajectories \(x[k] = A^k x[0]\), evaluates Z-domain transfer functions \(H(z) = \sum h[n] z^{-n}\) for impulse response sequences, and audits system asymptotic stability via characteristic matrix determinants \(\det(I - A)\).

Algebraic Knot Theory & Topological Invariants¶

• Files: algebraic_knot_theory.py | algebraic_knot_theory.ipynb
• Run: uv run recipes/algebraic_knot_theory.py
• Components: semiring.KnotSemiring, semiring.MonoidAlgebraSemiring, group.compose, group.signature
• Summary: Multiplies formal Skein module knot states over the connected sum monoid (\(\#\)), composes Artin braid group strand crossings \(B_n\) with parity signature invariants (\(\pm 1\)), and evaluates Laurent Jones polynomial multiplications \(V(K_1 \# K_2) = V(K_1) \cdot V(K_2)\).

Sheaf Cohomology & Multi-Agent Network Consensus¶

• Files: sheaf_cohomology_consensus.py | sheaf_cohomology_consensus.ipynb
• Run: uv run recipes/sheaf_cohomology_consensus.py
• Components: analysis.gradient, analysis.laplacian, semiring.MonoidAlgebraSemiring
• Summary: Measures edge channel state inconsistencies via coboundary gradients \(\delta_0(f)\), diffuses multi-robot state estimates toward global mean consensus via Sheaf Laplacian iterations (\(L_\mathcal{F} = \text{div}(\text{grad} f)\)), and aggregates localized agent observation sections in formal monoid linear combinations.

Trajectoid Rolling Kinematics & SO(3) Path Tracing¶

• Files: trajectoid_rolling_kinematics.py | trajectoid_rolling_kinematics.ipynb
• Run: uv run recipes/trajectoid_rolling_kinematics.py
• Components: analysis.gradient, matrix.core.dot, metrics.sparsity
• Summary: Evaluates discrete velocity vectors along periodic 2D figure-eight lemniscate curves via gradient, integrates 3D non-holonomic spatial orientation matrix steps \(R_{k+1} = R_k \cdot dR_k\) in \(SO(3)\), and audits contact matrix sparsity and closed-loop trajectory tracking precision.

Sparse Tensor Einstein Summation & Multimodal Fusion¶

• Files: sparse_tensor_einsum.py | sparse_tensor_einsum.ipynb
• Run: uv run recipes/sparse_tensor_einsum.py
• Components: tensor.einsum, tensor.outer_product, tensor.tensordot, tensor.flatten_tensor
• Summary: Evaluates arbitrary-rank sparse tensor contractions \(C_{i, l} = \bigoplus_{j, k} A_{i, j, k} \otimes B_{j, k, l}\) over polymorphic semirings (Standard and Tropical Min-Plus), computes rank-expanding tensor outer products \(A \otimes B\), and handles bidirectional nested dict conversions.

Schwarzschild Black Hole Spacetime & Gravitational Lensing¶

• Files: blackhole_spacetime_simulation.py | blackhole_spacetime_simulation.ipynb
• Run: uv run recipes/blackhole_spacetime_simulation.py
• Components: tensor.einsum, transforms.z_transform, analysis.gradient, analysis.forman_ricci_curvature, probability.entropy, probability.kl_divergence
• Summary: Constructs Schwarzschild spacetime metric tensors \(g_{\mu \nu}\) around event horizon \(r_s\), contracts inverse metrics \(g^{\mu \alpha} g_{\alpha \nu} = \delta^\mu_\nu\) via tensor.einsum, models gravitational redshift spectral modulation via z_transform, evaluates photon deflection angles \(\Delta \phi = \frac{4GM}{c^2 b}\) and spatial curvature near the photon sphere, and audits Bekenstein-Hawking entropy \(S_{\text{BH}} = \frac{A}{4 \ell_P^2}\) and Hawking radiation quantum information scrambling.

3D Gaussian Splatting & Projective Screen Rendering¶

• Files: gaussian_splatting_rendering.py | gaussian_splatting_rendering.ipynb
• Run: uv run recipes/gaussian_splatting_rendering.py
• Components: matrix.core.dot, matrix.core.transpose, analysis.gaussian_kernel
• Summary: Constructs 3D spatial Gaussian covariance matrices \(\Sigma = R S S^T R^T\) via \(SO(3)\) Euler rotation matrix compositions, projects 3D spatial ellipsoids into 2D screen coordinate covariance matrices \(\Sigma' = J W \Sigma W^T J^T\) using perspective Jacobian transformations, and performs depth-sorted volumetric \(\alpha\)-compositing ray-marching.

Simplicial Homology & Topological Betti Barcodes (EP-0110)¶

• Files: topological_homology_betti.py | topological_homology_betti.ipynb
• Run: uv run recipes/topological_homology_betti.py
• Components: homology.SimplicialComplex, homology.betti_numbers, analysis.SparseChainComplex
• Summary: Constructs \(k\)-simplices \((v_0, \dots, v_k)\), evaluates sparse boundary matrices \(D_k\), verifies homological nilpotency \(D_{k-1} \circ D_k = \mathbf{0}\), and computes Betti number invariants \(\beta_k = \dim(\ker D_k) - \text{rank}(D_{k+1})\).

Clifford Geometric Algebra & 3D Rotor Rotations (EP-0111)¶

• Files: clifford_rotor_kinematics.py | clifford_rotor_kinematics.ipynb
• Run: uv run recipes/clifford_rotor_kinematics.py
• Components: clifford.CliffordSemiring, clifford.rotor_rotation, semiring.QuotientMonoidAlgebraSemiring
• Summary: Implements multivector geometric product \(A B = A \cdot B + A \wedge B\) over \(Cl(p,q,r)\) blade keys and performs 3D spatial rotor rotations \(v' = R v R^\dagger\) without gimbal lock.

Galois Finite Fields & Cryptographic Arithmetic (EP-0112)¶

• Files: galois_field_cryptography.py | galois_field_cryptography.ipynb
• Run: uv run recipes/galois_field_cryptography.py
• Components: galois.GaloisFieldSemiring, galois.gf_matrix_mul, semiring.QuotientMonoidAlgebraSemiring
• Summary: Evaluates finite field arithmetic \(\text{GF}(p^m)\) over polynomial modulo quotient semirings \(P(x) = x^8 + x^4 + x^3 + x + 1\) and computes AES MixColumns matrix products.

Categorical Morphisms & Kleisli Monadic Composition (EP-0113)¶

• Files: categorical_kleisli_monads.py | categorical_kleisli_monads.ipynb
• Run: uv run recipes/categorical_kleisli_monads.py
• Components: category.kleisli_compose, semiring.ViterbiSemiring, semiring.TropicalSemiring
• Summary: Formalizes effectful monadic morphisms \(f: A \to T(B)\) via Kleisli matrix composition \(g \circ_T f = \text{dot}(f, g, \text{semiring})\) across probabilistic, cost-metric, and reachability monads.

Forward-Mode Automatic Differentiation¶

• Files: forward_mode_autodiff.py | forward_mode_autodiff.ipynb
• Run: uv run recipes/forward_mode_autodiff.py
• Components: semiring.StandardSemiring, matrix.core.dot, typing.SparseVector
• Summary: Executes exact machine-precision Forward-Mode AD via quotient polynomial rings \(\mathbb{R}[\epsilon]/(\epsilon^2)\) with custom carrier types DualNumber and GradientDualNumber plugged into StandardSemiring(dtype=DualNumber) with zero library core modifications.

Reverse-Mode Backpropagation & Sparse Neural Networks¶

• Files: sparse_neural_backprop.py | sparse_neural_backprop.ipynb
• Run: uv run recipes/sparse_neural_backprop.py
• Components: matrix.core.transpose, matrix.core.dot, typing.SparseMatrix
• Summary: Demonstrates the linear algebraic foundation of Deep Learning backpropagation: adjoint pullback via transposed sparse matrix multiplication (\(W^T \cdot \bar{z}\)) and outer product weight gradients (\(\bar{z} \otimes x^T\)). Trains a multi-layer sparse neural network (SparseMLP) on XOR.

Functional Reverse-Mode Autograd Engine¶

• Files: functional_autograd_engine.py | functional_autograd_engine.ipynb
• Run: uv run recipes/functional_autograd_engine.py
• Components: matrix.core.dot, typing.SparseMatrix
• Summary: Implements a pure functional Reverse-Mode Automatic Differentiation DAG engine in under 100 lines of Python. Features dynamic computation graphs, Vector-Jacobian Product (VJP) closures, reverse topological sort traversal, and parameter optimization.

Quantum Feynman Path Integrals & Interference¶

• Files: quantum_feynman_path_integral.py | quantum_feynman_path_integral.ipynb
• Run: uv run recipes/quantum_feynman_path_integral.py
• Components: semiring.StandardSemiring(dtype=complex), matrix.core.dot, typing.SparseMatrix
• Summary: Simulates Richard Feynman's discrete sum-over-histories formulation of quantum mechanics using standard Python complex numbers and StandardSemiring(dtype=complex). Evaluates multi-path wave interference, double-slit diffraction, topological Aharonov-Bohm phase shifts (\(\Delta \phi = \frac{q\Phi}{\hbar}\)), and Born's rule probabilities (\(P = |K|^2\)) with zero custom physics classes.

Relativistic Dirac Spinors & Spacetime Algebra¶

• Files: relativistic_dirac_spinor.py | relativistic_dirac_spinor.ipynb
• Run: uv run recipes/relativistic_dirac_spinor.py
• Components: clifford.CliffordSemiring(p=1, q=3), matrix.core.dot, typing.SparseVector
• Summary: Implements relativistic spin-\(\frac{1}{2}\) Dirac fermions in Hestenes' Spacetime Algebra (STA) over Minkowski spacetime \(\mathbb{R}^{1,3}\). Represents 4-spinors \(\Psi\) as even multivectors \(\psi \in Cl^+(1, 3)\), proves the \(4\pi\) rotation periodicity (\(\psi(2\pi) = -\psi(0), \psi(4\pi) = +\psi(0)\)), evaluates hyperbolic Lorentz boosts (\(L = \exp(-\frac{\xi}{2}\gamma_0\gamma_k)\)), computes conserved future-directed timelike probability 4-currents (\(J = \psi \gamma_0 \psi^\dagger\)), and routes spinor wavepackets through causal Minkowski diamond lattices.

Distributed Vector Clocks & Causal Semilattices¶

• Files: distributed_vector_clocks.py | distributed_vector_clocks.ipynb
• Run: uv run recipes/distributed_vector_clocks.py
• Components: lattice.combine, semiring.ArcticSemiring, semiring.BooleanSemiring, matrix.core.dot
• Summary: Models asynchronous multi-process distributed systems, Lamport's Happened-Before relation (\(\to\)), and Mattern/Fidge Vector Clock timestamps over coordinate Join-Semilattices \((\mathbb{N}^k, \le, \vee)\). Evaluates pairwise event causality matrices (\(a \to b\) vs \(a \parallel b\)), contracts multi-hop message DAGs via Boolean reachability and Arctic \((\max, +)\) critical path latency, and demonstrates state-based CRDT replica synchronization.

Matrix Fiber Bundles & Parallel Transport¶

• Files: matrix_bundle_parallel_transport.py | matrix_bundle_parallel_transport.ipynb
• Run: uv run recipes/matrix_bundle_parallel_transport.py
• Components: semiring.Semiring[np.ndarray], matrix.core.dot, matrix.core.power
• Summary: Models non-commutative matrix-valued semirings where elements are linear maps / rotation matrices (\(\mathbb{R}^{d \times d}\)). Evaluates sequential parallel transport across robot arm kinematic linkages, calculates closed-loop gauge field Wilson loop holonomy curvature \(W = \operatorname{Tr}(U_{\partial \Sigma})\), and audits multi-currency foreign exchange arbitrage cycles using tropical matrix Kleene star closure.

Convex Hull Semiring & Pareto Uncertainty¶

• Files: convex_hull_pareto_intervals.py | convex_hull_pareto_intervals.ipynb
• Run: uv run recipes/convex_hull_pareto_intervals.py
• Components: semiring.Semiring[tuple[float, float]], matrix.core.power
• Summary: Implements Dyer's Convex Hull Semiring over bounding intervals \([\underline{x}, \overline{x}]\) under convex hull union (\(\oplus\)) and Minkowski addition (\(\otimes\)). Solves multi-objective Pareto routing, propagating guaranteed worst-case and best-case delay envelopes across uncertain communication networks.

Combinatorial Dyck Paths & Catalan Numbers¶

• Files: combinatorial_dyck_paths.py | combinatorial_dyck_paths.ipynb
• Run: uv run recipes/combinatorial_dyck_paths.py
• Components: semiring.StandardSemiring, matrix.core.power
• Summary: Formulates enumerative combinatorics and lattice Dyck paths as walks on 1D height graphs. Evaluates exact Catalan numbers \(C_n = \frac{1}{n+1}\binom{2n}{n}\) via binary matrix exponentiation \((A^{2n})_{0,0}\) in \(\mathcal{O}(n^3 \log n)\) time, and calculates height-constrained path invariants.

Spectral Graph Clustering & Manifold Smoothing¶

• Files: spectral_graph_clustering.py | spectral_graph_clustering.ipynb
• Run: uv run recipes/spectral_graph_clustering.py
• Components: matrix.core.laplacian_matrix, analysis.fiedler_vector, analysis.spectral_bipartition, analysis.laplacian_smoothing, analysis.laplacian_spectrum
• Summary: Formulates graph manifold clustering and diffusion smoothing via Spectral Graph Theory (EP-0152). Computes discrete combinatorial Laplacians (\(L = D - W\)), solves algebraic connectivity \(\lambda_2\) and the Fiedler eigenvector \(\mathbf{v}_2\) via Rayleigh-Quotient CG, partitions communities bounding Cheeger conductance, low-pass filters spatial node noise via Dirichlet energy minimization, and audits semiring factory ergonomics (Semiring.default(), Semiring.normalize(), Semiring.create()).

Graphical Laboratory¶

DearPyGui Interactive Lab¶

• File: lab.py
• Run: uv run recipes/lab.py
• Summary: Desktop GUI built with DearPyGui featuring 12 interactive modules: real image file convolution with side-by-side texture preview, force-directed graph curvature visualization, semiring matrix powers, CYK parsing, DFA/NFA simulators, signal transforms, and information theory tools.

Development & Golden Source Sync¶

Authoring Recipes¶

All recipes in recipes/ are authored as Python scripts (.py) using Jupytext Percent format (# %% cell markers) as the canonical Golden Source. Jupyter Notebooks (.ipynb) are auto-generated from these scripts.

Pre-Commit Hook Setup¶

Install the pre-commit Git hook to automatically sync .ipynb notebooks whenever you edit .py recipe scripts:

# Ensure local repository hooks directory is active
git config --local core.hooksPath .git/hooks

# Install pre-commit hook
uvx pre-commit install

Manual Synchronization & Testing¶

# Refresh all Jupyter notebooks from Golden Source scripts
uvx jupytext --to notebook recipes/*.py

# Run automated nbmake tests on all notebooks
uv run pytest --nbmake recipes/