mathematicskit 0.1.0__tar.gz → 0.2.1__tar.gz

{mathematicskit-0.1.0 → mathematicskit-0.2.1}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 mathkit contributors
+Copyright (c) 2026 mathematicskit contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

mathematicskit-0.2.1/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: mathematicskit
+Version: 0.2.1
+Summary: Unified computational mathematics toolkit: numerical analysis, linear algebra, calculus, dynamical systems, optimization, probability, statistics, number theory, combinatorics, graph theory, abstract algebra, geometry, special functions, and fractals/chaos -- all hand-rolled from first principles.
+Author-email: Charles Poli <cpoli374@gmail.com>
+Maintainer-email: Charles Poli <cpoli374@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/cpoli/mathematicskit
+Project-URL: Issues, https://github.com/cpoli/mathematicskit/issues
+Project-URL: Changelog, https://github.com/cpoli/mathematicskit/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://cpoli.github.io/mathematicskit/
+Keywords: mathematics,numerical-analysis,linear-algebra,computational-mathematics,optimization,graph-theory,number-theory,probability,statistics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: matplotlib>=3.6
+Requires-Dist: numba>=0.58
+Requires-Dist: plotly>=5.15
+Requires-Dist: sympy>=1.11
+Requires-Dist: tqdm>=4.65
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: hypothesis>=6.90; extra == "test"
+Requires-Dist: pillow>=9.0; extra == "test"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: pydata-sphinx-theme>=0.15; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == "docs"
+Requires-Dist: myst-parser>=2.0; extra == "docs"
+Requires-Dist: sphinx-gallery>=0.15; extra == "docs"
+Requires-Dist: sphinx-design>=0.6; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: mathematicskit[docs,test]; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pre-commit>=3.7; extra == "dev"
+Dynamic: license-file
+
+# mathematicskit
+
+| | |
+|:--|:-:|
+| Package | [![PyPI version](https://img.shields.io/pypi/v/mathematicskit)](https://pypi.org/project/mathematicskit/) [![Python versions](https://img.shields.io/pypi/pyversions/mathematicskit)](https://pypi.org/project/mathematicskit/) |
+| Quality | [![License](https://img.shields.io/github/license/cpoli/mathematicskit)](https://github.com/cpoli/mathematicskit/blob/main/LICENSE) [![CI](https://github.com/cpoli/mathematicskit/actions/workflows/ci.yml/badge.svg)](https://github.com/cpoli/mathematicskit/actions/workflows/ci.yml) [![Coverage](https://img.shields.io/codecov/c/github/cpoli/mathematicskit)](https://codecov.io/gh/cpoli/mathematicskit) [![Coverage (manual)](https://img.shields.io/badge/coverage-96%25-brightgreen)](#coverage) |
+| Documentation | [![Docs](https://img.shields.io/badge/docs-cpoli.github.io%2Fmathematicskit-blue)](https://cpoli.github.io/mathematicskit/) |
+| Code style | [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) |
+| Downloads | [![Downloads](https://static.pepy.tech/badge/mathematicskit)](https://pepy.tech/project/mathematicskit) [![Downloads/Month](https://static.pepy.tech/badge/mathematicskit/month)](https://pepy.tech/project/mathematicskit) |
+| Community | [![GitHub Stars](https://img.shields.io/github/stars/cpoli/mathematicskit?style=social)](https://github.com/cpoli/mathematicskit) [![GitHub Forks](https://img.shields.io/github/forks/cpoli/mathematicskit?style=social)](https://github.com/cpoli/mathematicskit) [![Contributors](https://img.shields.io/github/contributors/cpoli/mathematicskit)](https://github.com/cpoli/mathematicskit/graphs/contributors) [![Last Commit](https://img.shields.io/github/last-commit/cpoli/mathematicskit)](https://github.com/cpoli/mathematicskit/commits/main) |
+
+A unified toolkit for computational mathematics, spanning the field end
+to end: Newton's method chasing roots and Poincare sections of the
+driven Duffing oscillator, Mandelbrot sets and the Feigenbaum route to
+chaos, Dijkstra's shortest paths and finite-field arithmetic, the
+Central Limit Theorem in action and Bessel functions in closed form --
+with each domain's docs tracing the field's own foundational
+breakthroughs in chronological, pedagogical order, every historical
+milestone linked directly to the runnable code that reproduces it. 14
+domain subpackages, one consistent NumPy-based API -- built directly on
+`numpy`/`scipy` for anything they already implement (decompositions,
+eigensolvers, quadrature, statistical distributions, optimization
+routines, and more), hand-rolling an algorithm from scratch only where
+no `numpy`/`scipy` equivalent exists (e.g. graph algorithms, the simplex
+method, modular arithmetic) or where the algorithm's own iterate
+behavior is the pedagogical subject (e.g. root-finder convergence
+history, autodiff). No hard dependency on `networkx`, `cvxpy`, or
+SageMath. Sharing common ODE integrators throughout. Conventionally
+imported as `mk`.
+
+All 14 domains from `mathkit-spec.md`'s build plan are implemented --
+see [Subpackages](#subpackages) for the full list, or browse the docs at
+<https://cpoli.github.io/mathematicskit/>.
+
+## Install
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Published on PyPI as `mathematicskit` (the shorter name `mathkit` was
+already taken by an unrelated package) -- `pip install mathematicskit`,
+then `import mathematicskit as mk` as usual.
+
+## Quick start
+
+```python
+import mathematicskit as mk
+
+spline = mk.numerical_analysis.CubicSpline(x=[0, 1, 2, 3], y=[0, 1, 0, 1], boundary="natural")
+print(spline.evaluate(1.5))
+```
+
+## Subpackages
+
+Domain subpackages, each with runnable examples linked below:
+
+- [`mathematicskit.numerical_analysis`](https://cpoli.github.io/mathematicskit/api/gallery/numerical_analysis/) -- root finding (bisection, Newton-Raphson, secant, fixed-point, hand-rolled for their convergence history), Lagrange/Newton (hand-rolled) plus scipy-backed cubic-spline interpolation, numpy-backed Chebyshev nodes, `numpy.linalg.lstsq`-based polynomial regression, and `numpy.linalg.cond`-based error/condition-number analysis.
+- [`mathematicskit.linalg`](https://cpoli.github.io/mathematicskit/api/gallery/linalg/) -- LU/QR/Cholesky decompositions and eigenvalue computation via `scipy.linalg`/`numpy.linalg`, power/inverse iteration (hand-rolled), SVD, conjugate gradient and GMRES via `scipy.sparse.linalg`, and least-squares stability (normal equations vs. QR vs. `numpy.linalg.lstsq`).
+- [`mathematicskit.calculus`](https://cpoli.github.io/mathematicskit/api/gallery/calculus/) -- finite-difference derivatives with Richardson extrapolation (hand-rolled), `scipy.integrate`-backed trapezoidal/Simpson/Gauss-Legendre/adaptive quadrature, forward-mode (dual numbers) and reverse-mode (backpropagation) automatic differentiation (hand-rolled), and Taylor/Maclaurin series.
+- [`mathematicskit.ode_dynamics`](https://cpoli.github.io/mathematicskit/api/gallery/ode_dynamics/) -- Jacobian-linearization fixed-point stability (node/saddle/spiral/center), phase portraits, the logistic map's Feigenbaum route to chaos, saddle-node/pitchfork/Hopf bifurcation normal forms, the Van der Pol limit cycle, and Poincare sections of the driven Duffing oscillator.
+- [`mathematicskit.fractals_chaos`](https://cpoli.github.io/mathematicskit/api/gallery/fractals_chaos/) -- Lyapunov exponent estimation, box-counting fractal dimension, Numba-accelerated Mandelbrot/Julia set generation, iterated function systems (Barnsley fern, Sierpinski triangle/carpet), and cellular automata (Wolfram rules, Conway's Game of Life).
+- [`mathematicskit.optimization`](https://cpoli.github.io/mathematicskit/api/gallery/optimization/) -- gradient descent and nonlinear conjugate gradient (hand-rolled, iterate-path-exposing), Newton's method and BFGS via `scipy.optimize.minimize`, Lagrange multipliers and KKT-condition verification, a quadratic-penalty method, and linear programming via `scipy.optimize.linprog`.
+- [`mathematicskit.probability`](https://cpoli.github.io/mathematicskit/api/gallery/probability/) -- binomial/Poisson/geometric/uniform/exponential/normal/gamma distributions via `scipy.stats` (plus mathematicskit's own MGFs), Monte Carlo integration with variance reduction (importance sampling, control variates), Law of Large Numbers/Central Limit Theorem simulation, and discrete-time Markov chains.
+- [`mathematicskit.statistics`](https://cpoli.github.io/mathematicskit/api/gallery/statistics/) -- descriptive statistics, z/t/chi-square hypothesis tests and one-way ANOVA, confidence intervals for means/proportions/variances, OLS linear regression with residual diagnostics, and bootstrap resampling via `scipy.stats.bootstrap`.
+- [`mathematicskit.number_theory`](https://cpoli.github.io/mathematicskit/api/gallery/number_theory/) -- the extended Euclidean algorithm and modular inverses, fast modular exponentiation, primality testing (trial division, Miller-Rabin) and prime generation, the Chinese Remainder Theorem, continued fractions and best rational approximations, Euler's totient/Mobius/divisor-sum functions, and linear/Pell Diophantine equation solvers (hand-rolled -- exact-integer number theory has no `numpy`/`scipy` equivalent).
+- [`mathematicskit.combinatorics`](https://cpoli.github.io/mathematicskit/api/gallery/combinatorics/) -- permutation/combination counting via `scipy.special.perm`/`comb` (sequence generation via `itertools`), a hand-rolled Pascal's triangle, integer partitions and Young/Ferrers diagrams, the inclusion-exclusion principle and derangements, and Stirling/Catalan/Bell numbers (hand-rolled -- no scipy/numpy equivalent).
+- [`mathematicskit.graph_theory`](https://cpoli.github.io/mathematicskit/api/gallery/graph_theory/) -- a lightweight own graph container (no `networkx`); shortest paths (Dijkstra/Bellman-Ford/Floyd-Warshall) and minimum spanning tree (Kruskal) via `scipy.sparse.csgraph`, with a hand-rolled Prim's kept for comparison; maximum flow/minimum cut via `scipy.sparse.csgraph.maximum_flow`; hand-rolled graph coloring (greedy, exact backtracking); and spectral graph theory (Laplacian via scipy, eigendecomposition via `numpy.linalg.eigh`).
+- [`mathematicskit.abstract_algebra`](https://cpoli.github.io/mathematicskit/api/gallery/abstract_algebra/) -- cyclic and permutation groups with Cayley tables and group-property checks, subgroup/coset enumeration, finite field arithmetic (`GF(p)`/`GF(p^n)` via irreducible polynomials), and polynomial ring arithmetic over Z/Q/finite fields (hand-rolled throughout -- no scipy/numpy equivalent).
+- [`mathematicskit.geometry`](https://cpoli.github.io/mathematicskit/api/gallery/geometry/) -- convex hull via `scipy.spatial.ConvexHull` (with a hand-rolled Graham scan comparison), Delaunay triangulation/Voronoi diagrams via `scipy.spatial`, hand-rolled segment intersection and point-in-polygon tests, polygon area/centroid via the shoelace formula, and curvature/arc-length/the Frenet-Serret frame for parametric curves.
+- [`mathematicskit.special_functions`](https://cpoli.github.io/mathematicskit/api/gallery/special_functions/) -- the gamma/beta functions and Bessel functions via `scipy.special`, orthogonal polynomial families (Legendre/Chebyshev/Hermite/Laguerre) via `numpy.polynomial` with numerically-verified orthogonality, and the discrete Fourier transform via `numpy.fft` alongside a hand-rolled naive-DFT-vs-radix-2-FFT pedagogical speed comparison.
+
+Shared infrastructure, used across the subpackages above rather than
+standalone toolkits:
+
+- `mathematicskit.constants` -- mathematical constants and default numerical
+  tolerances shared across subpackages.
+- `mathematicskit.integrators` -- shared numerical ODE integrators (RK4,
+  leapfrog, Yoshida4, adaptive Dormand-Prince), used by
+  `mathematicskit.ode_dynamics`.
+
+## Test
+
+Tests live alongside each subpackage, at `mathematicskit/<name>/tests/`.
+
+```bash
+pytest                                              # everything
+pytest mathematicskit/numerical_analysis/tests             # a single subpackage
+
+# docstring examples, across every subpackage:
+MPLBACKEND=Agg pytest --doctest-modules mathematicskit --ignore-glob="*/tests/*"
+```
+
+Both commands, plus `ruff check`/`ruff format --check`, run in CI on
+every PR (`.github/workflows/ci.yml`) across Python 3.9-3.12 on Linux and
+macOS. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
+
+### Coverage
+
+```bash
+MPLBACKEND=Agg pytest -q --cov=mathematicskit --cov-report=term
+```
+
+620 tests, 96% line coverage overall. Per-subpackage coverage:
+
+| Subpackage | Coverage | | Subpackage | Coverage |
+|:--|--:|---|:--|--:|
+| `abstract_algebra` | 97% | | `ode_dynamics` | 92% |
+| `calculus` | 95% | | `optimization` | 99% |
+| `combinatorics` | 98% | | `probability` | 98% |
+| `fractals_chaos` | 92% | | `special_functions` | 100% |
+| `geometry` | 100% | | `statistics` | 99% |
+| `graph_theory` | 99% | | `integrators` | 50% |
+| `linalg` | 95% | | `constants` | 100% |
+| `number_theory` | 99% | | | |
+| `numerical_analysis` | 97% | | | |
+
+`visualizers/` modules are smoke-tested only (correct return type/shape,
+or that `anim.save()` succeeds) rather than covered line-by-line, per the
+testing convention in [CLAUDE.md](CLAUDE.md). `integrators` sits lower
+because several of its fixed-step/adaptive methods aren't exercised
+directly by its own tests, only indirectly through the two subpackages
+(`ode_dynamics`, `fractals_chaos`) that call into it.
+
+## Docs
+
+Built docs are hosted at <https://cpoli.github.io/mathematicskit/>, served from
+the `gh-pages` branch. To build locally:
+
+```bash
+pip install -e ".[docs]"
+cd docs && make html
+```
+
+See `docs/source/history/` for a chronology of each domain's foundational
+results, linked to the corresponding implementation at each step.
+
+## Citation
+
+If you use mathematicskit in your research, please cite it — see
+[CITATION.cff](CITATION.cff).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Please note that this project
+follows the [Contributor Covenant](CODE_OF_CONDUCT.md).
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

mathematicskit-0.2.1/README.md

@@ -0,0 +1,151 @@
+# mathematicskit
+
+| | |
+|:--|:-:|
+| Package | [![PyPI version](https://img.shields.io/pypi/v/mathematicskit)](https://pypi.org/project/mathematicskit/) [![Python versions](https://img.shields.io/pypi/pyversions/mathematicskit)](https://pypi.org/project/mathematicskit/) |
+| Quality | [![License](https://img.shields.io/github/license/cpoli/mathematicskit)](https://github.com/cpoli/mathematicskit/blob/main/LICENSE) [![CI](https://github.com/cpoli/mathematicskit/actions/workflows/ci.yml/badge.svg)](https://github.com/cpoli/mathematicskit/actions/workflows/ci.yml) [![Coverage](https://img.shields.io/codecov/c/github/cpoli/mathematicskit)](https://codecov.io/gh/cpoli/mathematicskit) [![Coverage (manual)](https://img.shields.io/badge/coverage-96%25-brightgreen)](#coverage) |
+| Documentation | [![Docs](https://img.shields.io/badge/docs-cpoli.github.io%2Fmathematicskit-blue)](https://cpoli.github.io/mathematicskit/) |
+| Code style | [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff) |
+| Downloads | [![Downloads](https://static.pepy.tech/badge/mathematicskit)](https://pepy.tech/project/mathematicskit) [![Downloads/Month](https://static.pepy.tech/badge/mathematicskit/month)](https://pepy.tech/project/mathematicskit) |
+| Community | [![GitHub Stars](https://img.shields.io/github/stars/cpoli/mathematicskit?style=social)](https://github.com/cpoli/mathematicskit) [![GitHub Forks](https://img.shields.io/github/forks/cpoli/mathematicskit?style=social)](https://github.com/cpoli/mathematicskit) [![Contributors](https://img.shields.io/github/contributors/cpoli/mathematicskit)](https://github.com/cpoli/mathematicskit/graphs/contributors) [![Last Commit](https://img.shields.io/github/last-commit/cpoli/mathematicskit)](https://github.com/cpoli/mathematicskit/commits/main) |
+
+A unified toolkit for computational mathematics, spanning the field end
+to end: Newton's method chasing roots and Poincare sections of the
+driven Duffing oscillator, Mandelbrot sets and the Feigenbaum route to
+chaos, Dijkstra's shortest paths and finite-field arithmetic, the
+Central Limit Theorem in action and Bessel functions in closed form --
+with each domain's docs tracing the field's own foundational
+breakthroughs in chronological, pedagogical order, every historical
+milestone linked directly to the runnable code that reproduces it. 14
+domain subpackages, one consistent NumPy-based API -- built directly on
+`numpy`/`scipy` for anything they already implement (decompositions,
+eigensolvers, quadrature, statistical distributions, optimization
+routines, and more), hand-rolling an algorithm from scratch only where
+no `numpy`/`scipy` equivalent exists (e.g. graph algorithms, the simplex
+method, modular arithmetic) or where the algorithm's own iterate
+behavior is the pedagogical subject (e.g. root-finder convergence
+history, autodiff). No hard dependency on `networkx`, `cvxpy`, or
+SageMath. Sharing common ODE integrators throughout. Conventionally
+imported as `mk`.
+
+All 14 domains from `mathkit-spec.md`'s build plan are implemented --
+see [Subpackages](#subpackages) for the full list, or browse the docs at
+<https://cpoli.github.io/mathematicskit/>.
+
+## Install
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+```
+
+Published on PyPI as `mathematicskit` (the shorter name `mathkit` was
+already taken by an unrelated package) -- `pip install mathematicskit`,
+then `import mathematicskit as mk` as usual.
+
+## Quick start
+
+```python
+import mathematicskit as mk
+
+spline = mk.numerical_analysis.CubicSpline(x=[0, 1, 2, 3], y=[0, 1, 0, 1], boundary="natural")
+print(spline.evaluate(1.5))
+```
+
+## Subpackages
+
+Domain subpackages, each with runnable examples linked below:
+
+- [`mathematicskit.numerical_analysis`](https://cpoli.github.io/mathematicskit/api/gallery/numerical_analysis/) -- root finding (bisection, Newton-Raphson, secant, fixed-point, hand-rolled for their convergence history), Lagrange/Newton (hand-rolled) plus scipy-backed cubic-spline interpolation, numpy-backed Chebyshev nodes, `numpy.linalg.lstsq`-based polynomial regression, and `numpy.linalg.cond`-based error/condition-number analysis.
+- [`mathematicskit.linalg`](https://cpoli.github.io/mathematicskit/api/gallery/linalg/) -- LU/QR/Cholesky decompositions and eigenvalue computation via `scipy.linalg`/`numpy.linalg`, power/inverse iteration (hand-rolled), SVD, conjugate gradient and GMRES via `scipy.sparse.linalg`, and least-squares stability (normal equations vs. QR vs. `numpy.linalg.lstsq`).
+- [`mathematicskit.calculus`](https://cpoli.github.io/mathematicskit/api/gallery/calculus/) -- finite-difference derivatives with Richardson extrapolation (hand-rolled), `scipy.integrate`-backed trapezoidal/Simpson/Gauss-Legendre/adaptive quadrature, forward-mode (dual numbers) and reverse-mode (backpropagation) automatic differentiation (hand-rolled), and Taylor/Maclaurin series.
+- [`mathematicskit.ode_dynamics`](https://cpoli.github.io/mathematicskit/api/gallery/ode_dynamics/) -- Jacobian-linearization fixed-point stability (node/saddle/spiral/center), phase portraits, the logistic map's Feigenbaum route to chaos, saddle-node/pitchfork/Hopf bifurcation normal forms, the Van der Pol limit cycle, and Poincare sections of the driven Duffing oscillator.
+- [`mathematicskit.fractals_chaos`](https://cpoli.github.io/mathematicskit/api/gallery/fractals_chaos/) -- Lyapunov exponent estimation, box-counting fractal dimension, Numba-accelerated Mandelbrot/Julia set generation, iterated function systems (Barnsley fern, Sierpinski triangle/carpet), and cellular automata (Wolfram rules, Conway's Game of Life).
+- [`mathematicskit.optimization`](https://cpoli.github.io/mathematicskit/api/gallery/optimization/) -- gradient descent and nonlinear conjugate gradient (hand-rolled, iterate-path-exposing), Newton's method and BFGS via `scipy.optimize.minimize`, Lagrange multipliers and KKT-condition verification, a quadratic-penalty method, and linear programming via `scipy.optimize.linprog`.
+- [`mathematicskit.probability`](https://cpoli.github.io/mathematicskit/api/gallery/probability/) -- binomial/Poisson/geometric/uniform/exponential/normal/gamma distributions via `scipy.stats` (plus mathematicskit's own MGFs), Monte Carlo integration with variance reduction (importance sampling, control variates), Law of Large Numbers/Central Limit Theorem simulation, and discrete-time Markov chains.
+- [`mathematicskit.statistics`](https://cpoli.github.io/mathematicskit/api/gallery/statistics/) -- descriptive statistics, z/t/chi-square hypothesis tests and one-way ANOVA, confidence intervals for means/proportions/variances, OLS linear regression with residual diagnostics, and bootstrap resampling via `scipy.stats.bootstrap`.
+- [`mathematicskit.number_theory`](https://cpoli.github.io/mathematicskit/api/gallery/number_theory/) -- the extended Euclidean algorithm and modular inverses, fast modular exponentiation, primality testing (trial division, Miller-Rabin) and prime generation, the Chinese Remainder Theorem, continued fractions and best rational approximations, Euler's totient/Mobius/divisor-sum functions, and linear/Pell Diophantine equation solvers (hand-rolled -- exact-integer number theory has no `numpy`/`scipy` equivalent).
+- [`mathematicskit.combinatorics`](https://cpoli.github.io/mathematicskit/api/gallery/combinatorics/) -- permutation/combination counting via `scipy.special.perm`/`comb` (sequence generation via `itertools`), a hand-rolled Pascal's triangle, integer partitions and Young/Ferrers diagrams, the inclusion-exclusion principle and derangements, and Stirling/Catalan/Bell numbers (hand-rolled -- no scipy/numpy equivalent).
+- [`mathematicskit.graph_theory`](https://cpoli.github.io/mathematicskit/api/gallery/graph_theory/) -- a lightweight own graph container (no `networkx`); shortest paths (Dijkstra/Bellman-Ford/Floyd-Warshall) and minimum spanning tree (Kruskal) via `scipy.sparse.csgraph`, with a hand-rolled Prim's kept for comparison; maximum flow/minimum cut via `scipy.sparse.csgraph.maximum_flow`; hand-rolled graph coloring (greedy, exact backtracking); and spectral graph theory (Laplacian via scipy, eigendecomposition via `numpy.linalg.eigh`).
+- [`mathematicskit.abstract_algebra`](https://cpoli.github.io/mathematicskit/api/gallery/abstract_algebra/) -- cyclic and permutation groups with Cayley tables and group-property checks, subgroup/coset enumeration, finite field arithmetic (`GF(p)`/`GF(p^n)` via irreducible polynomials), and polynomial ring arithmetic over Z/Q/finite fields (hand-rolled throughout -- no scipy/numpy equivalent).
+- [`mathematicskit.geometry`](https://cpoli.github.io/mathematicskit/api/gallery/geometry/) -- convex hull via `scipy.spatial.ConvexHull` (with a hand-rolled Graham scan comparison), Delaunay triangulation/Voronoi diagrams via `scipy.spatial`, hand-rolled segment intersection and point-in-polygon tests, polygon area/centroid via the shoelace formula, and curvature/arc-length/the Frenet-Serret frame for parametric curves.
+- [`mathematicskit.special_functions`](https://cpoli.github.io/mathematicskit/api/gallery/special_functions/) -- the gamma/beta functions and Bessel functions via `scipy.special`, orthogonal polynomial families (Legendre/Chebyshev/Hermite/Laguerre) via `numpy.polynomial` with numerically-verified orthogonality, and the discrete Fourier transform via `numpy.fft` alongside a hand-rolled naive-DFT-vs-radix-2-FFT pedagogical speed comparison.
+
+Shared infrastructure, used across the subpackages above rather than
+standalone toolkits:
+
+- `mathematicskit.constants` -- mathematical constants and default numerical
+  tolerances shared across subpackages.
+- `mathematicskit.integrators` -- shared numerical ODE integrators (RK4,
+  leapfrog, Yoshida4, adaptive Dormand-Prince), used by
+  `mathematicskit.ode_dynamics`.
+
+## Test
+
+Tests live alongside each subpackage, at `mathematicskit/<name>/tests/`.
+
+```bash
+pytest                                              # everything
+pytest mathematicskit/numerical_analysis/tests             # a single subpackage
+
+# docstring examples, across every subpackage:
+MPLBACKEND=Agg pytest --doctest-modules mathematicskit --ignore-glob="*/tests/*"
+```
+
+Both commands, plus `ruff check`/`ruff format --check`, run in CI on
+every PR (`.github/workflows/ci.yml`) across Python 3.9-3.12 on Linux and
+macOS. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
+
+### Coverage
+
+```bash
+MPLBACKEND=Agg pytest -q --cov=mathematicskit --cov-report=term
+```
+
+620 tests, 96% line coverage overall. Per-subpackage coverage:
+
+| Subpackage | Coverage | | Subpackage | Coverage |
+|:--|--:|---|:--|--:|
+| `abstract_algebra` | 97% | | `ode_dynamics` | 92% |
+| `calculus` | 95% | | `optimization` | 99% |
+| `combinatorics` | 98% | | `probability` | 98% |
+| `fractals_chaos` | 92% | | `special_functions` | 100% |
+| `geometry` | 100% | | `statistics` | 99% |
+| `graph_theory` | 99% | | `integrators` | 50% |
+| `linalg` | 95% | | `constants` | 100% |
+| `number_theory` | 99% | | | |
+| `numerical_analysis` | 97% | | | |
+
+`visualizers/` modules are smoke-tested only (correct return type/shape,
+or that `anim.save()` succeeds) rather than covered line-by-line, per the
+testing convention in [CLAUDE.md](CLAUDE.md). `integrators` sits lower
+because several of its fixed-step/adaptive methods aren't exercised
+directly by its own tests, only indirectly through the two subpackages
+(`ode_dynamics`, `fractals_chaos`) that call into it.
+
+## Docs
+
+Built docs are hosted at <https://cpoli.github.io/mathematicskit/>, served from
+the `gh-pages` branch. To build locally:
+
+```bash
+pip install -e ".[docs]"
+cd docs && make html
+```
+
+See `docs/source/history/` for a chronology of each domain's foundational
+results, linked to the corresponding implementation at each step.
+
+## Citation
+
+If you use mathematicskit in your research, please cite it — see
+[CITATION.cff](CITATION.cff).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Please note that this project
+follows the [Contributor Covenant](CODE_OF_CONDUCT.md).
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

{mathematicskit-0.1.0/mathkit → mathematicskit-0.2.1/mathematicskit}/__init__.py

@@ -1,15 +1,15 @@
-"""mathkit: unified toolkit for computational mathematics.
+"""mathematicskit: unified toolkit for computational mathematics.
 
 Import as ``mk`` by convention::
 
-    import mathkit as mk
+    import mathematicskit as mk
     mk.numerical_analysis.CubicSpline(x=[0, 1, 2], y=[0, 1, 0], boundary="natural")
 
 Domains are added incrementally; see ``__all__`` for what's currently
 implemented, and CHANGELOG.md for the full roadmap.
 """
 
-from mathkit import (
+from mathematicskit import (
     abstract_algebra,
     calculus,
     combinatorics,
@@ -28,7 +28,7 @@ from mathkit import (
     statistics,
 )
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"
 
 __all__ = [
     "abstract_algebra",

mathematicskit-0.2.1/mathematicskit/abstract_algebra/__init__.py

@@ -0,0 +1,94 @@
+"""mathematicskit.abstract_algebra: group, ring, and field theory made computational.
+
+Every algorithm here is hand-rolled from its textbook definition --
+finite group/ring/field theory has no ``numpy``/``scipy`` equivalent.
+Cyclic, permutation, dihedral, and quaternion group implementations
+with Cayley table generation; group-property checks (order, identity,
+inverses, abelian, cyclicity); subgroup and coset enumeration for small
+groups; structure theory (normal subgroups and quotients, derived
+series and solvability, Sylow subgroups, composition series); group
+actions and Burnside orbit counting; homomorphisms and their kernels
+and images; Reed-Solomon codes over ``GF(p)``; finite
+field arithmetic (``GF(p)`` and ``GF(p^n)`` via irreducible polynomials
+over ``GF(p)``); and polynomial ring arithmetic (addition,
+multiplication, division with remainder, gcd) over :math:`\\mathbb{Z}`,
+:math:`\\mathbb{Q}`, and finite fields.
+"""
+
+from mathematicskit.abstract_algebra.core.base import (
+    CompositionSeriesResult,
+    FiniteGroup,
+    GroupPropertiesResult,
+    HomomorphismResult,
+    Polynomial,
+    SylowResult,
+)
+from mathematicskit.abstract_algebra.systems.actions import count_orbits, orbits
+from mathematicskit.abstract_algebra.systems.codes import rs_decode_erasures, rs_encode
+from mathematicskit.abstract_algebra.systems.finite_fields import GF, find_irreducible_polynomial, is_irreducible
+from mathematicskit.abstract_algebra.systems.groups import CyclicGroup, DihedralGroup, PermutationGroup, QuaternionGroup, group_properties
+from mathematicskit.abstract_algebra.systems.homomorphisms import analyze_homomorphism, homomorphism_image, homomorphism_kernel, is_homomorphism
+from mathematicskit.abstract_algebra.systems.polynomial_ring import poly_add, poly_divmod, poly_gcd, poly_mul, poly_sub
+from mathematicskit.abstract_algebra.systems.structure import (
+    QuotientGroup,
+    Subgroup,
+    commutator_subgroup,
+    composition_series,
+    derived_series,
+    elements_of_order,
+    generated_subgroup,
+    is_normal_subgroup,
+    is_solvable,
+    quotient_group,
+    sylow_subgroups,
+)
+from mathematicskit.abstract_algebra.systems.subgroups import all_subgroups, cyclic_subgroup, left_cosets
+from mathematicskit.abstract_algebra.utils.checks import is_cyclic
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "FiniteGroup",
+    "GroupPropertiesResult",
+    "Polynomial",
+    "CyclicGroup",
+    "PermutationGroup",
+    "group_properties",
+    "is_cyclic",
+    "cyclic_subgroup",
+    "all_subgroups",
+    "left_cosets",
+    "GF",
+    "is_irreducible",
+    "find_irreducible_polynomial",
+    "poly_add",
+    "poly_sub",
+    "poly_mul",
+    "poly_divmod",
+    "poly_gcd",
+    "SylowResult",
+    "CompositionSeriesResult",
+    "HomomorphismResult",
+    "DihedralGroup",
+    "QuaternionGroup",
+    "Subgroup",
+    "generated_subgroup",
+    "elements_of_order",
+    "is_normal_subgroup",
+    "QuotientGroup",
+    "quotient_group",
+    "commutator_subgroup",
+    "derived_series",
+    "is_solvable",
+    "sylow_subgroups",
+    "composition_series",
+    "orbits",
+    "count_orbits",
+    "is_homomorphism",
+    "homomorphism_kernel",
+    "homomorphism_image",
+    "analyze_homomorphism",
+    "rs_encode",
+    "rs_decode_erasures",
+]

{mathematicskit-0.1.0/mathkit → mathematicskit-0.2.1/mathematicskit}/abstract_algebra/core/base.py

@@ -1,5 +1,5 @@
 r"""Abstract base class for finite groups, and a coefficient-generic
-polynomial class, shared across mathkit.abstract_algebra's systems/
+polynomial class, shared across mathematicskit.abstract_algebra's systems/
 modules.
 
 Every algorithm in this domain is hand-rolled from its textbook
@@ -17,21 +17,21 @@ from typing import Optional
 
 import numpy as np
 
-__all__ = ["FiniteGroup", "GroupPropertiesResult", "Polynomial"]
+__all__ = ["FiniteGroup", "GroupPropertiesResult", "SylowResult", "CompositionSeriesResult", "HomomorphismResult", "Polynomial"]
 
 
 class FiniteGroup(ABC):
     r"""Common interface for a finite group :math:`(G, \cdot)`.
 
-    Concrete subclasses (:class:`~mathkit.abstract_algebra.systems.groups.CyclicGroup`,
-    :class:`~mathkit.abstract_algebra.systems.groups.PermutationGroup`)
+    Concrete subclasses (:class:`~mathematicskit.abstract_algebra.systems.groups.CyclicGroup`,
+    :class:`~mathematicskit.abstract_algebra.systems.groups.PermutationGroup`)
     provide the element set and the group operation; this base class
     derives the Cayley table, abelian check, and element orders purely
     from those. See Dummit & Foote, *Abstract Algebra*, 3rd ed., Ch. 1.
 
     Examples
     --------
-    >>> from mathkit.abstract_algebra.systems.groups import CyclicGroup
+    >>> from mathematicskit.abstract_algebra.systems.groups import CyclicGroup
     >>> g = CyclicGroup(4)
     >>> g.order
     4
@@ -124,6 +124,41 @@ class GroupPropertiesResult:
     """dict: ``{element: order}`` for every element."""
 
 
+@dataclass
+class SylowResult:
+    """Container for the Sylow :math:`p`-subgroups of a finite group."""
+
+    p: int
+    sylow_order: int
+    """int: :math:`p^k`, the largest power of ``p`` dividing :math:`|G|`."""
+    subgroups: list
+    """list of list: Every Sylow :math:`p`-subgroup, each as a list of elements."""
+
+    @property
+    def count(self) -> int:
+        """int: :math:`n_p`, the number of Sylow :math:`p`-subgroups."""
+        return len(self.subgroups)
+
+
+@dataclass
+class CompositionSeriesResult:
+    """Container for a composition series :math:`G = G_0 > G_1 > \\dots > G_m = \\{e\\}`."""
+
+    series: list
+    """list of list: The subgroups :math:`G_0, \\dots, G_m`, largest first."""
+    factor_orders: list
+    """list of int: The orders :math:`|G_i / G_{i+1}|` of the composition factors."""
+
+
+@dataclass
+class HomomorphismResult:
+    """Container for a group homomorphism's kernel and image."""
+
+    kernel: list
+    image: list
+    is_homomorphism: bool
+
+
 class Polynomial:
     r"""A polynomial with coefficients over :math:`\mathbb{Q}` (``modulus=None``,
     stored as exact :class:`fractions.Fraction`) or :math:`\mathrm{GF}(p)`
@@ -189,19 +224,29 @@ class Polynomial:
             return -1
         return len(self.coeffs) - 1
 
+    def _check_same_field(self, other: Polynomial) -> None:
+        """Reject arithmetic between polynomials over different coefficient fields."""
+        if not isinstance(other, Polynomial):
+            raise TypeError(f"expected a Polynomial, got {type(other).__name__}")
+        if self.modulus != other.modulus:
+            raise ValueError(f"cannot combine polynomials over different fields (modulus {self.modulus} vs {other.modulus})")
+
     def _pad(self, n: int) -> list:
         zero = Fraction(0) if self.modulus is None else 0
         return self.coeffs + [zero] * (n - len(self.coeffs))
 
     def __add__(self, other: Polynomial) -> Polynomial:
+        self._check_same_field(other)
         n = max(len(self.coeffs), len(other.coeffs))
         return self._wrap([self._reduce(a + b) for a, b in zip(self._pad(n), other._pad(n))])
 
     def __sub__(self, other: Polynomial) -> Polynomial:
+        self._check_same_field(other)
         n = max(len(self.coeffs), len(other.coeffs))
         return self._wrap([self._reduce(a - b) for a, b in zip(self._pad(n), other._pad(n))])
 
     def __mul__(self, other: Polynomial) -> Polynomial:
+        self._check_same_field(other)
         result = [Fraction(0) if self.modulus is None else 0] * (len(self.coeffs) + len(other.coeffs) - 1)
         for i, a in enumerate(self.coeffs):
             for j, b in enumerate(other.coeffs):
@@ -216,6 +261,7 @@ class Polynomial:
 
     def __divmod__(self, other: Polynomial):
         r"""Polynomial long division: ``self = quotient * other + remainder``, ``deg(remainder) < deg(other)``."""
+        self._check_same_field(other)
         if other.degree == -1:
             raise ZeroDivisionError("division by the zero polynomial")
         remainder = self._wrap(list(self.coeffs))