panchi 0.1.0a1__tar.gz

panchi-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gustavo Galvao e Silva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

panchi-0.1.0a1/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md
+include LICENSE
+include pyproject.toml
+include panchi/py.typed
+
+recursive-include panchi *.py
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude tests *
+

panchi-0.1.0a1/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: panchi
+Version: 0.1.0a1
+Summary: A Python-native linear algebra library for learning, experimentation, and visual intuition
+Author-email: Gustavo Galvao e Silva <gustavo.galvaoesilva@gmail.com>
+Maintainer-email: Gustavo Galvao e Silva <gustavo.galvaoesilva@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/Gustavo-Galvao-e-Silva/panchi
+Project-URL: Documentation, https://github.com/Gustavo-Galvao-e-Silva/panchi#readme
+Project-URL: Repository, https://github.com/Gustavo-Galvao-e-Silva/panchi
+Project-URL: Bug Tracker, https://github.com/Gustavo-Galvao-e-Silva/panchi/issues
+Project-URL: Changelog, https://github.com/Gustavo-Galvao-e-Silva/panchi/releases
+Keywords: linear algebra,mathematics,education,vectors,matrices,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: matplotlib>=3.5.0
+Provides-Extra: manim
+Requires-Dist: manim>=0.18.0; extra == "manim"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0; extra == "test"
+Provides-Extra: all
+Requires-Dist: panchi[dev,manim]; extra == "all"
+Dynamic: license-file
+
+# panchi
+
+**panchi** is a Python-native linear algebra library designed for learning, experimentation, and visual intuition.
+
+The goal is not performance. The goal is **clarity**.
+
+[![TestCI](https://github.com/Gustavo-Galvao-e-Silva/panchi/workflows/TestCI/badge.svg)](https://github.com/Gustavo-Galvao-e-Silva/panchi/actions/workflows/panchi-test.yml)
+[![PyPI version](https://img.shields.io/pypi/v/panchi.svg)](https://pypi.org/project/panchi/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+---
+
+## Why panchi?
+
+Most linear algebra libraries optimize for speed and abstraction. panchi optimizes for **understanding**.
+
+panchi is built for:
+- **Students** learning linear algebra who want to see the math happen, not just trust a black box
+- **Educators** who need transparent implementations to demonstrate concepts in lectures or workshops
+- **Self-learners** building intuition through experimentation and visual feedback
+- **Researchers** prototyping algorithms where readability matters more than runtime
+- **Developers** who want to understand what's happening under the hood before optimizing
+
+Think of panchi as a **laboratory notebook**, not a production engine.
+
+---
+
+## Philosophy
+
+1. **Explicit over implicit** – Algorithms are implemented directly, not delegated to opaque backends
+2. **Readable over clever** – Code prioritizes clarity and educational value over terse optimizations
+3. **Mathematical over computational** – Objects behave like mathematical entities with proper operator overloading
+4. **Visual by default** – Visualization is a first-class feature, not an afterthought
+5. **Informative errors** – Error messages guide learning by explaining what went wrong and why
+
+---
+
+## Features
+
+### ✅ Currently Available
+
+**Core Primitives**
+- `Vector` and `Matrix` classes with native Python data structures
+- Natural mathematical syntax through operator overloading (`+`, `-`, `*`, `**`)
+- Comprehensive shape checking with educational error messages
+
+**Vector Operations**
+- Addition, subtraction, scalar multiplication
+- Magnitude calculation and normalization
+- Dot product and cross product (3D)
+- Unit vectors and zero vectors
+
+**Matrix Operations**
+- Addition, subtraction, matrix multiplication
+- Scalar multiplication and matrix powers
+- Transpose operations
+- Matrix-vector transformations
+- Trace calculation for square matrices
+
+**Utilities**
+- Identity matrices and zero matrices
+- Random vectors and matrices with configurable ranges
+- 2D and 3D rotation matrices
+- Diagonal matrix construction
+
+### 🚧 In Development
+
+- Matrix determinants and inverses
+- Matrix decompositions (LU, QR, eigenvalue methods)
+- Interactive visualization toolkit
+- Animated transformations
+- Jupyter notebook integration
+
+### 🔮 Roadmap
+
+- Step-by-step algorithm demonstrations
+- Educational machine learning examples (PCA, linear regression)
+- Physics simulations using linear operators
+- Extended documentation with visual explanations
+
+---
+
+## Installation
+
+```bash
+pip install panchi
+```
+
+**Requirements:** Python 3.10 or higher
+
+For the optional Manim-powered visualizations:
+
+```bash
+pip install panchi[manim]
+```
+
+To install from source for development:
+
+```bash
+git clone https://github.com/Gustavo-Galvao-e-Silva/panchi.git
+cd panchi
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+```python
+from panchi.primitives import Vector, Matrix
+from panchi.operations import dot, identity, rotation_matrix_2d
+from math import pi
+
+# Vector operations
+v = Vector([3, 4])
+magnitude = v.magnitude
+normalized = v.normalize()
+
+# Matrix transformations
+rotation = rotation_matrix_2d(pi / 2)
+point = Vector([1, 0])
+rotated = rotation * point
+
+# Matrix algebra
+A = Matrix([[1, 2], [3, 4]])
+B = Matrix([[5, 6], [7, 8]])
+C = A * B
+trace = C.trace
+
+# Identity and special matrices
+I = identity(3)
+product = A * A.right_identity
+```
+
+---
+
+## Use Cases
+
+### 1. **Learning Linear Algebra**
+Work through textbook problems with code that mirrors mathematical notation:
+```python
+# Verify that (AB)^T = B^T A^T
+A = Matrix([[1, 2], [3, 4]])
+B = Matrix([[5, 6], [7, 8]])
+
+left_side = (A * B).T
+right_side = B.T * A.T
+
+assert left_side == right_side
+```
+
+---
+
+## Contributing
+
+panchi welcomes contributions that align with its educational mission:
+
+1. **Clarity First** – Code should be readable by someone learning linear algebra
+2. **Tests Required** – All new features need comprehensive pytest tests
+3. **Descriptive Docstrings** – Follow NumPy documentation style
+4. **Mathematical Accuracy** – Verify implementations against textbook algorithms
+
+### How to Contribute
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/determinant-calculation`)
+3. Write clear, well-documented code with tests
+4. Ensure all tests pass (`pytest tests/`)
+5. Submit a pull request with a detailed description
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+---
+
+## Documentation
+
+Full documentation will be available at [panchi.readthedocs.io](https://panchi.readthedocs.io) *(coming soon)*
+
+- **API Reference** – Complete function and class documentation
+- **Tutorials** – Step-by-step guides for common operations
+- **Examples** – Real-world use cases and demonstrations
+- **Theory** – Mathematical background and explanations
+
+---
+
+## Project Status
+
+**Current Version:** 0.1.0a1 (Alpha)
+
+panchi is in early alpha. It is installable and the core primitives are functional, but APIs may change as the library evolves. Not recommended for production use. Feedback and contributions are very welcome.
+
+---
+
+## Support
+
+- **Issues:** Report bugs or request features via [GitHub Issues](https://github.com/Gustavo-Galvao-e-Silva/panchi/issues)
+- **Discussions:** Ask questions in [GitHub Discussions](https://github.com/Gustavo-Galvao-e-Silva/panchi/discussions)
+
+---
+
+## License
+
+MIT License – see [LICENSE](LICENSE) for details.
+
+---
+
+## Acknowledgments
+
+panchi is inspired by educational resources that prioritize understanding:
+- Gilbert Strang's *Introduction to Linear Algebra*
+- 3Blue1Brown's *Essence of Linear Algebra* video series
+- The desire to make linear algebra accessible and visual
+
+---
+
+## Final Note
+
+panchi exists to answer a simple question:
+
+> **"What is linear algebra actually *doing*?"**
+
+If you've ever felt frustrated by libraries that hide the mathematics behind abstractions, or if you want to *see* transformations happen rather than just trust the output, panchi is for you.
+
+Linear algebra is beautiful. Let's make it visible.

panchi-0.1.0a1/README.md

@@ -0,0 +1,226 @@
+# panchi
+
+**panchi** is a Python-native linear algebra library designed for learning, experimentation, and visual intuition.
+
+The goal is not performance. The goal is **clarity**.
+
+[![TestCI](https://github.com/Gustavo-Galvao-e-Silva/panchi/workflows/TestCI/badge.svg)](https://github.com/Gustavo-Galvao-e-Silva/panchi/actions/workflows/panchi-test.yml)
+[![PyPI version](https://img.shields.io/pypi/v/panchi.svg)](https://pypi.org/project/panchi/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+---
+
+## Why panchi?
+
+Most linear algebra libraries optimize for speed and abstraction. panchi optimizes for **understanding**.
+
+panchi is built for:
+- **Students** learning linear algebra who want to see the math happen, not just trust a black box
+- **Educators** who need transparent implementations to demonstrate concepts in lectures or workshops
+- **Self-learners** building intuition through experimentation and visual feedback
+- **Researchers** prototyping algorithms where readability matters more than runtime
+- **Developers** who want to understand what's happening under the hood before optimizing
+
+Think of panchi as a **laboratory notebook**, not a production engine.
+
+---
+
+## Philosophy
+
+1. **Explicit over implicit** – Algorithms are implemented directly, not delegated to opaque backends
+2. **Readable over clever** – Code prioritizes clarity and educational value over terse optimizations
+3. **Mathematical over computational** – Objects behave like mathematical entities with proper operator overloading
+4. **Visual by default** – Visualization is a first-class feature, not an afterthought
+5. **Informative errors** – Error messages guide learning by explaining what went wrong and why
+
+---
+
+## Features
+
+### ✅ Currently Available
+
+**Core Primitives**
+- `Vector` and `Matrix` classes with native Python data structures
+- Natural mathematical syntax through operator overloading (`+`, `-`, `*`, `**`)
+- Comprehensive shape checking with educational error messages
+
+**Vector Operations**
+- Addition, subtraction, scalar multiplication
+- Magnitude calculation and normalization
+- Dot product and cross product (3D)
+- Unit vectors and zero vectors
+
+**Matrix Operations**
+- Addition, subtraction, matrix multiplication
+- Scalar multiplication and matrix powers
+- Transpose operations
+- Matrix-vector transformations
+- Trace calculation for square matrices
+
+**Utilities**
+- Identity matrices and zero matrices
+- Random vectors and matrices with configurable ranges
+- 2D and 3D rotation matrices
+- Diagonal matrix construction
+
+### 🚧 In Development
+
+- Matrix determinants and inverses
+- Matrix decompositions (LU, QR, eigenvalue methods)
+- Interactive visualization toolkit
+- Animated transformations
+- Jupyter notebook integration
+
+### 🔮 Roadmap
+
+- Step-by-step algorithm demonstrations
+- Educational machine learning examples (PCA, linear regression)
+- Physics simulations using linear operators
+- Extended documentation with visual explanations
+
+---
+
+## Installation
+
+```bash
+pip install panchi
+```
+
+**Requirements:** Python 3.10 or higher
+
+For the optional Manim-powered visualizations:
+
+```bash
+pip install panchi[manim]
+```
+
+To install from source for development:
+
+```bash
+git clone https://github.com/Gustavo-Galvao-e-Silva/panchi.git
+cd panchi
+pip install -e ".[dev]"
+```
+
+---
+
+## Quick Start
+
+```python
+from panchi.primitives import Vector, Matrix
+from panchi.operations import dot, identity, rotation_matrix_2d
+from math import pi
+
+# Vector operations
+v = Vector([3, 4])
+magnitude = v.magnitude
+normalized = v.normalize()
+
+# Matrix transformations
+rotation = rotation_matrix_2d(pi / 2)
+point = Vector([1, 0])
+rotated = rotation * point
+
+# Matrix algebra
+A = Matrix([[1, 2], [3, 4]])
+B = Matrix([[5, 6], [7, 8]])
+C = A * B
+trace = C.trace
+
+# Identity and special matrices
+I = identity(3)
+product = A * A.right_identity
+```
+
+---
+
+## Use Cases
+
+### 1. **Learning Linear Algebra**
+Work through textbook problems with code that mirrors mathematical notation:
+```python
+# Verify that (AB)^T = B^T A^T
+A = Matrix([[1, 2], [3, 4]])
+B = Matrix([[5, 6], [7, 8]])
+
+left_side = (A * B).T
+right_side = B.T * A.T
+
+assert left_side == right_side
+```
+
+---
+
+## Contributing
+
+panchi welcomes contributions that align with its educational mission:
+
+1. **Clarity First** – Code should be readable by someone learning linear algebra
+2. **Tests Required** – All new features need comprehensive pytest tests
+3. **Descriptive Docstrings** – Follow NumPy documentation style
+4. **Mathematical Accuracy** – Verify implementations against textbook algorithms
+
+### How to Contribute
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/determinant-calculation`)
+3. Write clear, well-documented code with tests
+4. Ensure all tests pass (`pytest tests/`)
+5. Submit a pull request with a detailed description
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+
+---
+
+## Documentation
+
+Full documentation will be available at [panchi.readthedocs.io](https://panchi.readthedocs.io) *(coming soon)*
+
+- **API Reference** – Complete function and class documentation
+- **Tutorials** – Step-by-step guides for common operations
+- **Examples** – Real-world use cases and demonstrations
+- **Theory** – Mathematical background and explanations
+
+---
+
+## Project Status
+
+**Current Version:** 0.1.0a1 (Alpha)
+
+panchi is in early alpha. It is installable and the core primitives are functional, but APIs may change as the library evolves. Not recommended for production use. Feedback and contributions are very welcome.
+
+---
+
+## Support
+
+- **Issues:** Report bugs or request features via [GitHub Issues](https://github.com/Gustavo-Galvao-e-Silva/panchi/issues)
+- **Discussions:** Ask questions in [GitHub Discussions](https://github.com/Gustavo-Galvao-e-Silva/panchi/discussions)
+
+---
+
+## License
+
+MIT License – see [LICENSE](LICENSE) for details.
+
+---
+
+## Acknowledgments
+
+panchi is inspired by educational resources that prioritize understanding:
+- Gilbert Strang's *Introduction to Linear Algebra*
+- 3Blue1Brown's *Essence of Linear Algebra* video series
+- The desire to make linear algebra accessible and visual
+
+---
+
+## Final Note
+
+panchi exists to answer a simple question:
+
+> **"What is linear algebra actually *doing*?"**
+
+If you've ever felt frustrated by libraries that hide the mathematics behind abstractions, or if you want to *see* transformations happen rather than just trust the output, panchi is for you.
+
+Linear algebra is beautiful. Let's make it visible.

panchi-0.1.0a1/panchi/__init__.py

@@ -0,0 +1,46 @@
+"""
+Panchi - A Python-native linear algebra library for learning and experimentation.
+
+Panchi prioritizes clarity and understanding over performance, making it ideal
+for students, educators, and anyone who wants to see how linear algebra really works.
+"""
+
+__version__ = "0.1.0"
+
+from panchi.primitives.vector import Vector
+from panchi.primitives.matrix import Matrix
+from panchi.primitives.factories import (
+    identity,
+    zero_matrix,
+    one_matrix,
+    zero_vector,
+    one_vector,
+    unit_vector,
+    diagonal,
+    random_vector,
+    random_matrix,
+    rotation_matrix_2d,
+    rotation_matrix_3d,
+)
+from panchi.primitives.vector_operations import (
+    dot,
+    cross,
+)
+
+__all__ = [
+    "Vector",
+    "Matrix",
+    "identity",
+    "zero_matrix",
+    "one_matrix",
+    "zero_vector",
+    "one_vector",
+    "unit_vector",
+    "diagonal",
+    "random_vector",
+    "random_matrix",
+    "rotation_matrix_2d",
+    "rotation_matrix_3d",
+    "dot",
+    "cross",
+]

panchi-0.1.0a1/panchi/algorithms/__init__.py

@@ -0,0 +1,20 @@
+"""
+Matrix algorithms: row operations and row reductions.
+
+This package provides the building blocks for operating on and reducing
+matrices. Row operations represent the three elementary transformations
+used in Gaussian elimination, and reductions apply those operations
+systematically to bring a matrix into REF or RREF.
+"""
+
+from panchi.algorithms.row_operations import RowSwap, RowScale, RowAdd
+from panchi.algorithms.reductions import Reduction, ref, rref
+
+__all__ = [
+    "RowSwap",
+    "RowScale",
+    "RowAdd",
+    "Reduction",
+    "ref",
+    "rref",
+]

panchi-0.1.0a1/panchi/algorithms/decompositions.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from panchi.primitives.matrix import Matrix
+from panchi.primitives.factories import identity
+from panchi.algorithms.reductions import ref
+from panchi.algorithms.row_operations import RowOperation, RowAdd, RowSwap
+from panchi.algorithms.results import LUDecomposition
+
+
+def _calculate_l(n: int, steps: list[RowOperation]) -> Matrix:
+    l = identity(n)
+    for step in steps:
+        if isinstance(step, RowAdd):
+            l[step.target][step.source] = -step.scalar
+
+    return l
+
+
+def _calculate_p(n: int, steps: list[RowOperation]) -> Matrix:
+    p = identity(n)
+    for step in steps:
+        if isinstance(step, RowSwap):
+            p = step.apply(p)
+
+    return p
+
+
+def lu(matrix: Matrix) -> LUDecomposition:
+    matrix_ref = ref(matrix)
+    n = matrix.rows
+    steps = matrix_ref.steps
+    l = _calculate_l(n, steps)
+    u = matrix_ref.result
+    p = _calculate_p(n, steps)
+    return LUDecomposition(matrix, l, u, p, steps)