Quickstart Guide

Install the framework and discover the power of physics-constrained scientific computing.

1. Installation

Phaethon is fully modular. You only install what you need.

Minimal Installation

Includes Units & Dimensional Analysis and NumPy integration.

pip install phaethon

Complete Ecosystem

Installs everything: Pandas, Polars, RapidFuzz, Sci-ML, Torch, H5, and Arrow.

pip install 'phaethon[all]'

Targeted Bundles & Individual Packages

If you are deploying to constrained environments (like edge devices or strict Docker containers), you can selectively install specific capability bundles:

pip install 'phaethon[dataframe]' Pandas & RapidFuzz (Data pipelines)
pip install 'phaethon[sciml]' Scikit-Learn & PyTorch (Machine Learning)
pip install 'phaethon[io]' h5py & pyarrow (Polyglot Storage)

*You can also target specific engine backends directly: [pandas], [polars], [sklearn], [torch].

2. Units & Dimensional Analysis

Phaethon understands the laws of physics natively. It synthesizes complex dimensions on the fly and allows seamless conversions while mathematically blocking impossible operations.

python
import phaethon.units as u

mass = u.Kilogram(1500)
acceleration = u.MeterPerSecondSquared(9.8)

# The engine dynamically synthesizes the correct physical dimension
force = mass * acceleration
print(force)
# 14700.0 N

# Seamlessly convert to other valid units within the same dimension
print(force.to(u.Kilonewton))
# 14.7 kN

# Mathematically blocking impossible physical states before they corrupt pipelines
impossible = mass + acceleration
# DimensionMismatchError: Cannot add 'mass' and 'acceleration'.

3. Hybrid Data Engineering

Build strict schemas to clean messy sensor strings, interpolate dead zones, and enforce physical bounds using the underlying Rust/C++ engine.

python
import phaethon as ptn
import pandas as pd
import phaethon.units as u

class RocketSchema(ptn.Schema):
    # Parses raw strings, drops 'ERR' signals, and enforces Absolute Zero
    temperature: u.Celsius = ptn.Field(
        source="raw_temp", 
        parse_string=True, 
        min=-273.15, 
        on_error="clip"
    )

# Load real-world chaotic sensor outputs from disk
dirty_data = pd.read_csv("telemetry_export.csv")

# The Rust/C++ engine normalizes millions of rows in a single, extreme-throughput pass
clean_data = RocketSchema.normalize(dirty_data)

4. The Dimension-Aware Dataset

Seamlessly transition cleaned DataFrames into a Phaethon Dataset. This unified columnar store holds both naked arrays and PyTorch autograd tensors simultaneously.

python
# Translate the DataFrame into a zero-overhead Phaethon Dataset
dataset = RocketSchema.astensor(clean_data, requires_grad=True)

# Extract a PyTorch-backed PTensor. 
# Its physical DNA and autograd state remain perfectly intact.
temp_tensor = dataset['temperature'].tensor
time_tensor = dataset['time'].tensor

print(temp_tensor.requires_grad)
# True

5. Native Physical Calculus

Feed the extracted PyTorch tensors directly into Phaethon's calculus engine. Differentiating tensors automatically computes gradients and synthesizes the correct derivative units within the autograd graph.

python
import phaethon.pinns as pnn

# Differentiating Temperature over Time (dT/dt)
cooling_rate = pnn.grad(outputs=temp_tensor, inputs=time_tensor)

# Phaethon automatically infers the derived physical unit!
print(cooling_rate.unit.symbol)
# °C/s

# Formulate Physics-Informed Neural Network (PINNs) loss functions securely
pde_loss = pnn.ResidualLoss()(cooling_rate, target=0.0)
pde_loss.backward()

Where to go next?

Now that you understand the core lifecycle, dive deeper into the technical architecture or explore our real-world interactive examples.