Metadata-Version: 2.5
Name: algebrax
Version: 0.9.0
Summary: Algebraic Structures and Semirings for Python
Project-URL: Homepage, https://github.com/erivlis/algebrax
Project-URL: Source Code, https://github.com/erivlis/algebrax.git
Project-URL: Bug Tracker, https://github.com/erivlis/algebrax/issues
Project-URL: Documentation, https://erivlis.github.io/algebrax
Author-email: Eran Rivlis <eran@rivlis.info>
Maintainer-email: Eran Rivlis <eran@rivlis.info>
License-Expression: MIT
License-File: LICENSE
Keywords: algebra,field,group,mapping,math,mathematics,matrix,monoid,ring,semiring
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: mappingtools>=0.10.0
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/assets/images/banner.png" alt="AlgebraX Banner" width="100%">
</p>

<p align="center">
  <b>AlgebraX - Algebraic Primitives for Sparse Data Structures in Python</b>
</p>

<table>
  <tr style="vertical-align: middle;">
    <td>Package</td>
    <td>
      <img alt="PyPI - Version" class="off-glb" loading="lazy" src="https://img.shields.io/pypi/v/algebrax.svg?logo=pypi&logoColor=lightblue">
      <img alt="PyPI - Status" class="off-glb" loading="lazy" src="https://img.shields.io/pypi/status/algebrax.svg?logo=pypi&logoColor=lightblue">
      <img alt="PyPI - Python Version" class="off-glb" loading="lazy" src="https://img.shields.io/pypi/pyversions/algebrax.svg?logo=python&label=Python&logoColor=lightblue">
      <!--img alt="PyPI - Downloads" src="https://img.shields.io/pypi/dd/algebrax?logo=pypi&logoColor=lightblue"-->
      <img alt="PyPI - Dependents" src="https://dependents.info/erivlis/algebrax/badge?logo=pypi&logoColor=lightblue">
      <img alt="Libraries.io SourceRank" src="https://img.shields.io/librariesio/sourcerank/pypi/algebrax.svg?logo=Libraries.io&label=SourceRank">
    </td>
  </tr>
  <tr>
    <td>Code</td>
    <td>
      <img alt="GitHub" src="https://img.shields.io/github/license/erivlis/algebrax">
      <img alt="GitHub repo size" src="https://img.shields.io/github/repo-size/erivlis/algebrax.svg?label=Size&logo=git">
      <img alt="GitHub last commit (by committer)" src="https://img.shields.io/github/last-commit/erivlis/algebrax.svg?&logo=git">
      <a href="https://github.com/erivlis/algebrax/graphs/contributors"><img alt="Contributors" src="https://img.shields.io/github/contributors/erivlis/algebrax.svg?&logo=git"></a>
    </td>
  </tr>
  <tr>
    <td>Tools</td>
    <td>
      <a href="https://www.jetbrains.com/pycharm/"><img alt="PyCharm" src="https://img.shields.io/badge/PyCharm-FCF84A.svg?logo=PyCharm&logoColor=black&labelColor=21D789&color=FCF84A"></a>
      <a href="https://github.com/astral-sh/uv"><img alt="uv" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" style="max-width:100%;"></a>
      <a href="https://github.com/astral-sh/ruff"><img alt="Ruff" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" style="max-width:100%;"></a>
      <a href="https://hatch.pypa.io"><img alt="Hatch project" class="off-glb" loading="lazy" src="https://img.shields.io/badge/%F0%9F%A5%9A-Hatch-4051b5.svg"></a>
      <a href="https://commitizen-tools.github.io/commitizen"><img alt="commitizen" src="https://custom-icon-badges.demolab.com/badge/commitizen-7e56c2?logo=commitizen&labelColor=grey"></a>
      <a href="https://zensical.org/"><img alt="Zensical" src="https://custom-icon-badges.demolab.com/badge/zensical-ff9100?logo=zensical&labelColor=grey"></a>
      <a href="https://jupytext.org/"><img alt="Jupytext" src="https://img.shields.io/badge/Jupytext-FF6F61?logo=jupyter&labelColor=grey"></a>
      <a href="https://library-skills.io"><img alt="agentskills" src="https://img.shields.io/badge/agentskills-white?logo=agentskills&labelColor=grey"></a>
    </td>
  </tr>
  <tr>
    <td>CI/CD</td>
    <td>
      <a href="https://github.com/erivlis/algebrax/actions/workflows/test.yml"><img alt="Test" src="https://github.com/erivlis/algebrax/actions/workflows/test.yml/badge.svg"></a>
      <a href="https://github.com/erivlis/algebrax/actions/workflows/test-beta.yml"><img alt="Publish" src="https://github.com/erivlis/algebrax/actions/workflows/test-beta.yml/badge.svg"></a>
      <a href="https://github.com/erivlis/algebrax/actions/workflows/benchmark.yml"><img alt="Benchmarks" src="https://github.com/erivlis/algebrax/actions/workflows/benchmark.yml/badge.svg"></a>
      <a href="https://github.com/erivlis/algebrax/actions/workflows/publish.yml"><img alt="Publish" src="https://github.com/erivlis/algebrax/actions/workflows/publish.yml/badge.svg"></a>
      <a href="https://github.com/erivlis/algebrax/actions/workflows/publish-docs.yaml"><img alt="Publish Docs" src="https://github.com/erivlis/algebrax/actions/workflows/publish-docs.yml/badge.svg"></a>
    </td>
  </tr>
  <tr>
    <td>Scans</td>
    <td>
      <a href="https://codecov.io/gh/erivlis/algebrax"><img alt="Coverage" src="https://codecov.io/gh/erivlis/algebrax/graph/badge.svg?token=POODT8M9NV"/></a>
      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_algebrax"><img alt="Quality Gate Status" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_algebrax&metric=alert_status"></a>
      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_algebrax"><img alt="Security Rating" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_algebrax&metric=security_rating"></a>
      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_algebrax"><img alt="Maintainability Rating" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_algebrax&metric=sqale_rating"></a>
      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_algebrax"><img alt="Reliability Rating" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_algebrax&metric=reliability_rating"></a>
      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_algebrax"><img alt="Lines of Code" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_algebrax&metric=ncloc"></a>
      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_algebrax"><img alt="Vulnerabilities" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_algebrax&metric=vulnerabilities"></a>
      <a href="https://sonarcloud.io/summary/new_code?id=erivlis_algebrax"><img alt="Bugs" src="https://sonarcloud.io/api/project_badges/measure?project=erivlis_algebrax&metric=bugs"></a>
      <a href="https://app.codacy.com/gh/erivlis/algebrax/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade"><img alt="Codacy Quality" src="https://app.codacy.com/project/badge/Grade/8b83a99f939b4883ae2f37d7ec3419d1"></a>
      <a href="https://app.codacy.com/gh/erivlis/algebrax/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage"><img alt="Codacy Coverage" src="https://app.codacy.com/project/badge/Coverage/8b83a99f939b4883ae2f37d7ec3419d1"/></a>
      <a href="https://www.codefactor.io/repository/github/erivlis/algebrax/overview/main"><img src="https://www.codefactor.io/repository/github/erivlis/algebrax/badge/main" alt="CodeFactor" /></a>
      <a href="https://snyk.io/test/github/erivlis/algebrax"><img alt="Snyk" src="https://snyk.io/test/github/erivlis/algebrax/badge.svg"></a>
      <a href="https://app.codspeed.io/erivlis/algebrax?utm_source=badge"><img src="https://img.shields.io/endpoint?url=https://codspeed.io/badge.json" alt="CodSpeed"/></a>
      <a href="https://scorecard.dev/viewer/?uri=github.com/erivlis/algebrax"><img src="https://api.scorecard.dev/projects/github.com/erivlis/algebrax/badge" alt="OpenSSF Scorecard"/></a>
    </td>
  </tr>
  <tr>
    <td>Mentions</td>
    <td>
      <!-- <a href="https://www.youtube.com/live/k01G0b0Y0Jg?si=030OT8sK3BqPyy8r&t=1028"><img alt="PythonBytes Podcast" src="https://img.shields.io/badge/Python_Bytes-Ep. 361-D7F9FF?logo=applepodcasts&labelColor=blue"></a> -->
      <!-- a href="https://pythonhub.dev/digest/2024-08-06/"><img alt="Static Badge" src="https://img.shields.io/badge/PythonHub-2024.08.06-gold?labelColor=blue"></a -->
      <a href="https://pythonhub.dev/digest/2026-08-09/"><img alt="Python Hub" src="https://custom-icon-badges.demolab.com/badge/Python%20Hub-2026.08.09-gold?logo=pythonhub&labelColor=grey"></a>
      <a href="https://x.com/PythonHub/status/2085323880172749251"><img alt="X" src="https://img.shields.io/twitter/url?url=https%3A%2F%2Fx.com%2FPythonHub%2Fstatus%2F2085323880172749251"></a>
    </td>
  </tr>
