Formulon

An optimized, open-source computational library for mathematical physics, classical mechanics, electronics, wave optics, electromagnetism, thermodynamics, fluid mechanics, and modern (relativistic/quantum) physics -- with an optional quantum-computing extension built on Qiskit and PennyLane.

formulon bridges theoretical formulations and numerical execution. Hot numerical loops are accelerated with NumPy, special functions are backed by SciPy, and pure recurrence-relation computations (e.g. Legendre/Laguerre/Hermite polynomials) are JIT-compiled with Numba in true nopython mode.

🚀 Key Features

• 232 physics functions across 8 domains (see table below): classical mechanics, waves & optics, thermodynamics, electromagnetism, fluid mechanics, mathematical physics (Fourier analysis, vector calculus theorems, special functions, PDE solvers), and modern physics (relativity, quantum mechanics, nuclear decay).
• Real JIT acceleration where it counts: pure numeric recurrences (Legendre, Laguerre, Hermite polynomials) run in Numba nopython mode. Functions that just delegate to SciPy (e.g. Bessel functions) are left as plain Python, since JIT-wrapping a SciPy call adds overhead with zero speedup.
• Runtime physical-bounds validation: a decorator-driven validator layer checks every input against real physical constraints (can't exceed light speed, can't go below absolute zero, etc.) before a calculation runs, and turns raw Python exceptions (ZeroDivisionError, OverflowError) into physically-meaningful error messages.
• Optional quantum-computing extension (formulon.quantum_computing): small, local-simulator-only circuits in Qiskit and PennyLane, including an original Legendre-polynomial quantum feature map and kernel that bridges this library's own classical special functions into quantum machine learning. Not installed by default -- see below.

📦 Installation

pip install formulon-physics

Optional quantum-computing extras:

pip install "formulon-physics[qiskit]"      # Qiskit-backed circuits
pip install "formulon-physics[pennylane]"   # PennyLane-backed circuits
pip install "formulon-physics[quantum]"     # both

⚡ Quick Start

import formulon

formulon.newtons_second_law(mass=2.0, acceleration=3.0)   # 6.0 N
formulon.lorentz_factor(v=2.5e8)                           # relativistic gamma
formulon.legendre_polynomial(n=2, x=0.5)                   # -0.125

# Optional: quantum computing extension
from formulon.quantum_computing import qiskit_circuits as qc

qc.bell_pair_probabilities()                    # {"00": 0.5, "11": 0.5}
qc.legendre_quantum_kernel(0.2, 0.8, degree=3)  # fidelity kernel in [0, 1]

📦 Project Architecture

src/formulon/
├── __init__.py                # Package namespace constructor
├── __about__.py                # Dynamic version registry (Hatch)
├── validator.py                # Physical-bounds validation & error handling
├── classicalmechanics.py       # Kinematics, dynamics, rotational mechanics (60 fns)
├── electromagnetism.py         # Electrostatics, magnetostatics, circuits (49 fns)
├── wavedynamics.py             # Wave mechanics, acoustics, ray optics (33 fns)
├── mathematicalphysics.py      # Fourier analysis, vector calculus, special functions (23 fns)
├── thermodynamics.py           # Thermal expansion, kinetic theory, cycles (23 fns)
├── modernphysics.py            # Special relativity, quantum mechanics, nuclear decay (18 fns)
├── fluidmechanics.py           # Fluid statics/dynamics (17 fns)
├── mathematicalseries.py       # Numba-accelerated series & sequences (9 fns)
└── quantum_computing/          # OPTIONAL -- not imported by default
    ├── qiskit_circuits.py      # Bell pairs, Legendre feature map/kernel, QFT, Grover
    └── pennylane_circuits.py   # Legendre feature map/kernel, VQE-style ansatz, gradients

🧪 Testing

pip install -e ".[quantum]"
pytest --cov

Quantum tests are automatically skipped (not failed) if Qiskit/PennyLane aren't installed.

License

Apache License 2.0. See LICENSE.

Developed by SRI KALEESWARAR S, a Physics postgraduate student from India. Thanks to my professors at Scott Christian College, with special mention to Kaniyam.com and Open Science Labs.