physicskit

Package
Quality
Documentation
Code style
Downloads
Community

A unified scientific toolkit for computational physics, spanning the field end to end: the quantum mechanics of a single hydrogen atom, the numerical relativity of colliding black holes, turbulent fluid instabilities, topological superconductors, magnetically confined plasmas, and chaotic quantum billiards -- 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, sharing common ODE integrators and physical constants throughout. Conventionally imported as pk.

Install

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

Quick start

import physicskit as pk
import numpy as np

H = lambda k1, k2: pk.condensed.haldane_model(k1, k2, phi=np.pi / 2)
chern_numbers = pk.condensed.compute_chern_number(H, grid_size=30)
print(chern_numbers)  # [1, -1]

Every subpackage below links to its worked examples; see Subpackages for the full list, or browse the docs at https://cpoli.github.io/physicskit/.

Subpackages

Domain subpackages, each with runnable examples linked below:

• physicskit.astro -- stellar structure (Tolman-Oppenheimer-Volkoff, polytropes), N-body dynamics, orbital mechanics, galactic rotation curves, stellar convection and the magnetic dynamo.
• physicskit.chaos -- chaotic dynamical systems and 2D quantum billiards.
• physicskit.classical -- classical mechanics: Newtonian, Lagrangian, Hamiltonian, lattice, and rigid-body dynamics.
• physicskit.condensed -- tight-binding models, topological band theory (Chern numbers, edge states), correlated-electron superconductivity.
• physicskit.fields -- FDTD electrodynamics, KdV/NLS/Sine-Gordon solitons, BEC vortex lattices.
• physicskit.fluids -- potential flow, viscous exact solutions, point-vortex dynamics, Kelvin-Helmholtz and Rayleigh-Taylor instabilities, compressible shocks, and the 2D incompressible Navier-Stokes solver underlying them.
• physicskit.optics -- ray, wave, and Gaussian-beam optics; quantum optics (squeezed states, Wigner functions).
• physicskit.particle -- relativistic kinematics, particle decays and scattering, nuclear physics.
• physicskit.plasma -- Boris-pusher single-particle motion, guiding-center drifts, Grad-Shafranov MHD equilibrium, magnetic reconnection, cold-plasma wave dispersion, particle-in-cell Vlasov-Poisson kinetics.
• physicskit.quantum -- quantum mechanics: wave packets, potentials, hydrogen, entanglement, measurement.
• physicskit.relativity -- numerical general relativity: black holes, lensing, gravitational waves, cosmology.
• physicskit.rmt -- random matrix theory, organized around Dyson's threefold way.
• physicskit.semiclassical -- WKB/EBK quantization, Van Vleck/Herman-Kluk semiclassical propagators, the Gutzwiller trace formula, and quantum scarring.
• physicskit.statphys -- statistical mechanics: lattice models, molecular dynamics, criticality, disordered systems.

Shared infrastructure, used across the subpackages above rather than standalone toolkits:

• physicskit.constants -- SI physical constants shared across subpackages, plus a few well-defined unit conversions (energy/temperature, eV/joules, gravitational G=1 unit systems).
• physicskit.integrators -- shared numerical ODE integrators (RK4, leapfrog, Yoshida4, adaptive Dormand-Prince) used across the other subpackages.

Test

Tests live alongside each subpackage, at physicskit/<name>/tests/.

pytest                                              # everything
pytest physicskit/rmt/tests                         # a single subpackage

# docstring examples, across every subpackage (pyvista's 3D viewer is
# optional and skipped rather than installed as a hard test dependency):
MPLBACKEND=Agg pytest --doctest-modules physicskit \
    --ignore-glob="*/tests/*" \
    --ignore=physicskit/chaos/visualizers/viewer3d.py

Both commands, plus ruff check/ruff format --check, run in CI on every PR (.github/workflows/ci.yml) across Python 3.10-3.12 on Linux and macOS. See CONTRIBUTING.md before opening a PR.

Coverage

MPLBACKEND=Agg pytest -q -n auto --cov=physicskit --cov-report=term

1,720 tests, 96% line coverage overall. Per-subpackage coverage:

Every subpackage is at 100% coverage outside visualizers/ modules (99.9% in aggregate — six rare bootstrap-loop edge cases remain uncovered across statphys.chapters.percolation and rmt.stats). chaos, quantum, and statphys still sit lower overall because their 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. @njit-compiled lines are excluded from coverage entirely (pyproject.toml, [tool.coverage.report]) since coverage.py cannot trace into numba-compiled native code.

Docs

Built docs are hosted at https://cpoli.github.io/physicskit/, served from the gh-pages branch. To build locally:

pip install -e ".[docs]"
cd docs && make html

See docs/source/history/ for a chronology of each field's foundational breakthroughs, linked to the corresponding implementation at each step.

Citation

If you use physicskit in your research, please cite it — see CITATION.cff.

Contributing

See CONTRIBUTING.md. Please note that this project follows the Contributor Covenant.

License

MIT -- see LICENSE.