https://github.com/rannd1nt/phaethon
End-to-End Physics-Constrained Scientific Computing & Sci-ML Framework
https://github.com/rannd1nt/phaethon
data-science engineering frameworks linear-algebra machine-learning numpy pandas pde physics pinns python python-library python3 scientific-computing scientific-machine-learning scikit-learn sklearn torch type-hints units
Last synced: 2 days ago
JSON representation
End-to-End Physics-Constrained Scientific Computing & Sci-ML Framework
- Host: GitHub
- URL: https://github.com/rannd1nt/phaethon
- Owner: rannd1nt
- License: mit
- Created: 2025-03-30T08:46:19.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-06T18:09:43.000Z (2 days ago)
- Last Synced: 2026-04-06T18:18:59.835Z (2 days ago)
- Topics: data-science, engineering, frameworks, linear-algebra, machine-learning, numpy, pandas, pde, physics, pinns, python, python-library, python3, scientific-computing, scientific-machine-learning, scikit-learn, sklearn, torch, type-hints, units
- Language: Python
- Homepage: https://phaethon.readthedocs.io
- Size: 659 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
Phaethon
The End-to-End Physics-Constrained Scientific Computing & Sci-ML Framework.
Phaethon is a Python framework that unifies strict dimensional tensor algebra, Scientific Machine Learning (Sci-ML), and declarative data engineering. It is designed to ensure mathematical and physical integrity from the data ingestion layer to the final neural prediction.
## š Documentation
For complete tutorials, API references, and architectural concepts, visit the official documentation:
š **[phaethon.readthedocs.io](https://phaethon.readthedocs.io/)**
---
## ā” Core Ecosystem
Phaethon builds directly upon the **NumPy Array Protocol** to operate as a zero-overhead native proxy, extending physical safety to modern ML ecosystems.
1. **Metaclass-Driven Algebra:** Dynamic dimensional synthesis (e.g., `u.Meter / u.Second -> MeterPerSecond`). Inherently evaluates isomorphic firewalls, domain locks, and logarithmic math.
2. **Scientific Compute:** Physics-aware linear algebra (`ptn.linalg`) and strictly bounded stochastic tensor generation (`ptn.random`).
3. **Classic Sci-ML:** Equips Scikit-Learn with dimensional meta-estimators, axiom validators, and automated Buckingham Pi feature synthesis.
4. **Neural PDEs (PINNs):** Deep PyTorch integration. The `PTensor` allows gradients to flow safely through physical laws using native calculus (`pnn.grad`, `pnn.laplace`).
5. **Hybrid Data Engineering:** Normalizes raw CSVs/DataFrames and enforces physical limits at the ingestion layer using a Rust backend, bridging directly into PyTorch via `.phx` or `.parquet` formats.
---
## āļø The Physics Engine: A Modern Alternative
Legacy unit libraries (like Pint or Astropy) rely on generic object wrappers and runtime string evaluation, resulting in high computational overhead and blind IDEs. Phaethon rebuilds dimensional analysis from the ground up using modern Python architecture:
* **Zero-Overhead NumPy Proxies (NEP 13/18):** `BaseUnit` does not strictly subclass `np.ndarray` to avoid the brittle inheritance trap. Instead, it acts as a duck-typed protocol proxy, intercepting operations at the NumPy C-API layer. This allows it to natively fuse physics into floats, massive `ndarrays`, and even `MaskedArrays` without Python-level bottlenecks.
* **Metaclass JIT Caching:** Physical dimensions are concrete Python classes. When dimensions interact algebraically, the `_PhaethonUnitMeta` dynamically synthesizes a new class blueprint in memory and caches it via LRU. Math operations operate at raw C-speed without string parsing.
* **Flawless Static Typing (DX):** Because every dimension is a real class, IDEs (Mypy/Pylance) can strictly type-check physics out of the box (e.g., `def calc(x: u.LengthUnit)` will statically reject `u.Kilogram`).
### Scientific Computing Example
Phaethon extends dimensional safety into advanced linear algebra and stochastic generation.
```python
import phaethon as ptn
import phaethon.units as u
# 1. Zero-overhead NumPy tensor creation
mass_matrix = ptn.array([[10.0, 2.0], [3.0, 5.0]], u.Kilogram)
force_vector = u.Newton([50.0, 25.0]) # or just instantiate directly
# 2. Native Linear Algebra - Automatically synthesizes Acceleration (m/sĀ²)
acceleration = ptn.linalg.solve(mass_matrix, force_vector)
# 3. Logarithmic Algebra & Isomorphic Firewalls natively supported
signal = u.DecibelMilliwatt(30) + u.DecibelMilliwatt(30)
# Evaluates precisely to ~33.01 dBm via implicit linearization
```
---
## š End-to-End Example: Physics-Informed Neural Networks
The following workflow demonstrates Phaethon's end-to-end capability: parsing raw sensor data, extracting it into a dimension-aware dataset, and training a neural network to solve Burgers' Equation while mathematically guaranteeing dimensional integrity.
### Step 1: Ingesting Data (Schema)
Normalize chaotic inputs, apply boundary constraints, and extract data into PyTorch-ready tensors.
```python
import pandas as pd
import phaethon as ptn
import phaethon.units as u
# Declaratively enforce physical laws on incoming data
class SensorSchema(ptn.Schema):
x_pos: u.Meter = ptn.Field("Position", parse_string=True)
t_time: u.Second = ptn.Field("Time", min=0.0, on_error="clip")
# Load and normalize a raw DataFrame
messy_df = pd.read_csv("sensor_telemetry.csv")
clean_df = SensorSchema.normalize(messy_df)
# Bridge directly into PyTorch PTensors (Physics-Aware Tensors)
dataset = SensorSchema.astensor(clean_df, requires_grad=['x_pos', 't_time'])
x_sensor = dataset['x_pos'].tensor
t_sensor = dataset['t_time'].tensor
```
### Step 2: Neural Architecture (Assembly)
Standard PyTorch layers cannot digest physical metadata. Phaethon's `assemble` securely standardizes and strips the units, feeding pure features to the network before resurrecting the physics on the output.
```python
import torch.nn as nn
import phaethon.pinns as pnn
class ShockwaveNet(nn.Module):
def __init__(self):
super().__init__()
self.net = nn.Sequential(
nn.Linear(2, 128), nn.SiLU(),
nn.Linear(128, 128), nn.SiLU(),
nn.Linear(128, 1)
)
def forward(self, x_raw, t_raw):
# 1. Standardize inputs to base units safely
x_std = x_raw.asunit(u.Meter)
t_std = t_raw.asunit(u.Second)
# 2. Assemble physical tensors into naked PyTorch features
features = pnn.assemble(x_std, t_std, dim=-1)
# 3. Forward Pass & Resurrect Physical Identity (Velocity)
u_mag = self.net(features)
return pnn.PTensor(u_mag, unit=u.MeterPerSecond), x_std, t_std
```
### Step 3: Native Calculus & Loss Evaluation
Train the network using native differential calculus. Phaethon automatically synthesizes derivative units, and the `ResidualLoss` strictly ensures dimensional balance on the PDE.
```python
model = ShockwaveNet()
pde_loss_fn = pnn.ResidualLoss()
nu = pnn.PTensor(0.01 / 3.14159, unit=u.SquareMeterPerSecond)
# Forward pass
u_pred, x_s, t_s = model(x_sensor, t_sensor)
# Native PyTorch Calculus (Automatically synthesizes derived units)
du_dt = pnn.grad(u_pred, t_s, create_graph=True)
du_dx = pnn.grad(u_pred, x_s, create_graph=True)
d2u_dx2 = pnn.laplace(u_pred, x_s)
# Formulate the PDE Residual (Burgers' Equation)
# If dimensions mismatch (e.g., subtracting Force from Acceleration), execution halts.
pde_residual = du_dt + (u_pred * du_dx) - (nu * d2u_dx2)
# Compute Physics-Informed Penalty
loss = pde_loss_fn(pde_residual, target=0.0)
loss.backward()
```
---
## š¦ Installation & Modularity
Phaethon requires **Python >= 3.11** and is compiled via Maturin (Rust backend). Install only the scientific stack you need to avoid environment bloat:
```bash
# Core Physics Engine Only
pip install phaethon
# Data Engineering (Pandas + Rapidfuzz)
pip install 'phaethon[dataframe]'
# Neural PDEs & PINNs (PyTorch)
pip install 'phaethon[torch]'
# Classic Sci-ML (Scikit-learn)
pip install 'phaethon[sklearn]'
# The Complete Sci-ML Ecosystem
pip install 'phaethon[all]'
```
---
## š¤ Contributing
Contributions from the open-source community are greatly appreciated. Whether you are adding a new physical domain, optimizing the Rust backend, or expanding the Scikit-Learn transformers, your help is welcome.
Please read our **[CONTRIBUTING.md](CONTRIBUTING.md)** to set up your development environment, install the `[dev]` dependencies, and run the test suite.
## š License
Distributed under the MIT License. See the `LICENSE` file for more information.