rannd1nt/phaethon

Purpose and Public Surface

Phaethon is a Python 3.11+ physics-constrained scientific-computing and Sci-ML library. It combines dimension-aware NumPy algebra, validated tabular ingestion, scikit-learn integration, and PyTorch PINNs. Main package entry points are src/phaethon/__init__.py, with focused public facades at src/phaethon/units.py, src/phaethon/linalg.py, src/phaethon/random.py, src/phaethon/ml.py, and src/phaethon/pinns.py.

Dimensional Algebra Core

The unit system defines physical dimensions as Python types and supports derived-unit synthesis, compatibility checks, conversions, and domain-specific units. The base algebra/runtime is centered on src/phaethon/core/base.py, src/phaethon/core/axioms.py, and src/phaethon/core/units/__init__.py; concrete domains are distributed under src/phaethon/core/units/ (for example, length.py, force.py, and thermodynamics.py). src/phaethon/axiom.py exposes the constraint/axiom layer publicly.

Numerical Compute Boundary

Dimension-carrying values integrate with NumPy’s array protocols rather than requiring ndarray inheritance. Core tensor/array behavior and physics-aware math reside in src/phaethon/core/tensor.py, src/phaethon/core/linalg.py, and src/phaethon/core/random.py. Flow is: callers construct or convert values with a unit, algebra propagates/synthesizes units, and specialized linear-algebra or random operations preserve valid output dimensions.

Declarative Data Pipeline

Schemas turn external tabular data into normalized, physically validated datasets and tensor-ready columns. The public model is implemented in src/phaethon/core/schema.py, src/phaethon/core/dataset.py, and src/phaethon/core/semantics.py. Data-engine adapters are separated behind src/phaethon/core/backends/protocol.py, with equivalent Pandas and Polars implementations under src/phaethon/core/backends/pd_engine/engine.py and src/phaethon/core/backends/pl_engine/engine.py. This is the boundary for CSV/DataFrame inputs, field localization/conversion, validation, and imputation.

Rust Acceleration and I/O

A Maturin-built Rust extension supplies performance-sensitive backend functionality, with Rust crate definitions in Cargo.toml and native module code in rust_src/lib.rs. Python-side data I/O is coordinated by src/phaethon/core/io.py. The intended interchange boundary includes .phx and Parquet-oriented workflows, allowing normalized data to move toward tensor and ML stages without losing semantic metadata.

Sci-ML Adapters

Classic ML support wraps or augments scikit-learn-style workflows with dimension-aware estimators, feature generation, preprocessing, metrics, and selection. Its architectural surface is src/phaethon/core/ml/estimator.py, src/phaethon/core/ml/features.py, and src/phaethon/core/ml/preprocessing.py. This layer consumes validated numerical/semantic data and produces ML-compatible feature and estimator flows while enforcing physical constraints.

PINN and PyTorch Path

The PINN subsystem bridges physical units into autograd-compatible PyTorch tensors. src/phaethon/core/pinns/tensor.py provides PTensor; src/phaethon/core/pinns/calculus.py implements unit-aware derivatives; and src/phaethon/core/pinns/loss.py enforces dimensionally valid residual losses. Typical flow is schema dataset → PTensor inputs → unit-stripped/assembled neural features → unit-restored predictions → calculus operators → residual loss → standard PyTorch backpropagation.

Runtime Dependencies and Delivery

The material runtimes are Python, NumPy, optional Pandas/Polars, optional PyTorch, optional scikit-learn, and compiled Rust. Packaging and optional dependency groups are defined in pyproject.toml; CI and package publication are automated through .github/workflows/ci.yml and .github/workflows/publish.yml. Documentation is built for ReadTheDocs via .readthedocs.yaml.