mathematicskit 0.2.0__tar.gz → 0.4.0__tar.gz

{mathematicskit-0.2.0 → mathematicskit-0.4.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: mathematicskit
-Version: 0.2.0
-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.
+Version: 0.4.0
+Summary: Unified computational mathematics toolkit: numerical analysis, linear algebra, calculus, dynamical systems, partial differential equations, optimization, probability, statistics, number theory, combinatorics, complex analysis, graph theory, abstract algebra, geometry, special functions, and fractals/chaos -- built on numpy/scipy, hand-rolling algorithms only where no library equivalent exists.
 Author-email: Charles Poli <cpoli374@gmail.com>
 Maintainer-email: Charles Poli <cpoli374@gmail.com>
 License: MIT
@@ -9,26 +9,29 @@ 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
+Keywords: mathematics,numerical-analysis,linear-algebra,computational-mathematics,optimization,partial-differential-equations,graph-theory,number-theory,probability,statistics,education,numerical-methods,dynamical-systems,fractals
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Education
 Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
 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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Classifier: Topic :: Education
 Classifier: Topic :: Scientific/Engineering :: Mathematics
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 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: fast
+Requires-Dist: numba>=0.58; extra == "fast"
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
 Requires-Dist: pytest-cov; extra == "test"
@@ -41,8 +44,10 @@ 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"
+Requires-Dist: jupyterlite-sphinx>=0.17; extra == "docs"
+Requires-Dist: jupyterlite-pyodide-kernel>=0.4; extra == "docs"
 Provides-Extra: dev
-Requires-Dist: mathematicskit[docs,test]; extra == "dev"
+Requires-Dist: mathematicskit[docs,fast,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"
@@ -58,50 +63,68 @@ Dynamic: license-file
 | 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/>.
+| Try it online | [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/cpoli/mathematicskit/blob/main/notebooks/quickstart.ipynb) [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/cpoli/mathematicskit/main?labpath=notebooks%2Fquickstart.ipynb) [![JupyterLite](https://jupyterlite.rtfd.io/en/latest/_static/badge.svg)](https://cpoli.github.io/mathematicskit/lite/lab/) |
+
+**See how the algorithms of computational mathematics actually work.**
+mathematicskit is a Python toolkit for learning and teaching numerical
+methods, dynamical systems, and discrete mathematics. Every iterative method
+keeps its iterates, every result is an inspectable dataclass, every domain
+ships plotting helpers, and each domain's docs walk through the field's
+breakthroughs in historical order, each one linked to runnable code that
+reproduces it.
+
+![Mandelbrot set, Newton vs. bisection convergence, and the logistic-map bifurcation diagram, all drawn with mathematicskit](https://raw.githubusercontent.com/cpoli/mathematicskit/main/docs/source/_static/images/readme_hero.png)
+
+- **For students:** watch Newton's method converge quadratically while
+  bisection converges linearly, see the Runge phenomenon appear, trace the
+  Feigenbaum route to chaos, all in a few lines each.
+- **For instructors:** 16 domains, one consistent API, and hundreds of
+  gallery examples, each downloadable as a notebook or runnable in the
+  browser, ready to hand out as course material.
+- **Built on numpy/scipy:** production-grade library routines under the
+  hood, with algorithms hand-rolled only where the steps themselves are
+  what you're learning (see [Design](#design)).
+
+mathematicskit is part of a family of packages --
+[physicskit](https://github.com/cpoli/physicskit), **mathematicskit**
+and [chemistrykit](https://github.com/cpoli/chemistrykit) -- that share
+the same architecture, API conventions, and history-driven documentation.
 
 ## Install
 
 ```bash
-python -m venv .venv && source .venv/bin/activate
-pip install -e ".[dev]"
+pip install "mathematicskit[fast]"   # with numba JIT acceleration (recommended)
+pip install mathematicskit           # pure numpy/scipy/matplotlib, e.g. for Pyodide/JupyterLite
 ```
 
-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.
+Then `import mathematicskit as mk`. (The shorter name `mathkit` was
+already taken on PyPI by an unrelated package.) The `fast` extra adds
+[numba](https://numba.pydata.org/), which compiles the inner loops of
+`ode_dynamics`, `fractals_chaos`, `pde`, and `integrators`. Without it
+those kernels run as plain Python: same results, slower.
+
+For development: `pip install -e ".[dev]"` (see [CONTRIBUTING.md](CONTRIBUTING.md)).
 
 ## Quick start
 
 ```python
+import numpy as np
 import mathematicskit as mk
+from mathematicskit.numerical_analysis.visualizers import plot_convergence_history
+
+f, fprime = (lambda x: x**2 - 2.0), (lambda x: 2.0 * x)
+newton = mk.numerical_analysis.NewtonRaphson(f, fprime, x0=3.0, tol=1e-14).solve()
+bisection = mk.numerical_analysis.Bisection(f, 0.0, 3.0, tol=1e-14).solve()
+print(len(newton.history), len(bisection.history))  # 8 iterates vs. 49
 
-spline = mk.numerical_analysis.CubicSpline(x=[0, 1, 2, 3], y=[0, 1, 0, 1], boundary="natural")
-print(spline.evaluate(1.5))
+ax = plot_convergence_history(bisection, root_exact=np.sqrt(2))
+plot_convergence_history(newton, root_exact=np.sqrt(2), ax=ax)
+ax.legend()
 ```
 
+The [quickstart notebook](https://github.com/cpoli/mathematicskit/blob/main/notebooks/quickstart.ipynb) tours six domains in
+ten minutes. Open it in Colab or Binder using the badges above.
+
 ## Subpackages
 
 Domain subpackages, each with runnable examples linked below:
@@ -110,16 +133,18 @@ Domain subpackages, each with runnable examples linked below:
 - [`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.pde`](https://cpoli.github.io/mathematicskit/api/gallery/pde/) -- the heat equation in 1D and 2D by the method of lines on `mathematicskit.integrators` and by the theta-method family (FTCS, Crank-Nicolson, backward Euler via `scipy.sparse.linalg.splu`); the wave equation with symplectic leapfrog stepping against d'Alembert's solution; upwind, Lax-Friedrichs and Lax-Wendroff advection; Poisson/Laplace problems solved with `scipy.sparse.linalg.spsolve` or `mathematicskit.linalg`'s CG/Jacobi/Gauss-Seidel/SOR; CFL checks and von Neumann amplification factors; and Fourier (`numpy.fft`) and Chebyshev spectral methods.
 - [`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.complex_analysis`](https://cpoli.github.io/mathematicskit/api/gallery/complex_analysis/) -- the Cauchy-Riemann equations, contour integrals via `scipy.integrate.quad` (`complex_func=True`), winding numbers and Cauchy's integral formula, residues (periodic trapezoidal rule), the residue theorem and the argument principle, conformal maps (Möbius transformations, Joukowski airfoils), and domain coloring.
 - [`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.
+- [`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, the discrete Fourier transform via `numpy.fft` alongside a hand-rolled naive-DFT-vs-radix-2-FFT pedagogical speed comparison, and signal processing: direct/FFT convolution and Butterworth/Chebyshev/window-FIR filters via `scipy.signal`, the Z-transform with partial-fraction inversion, the Laplace transform with hand-rolled Talbot/Gaver-Stehfest numerical inversion, and hand-rolled Daubechies wavelets, the discrete wavelet transform, and the Morlet continuous wavelet transform (no numpy/scipy equivalent since scipy 1.15).
 
 Shared infrastructure, used across the subpackages above rather than
 standalone toolkits:
@@ -130,6 +155,20 @@ standalone toolkits:
   leapfrog, Yoshida4, adaptive Dormand-Prince), used by
   `mathematicskit.ode_dynamics`.
 
+## Design
+
+mathematicskit calls `numpy`/`scipy` directly for anything they already
+implement (decompositions, eigensolvers, quadrature, statistical
+distributions, optimization routines, and more), and hand-rolls an
+algorithm only where no `numpy`/`scipy` equivalent exists (e.g. graph
+algorithms, finite fields, 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. The ODE integrators are shared across
+domains.
+
+The public API follows the [stability and deprecation policy](CONTRIBUTING.md#api-stability-and-deprecation-policy).
+
 ## Test
 
 Tests live alongside each subpackage, at `mathematicskit/<name>/tests/`.
@@ -143,7 +182,7 @@ 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
+every PR (`.github/workflows/ci.yml`) across Python 3.10-3.14 on Linux and
 macOS. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
 
 ### Coverage
@@ -152,26 +191,31 @@ macOS. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
 MPLBACKEND=Agg pytest -q --cov=mathematicskit --cov-report=term
 ```
 
-620 tests, 96% line coverage overall. Per-subpackage coverage:
+1568 tests, 96% line coverage overall (94% excluding the test files
+themselves). Per-subpackage coverage, excluding tests:
 
 | 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% | | | |
+| `abstract_algebra` | 97% | | `numerical_analysis` | 95% |
+| `calculus` | 93% | | `ode_dynamics` | 85% |
+| `combinatorics` | 96% | | `optimization` | 99% |
+| `complex_analysis` | 99% | | `pde` | 94% |
+| `fractals_chaos` | 83% | | `probability` | 98% |
+| `geometry` | 99% | | `special_functions` | 99% |
+| `graph_theory` | 99% | | `statistics` | 99% |
+| `linalg` | 94% | | `integrators` | 41% |
+| `number_theory` | 97% | | `constants` | 100% |
 
 `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.
+testing convention in [CLAUDE.md](CLAUDE.md). `integrators` looks low
+only because its bodies are `@njit`-compiled, and coverage cannot trace
+compiled code; every integrator is tested directly, and with the JIT
+disabled the subpackage is fully covered:
+
+```bash
+NUMBA_DISABLE_JIT=1 MPLBACKEND=Agg pytest -q mathematicskit/integrators --cov=mathematicskit.integrators
+```
 
 ## Docs
 

{mathematicskit-0.2.0 → mathematicskit-0.4.0}/README.md

@@ -8,50 +8,68 @@
 | 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/>.
+| Try it online | [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/cpoli/mathematicskit/blob/main/notebooks/quickstart.ipynb) [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/cpoli/mathematicskit/main?labpath=notebooks%2Fquickstart.ipynb) [![JupyterLite](https://jupyterlite.rtfd.io/en/latest/_static/badge.svg)](https://cpoli.github.io/mathematicskit/lite/lab/) |
+
+**See how the algorithms of computational mathematics actually work.**
+mathematicskit is a Python toolkit for learning and teaching numerical
+methods, dynamical systems, and discrete mathematics. Every iterative method
+keeps its iterates, every result is an inspectable dataclass, every domain
+ships plotting helpers, and each domain's docs walk through the field's
+breakthroughs in historical order, each one linked to runnable code that
+reproduces it.
+
+![Mandelbrot set, Newton vs. bisection convergence, and the logistic-map bifurcation diagram, all drawn with mathematicskit](https://raw.githubusercontent.com/cpoli/mathematicskit/main/docs/source/_static/images/readme_hero.png)
+
+- **For students:** watch Newton's method converge quadratically while
+  bisection converges linearly, see the Runge phenomenon appear, trace the
+  Feigenbaum route to chaos, all in a few lines each.
+- **For instructors:** 16 domains, one consistent API, and hundreds of
+  gallery examples, each downloadable as a notebook or runnable in the
+  browser, ready to hand out as course material.
+- **Built on numpy/scipy:** production-grade library routines under the
+  hood, with algorithms hand-rolled only where the steps themselves are
+  what you're learning (see [Design](#design)).
+
+mathematicskit is part of a family of packages --
+[physicskit](https://github.com/cpoli/physicskit), **mathematicskit**
+and [chemistrykit](https://github.com/cpoli/chemistrykit) -- that share
+the same architecture, API conventions, and history-driven documentation.
 
 ## Install
 
 ```bash
-python -m venv .venv && source .venv/bin/activate
-pip install -e ".[dev]"
+pip install "mathematicskit[fast]"   # with numba JIT acceleration (recommended)
+pip install mathematicskit           # pure numpy/scipy/matplotlib, e.g. for Pyodide/JupyterLite
 ```
 
-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.
+Then `import mathematicskit as mk`. (The shorter name `mathkit` was
+already taken on PyPI by an unrelated package.) The `fast` extra adds
+[numba](https://numba.pydata.org/), which compiles the inner loops of
+`ode_dynamics`, `fractals_chaos`, `pde`, and `integrators`. Without it
+those kernels run as plain Python: same results, slower.
+
+For development: `pip install -e ".[dev]"` (see [CONTRIBUTING.md](CONTRIBUTING.md)).
 
 ## Quick start
 
 ```python
+import numpy as np
 import mathematicskit as mk
+from mathematicskit.numerical_analysis.visualizers import plot_convergence_history
+
+f, fprime = (lambda x: x**2 - 2.0), (lambda x: 2.0 * x)
+newton = mk.numerical_analysis.NewtonRaphson(f, fprime, x0=3.0, tol=1e-14).solve()
+bisection = mk.numerical_analysis.Bisection(f, 0.0, 3.0, tol=1e-14).solve()
+print(len(newton.history), len(bisection.history))  # 8 iterates vs. 49
 
-spline = mk.numerical_analysis.CubicSpline(x=[0, 1, 2, 3], y=[0, 1, 0, 1], boundary="natural")
-print(spline.evaluate(1.5))
+ax = plot_convergence_history(bisection, root_exact=np.sqrt(2))
+plot_convergence_history(newton, root_exact=np.sqrt(2), ax=ax)
+ax.legend()
 ```
 
+The [quickstart notebook](https://github.com/cpoli/mathematicskit/blob/main/notebooks/quickstart.ipynb) tours six domains in
+ten minutes. Open it in Colab or Binder using the badges above.
+
 ## Subpackages
 
 Domain subpackages, each with runnable examples linked below:
@@ -60,16 +78,18 @@ Domain subpackages, each with runnable examples linked below:
 - [`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.pde`](https://cpoli.github.io/mathematicskit/api/gallery/pde/) -- the heat equation in 1D and 2D by the method of lines on `mathematicskit.integrators` and by the theta-method family (FTCS, Crank-Nicolson, backward Euler via `scipy.sparse.linalg.splu`); the wave equation with symplectic leapfrog stepping against d'Alembert's solution; upwind, Lax-Friedrichs and Lax-Wendroff advection; Poisson/Laplace problems solved with `scipy.sparse.linalg.spsolve` or `mathematicskit.linalg`'s CG/Jacobi/Gauss-Seidel/SOR; CFL checks and von Neumann amplification factors; and Fourier (`numpy.fft`) and Chebyshev spectral methods.
 - [`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.complex_analysis`](https://cpoli.github.io/mathematicskit/api/gallery/complex_analysis/) -- the Cauchy-Riemann equations, contour integrals via `scipy.integrate.quad` (`complex_func=True`), winding numbers and Cauchy's integral formula, residues (periodic trapezoidal rule), the residue theorem and the argument principle, conformal maps (Möbius transformations, Joukowski airfoils), and domain coloring.
 - [`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.
+- [`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, the discrete Fourier transform via `numpy.fft` alongside a hand-rolled naive-DFT-vs-radix-2-FFT pedagogical speed comparison, and signal processing: direct/FFT convolution and Butterworth/Chebyshev/window-FIR filters via `scipy.signal`, the Z-transform with partial-fraction inversion, the Laplace transform with hand-rolled Talbot/Gaver-Stehfest numerical inversion, and hand-rolled Daubechies wavelets, the discrete wavelet transform, and the Morlet continuous wavelet transform (no numpy/scipy equivalent since scipy 1.15).
 
 Shared infrastructure, used across the subpackages above rather than
 standalone toolkits:
@@ -80,6 +100,20 @@ standalone toolkits:
   leapfrog, Yoshida4, adaptive Dormand-Prince), used by
   `mathematicskit.ode_dynamics`.
 
+## Design
+
+mathematicskit calls `numpy`/`scipy` directly for anything they already
+implement (decompositions, eigensolvers, quadrature, statistical
+distributions, optimization routines, and more), and hand-rolls an
+algorithm only where no `numpy`/`scipy` equivalent exists (e.g. graph
+algorithms, finite fields, 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. The ODE integrators are shared across
+domains.
+
+The public API follows the [stability and deprecation policy](CONTRIBUTING.md#api-stability-and-deprecation-policy).
+
 ## Test
 
 Tests live alongside each subpackage, at `mathematicskit/<name>/tests/`.
@@ -93,7 +127,7 @@ 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
+every PR (`.github/workflows/ci.yml`) across Python 3.10-3.14 on Linux and
 macOS. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
 
 ### Coverage
@@ -102,26 +136,31 @@ macOS. See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
 MPLBACKEND=Agg pytest -q --cov=mathematicskit --cov-report=term
 ```
 
-620 tests, 96% line coverage overall. Per-subpackage coverage:
+1568 tests, 96% line coverage overall (94% excluding the test files
+themselves). Per-subpackage coverage, excluding tests:
 
 | 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% | | | |
+| `abstract_algebra` | 97% | | `numerical_analysis` | 95% |
+| `calculus` | 93% | | `ode_dynamics` | 85% |
+| `combinatorics` | 96% | | `optimization` | 99% |
+| `complex_analysis` | 99% | | `pde` | 94% |
+| `fractals_chaos` | 83% | | `probability` | 98% |
+| `geometry` | 99% | | `special_functions` | 99% |
+| `graph_theory` | 99% | | `statistics` | 99% |
+| `linalg` | 94% | | `integrators` | 41% |
+| `number_theory` | 97% | | `constants` | 100% |
 
 `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.
+testing convention in [CLAUDE.md](CLAUDE.md). `integrators` looks low
+only because its bodies are `@njit`-compiled, and coverage cannot trace
+compiled code; every integrator is tested directly, and with the JIT
+disabled the subpackage is fully covered:
+
+```bash
+NUMBA_DISABLE_JIT=1 MPLBACKEND=Agg pytest -q mathematicskit/integrators --cov=mathematicskit.integrators
+```
 
 ## Docs
 

{mathematicskit-0.2.0 → mathematicskit-0.4.0}/mathematicskit/__init__.py

@@ -9,10 +9,15 @@ Domains are added incrementally; see ``__all__`` for what's currently
 implemented, and CHANGELOG.md for the full roadmap.
 """
 
-from mathematicskit import (
+# Defined before the subpackage imports: each subpackage re-exports it via
+# ``from mathematicskit import __version__`` while this module is still loading.
+__version__ = "0.4.0"
+
+from mathematicskit import (  # noqa: E402
     abstract_algebra,
     calculus,
     combinatorics,
+    complex_analysis,
     constants,
     fractals_chaos,
     geometry,
@@ -23,17 +28,17 @@ from mathematicskit import (
     numerical_analysis,
     ode_dynamics,
     optimization,
+    pde,
     probability,
     special_functions,
     statistics,
 )
 
-__version__ = "0.1.0"
-
 __all__ = [
     "abstract_algebra",
     "calculus",
     "combinatorics",
+    "complex_analysis",
     "constants",
     "fractals_chaos",
     "geometry",
@@ -44,6 +49,7 @@ __all__ = [
     "numerical_analysis",
     "ode_dynamics",
     "optimization",
+    "pde",
     "probability",
     "special_functions",
     "statistics",

mathematicskit-0.4.0/mathematicskit/_jit.py

@@ -0,0 +1,47 @@
+"""Optional Numba acceleration.
+
+Numba is an optional dependency (``pip install mathematicskit[fast]``).
+When it is installed, :func:`njit` is :func:`numba.njit`. When it is not
+(including in Pyodide/JupyterLite, where Numba cannot run), :func:`njit`
+is a no-op decorator: every kernel runs as plain Python/NumPy with
+identical results, only slower. Both call forms are supported --
+``@njit`` and ``@njit(cache=True)`` -- so decorated code never needs to
+know which is in use.
+
+Examples
+--------
+>>> from mathematicskit.integrators import njit
+>>> @njit
+... def square(x):
+...     return x * x
+>>> square(3.0)
+9.0
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+__all__ = ["HAS_NUMBA", "njit"]
+
+try:
+    from numba import njit as _numba_njit
+
+    HAS_NUMBA = True
+except ImportError:  # pragma: no cover - exercised only without numba installed
+    HAS_NUMBA = False
+
+
+def _identity_njit(*args: Any, **kwargs: Any) -> Any:
+    """Stand-in for :func:`numba.njit` that returns the function unchanged."""
+    if len(args) == 1 and callable(args[0]) and not kwargs:
+        return args[0]
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        return func
+
+    return decorator
+
+
+njit: Callable[..., Any] = _numba_njit if HAS_NUMBA else _identity_njit