# rannd1nt/phaethon architecture

> Architecture diagram of the GitHub repository rannd1nt/phaethon, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/rannd1nt/phaethon
- Repository: https://github.com/rannd1nt/phaethon

## Overview

#### 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`.

Main entry points: [`src/phaethon/core/base.py`](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/base.py) (Unit runtime), [`src/phaethon/core/schema.py`](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/schema.py) (Schema & semantics), [`src/phaethon/core/dataset.py`](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/dataset.py) (Normalized dataset), [`src/phaethon/core/backends/protocol.py`](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/backends/protocol.py) (Backend protocol)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public["Public API"]
  node_package["Phaethon package<br/>Python entry point<br/>[__init__.py]"]
  node_facades["Focused facades<br/>Python API<br/>[units.py]"]
  node_axiom_api["Axiom API<br/>Python API<br/>[axiom.py]"]
end

subgraph group_units["Dimensional Core"]
  node_base["Unit runtime<br/>dimensional algebra<br/>[base.py]"]
  node_axioms["Constraints &amp; axioms<br/>validation rules<br/>[axioms.py]"]
  node_unit_catalog["Unit catalog<br/>physical dimensions<br/>[__init__.py]"]
  node_tensor["Dimensioned tensors<br/>NumPy integration<br/>[tensor.py]"]
  node_numeric_ops["Linalg &amp; random ops<br/>physics-aware operations<br/>[linalg.py]"]
end

subgraph group_data["Data Pipeline"]
  node_schema["Schema &amp; semantics<br/>data model<br/>[schema.py]"]
  node_dataset[("Normalized dataset<br/>validated tabular data<br/>[dataset.py]")]
  node_backend_protocol{{"Backend protocol<br/>adapter boundary<br/>[protocol.py]"}}
  node_pandas_engine["Pandas engine<br/>data adapter<br/>[engine.py]"]
  node_polars_engine["Polars engine<br/>data adapter<br/>[engine.py]"]
  node_io["Semantic I/O<br/>dataset interchange<br/>[io.py]"]
end

subgraph group_ml["Sci-ML"]
  node_ml_estimator["Dimension-aware estimators<br/>scikit-learn adapter<br/>[estimator.py]"]
  node_ml_features["Features &amp; preprocessing<br/>ML transforms<br/>[features.py]"]
  node_ptensor["PTensor bridge<br/>PyTorch tensor adapter<br/>[tensor.py]"]
  node_calculus["Unit-aware calculus<br/>PINN derivatives<br/>[calculus.py]"]
  node_loss["Residual loss<br/>PINN objective<br/>[loss.py]"]
end

subgraph group_delivery["Native Build &amp; Delivery"]
  node_rust{{"Rust extension<br/>native acceleration<br/>[lib.rs]"}}
  node_packaging["Package configuration<br/>Python packaging<br/>[pyproject.toml]"]
  node_cargo["Rust crate<br/>native build manifest<br/>[Cargo.toml]"]
  node_ci["CI<br/>automation<br/>[ci.yml]"]
  node_publish["Publishing<br/>release automation<br/>[publish.yml]"]
end

node_package -->|"exports"| node_facades
node_package -->|"exports"| node_axiom_api
node_facades -->|"uses"| node_base
node_axiom_api -->|"exposes"| node_axioms
node_base -->|"resolves units"| node_unit_catalog
node_base -->|"checks constraints"| node_axioms
node_tensor -->|"carries dimensions"| node_base
node_numeric_ops -->|"operates on"| node_tensor
node_schema -->|"converts fields"| node_base
node_schema -->|"normalizes into"| node_dataset
node_backend_protocol -.->|"implemented by"| node_pandas_engine
node_backend_protocol -.->|"implemented by"| node_polars_engine
node_pandas_engine -->|"ingests tabular data"| node_schema
node_polars_engine -->|"ingests tabular data"| node_schema
node_io -->|"reads and writes"| node_dataset
node_dataset -->|"supplies validated data"| node_ml_features
node_ml_features -->|"feeds features"| node_ml_estimator
node_dataset -->|"becomes inputs"| node_ptensor
node_ptensor -->|"differentiated by"| node_calculus
node_calculus -->|"produces residuals"| node_loss
node_rust -.->|"accelerates backend work"| node_backend_protocol
node_packaging -->|"builds with Maturin"| node_rust
node_cargo -->|"defines crate"| node_rust
node_ci -->|"validates"| node_packaging
node_publish -->|"publishes"| node_packaging

