diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 0000000..7a2dddf --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,31 @@ +cff-version: 1.2.0 +message: "If you use this software, please cite it as below." +title: "conformal-toolkit: Symbolic and Discrete Conformal Geometry for SageMath and PyTorch" +abstract: >- + A Python toolkit for computing conformal invariants both symbolically + (exact formulas via SageMath/SageManifolds) and discretely (per-vertex mesh + features via PyTorch): tractor calculus, GJMS operators, Q-curvature, the + conformal fundamental forms and Willmore densities of Blitz-Gover-Waldron, + Carroll geometry, and Fefferman-Graham holographic data. The hypersurface + module implements the conformal hypersurface invariant theory of Samuel Blitz, + A. Rod Gover, and Andrew Waldron. +type: software +authors: + - family-names: Rihm + given-names: Eric + email: admin@strata-networks.com +repository-code: "https://github.com/ericrihm/conformal-toolkit" +url: "https://github.com/ericrihm/conformal-toolkit" +license: MIT +version: 0.1.1 +date-released: "2026-05-31" +keywords: + - conformal geometry + - differential geometry + - tractor calculus + - Q-curvature + - GJMS operators + - Willmore energy + - geometric deep learning + - SageMath + - PyTorch diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..2b090b8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,55 @@ +# Contributing + +Thanks for your interest — corrections and contributions are genuinely welcome. +This project values being *correctable*: if you find an error in the math, the +code, the docs, or in [`ERRATA.md`](ERRATA.md) itself, that's the system working. + +## Reporting a math/correctness error (errata) + +This is the highest-value contribution. Follow the same method the project's own +audit used (see [`ERRATA.md` → "How we caught them"](ERRATA.md)): + +1. Open an issue titled `Errata: `. +2. Give the counter-evidence as concretely as possible: + - a **specific geometry** (a sphere radius, a flat patch, an explicit metric) + on which the claim returns the wrong number; or + - a **conformal-weight argument** showing the terms can't match. + A failing check on a named anchor metric is the gold standard. +3. Propose the corrected formula, **stating your normalization convention** + (Branson vs. analyst signs differ — many conformal-geometry "errors" are + convention clashes), with a reference if you have one. +4. If you can, add a regression test pinning the right value on the anchor — + *verified-on-an-anchor beats argued-in-prose.* + +Open mathematical problems where help is explicitly wanted are listed at the end +of [`ERRATA.md`](ERRATA.md) (e.g. the complete weight-4 hypersurface invariant +basis, the Fialkow/Weyl terms in `L₂`, the full extrinsic `Q₄`). + +## Development & tests + +The suite runs on two independent tracks (see the README section +*"How it's tested"*): + +```bash +# Track B — discrete (PyTorch only, no SageMath needed): +pip install -e ".[dev,ml]" +pytest tests/test_discrete/ tests/test_features/ -v + +# Track A — symbolic (needs SageMath 10.x): +./sage-run.sh test # auto-detects native micromamba or the Sage Docker image +# or target specific modules: +./sage-run.sh pytest tests/test_core/ -v +``` + +Both tracks run automatically on every push and pull request via GitHub Actions +([`.github/workflows/test.yml`](.github/workflows/test.yml)) — please make sure +they're green. If you add or correct a formula, add a regression anchor (a known +closed-form value on a concrete geometry) alongside it; see +`tests/test_discrete/test_errata_anchors.py` for the pattern. + +## Conventions + +- Match the surrounding code style; keep changes focused. +- Tag any in-code note about a known limitation or correction with a stable + `# ERRATA ` reference so it stays traceable to the errata log. +- By contributing you agree your contributions are licensed under the MIT License. diff --git a/ERRATA.md b/ERRATA.md index 08289d1..09c2769 100644 --- a/ERRATA.md +++ b/ERRATA.md @@ -173,8 +173,12 @@ below. - **Claimed:** `count_invariants(4, ambient_dim=5) = 4` with basis `{|L₂|², tr(L₁⁴), W·L₁, |W|²}`, presented as the complete independent set. - **Why it's wrong:** the algebraic quartic `(|L₁|²)²` is **independent** of - `tr(L₁⁴)` for `n≥4` (their eigenvalue difference is `4abc(a+b+c) ≠ 0`) yet is - entirely absent. A complete *pointwise* weight-4 classification also needs the + `tr(L₁⁴)`: in eigenvalues `λᵢ` of `L₁`, their difference is + `(Σλᵢ²)² − Σλᵢ⁴ = 2·Σ_{i= 4 (their difference is 4abc(a+b+c) - in eigenvalues, generically nonzero); and + distinct from tr(L_1^4): in eigenvalues their difference is + (sum lam_i^2)^2 - sum lam_i^4 = 2 * sum_{i 0 + whenever L_1 has >= 2 nonzero principal curvatures (e.g. trace-free + eigenvalues (1,2,-3) give 196 vs 98); and * it omits the tangential-derivative invariants (e.g. |nabla_bar L_1|^2 / L_1 . Delta_bar L_1, |div L_1|^2) and the curvature coupling J_bar |L_1|^2 that a complete pointwise weight-4 classification carries. diff --git a/docs/outreach/blitz-email-draft.md b/docs/outreach/blitz-email-draft.md index 9e3c4d3..6a4f6e4 100644 --- a/docs/outreach/blitz-email-draft.md +++ b/docs/outreach/blitz-email-draft.md @@ -14,7 +14,7 @@ I'm Eric Rihm, a software engineer working at the intersection of differential g 2. **Research paper** -- Extend the classification computationally to higher-order L_k and use the toolkit to discover new identities or verify conjectured ones. The software can search spaces that are infeasible by hand. 3. **ML/applications paper** -- I've also built a pipeline that uses conformal invariants as features for graph neural networks, applied to shape analysis. This is a novel bridge between conformal geometry and geometric deep learning -- could be a good fit for an ICML or NeurIPS workshop. -The repo is public with 125 tests and 6 example notebooks: +The repo is public with 160 tests and 6 example notebooks: https://github.com/ericrihm/conformal-toolkit Notebook 02 directly demonstrates your classification and would be the best place to start. diff --git a/pyproject.toml b/pyproject.toml index a0fdb9f..0d68383 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "conformal-toolkit" -version = "0.1.0" +version = "0.1.1" description = "Computational conformal geometry and conformal invariants for geometric deep learning" readme = "README.md" license = "MIT"