{"id":46339020,"url":"https://github.com/rannd1nt/phaethon","last_synced_at":"2026-04-06T19:03:10.530Z","repository":{"id":285210157,"uuid":"957390318","full_name":"rannd1nt/phaethon","owner":"rannd1nt","description":"End-to-End Physics-Constrained Scientific Computing \u0026 Sci-ML Framework","archived":false,"fork":false,"pushed_at":"2026-04-06T18:09:43.000Z","size":675,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-06T18:18:59.835Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"https://phaethon.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rannd1nt.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-03-30T08:46:19.000Z","updated_at":"2026-04-06T18:09:47.000Z","dependencies_parsed_at":"2025-03-30T10:24:39.312Z","dependency_job_id":"91453b5f-abd7-4f27-9904-2afa24489cf4","html_url":"https://github.com/rannd1nt/phaethon","commit_stats":null,"previous_names":["zranndts/unit-flex","rannd1nt/chisa","rannd1nt/phaethon"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/rannd1nt/phaethon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rannd1nt%2Fphaethon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rannd1nt%2Fphaethon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rannd1nt%2Fphaethon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rannd1nt%2Fphaethon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rannd1nt","download_url":"https://codeload.github.com/rannd1nt/phaethon/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rannd1nt%2Fphaethon/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31485516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T17:22:55.647Z","status":"ssl_error","status_checked_at":"2026-04-06T17:22:54.741Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-03-04T19:33:43.071Z","updated_at":"2026-04-06T19:03:10.525Z","avatar_url":"https://github.com/rannd1nt.png","language":"Python","readme":"\u003cdiv align=\"center\"\u003e\n\n\u003ch1\u003ePhaethon\u003c/h1\u003e\n\n\u003cp\u003e\n\u003cimg src=\"https://img.shields.io/badge/MADE_WITH-PYTHON-blue?style=for-the-badge\u0026logo=python\u0026logoColor=white\" alt=\"Python\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/FOUNDATION-NUMPY-013243?style=for-the-badge\u0026logo=numpy\u0026logoColor=white\" alt=\"NumPy\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/INTEGRATION-PYTORCH-EE4C2C?style=for-the-badge\u0026logo=pytorch\u0026logoColor=white\" alt=\"PyTorch\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/INTEGRATION-PANDAS-150458?style=for-the-badge\u0026logo=pandas\u0026logoColor=white\" alt=\"Pandas\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/LICENSE-MIT-red?style=for-the-badge\" alt=\"License\"\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n\u003ci\u003eThe End-to-End Physics-Constrained Scientific Computing \u0026 Sci-ML Framework.\u003c/i\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\nPhaethon 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.\n\n## 📖 Documentation\nFor complete tutorials, API references, and architectural concepts, visit the official documentation:\n\n📌 **[phaethon.readthedocs.io](https://phaethon.readthedocs.io/)**\n\n---\n\n## ⚡ Core Ecosystem\n\nPhaethon builds directly upon the **NumPy Array Protocol** to operate as a zero-overhead native proxy, extending physical safety to modern ML ecosystems.\n\n1. **Metaclass-Driven Algebra:** Dynamic dimensional synthesis (e.g., `u.Meter / u.Second -\u003e MeterPerSecond`). Inherently evaluates isomorphic firewalls, domain locks, and logarithmic math.\n2. **Scientific Compute:** Physics-aware linear algebra (`ptn.linalg`) and strictly bounded stochastic tensor generation (`ptn.random`).\n3. **Classic Sci-ML:** Equips Scikit-Learn with dimensional meta-estimators, axiom validators, and automated Buckingham Pi feature synthesis.\n4. **Neural PDEs (PINNs):** Deep PyTorch integration. The `PTensor` allows gradients to flow safely through physical laws using native calculus (`pnn.grad`, `pnn.laplace`).\n5. **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.\n\n---\n\n## ⚛️ The Physics Engine: A Modern Alternative\n\nLegacy 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:\n\n* **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.\n* **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.\n* **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`).\n\n### Scientific Computing Example\nPhaethon extends dimensional safety into advanced linear algebra and stochastic generation.\n\n```python\nimport phaethon as ptn\nimport phaethon.units as u\n\n# 1. Zero-overhead NumPy tensor creation\nmass_matrix = ptn.array([[10.0, 2.0], [3.0, 5.0]], u.Kilogram)\nforce_vector = u.Newton([50.0, 25.0]) # or just instantiate directly\n\n# 2. Native Linear Algebra - Automatically synthesizes Acceleration (m/s²)\nacceleration = ptn.linalg.solve(mass_matrix, force_vector)\n\n# 3. Logarithmic Algebra \u0026 Isomorphic Firewalls natively supported\nsignal = u.DecibelMilliwatt(30) + u.DecibelMilliwatt(30)\n# Evaluates precisely to ~33.01 dBm via implicit linearization\n```\n\n---\n\n## 🚀 End-to-End Example: Physics-Informed Neural Networks\n\nThe 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.\n\n### Step 1: Ingesting Data (Schema)\nNormalize chaotic inputs, apply boundary constraints, and extract data into PyTorch-ready tensors.\n\n```python\nimport pandas as pd\nimport phaethon as ptn\nimport phaethon.units as u\n\n# Declaratively enforce physical laws on incoming data\nclass SensorSchema(ptn.Schema):\n    x_pos: u.Meter = ptn.Field(\"Position\", parse_string=True)\n    t_time: u.Second = ptn.Field(\"Time\", min=0.0, on_error=\"clip\")\n\n# Load and normalize a raw DataFrame\nmessy_df = pd.read_csv(\"sensor_telemetry.csv\")\nclean_df = SensorSchema.normalize(messy_df)\n\n# Bridge directly into PyTorch PTensors (Physics-Aware Tensors)\ndataset = SensorSchema.astensor(clean_df, requires_grad=['x_pos', 't_time'])\n\nx_sensor = dataset['x_pos'].tensor\nt_sensor = dataset['t_time'].tensor\n```\n\n### Step 2: Neural Architecture (Assembly)\nStandard 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.\n\n```python\nimport torch.nn as nn\nimport phaethon.pinns as pnn\n\nclass ShockwaveNet(nn.Module):\n    def __init__(self):\n        super().__init__()\n        self.net = nn.Sequential(\n            nn.Linear(2, 128), nn.SiLU(),\n            nn.Linear(128, 128), nn.SiLU(),\n            nn.Linear(128, 1)\n        )\n        \n    def forward(self, x_raw, t_raw):\n        # 1. Standardize inputs to base units safely\n        x_std = x_raw.asunit(u.Meter)\n        t_std = t_raw.asunit(u.Second)\n        \n        # 2. Assemble physical tensors into naked PyTorch features\n        features = pnn.assemble(x_std, t_std, dim=-1)\n        \n        # 3. Forward Pass \u0026 Resurrect Physical Identity (Velocity)\n        u_mag = self.net(features)\n        return pnn.PTensor(u_mag, unit=u.MeterPerSecond), x_std, t_std\n```\n\n### Step 3: Native Calculus \u0026 Loss Evaluation\nTrain the network using native differential calculus. Phaethon automatically synthesizes derivative units, and the `ResidualLoss` strictly ensures dimensional balance on the PDE.\n\n```python\nmodel = ShockwaveNet()\npde_loss_fn = pnn.ResidualLoss()\nnu = pnn.PTensor(0.01 / 3.14159, unit=u.SquareMeterPerSecond)\n\n# Forward pass\nu_pred, x_s, t_s = model(x_sensor, t_sensor)\n\n# Native PyTorch Calculus (Automatically synthesizes derived units)\ndu_dt = pnn.grad(u_pred, t_s, create_graph=True)\ndu_dx = pnn.grad(u_pred, x_s, create_graph=True)\nd2u_dx2 = pnn.laplace(u_pred, x_s)\n\n# Formulate the PDE Residual (Burgers' Equation)\n# If dimensions mismatch (e.g., subtracting Force from Acceleration), execution halts.\npde_residual = du_dt + (u_pred * du_dx) - (nu * d2u_dx2) \n\n# Compute Physics-Informed Penalty\nloss = pde_loss_fn(pde_residual, target=0.0)\nloss.backward()\n```\n\n---\n\n## 📦 Installation \u0026 Modularity\nPhaethon requires **Python \u003e= 3.11** and is compiled via Maturin (Rust backend). Install only the scientific stack you need to avoid environment bloat:\n\n```bash\n# Core Physics Engine Only\npip install phaethon\n\n# Data Engineering (Pandas + Rapidfuzz)\npip install 'phaethon[dataframe]'\n\n# Neural PDEs \u0026 PINNs (PyTorch)\npip install 'phaethon[torch]'\n\n# Classic Sci-ML (Scikit-learn)\npip install 'phaethon[sklearn]'\n\n# The Complete Sci-ML Ecosystem\npip install 'phaethon[all]'\n```\n\n---\n\n## 🤝 Contributing\nContributions 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.\n\nPlease read our **[CONTRIBUTING.md](CONTRIBUTING.md)** to set up your development environment, install the `[dev]` dependencies, and run the test suite.\n\n## 📜 License\nDistributed under the MIT License. See the `LICENSE` file for more information.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frannd1nt%2Fphaethon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frannd1nt%2Fphaethon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frannd1nt%2Fphaethon/lists"}