quantum-playground 0.3.0__tar.gz

quantum_playground-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 StativeSh
+
+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.

quantum_playground-0.3.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: quantum-playground
+Version: 0.3.0
+Summary: A physics and maths playground: simulations, symbolic maths and notebooks.
+License-Expression: MIT
+Project-URL: Homepage, https://stativesh.github.io/quantum-playground/
+Project-URL: Documentation, https://stativesh.github.io/quantum-playground/api/
+Project-URL: Source, https://github.com/StativeSh/quantum-playground
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: sympy
+Requires-Dist: matplotlib
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: jupyterlab; extra == "dev"
+Requires-Dist: ipykernel; extra == "dev"
+Requires-Dist: pandas; extra == "dev"
+Requires-Dist: nbconvert; extra == "dev"
+Requires-Dist: pdoc; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Provides-Extra: browser
+Requires-Dist: playwright; extra == "browser"
+Dynamic: license-file
+
+# quantum-playground
+
+[![CI](https://github.com/StativeSh/quantum-playground/actions/workflows/ci.yml/badge.svg)](https://github.com/StativeSh/quantum-playground/actions/workflows/ci.yml)
+[![Pages](https://github.com/StativeSh/quantum-playground/actions/workflows/pages.yml/badge.svg)](https://stativesh.github.io/quantum-playground/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+A physics and maths playground in Python: simulations, symbolic mechanics and Jupyter notebooks, with tests that check every solver against known analytic results.
+
+**[Website](https://stativesh.github.io/quantum-playground/)**: every figure and animation, the executed notebooks and lessons, the [API reference](https://stativesh.github.io/quantum-playground/api/), and an [interactive explorer](https://stativesh.github.io/quantum-playground/explorer/) with live experiments: the pendulum, quantum tunnelling, the double slit, Kepler orbits, the Lorenz attractor and the Ising model.
+
+<table>
+  <tr>
+    <td align="center"><img src="docs/images/double-slit.gif" width="260" alt="Wavepacket passing through two slits"><br><sub>Double slit: a 2D Schrödinger simulation</sub></td>
+    <td align="center"><img src="docs/images/double-pendulum.gif" width="260" alt="Chaotic double pendulum"><br><sub>Chaotic double pendulum</sub></td>
+    <td align="center"><img src="docs/images/figure-eight.gif" width="260" alt="Three-body figure-eight orbit"><br><sub>Three-body figure-eight orbit</sub></td>
+  </tr>
+</table>
+
+<img src="docs/images/wavepacket.gif" width="100%" alt="Wavepacket tunnelling through a barrier">
+
+| | |
+|---|---|
+| ![Hydrogen orbitals](docs/images/hydrogen.png) | ![Double-slit fringes against theory](docs/images/double-slit.png) |
+| Hydrogen orbitals $\lvert\psi_{nlm}\rvert$ | Double-slit fringes against the two-source prediction |
+| ![Ising model](docs/images/ising.png) | ![Phase portraits](docs/images/phase-portrait.png) |
+| 2D Ising model against Onsager's exact result | Phase portraits with classified fixed points |
+| ![Mandelbrot set](docs/images/mandelbrot.png) | ![Domain colouring](docs/images/domain-coloring.png) |
+| Mandelbrot set | Domain colouring and the argument principle |
+
+## Quick start
+
+```bash
+make install          # venv + editable install + Jupyter kernel
+make test             # run the test suite
+make demos            # render every demo figure into ./figures
+make animations       # render every GIF into ./figures
+make lab              # open JupyterLab
+```
+
+Or without `make`:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+.venv/bin/qplay list
+.venv/bin/qplay run pendulum wavepacket mandelbrot
+```
+
+## What is in the box
+
+| Module | Topics |
+|---|---|
+| `qplay.mechanics` | damped/driven oscillator, nonlinear and double pendulum, projectile with drag, N-body gravity (figure-eight orbit) |
+| `qplay.waves` | 1D wave equation, heat equation (Crank-Nicolson), Fourier series, spectra |
+| `qplay.em` | point-charge fields, Laplace solver, charged particle in $\mathbf E$ and $\mathbf B$ fields |
+| `qplay.quantum` | Schrödinger eigenstates for any 1D potential, split-step dynamics in 1D and 2D with absorbing edges, tunnelling, the double-slit experiment, hydrogen orbitals $R_{nl}Y_l^m$, spin-1/2, oscillator eigenstates and coherent states |
+| `qplay.atomic` | angular momentum matrices, spin-orbit coupling, Zeeman effect from Landé $g_J$ to Paschen-Back, hydrogen fine structure against the Dirac energy |
+| `qplay.kinetic` | hard-sphere gas in a box: Maxwell-Boltzmann distribution emerging from collisions, pressure from wall impulses, $pV = Nk_BT$ with the hard-sphere correction |
+| `qplay.nuclear` | half-life, Bateman decay chains, matrix-exponential chains, Monte Carlo decay |
+| `qplay.circuits` | RC charging and discharging, series RLC circuit, impedance, resonance and $Q$ factor |
+| `qplay.statmech` | 2D Ising model (Metropolis), Onsager's exact magnetisation and $T_c = 2/\ln(1+\sqrt2)$ |
+| `qplay.relativity` | time dilation, length contraction, velocity addition, Lorentz boosts |
+| `qplay.chaos` | Lorenz system, logistic map, Lyapunov exponent, Mandelbrot and Julia sets |
+| `qplay.symbolic` | SymPy: Lagrangian $\to$ Euler-Lagrange equations $\to$ runnable simulation |
+| `qplay.hamiltonian` | Legendre transform, Hamilton's equations, Hamiltonian $\to$ runnable simulation |
+| `qplay.dynamics` | phase portraits with automatically classified fixed points (saddle, node, spiral, center) |
+| `qplay.complexplane` | domain colouring, argument principle (zeros $-$ poles from a winding number) |
+| `qplay.linalg` | Gram-Schmidt, power iteration, how a matrix maps the unit circle (SVD) |
+| `qplay.numerics` | bisection, Newton, Simpson, finite differences, Monte Carlo |
+| `qplay.integrators` | Euler, RK4, velocity Verlet, adaptive wrapper |
+
+## Notebooks
+
+| Notebook | Contents |
+|---|---|
+| `01_classical_mechanics` | period vs amplitude, double-pendulum chaos, deriving equations of motion symbolically |
+| `02_quantum_mechanics` | oscillator and double-well states, tunnelling, wavepackets, Rabi oscillations |
+| `03_maths_and_chaos` | Newton's method, Gibbs phenomenon, bifurcation diagram, fractals |
+| `04_orbitals_interference_and_phase_space` | hydrogen orbitals, double slit, Ising phase transition, Legendre transform, phase planes, complex functions, linear maps |
+
+## Lessons for A-level and IB
+
+Guided lessons in `lessons/`, each mapped to specification points, with exam-style questions that check your answers and worked solutions at the end. Every lesson and notebook has an **Open in Colab** button, so it runs in a browser with nothing to install.
+
+Each lesson opens by saying which earlier lessons it builds on (and why) and which it leads to. Suggested routes:
+
+| Route | Lessons, in order |
+|---|---|
+| Mechanics | 2 projectile motion → 3 circular motion and orbits → 1 simple harmonic motion |
+| Waves to quantum | 1 simple harmonic motion → 4 stationary waves → 7 wave–particle duality |
+| Fields | 3 circular motion and orbits → 5 electric fields → 6 charged particles in fields |
+| Modern physics | 5 electric fields → 7 wave–particle duality → 8 special relativity |
+| Thermal physics | 3 circular motion and orbits → 9 ideal gases and kinetic theory |
+
+The prerequisites and routes live in `lessons/path.json`; `python scripts/lesson_path.py --write` copies them into the lesson headers, and the tests check that the two agree.
+
+| Lesson | Covers |
+|---|---|
+| [`01_simple_harmonic_motion`](https://colab.research.google.com/github/StativeSh/quantum-playground/blob/main/lessons/01_simple_harmonic_motion.ipynb) | SHM equations and phase, spring and pendulum periods, energy, damping, resonance |
+| [`02_projectile_motion`](https://colab.research.google.com/github/StativeSh/quantum-playground/blob/main/lessons/02_projectile_motion.ipynb) | independent horizontal and vertical motion, resolving velocity, time of flight, range and the 45° rule, launches from a height, air resistance |
+| [`03_circular_motion_and_orbits`](https://colab.research.google.com/github/StativeSh/quantum-playground/blob/main/lessons/03_circular_motion_and_orbits.ipynb) | centripetal acceleration, orbital speed and period, geostationary orbits, Kepler's third law on a log-log plot, orbital energy and escape velocity |
+| [`04_stationary_waves`](https://colab.research.google.com/github/StativeSh/quantum-playground/blob/main/lessons/04_stationary_waves.ipynb) | nodes and antinodes, harmonics on a string, why a plucked string is missing some harmonics, open and closed pipes, Fourier series |
+| [`05_electric_fields`](https://colab.research.google.com/github/StativeSh/quantum-playground/blob/main/lessons/05_electric_fields.ipynb) | Coulomb's law, field lines and equipotentials, $E = -dV/dr$, uniform fields between plates and edge effects |
+| [`06_charged_particles_in_fields`](https://colab.research.google.com/github/StativeSh/quantum-playground/blob/main/lessons/06_charged_particles_in_fields.ipynb) | parabolic paths in $E$, circles in $B$ with $r = mv/BQ$, cyclotron period, velocity selector, mass spectrometer, helices |
+| [`07_wave_particle_duality`](https://colab.research.google.com/github/StativeSh/quantum-playground/blob/main/lessons/07_wave_particle_duality.ipynb) | photoelectric effect, Young's double slit, de Broglie wavelength, a simulated electron through two slits, building the pattern one particle at a time |
+| [`08_special_relativity`](https://colab.research.google.com/github/StativeSh/quantum-playground/blob/main/lessons/08_special_relativity.ipynb) | postulates, time dilation and the muon experiment, length contraction, velocity addition, relativity of simultaneity, $E = \gamma mc^2$ |
+| [`09_ideal_gases_and_kinetic_theory`](https://colab.research.google.com/github/StativeSh/quantum-playground/blob/main/lessons/09_ideal_gases_and_kinetic_theory.ipynb) | gas laws, a simulated gas relaxing to Maxwell-Boltzmann, pressure from collisions, temperature as molecular kinetic energy, when gases stop being ideal |
+
+## Demos and animations
+
+`qplay list` shows everything. Twenty-five static figures (`qplay run NAME`), including `hydrogen`, `double-slit`, `ising`, `maxwell-boltzmann`, `coherent-state`, `zeeman`, `decay-chain` and `rlc-resonance`, and six GIFs (`qplay animate NAME`): `double-pendulum`, `wavepacket`, `figure-eight`, `double-slit`, `ising` and `gas`.
+
+## Example
+
+Derive the equation of motion of a pendulum from its Lagrangian $L = \tfrac12 m\ell^2\dot\theta^2 + mg\ell\cos\theta$, then simulate it:
+
+```python
+import sympy as sp
+from qplay import symbolic, integrators
+
+t, m, l, g = sp.symbols("t m l g", positive=True)
+th = sp.Function("theta")(t)
+L = m * l**2 * sp.diff(th, t)**2 / 2 + m * g * l * sp.cos(th)
+
+symbolic.accelerations(L, [th], t)        # [-g*sin(theta)/l]
+rhs = symbolic.to_numeric_rhs(L, [th], t, {m: 1, l: 1, g: 9.81})
+t_arr, y = integrators.solve(rhs, [1.0, 0.0], (0, 10))
+```
+
+## Adding a demo
+
+```python
+# src/qplay/demos.py
+@demo("my-demo")
+def my_demo():
+    """One-line description shown by `qplay list`."""
+    fig, ax = plt.subplots()
+    ...
+    return fig
+```
+
+It appears in `qplay list` and is covered by the test suite automatically. Animations work the same way with `@animation("name")` in `src/qplay/animations.py`, returning `(fig, update, frames)`.
+
+## Development
+
+See `CLAUDE.md` for conventions.
+
+- `make test` is the fast loop: it skips tests marked `slow` (the site build, the biggest simulations and the browser tests). `make test-all` runs everything, and `make coverage` adds a line-by-line coverage report that fails below 95%.
+- `tests/test_explorer.py` drives the explorer in headless Chromium: it moves sliders and checks every readout against the Python package or an analytic formula, and lets the animations run to check what they converge to (orbital period, Lorenz separation, Ising magnetisation). Install with `pip install -e ".[browser]"` and `python -m playwright install chromium`, then `make test-browser`. Without Playwright these tests are skipped; CI installs it and fails if the browser is missing.
+- CI runs every test with coverage on Python 3.10, 3.12 and 3.13, and executes the notebooks and lessons.
+- The website is built by `.github/workflows/pages.yml` on every push to `main`: `scripts/build_site.py` renders all demos and animations, executes the notebooks to HTML, builds the API reference from the docstrings with pdoc, and copies the explorer from `site_src/`. Build it locally with `make site` (output in `_site/`), or just the API reference with `make api`. The README images live in `docs/images/` and are regenerated with `make readme-media`.
+- Releases: the distribution is called `quantum-playground` (the import name is still `qplay`; the name `qplay` is taken on PyPI). Pushing a tag such as `v0.3.0` runs `.github/workflows/release.yml`, which checks the tag matches `qplay.__version__`, runs the tests, builds the wheel and publishes it to PyPI through a trusted publisher. `make dist` builds the same files locally.
+
+## License
+
+MIT, see `LICENSE`.

quantum_playground-0.3.0/README.md

@@ -0,0 +1,156 @@
+# quantum-playground
+
+[![CI](https://github.com/StativeSh/quantum-playground/actions/workflows/ci.yml/badge.svg)](https://github.com/StativeSh/quantum-playground/actions/workflows/ci.yml)
+[![Pages](https://github.com/StativeSh/quantum-playground/actions/workflows/pages.yml/badge.svg)](https://stativesh.github.io/quantum-playground/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+A physics and maths playground in Python: simulations, symbolic mechanics and Jupyter notebooks, with tests that check every solver against known analytic results.
+
+**[Website](https://stativesh.github.io/quantum-playground/)**: every figure and animation, the executed notebooks and lessons, the [API reference](https://stativesh.github.io/quantum-playground/api/), and an [interactive explorer](https://stativesh.github.io/quantum-playground/explorer/) with live experiments: the pendulum, quantum tunnelling, the double slit, Kepler orbits, the Lorenz attractor and the Ising model.
+
+<table>
+  <tr>
+    <td align="center"><img src="docs/images/double-slit.gif" width="260" alt="Wavepacket passing through two slits"><br><sub>Double slit: a 2D Schrödinger simulation</sub></td>
+    <td align="center"><img src="docs/images/double-pendulum.gif" width="260" alt="Chaotic double pendulum"><br><sub>Chaotic double pendulum</sub></td>
+    <td align="center"><img src="docs/images/figure-eight.gif" width="260" alt="Three-body figure-eight orbit"><br><sub>Three-body figure-eight orbit</sub></td>
+  </tr>
+</table>
+
+<img src="docs/images/wavepacket.gif" width="100%" alt="Wavepacket tunnelling through a barrier">
+
+| | |
+|---|---|
+| ![Hydrogen orbitals](docs/images/hydrogen.png) | ![Double-slit fringes against theory](docs/images/double-slit.png) |
+| Hydrogen orbitals $\lvert\psi_{nlm}\rvert$ | Double-slit fringes against the two-source prediction |
+| ![Ising model](docs/images/ising.png) | ![Phase portraits](docs/images/phase-portrait.png) |
+| 2D Ising model against Onsager's exact result | Phase portraits with classified fixed points |
+| ![Mandelbrot set](docs/images/mandelbrot.png) | ![Domain colouring](docs/images/domain-coloring.png) |
+| Mandelbrot set | Domain colouring and the argument principle |
+
+## Quick start
+
+```bash
+make install          # venv + editable install + Jupyter kernel
+make test             # run the test suite
+make demos            # render every demo figure into ./figures
+make animations       # render every GIF into ./figures
+make lab              # open JupyterLab
+```
+
+Or without `make`:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -r requirements.txt
+.venv/bin/qplay list
+.venv/bin/qplay run pendulum wavepacket mandelbrot
+```
+
+## What is in the box
+
+| Module | Topics |
+|---|---|
+| `qplay.mechanics` | damped/driven oscillator, nonlinear and double pendulum, projectile with drag, N-body gravity (figure-eight orbit) |
+| `qplay.waves` | 1D wave equation, heat equation (Crank-Nicolson), Fourier series, spectra |
+| `qplay.em` | point-charge fields, Laplace solver, charged particle in $\mathbf E$ and $\mathbf B$ fields |
+| `qplay.quantum` | Schrödinger eigenstates for any 1D potential, split-step dynamics in 1D and 2D with absorbing edges, tunnelling, the double-slit experiment, hydrogen orbitals $R_{nl}Y_l^m$, spin-1/2, oscillator eigenstates and coherent states |
+| `qplay.atomic` | angular momentum matrices, spin-orbit coupling, Zeeman effect from Landé $g_J$ to Paschen-Back, hydrogen fine structure against the Dirac energy |
+| `qplay.kinetic` | hard-sphere gas in a box: Maxwell-Boltzmann distribution emerging from collisions, pressure from wall impulses, $pV = Nk_BT$ with the hard-sphere correction |
+| `qplay.nuclear` | half-life, Bateman decay chains, matrix-exponential chains, Monte Carlo decay |
+| `qplay.circuits` | RC charging and discharging, series RLC circuit, impedance, resonance and $Q$ factor |
+| `qplay.statmech` | 2D Ising model (Metropolis), Onsager's exact magnetisation and $T_c = 2/\ln(1+\sqrt2)$ |
+| `qplay.relativity` | time dilation, length contraction, velocity addition, Lorentz boosts |
+| `qplay.chaos` | Lorenz system, logistic map, Lyapunov exponent, Mandelbrot and Julia sets |
+| `qplay.symbolic` | SymPy: Lagrangian $\to$ Euler-Lagrange equations $\to$ runnable simulation |
+| `qplay.hamiltonian` | Legendre transform, Hamilton's equations, Hamiltonian $\to$ runnable simulation |
+| `qplay.dynamics` | phase portraits with automatically classified fixed points (saddle, node, spiral, center) |
+| `qplay.complexplane` | domain colouring, argument principle (zeros $-$ poles from a winding number) |
+| `qplay.linalg` | Gram-Schmidt, power iteration, how a matrix maps the unit circle (SVD) |
+| `qplay.numerics` | bisection, Newton, Simpson, finite differences, Monte Carlo |
+| `qplay.integrators` | Euler, RK4, velocity Verlet, adaptive wrapper |
+
+## Notebooks
+
+| Notebook | Contents |
+|---|---|
+| `01_classical_mechanics` | period vs amplitude, double-pendulum chaos, deriving equations of motion symbolically |
+| `02_quantum_mechanics` | oscillator and double-well states, tunnelling, wavepackets, Rabi oscillations |
+| `03_maths_and_chaos` | Newton's method, Gibbs phenomenon, bifurcation diagram, fractals |
+| `04_orbitals_interference_and_phase_space` | hydrogen orbitals, double slit, Ising phase transition, Legendre transform, phase planes, complex functions, linear maps |
+
+## Lessons for A-level and IB
+
+Guided lessons in `lessons/`, each mapped to specification points, with exam-style questions that check your answers and worked solutions at the end. Every lesson and notebook has an **Open in Colab** button, so it runs in a browser with nothing to install.
+
+Each lesson opens by saying which earlier lessons it builds on (and why) and which it leads to. Suggested routes:
+
+| Route | Lessons, in order |
+|---|---|
+| Mechanics | 2 projectile motion → 3 circular motion and orbits → 1 simple harmonic motion |
+| Waves to quantum | 1 simple harmonic motion → 4 stationary waves → 7 wave–particle duality |
+| Fields | 3 circular motion and orbits → 5 electric fields → 6 charged particles in fields |
+| Modern physics | 5 electric fields → 7 wave–particle duality → 8 special relativity |
+| Thermal physics | 3 circular motion and orbits → 9 ideal gases and kinetic theory |
+
+The prerequisites and routes live in `lessons/path.json`; `python scripts/lesson_path.py --write` copies them into the lesson headers, and the tests check that the two agree.
+
+| Lesson | Covers |
+|---|---|
+| [`01_simple_harmonic_motion`](https://colab.research.google.com/github/StativeSh/quantum-playground/blob/main/lessons/01_simple_harmonic_motion.ipynb) | SHM equations and phase, spring and pendulum periods, energy, damping, resonance |
+| [`02_projectile_motion`](https://colab.research.google.com/github/StativeSh/quantum-playground/blob/main/lessons/02_projectile_motion.ipynb) | independent horizontal and vertical motion, resolving velocity, time of flight, range and the 45° rule, launches from a height, air resistance |
+| [`03_circular_motion_and_orbits`](https://colab.research.google.com/github/StativeSh/quantum-playground/blob/main/lessons/03_circular_motion_and_orbits.ipynb) | centripetal acceleration, orbital speed and period, geostationary orbits, Kepler's third law on a log-log plot, orbital energy and escape velocity |
+| [`04_stationary_waves`](https://colab.research.google.com/github/StativeSh/quantum-playground/blob/main/lessons/04_stationary_waves.ipynb) | nodes and antinodes, harmonics on a string, why a plucked string is missing some harmonics, open and closed pipes, Fourier series |
+| [`05_electric_fields`](https://colab.research.google.com/github/StativeSh/quantum-playground/blob/main/lessons/05_electric_fields.ipynb) | Coulomb's law, field lines and equipotentials, $E = -dV/dr$, uniform fields between plates and edge effects |
+| [`06_charged_particles_in_fields`](https://colab.research.google.com/github/StativeSh/quantum-playground/blob/main/lessons/06_charged_particles_in_fields.ipynb) | parabolic paths in $E$, circles in $B$ with $r = mv/BQ$, cyclotron period, velocity selector, mass spectrometer, helices |
+| [`07_wave_particle_duality`](https://colab.research.google.com/github/StativeSh/quantum-playground/blob/main/lessons/07_wave_particle_duality.ipynb) | photoelectric effect, Young's double slit, de Broglie wavelength, a simulated electron through two slits, building the pattern one particle at a time |
+| [`08_special_relativity`](https://colab.research.google.com/github/StativeSh/quantum-playground/blob/main/lessons/08_special_relativity.ipynb) | postulates, time dilation and the muon experiment, length contraction, velocity addition, relativity of simultaneity, $E = \gamma mc^2$ |
+| [`09_ideal_gases_and_kinetic_theory`](https://colab.research.google.com/github/StativeSh/quantum-playground/blob/main/lessons/09_ideal_gases_and_kinetic_theory.ipynb) | gas laws, a simulated gas relaxing to Maxwell-Boltzmann, pressure from collisions, temperature as molecular kinetic energy, when gases stop being ideal |
+
+## Demos and animations
+
+`qplay list` shows everything. Twenty-five static figures (`qplay run NAME`), including `hydrogen`, `double-slit`, `ising`, `maxwell-boltzmann`, `coherent-state`, `zeeman`, `decay-chain` and `rlc-resonance`, and six GIFs (`qplay animate NAME`): `double-pendulum`, `wavepacket`, `figure-eight`, `double-slit`, `ising` and `gas`.
+
+## Example
+
+Derive the equation of motion of a pendulum from its Lagrangian $L = \tfrac12 m\ell^2\dot\theta^2 + mg\ell\cos\theta$, then simulate it:
+
+```python
+import sympy as sp
+from qplay import symbolic, integrators
+
+t, m, l, g = sp.symbols("t m l g", positive=True)
+th = sp.Function("theta")(t)
+L = m * l**2 * sp.diff(th, t)**2 / 2 + m * g * l * sp.cos(th)
+
+symbolic.accelerations(L, [th], t)        # [-g*sin(theta)/l]
+rhs = symbolic.to_numeric_rhs(L, [th], t, {m: 1, l: 1, g: 9.81})
+t_arr, y = integrators.solve(rhs, [1.0, 0.0], (0, 10))
+```
+
+## Adding a demo
+
+```python
+# src/qplay/demos.py
+@demo("my-demo")
+def my_demo():
+    """One-line description shown by `qplay list`."""
+    fig, ax = plt.subplots()
+    ...
+    return fig
+```
+
+It appears in `qplay list` and is covered by the test suite automatically. Animations work the same way with `@animation("name")` in `src/qplay/animations.py`, returning `(fig, update, frames)`.
+
+## Development
+
+See `CLAUDE.md` for conventions.
+
+- `make test` is the fast loop: it skips tests marked `slow` (the site build, the biggest simulations and the browser tests). `make test-all` runs everything, and `make coverage` adds a line-by-line coverage report that fails below 95%.
+- `tests/test_explorer.py` drives the explorer in headless Chromium: it moves sliders and checks every readout against the Python package or an analytic formula, and lets the animations run to check what they converge to (orbital period, Lorenz separation, Ising magnetisation). Install with `pip install -e ".[browser]"` and `python -m playwright install chromium`, then `make test-browser`. Without Playwright these tests are skipped; CI installs it and fails if the browser is missing.
+- CI runs every test with coverage on Python 3.10, 3.12 and 3.13, and executes the notebooks and lessons.
+- The website is built by `.github/workflows/pages.yml` on every push to `main`: `scripts/build_site.py` renders all demos and animations, executes the notebooks to HTML, builds the API reference from the docstrings with pdoc, and copies the explorer from `site_src/`. Build it locally with `make site` (output in `_site/`), or just the API reference with `make api`. The README images live in `docs/images/` and are regenerated with `make readme-media`.
+- Releases: the distribution is called `quantum-playground` (the import name is still `qplay`; the name `qplay` is taken on PyPI). Pushing a tag such as `v0.3.0` runs `.github/workflows/release.yml`, which checks the tag matches `qplay.__version__`, runs the tests, builds the wheel and publishes it to PyPI through a trusted publisher. `make dist` builds the same files locally.
+
+## License
+
+MIT, see `LICENSE`.

quantum_playground-0.3.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "quantum-playground"
+version = "0.3.0"
+description = "A physics and maths playground: simulations, symbolic maths and notebooks."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = ["numpy", "scipy", "sympy", "matplotlib"]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-cov", "jupyterlab", "ipykernel", "pandas", "nbconvert", "pdoc", "build"]
+# Browser tests of the explorer (tests/test_explorer.py); also run `python -m playwright install chromium`.
+browser = ["playwright"]
+
+[project.urls]
+Homepage = "https://stativesh.github.io/quantum-playground/"
+Documentation = "https://stativesh.github.io/quantum-playground/api/"
+Source = "https://github.com/StativeSh/quantum-playground"
+
+[project.scripts]
+qplay = "qplay.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+# Slow tests (site build, big simulations) are skipped by default; `make test-all` or `pytest -m ""` runs them.
+addopts = "-q -m 'not slow'"
+markers = ["slow: takes more than a couple of seconds; skipped unless selected with -m \"\" or -m slow"]
+
+[tool.coverage.run]
+source = ["qplay"]
+
+[tool.coverage.report]
+fail_under = 95
+show_missing = true
+skip_covered = true

quantum_playground-0.3.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

quantum_playground-0.3.0/src/qplay/__init__.py

@@ -0,0 +1,29 @@
+"""qplay: a small physics and maths playground.
+
+Modules
+-------
+integrators  time-stepping schemes (Euler, RK4, velocity Verlet, adaptive wrapper)
+mechanics    oscillators, pendulums, projectiles, N-body gravity
+waves        1D wave and heat equations, Fourier series, spectra
+em           point-charge fields, Laplace solver, charged-particle motion
+quantum      Schroedinger solvers (1D and 2D), tunnelling, double slit, hydrogen orbitals, spin-1/2,
+             oscillator eigenstates and coherent states
+statmech     2D Ising model and Onsager's exact solution
+relativity   Lorentz transformations and special-relativity helpers
+kinetic      hard-sphere gas, Maxwell-Boltzmann distribution, ideal-gas law
+atomic       angular momentum, spin-orbit coupling, Zeeman effect, hydrogen fine structure
+nuclear      radioactive decay, Bateman decay chains, Monte Carlo decay
+circuits     RC charging and discharging, series RLC resonance
+chaos        Lorenz system, logistic map, Mandelbrot/Julia sets
+symbolic     SymPy helpers: Euler-Lagrange equations, Lagrangian -> simulation
+hamiltonian  Legendre transform, Hamilton's equations, Hamiltonian -> simulation
+dynamics     phase portraits and fixed-point classification for 2D systems
+complexplane domain colouring and the argument principle
+linalg       Gram-Schmidt, power iteration, how a matrix maps the unit circle
+numerics     root finding, quadrature, finite differences, Monte Carlo
+plotting     figure saving and GIF helpers
+demos        ready-made figures, run with ``python -m qplay run <name>``
+animations   GIFs, run with ``python -m qplay animate <name>``
+"""
+
+__version__ = "0.3.0"

quantum_playground-0.3.0/src/qplay/__main__.py

@@ -0,0 +1,58 @@
+"""Command line.
+
+    qplay list                         show demos and animations
+    qplay run <name|all> [--out DIR]   render demo figures (PNG)
+    qplay animate <name|all> [--frames N] [--fps F] [--out DIR]   render animations (GIF)
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from . import __version__, animations, demos
+
+
+def _summary(fn):
+    doc = (fn.__doc__ or "").strip().splitlines()
+    return doc[0] if doc else ""
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="qplay", description="Physics and maths playground")
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("list", help="list demos and animations")
+    run = sub.add_parser("run", help="render demos to PNG files")
+    run.add_argument("names", nargs="+", help="demo names, or 'all'")
+    run.add_argument("--out", default="figures", help="output directory (default: figures)")
+    anim = sub.add_parser("animate", help="render animations to GIF files")
+    anim.add_argument("names", nargs="+", help="animation names, or 'all'")
+    anim.add_argument("--out", default="figures", help="output directory (default: figures)")
+    anim.add_argument("--frames", type=int, default=120, help="number of frames (default: 120)")
+    anim.add_argument("--fps", type=int, default=24, help="frames per second (default: 24)")
+    args = parser.parse_args(argv)
+
+    if args.command == "list":
+        print("Demos (qplay run NAME):")
+        for name in sorted(demos.DEMOS):
+            print(f"  {name:22s}{_summary(demos.DEMOS[name])}")
+        print("Animations (qplay animate NAME):")
+        for name in sorted(animations.ANIMATIONS):
+            print(f"  {name:22s}{_summary(animations.ANIMATIONS[name])}")
+        return 0
+
+    registry = demos.DEMOS if args.command == "run" else animations.ANIMATIONS
+    names = sorted(registry) if args.names == ["all"] else args.names
+    for name in names:
+        try:
+            if args.command == "run":
+                print(demos.run(name, args.out))
+            else:
+                print(animations.render(name, args.out, n_frames=args.frames, fps=args.fps))
+        except KeyError as err:
+            parser.error(str(err.args[0]))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())