{"id":49882186,"url":"https://github.com/helixprojectai-code/helix-trefoil-loss","last_synced_at":"2026-05-15T15:35:08.812Z","repository":{"id":354353380,"uuid":"1222680704","full_name":"helixprojectai-code/helix-trefoil-loss","owner":"helixprojectai-code","description":"A PyTorch topological regularizer based on the Helix-TTD Constitutional Hamiltonian. Enforces phase-locked AI alignment via trefoil knot invariants to suppress drift and barren plateaus.","archived":false,"fork":false,"pushed_at":"2026-04-28T07:25:27.000Z","size":304,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-28T08:32:11.243Z","etag":null,"topics":["ai-alignment","constitutional-ai","helix-framework","loss-functions","machine-learning","pytorch","quantum-optimization","topological-physics"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/helixprojectai-code.png","metadata":{"files":{"readme":"README.md","changelog":null,"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":"2026-04-27T15:48:15.000Z","updated_at":"2026-04-28T07:25:32.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/helixprojectai-code/helix-trefoil-loss","commit_stats":null,"previous_names":["helixprojectai-code/helix-trefoil-loss"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/helixprojectai-code/helix-trefoil-loss","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helixprojectai-code%2Fhelix-trefoil-loss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helixprojectai-code%2Fhelix-trefoil-loss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helixprojectai-code%2Fhelix-trefoil-loss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helixprojectai-code%2Fhelix-trefoil-loss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/helixprojectai-code","download_url":"https://codeload.github.com/helixprojectai-code/helix-trefoil-loss/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/helixprojectai-code%2Fhelix-trefoil-loss/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33071332,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-15T11:35:32.926Z","status":"ssl_error","status_checked_at":"2026-05-15T11:35:31.362Z","response_time":103,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["ai-alignment","constitutional-ai","helix-framework","loss-functions","machine-learning","pytorch","quantum-optimization","topological-physics"],"created_at":"2026-05-15T15:35:03.126Z","updated_at":"2026-05-15T15:35:08.803Z","avatar_url":"https://github.com/helixprojectai-code.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Trefoil Loss Function\n\n![CI](https://github.com/helixprojectai-code/helix-trefoil-loss/actions/workflows/python-ci.yml/badge.svg) ![License](https://img.shields.io/badge/License-Apache%202.0%20(Duck%20Clause)-blue.svg) ![Grammar](https://img.shields.io/badge/Grammar-Helix%20TTD%20v1.0-orange.svg) ![Attractor](https://img.shields.io/badge/Phase--Lock-%CE%B3%3D1%2F3-success.svg)\n\n![Bess Knott](bess-knott.jpg)\n\n---\n\n## 1. The Theory: Physics as a Loss Function\n\nThe `TrefoilLoss` function is a profound departure from traditional AI optimization. Instead of driving a neural network to blindly hunt for a minimum error state using stochastic gradient descent (which often leads to chaotic feature hallucination or barren plateaus), `TrefoilLoss` enforces **structural shape over motion**.\n\nRooted in the constitutional physics of the Helix-TTD framework, it treats the weight matrix of an AI as a dynamic topology. The loss function actively penalizes any drift away from a mathematically stable topological attractor: the **Trefoil Knot ($3_1$)**. \n\nBy demanding the system lock to a unitary phase constraint of **$\\gamma = 1/3$**, the loss function ensures that as the AI learns, it remains structurally sound, predictable, and constitutionally governed. The AI does not wander; it is tethered to geometry.\n\n## 2. The Omm Postulate: Recursion All The Way Through Shape\n\nIf the macroscopic shape of the loss function is governed by the Trefoil knot, what happens at the microscopic limit of the neural weights? \n\nThe **Omm Postulate** dictates that true topological governance must be fractal. When the phase-locking constraint ($\\gamma = 1/3$) and the knot winding number ($w=3$) are applied recursively down to infinite depth, the resulting wave equation is precisely the **Weierstrass Function**:\n\n$$ \\Psi_{\\Omega}(x) = \\sum_{n=0}^{\\infty} \\left(\\frac{1}{3}\\right)^n \\cos(3^n \\pi x) $$\n\nThis means the `TrefoilLoss` function enforces a fractal geometry that is *continuous everywhere but differentiable nowhere*. The shape of the knot is present at the macroscopic architectural level exactly as it is at the deepest, microscopic level of individual tensor perturbations. The governance goes all the way down. (See `/theory/omm_recursion/` for the mathematical proofs).\n\n## 3. Usage \u0026 Implementation\n\nThe `TrefoilLoss` is designed to wrap around your standard PyTorch loss functions (like CrossEntropy or MSE) and act as a stabilizing governor.\n\n```python\nimport torch\nfrom trefoil_loss import TrefoilLoss\n\n# 1. Initialize the constraint \n# target_gamma: The constitutional phase-lock invariant (1/3)\n# protection_factor: Knot crossing density (Default: 13-crossing shield)\ncriterion = TrefoilLoss(target_gamma=1/3, protection_factor=13)\n\n# 2. During your training loop:\n# Calculate your standard gradient descent loss\nbase_loss = standard_criterion(outputs, labels)\n\n# Pass it through the Trefoil Governor\n# The current_gamma tracks the current trace/drift of the weight matrix\ntotal_loss = criterion(base_loss, current_gamma=torch.tensor(1/3))\n\n# 3. Backpropagate the governed loss\ntotal_loss.backward()\n```\n\n## 4. How to Read the Results\n\nWhen utilizing the `TrefoilLoss` function, you will observe distinct behavior in your training telemetry compared to standard SGD:\n\n*   **Loss Curve Smoothing:** Instead of chaotic spikes and dips, the loss curve will exhibit periodic, predictable dampening. This is the \"Arnold Tongue\" synchronization effect taking hold.\n*   **The $\\gamma$ Telemetry:** If the system is healthy, the observed $\\gamma$ metric of the network will pull cleanly towards $0.3333$. \n*   **Protection Factor Scaling:** As you increase the `protection_factor` (e.g., from 7 to 13), the simulation overhead required for stochastic noise to break the shape grows exponentially. Higher protection factors yield slower, but vastly more stable and robust convergence.\n*   **Drift Violations:** If the internal drift of the weight matrix exceeds the constitutional bounds, the loss function acts as a physical circuit breaker, dramatically spiking the loss to force the gradients back into the topological bounds. \n\n---\n*Motion without shape is noise. Code follows shape, not the other way around.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhelixprojectai-code%2Fhelix-trefoil-loss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhelixprojectai-code%2Fhelix-trefoil-loss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhelixprojectai-code%2Fhelix-trefoil-loss/lists"}