Metadata-Version: 2.1
Name: formulon-physics
Version: 0.6.0
Summary: An optimized open-source computational library for high-performance mathematical and physical formulas.
Project-URL: Documentation, https://github.com/SRIKALEESWARAR-S/formulon#readme
Project-URL: Issues, https://github.com/SRIKALEESWARAR-S/formulon/issues
Project-URL: Source, https://github.com/SRIKALEESWARAR-S/formulon
Author-email: SRIKALEESWARAR-S <srikaleeswarar675@gmail.com>
License: Apache-2.0
License-File: LICENSE
Keywords: education,formulas,numba,numpy,physics,science,scipy
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: numba>=0.56.0
Requires-Dist: numpy>=1.22.0
Requires-Dist: scipy>=1.8.0
Provides-Extra: pennylane
Requires-Dist: pennylane>=0.35; extra == 'pennylane'
Provides-Extra: qiskit
Requires-Dist: qiskit>=1.0; extra == 'qiskit'
Provides-Extra: quantum
Requires-Dist: formulon-physics[pennylane,qiskit]; extra == 'quantum'
Description-Content-Type: text/markdown

# Formulon

[![PyPI version](https://img.shields.io/pypi/v/formulon-physics.svg)](https://pypi.org/project/formulon-physics/)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python Support](https://img.shields.io/pypi/pyversions/formulon-physics.svg)](https://pypi.org/project/formulon-physics/)

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

```bash
pip install formulon-physics
```

Optional quantum-computing extras:

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

---

## ⚡ Quick Start

```python
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

```text
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

```bash
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](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.