</table>


---

`AlgebraX` treats Python's native `dict` as a first-class sparse algebraic object, unifying linear algebra, graph
algorithms, formal language theory, signal transforms, and information metrics under a single polymorphic framework.

## Key Features

* ⚡ **Zero Heavy Dependencies**: Pure Python core requiring no C++ build steps. Includes native bidirectional converters
  between sparse dict mappings and dense multidimensional arrays.
* 🔄 **Polymorphic Semiring Computing**: By swapping the algebraic semiring $(\oplus, \otimes)$, the exact same matrix
  algorithms compute standard linear algebra, tropical shortest path latencies, or symbolic rule provenance.
* 🌌 **Sparse Multidimensional Tensors**: Arbitrary nested mappings behave as infinite-dimensional sparse tensors, tries,
  and lattices (`AlgebraicTrie`) with custom key operators.
* 🔬 **Interactive Desktop GUI**: Repo includes [DearPyGui](https://github.com/hoffstadt/DearPyGui)  with 12 interactive
  modules, dynamic texture previews, force-directed graph canvases, and signal transforms.

---

## Installation

```bash
# Using uv (recommended)
uv add algebrax

# Using pip
pip install algebrax
```

---

## 5-Minute Quickstart

By changing the `semiring` parameter in `matrix.dot`, you can transform standard linear matrix multiplication into
shortest-path solvers or symbolic rule derivation tracking:

```python
import algebrax as ax

# Define a Sparse Graph Adjacency / Distance Matrix
graph = {
    0: {1: 2.0, 2: 10.0},
    1: {2: 3.0},
}

# 1. Standard Linear Matrix Multiplication (+, *)
linear_mult = ax.matrix.dot(graph, graph, semiring=ax.semiring.StandardSemiring())
print('Linear Combination (0->2):', linear_mult[0][2])
# Output: 30.0

# 2. Tropical Shortest Path (min, +)
shortest_path = ax.matrix.dot(graph, graph, semiring=ax.semiring.TropicalSemiring())
print('Shortest Path Cost (0->1->2):', shortest_path[0][2])
# Output: 5.0

# 3. Symbolic Provenance Rule Tracking
provenance_graph = {
    0: {1: {('rule_A',): 1}, 2: {('rule_C',): 1}},
    1: {2: {('rule_B',): 1}},
}
provenance_mult = ax.matrix.dot(provenance_graph, provenance_graph, semiring=ax.semiring.ProvenanceSemiring())
print('Symbolic Derivation Polynomial:', provenance_mult[0][2])
# Output: {('rule_A', 'rule_B'): 1}
```

---

## Use Case Recipes & Jupyter Notebooks

The [`recipes/`](recipes) directory contains standalone CLI scripts and matching interactive `.ipynb` notebooks for 29
real-world scenarios:

| Category                       |                                               Recipe & Notebook                                               | Core Algebraic Components                                                                                                |
|:-------------------------------|:-------------------------------------------------------------------------------------------------------------:|:-------------------------------------------------------------------------------------------------------------------------|
| **Image Processing**           |               [`🐍`](recipes/image_processing.py) &nbsp; [`📓`](recipes/image_processing.ipynb)               | `transforms.convolve`, `StandardSemiring`, `ArcticSemiring`, `TropicalSemiring`                                          |
| **Traffic Resilience**         |     [`🐍`](recipes/traffic_network_resilience.py) &nbsp; [`📓`](recipes/traffic_network_resilience.ipynb)     | `semiring.TropicalSemiring`, `matrix.power`, `analysis.forman_ricci_curvature`                                           |
| **NLP Parsing**                |          [`🐍`](recipes/nlp_provenance_parser.py) &nbsp; [`📓`](recipes/nlp_provenance_parser.ipynb)          | `matrix.dot`, `semiring.ProvenanceSemiring`, `probability.entropy`                                                       |
| **Post-Quantum Security**      |   [`🐍`](recipes/post_quantum_crypto_exchange.py) &nbsp; [`📓`](recipes/post_quantum_crypto_exchange.ipynb)   | `semiring.DigitalSemiring`, `transforms.z_transform`, `probability.mutual_information`                                   |
| **Supply Chain Logistics**     | [`🐍`](recipes/supply_chain_optimal_transport.py) &nbsp; [`📓`](recipes/supply_chain_optimal_transport.ipynb) | `trie.AlgebraicTrie`, `lattice.join`, `lattice.meet`, `probability.kl_divergence`                                        |
| **Financial Risk**             |       [`🐍`](recipes/financial_risk_portfolio.py) &nbsp; [`📓`](recipes/financial_risk_portfolio.ipynb)       | `automata.simulate_dfa`, `analysis.eigen_centrality`, `semiring.VarianceSemiring`                                        |
| **Structural Analysis**        |  [`🐍`](recipes/vibration_structural_analysis.py) &nbsp; [`📓`](recipes/vibration_structural_analysis.ipynb)  | `group.compose`, `group.signature`, `matrix.academic.determinant`, `transforms.hilbert`                                  |
| **Telecommunications**         |        [`🐍`](recipes/telecom_fractal_network.py) &nbsp; [`📓`](recipes/telecom_fractal_network.ipynb)        | `transforms.walsh_hadamard`, `analysis.laplacian`, `metrics.box_counting_dimension`                                      |
| **Quantum Optimization**       |    [`🐍`](recipes/quantum_convex_optimization.py) &nbsp; [`📓`](recipes/quantum_convex_optimization.ipynb)    | `transforms.legendre_fenchel`, `matrix.block_diag`, `matrix.trace`, `automata.simulate_nfa`                              |
| **Sensor Reliability**         |     [`🐍`](recipes/sensor_network_reliability.py) &nbsp; [`📓`](recipes/sensor_network_reliability.ipynb)     | `semiring.ViterbiSemiring`, `matrix.power`, `analysis.gaussian_kernel`, `analysis.gradient`                              |
| **Holographic Duality**        |      [`🐍`](recipes/holographic_bulk_boundary.py) &nbsp; [`📓`](recipes/holographic_bulk_boundary.ipynb)      | `analysis.forman_ricci_curvature`, `analysis.divergence`, `trie.AlgebraicTrie`, `probability.entropy`                    |
| **Optical Holography**         |  [`🐍`](recipes/optical_holography_simulation.py) &nbsp; [`📓`](recipes/optical_holography_simulation.ipynb)  | `transforms.dft`, `transforms.idft`, `probability.entropy`                                                               |
| **Topological Data Analysis**  |      [`🐍`](recipes/topological_data_analysis.py) &nbsp; [`📓`](recipes/topological_data_analysis.ipynb)      | `semiring.BooleanSemiring`, `matrix.power`, `analysis.forman_ricci_curvature`, `matrix.academic.determinant`             |
| **Control Theory**             |     [`🐍`](recipes/control_theory_state_space.py) &nbsp; [`📓`](recipes/control_theory_state_space.ipynb)     | `matrix.power`, `transforms.z_transform`, `matrix.academic.determinant`                                                  |
| **Algebraic Knot Theory**      |          [`🐍`](recipes/algebraic_knot_theory.py) &nbsp; [`📓`](recipes/algebraic_knot_theory.ipynb)          | `semiring.KnotSemiring`, `semiring.MonoidAlgebraSemiring`, `group.compose`, `group.signature`                            |
| **Sheaf Cohomology**           |     [`🐍`](recipes/sheaf_cohomology_consensus.py) &nbsp; [`📓`](recipes/sheaf_cohomology_consensus.ipynb)     | `analysis.gradient`, `analysis.laplacian`, `semiring.MonoidAlgebraSemiring`                                              |
| **Trajectoid Kinematics**      |  [`🐍`](recipes/trajectoid_rolling_kinematics.py) &nbsp; [`📓`](recipes/trajectoid_rolling_kinematics.ipynb)  | `analysis.gradient`, `matrix.dot`, `metrics.sparsity`                                                                    |
| **Sparse Tensor Einsum**       |           [`🐍`](recipes/sparse_tensor_einsum.py) &nbsp; [`📓`](recipes/sparse_tensor_einsum.ipynb)           | `tensor.einsum`, `tensor.outer_product`, `tensor.tensordot`, `tensor.flatten_tensor`                                     |
| **Black Hole Spacetime**       | [`🐍`](recipes/blackhole_spacetime_simulation.py) &nbsp; [`📓`](recipes/blackhole_spacetime_simulation.ipynb) | `tensor.einsum`, `transforms.z_transform`, `analysis.gradient`, `probability.entropy`                                    |
| **3D Gaussian Splatting**      |   [`🐍`](recipes/gaussian_splatting_rendering.py) &nbsp; [`📓`](recipes/gaussian_splatting_rendering.ipynb)   | `matrix.dot`, `matrix.transpose`, `analysis.gaussian_kernel`                                                             |
| **Simplicial Homology**        |     [`🐍`](recipes/topological_homology_betti.py) &nbsp; [`📓`](recipes/topological_homology_betti.ipynb)     | `homology.SimplicialComplex`, `homology.betti_numbers`, `analysis.SparseChainComplex`                                    |
| **Clifford Geometric Algebra** |      [`🐍`](recipes/clifford_rotor_kinematics.py) &nbsp; [`📓`](recipes/clifford_rotor_kinematics.ipynb)      | `clifford.CliffordSemiring`, `clifford.rotor_rotation`, `semiring.QuotientMonoidAlgebraSemiring`                         |
| **Galois Finite Fields**       |      [`🐍`](recipes/galois_field_cryptography.py) &nbsp; [`📓`](recipes/galois_field_cryptography.ipynb)      | `galois.GaloisFieldSemiring`, `galois.gf_matrix_mul`, `semiring.QuotientMonoidAlgebraSemiring`                           |
| **Forward-Mode Autodiff**      |          [`🐍`](recipes/forward_mode_autodiff.py) &nbsp; [`📓`](recipes/forward_mode_autodiff.ipynb)          | `StandardSemiring(DualNumber)`, `GradientDualNumber`, multi-hop gradient flow                                            |
| **Sparse Neural Backprop**     |         [`🐍`](recipes/sparse_neural_backprop.py) &nbsp; [`📓`](recipes/sparse_neural_backprop.ipynb)         | `matrix.transpose`, `matrix.dot`, adjoint pullback $W^T \cdot \bar{z}$, outer products                                   |
| **Functional Autograd Engine** |     [`🐍`](recipes/functional_autograd_engine.py) &nbsp; [`📓`](recipes/functional_autograd_engine.ipynb)     | `Value` computational DAG, reverse topological VJP traversal, parameter optimization                                     |
| **Quantum Path Integrals**     |  [`🐍`](recipes/quantum_feynman_path_integral.py) &nbsp; [`📓`](recipes/quantum_feynman_path_integral.ipynb)  | `StandardSemiring(dtype=complex)`, native `complex`, discrete Feynman path summation, Born's rule, Aharonov-Bohm         |
| **Relativistic Dirac Spinors** |      [`🐍`](recipes/relativistic_dirac_spinor.py) &nbsp; [`📓`](recipes/relativistic_dirac_spinor.ipynb)      | `clifford.CliffordSemiring(1,3)`, Dirac spinors $\psi \in Cl^+(1,3)$, $4\pi$ rotation periodicity, 4-current $J$         |
| **Distributed Vector Clocks**  |      [`🐍`](recipes/distributed_vector_clocks.py) &nbsp; [`📓`](recipes/distributed_vector_clocks.ipynb)      | `lattice.combine` (supremum join), `semiring.ArcticSemiring`, causal Happened-Before $\to$, CRDT version vectors         |
| **Spectral Graph Clustering**  |      [`🐍`](recipes/spectral_graph_clustering.py) &nbsp; [`📓`](recipes/spectral_graph_clustering.ipynb)      | `matrix.core.laplacian_matrix`, `analysis.fiedler_vector`, `analysis.laplacian_smoothing`, `analysis.laplacian_spectrum` |

Run any recipe using `uv`:

```bash
uv run recipes/image_processing.py
```

---

## Graphical Desktop Laboratory

Launch the interactive [DearPyGui](https://github.com/hoffstadt/DearPyGui) laboratory application featuring 12
interactive modules, live image convolution texture previews, force-directed graph canvases, signal transforms, and
information theory calculators:

```bash
uv run recipes/lab.py
```

---

## Documentation

Comprehensive documentation is hosted online and structured into distinct pillars:

* 🚀 [**Start**](docs/index.md): Installation, quickstart, and core philosophy.
* 📖 [**User Guide**](docs/guide/semirings/index.md): In-depth reference for built-in Semirings, Matrices, Tries, Homology, Transforms, and Discrete Analysis.
* 🍳 [**Recipes & GUI Lab**](docs/recipes.md): Real-world use cases, Jupyter notebooks, and laboratory documentation.

---

## Development & Contributing

### Golden Source Recipes & Jupytext Sync

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

#### Pre-Commit Hook Setup

Install the `pre-commit` hook to automatically sync `.ipynb` notebooks whenever you modify a `.py` recipe script:

```bash
# Ensure local repository hooks directory is active (recommended if global hooksPath is set)
git config --local core.hooksPath .git/hooks

# Install pre-commit hook
uvx pre-commit install
```

#### Manual Sync & Testing

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

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

---

## License

Distributed under the MIT License. See [`LICENSE`](LICENSE) for more information.