click node_package "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/__init__.py"
click node_facades "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/units.py"
click node_axiom_api "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/axiom.py"
click node_base "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/base.py"
click node_axioms "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/axioms.py"
click node_unit_catalog "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/units/__init__.py"
click node_tensor "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/tensor.py"
click node_numeric_ops "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/linalg.py"
click node_schema "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/schema.py"
click node_dataset "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/dataset.py"
click node_backend_protocol "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/backends/protocol.py"
click node_pandas_engine "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/backends/pd_engine/engine.py"
click node_polars_engine "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/backends/pl_engine/engine.py"
click node_io "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/io.py"
click node_ml_estimator "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/ml/estimator.py"
click node_ml_features "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/ml/features.py"
click node_ptensor "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/pinns/tensor.py"
click node_calculus "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/pinns/calculus.py"
click node_loss "https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/pinns/loss.py"
click node_rust "https://github.com/rannd1nt/phaethon/blob/main/rust_src/lib.rs"
click node_packaging "https://github.com/rannd1nt/phaethon/blob/main/pyproject.toml"
click node_cargo "https://github.com/rannd1nt/phaethon/blob/main/Cargo.toml"
click node_ci "https://github.com/rannd1nt/phaethon/blob/main/.github/workflows/ci.yml"
click node_publish "https://github.com/rannd1nt/phaethon/blob/main/.github/workflows/publish.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_package,node_facades,node_axiom_api toneBlue
class node_base,node_axioms,node_unit_catalog,node_tensor,node_numeric_ops toneAmber
class node_schema,node_dataset,node_backend_protocol,node_pandas_engine,node_polars_engine,node_io toneMint
class node_ml_estimator,node_ml_features,node_ptensor,node_calculus,node_loss toneRose
class node_rust,node_packaging,node_cargo,node_ci,node_publish toneIndigo
```

## Components

### Public API

- [Phaethon package](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/__init__.py): Python entry point · Top-level package surface. · `src/phaethon/__init__.py`
- [Focused facades](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/units.py): Python API · Units, linalg, random, ML, and PINN public modules. · `src/phaethon/units.py`
- [Axiom API](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/axiom.py): Python API · `src/phaethon/axiom.py`

### Dimensional Core

- [Unit runtime](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/base.py): dimensional algebra · Defines dimension-aware values and derived-unit behavior. · `src/phaethon/core/base.py`
- [Constraints & axioms](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/axioms.py): validation rules · `src/phaethon/core/axioms.py`
- [Unit catalog](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/units/__init__.py): physical dimensions · Base and domain-specific unit definitions. · `src/phaethon/core/units/__init__.py`
- [Dimensioned tensors](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/tensor.py): NumPy integration · Uses NumPy array protocols without ndarray inheritance. · `src/phaethon/core/tensor.py`
- [Linalg & random ops](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/linalg.py): physics-aware operations · Preserves valid output dimensions. · `src/phaethon/core/linalg.py`

### Data Pipeline

- [Schema & semantics](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/schema.py): data model · Localizes, converts, and validates physical fields. · `src/phaethon/core/schema.py`
- [Normalized dataset](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/dataset.py): validated tabular data · Tensor-ready columns retaining semantic metadata. · `src/phaethon/core/dataset.py`
- [Backend protocol](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/backends/protocol.py): adapter boundary · `src/phaethon/core/backends/protocol.py`
- [Pandas engine](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/backends/pd_engine/engine.py): data adapter · `src/phaethon/core/backends/pd_engine/engine.py`
- [Polars engine](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/backends/pl_engine/engine.py): data adapter · `src/phaethon/core/backends/pl_engine/engine.py`
- [Semantic I/O](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/io.py): dataset interchange · Coordinates .phx and Parquet-oriented workflows. · `src/phaethon/core/io.py`

### Sci-ML

- [Dimension-aware estimators](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/ml/estimator.py): scikit-learn adapter · Constrained estimator workflows. · `src/phaethon/core/ml/estimator.py`
- [Features & preprocessing](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/ml/features.py): ML transforms · Builds physically valid features and preprocessing flows. · `src/phaethon/core/ml/features.py`
- [PTensor bridge](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/pinns/tensor.py): PyTorch tensor adapter · Bridges units into autograd-compatible tensors. · `src/phaethon/core/pinns/tensor.py`
- [Unit-aware calculus](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/pinns/calculus.py): PINN derivatives · `src/phaethon/core/pinns/calculus.py`
- [Residual loss](https://github.com/rannd1nt/phaethon/blob/main/src/phaethon/core/pinns/loss.py): PINN objective · Enforces dimensionally valid residuals before PyTorch backpropagation. · `src/phaethon/core/pinns/loss.py`

### Native Build & Delivery

- [Rust extension](https://github.com/rannd1nt/phaethon/blob/main/rust_src/lib.rs): native acceleration · Maturin-built performance-sensitive backend module. · `rust_src/lib.rs`
- [Package configuration](https://github.com/rannd1nt/phaethon/blob/main/pyproject.toml): Python packaging · Defines optional runtime dependency groups and native build. · `pyproject.toml`
- [Rust crate](https://github.com/rannd1nt/phaethon/blob/main/Cargo.toml): native build manifest · `Cargo.toml`
- [CI](https://github.com/rannd1nt/phaethon/blob/main/.github/workflows/ci.yml): automation · `.github/workflows/ci.yml`
- [Publishing](https://github.com/rannd1nt/phaethon/blob/main/.github/workflows/publish.yml): release automation · `.github/workflows/publish.yml`

## Connections

- Phaethon package → Focused facades: exports
- Phaethon package → Axiom API: exports
- Focused facades → Unit runtime: uses
- Axiom API → Constraints & axioms: exposes
- Unit runtime → Unit catalog: resolves units
- Unit runtime → Constraints & axioms: checks constraints
- Dimensioned tensors → Unit runtime: carries dimensions
- Linalg & random ops → Dimensioned tensors: operates on
- Schema & semantics → Unit runtime: converts fields
- Schema & semantics → Normalized dataset: normalizes into
- Backend protocol → Pandas engine: implemented by
- Backend protocol → Polars engine: implemented by
- Pandas engine → Schema & semantics: ingests tabular data
- Polars engine → Schema & semantics: ingests tabular data
- Semantic I/O → Normalized dataset: reads and writes
- Normalized dataset → Features & preprocessing: supplies validated data
- Features & preprocessing → Dimension-aware estimators: feeds features
- Normalized dataset → PTensor bridge: becomes inputs
- PTensor bridge → Unit-aware calculus: differentiated by
- Unit-aware calculus → Residual loss: produces residuals
- Rust extension → Backend protocol: accelerates backend work
- Package configuration → Rust extension: builds with Maturin
- Rust crate → Rust extension: defines crate
- CI → Package configuration: validates
- Publishing → Package configuration: publishes