holant-tools 0.1.0__tar.gz

holant_tools-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+holant-tools
+
+Copyright (c) 2026 Edward Chalk (sapientronic.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+1. The above copyright notice and this permission notice shall be included
+   in all copies or substantial portions of the Software.
+
+2. Attribution. Any publication, presentation, derivative work, or product
+   that uses or builds on this Software must include visible attribution to
+   Edward Chalk and sapientronic.ai. The phrase "Built with holant-tools by
+   Edward Chalk (sapientronic.ai)" or equivalent is acceptable.
+
+3. The Software is provided "AS IS", without warranty of any kind, express
+   or implied, including but not limited to the warranties of merchantability,
+   fitness for a particular purpose, and noninfringement. In no event shall
+   the authors or copyright holders be liable for any claim, damages, or
+   other liability, whether in an action of contract, tort, or otherwise,
+   arising from, out of, or in connection with the Software or the use or
+   other dealings in the Software.
+
+This license is modeled on the MIT License with an explicit attribution
+clause (clause 2).

holant_tools-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: holant-tools
+Version: 0.1.0
+Summary: Decision procedures for matchgate-Holant tractability: polynomial-time SRP solver, Galluccio-Loebl Holant evaluator, hardness-candidate screening.
+Author-email: Edward Chalk <edward.chalk@sapientronic.ai>
+License: holant-tools
+        
+        Copyright (c) 2026 Edward Chalk (sapientronic.ai)
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to use,
+        copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+        the Software, and to permit persons to whom the Software is furnished to do
+        so, subject to the following conditions:
+        
+        1. The above copyright notice and this permission notice shall be included
+           in all copies or substantial portions of the Software.
+        
+        2. Attribution. Any publication, presentation, derivative work, or product
+           that uses or builds on this Software must include visible attribution to
+           Edward Chalk and sapientronic.ai. The phrase "Built with holant-tools by
+           Edward Chalk (sapientronic.ai)" or equivalent is acceptable.
+        
+        3. The Software is provided "AS IS", without warranty of any kind, express
+           or implied, including but not limited to the warranties of merchantability,
+           fitness for a particular purpose, and noninfringement. In no event shall
+           the authors or copyright holders be liable for any claim, damages, or
+           other liability, whether in an action of contract, tort, or otherwise,
+           arising from, out of, or in connection with the Software or the use or
+           other dealings in the Software.
+        
+        This license is modeled on the MIT License with an explicit attribution
+        clause (clause 2).
+        
+Project-URL: Homepage, https://github.com/pcoz/holant-tools
+Project-URL: Repository, https://github.com/pcoz/holant-tools
+Project-URL: Issues, https://github.com/pcoz/holant-tools/issues
+Keywords: holant,matchgate,holographic-algorithm,constraint-counting,tractability,complexity,cai-lu,pfaffian,srp,weighted-model-counting
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sympy>=1.10
+Dynamic: license-file
+
+# holant-tools
+
+**Decision procedures for matchgate-Holant tractability.**
+
+`holant-tools` decides, in polynomial time, whether a set of matchgate constraint functions admits a polynomial-time holographic-algorithm route — and if so, gives you the basis on which to construct it. The kernel implementation of a tractability-routing layer that could sit on top of general-purpose constraint solvers.
+
+To the author's knowledge, this is the first published runnable implementation of Cai–Lu 2011's polynomial-time Simultaneous Realizability Problem solver — a result that has stood as paper-only since 2011.
+
+## Install
+
+```bash
+pip install holant-tools
+```
+
+Requires Python ≥ 3.9 and `sympy`.
+
+## 30-second example: Cai–Lu §5.1 reproduced
+
+The canonical published example is `#_7 Pl-Rtw-Mon-3CNF` — a $\#\mathsf{P}$-complete counting problem that is tractable mod 7. Two signatures: `EQ_2 = [1, 0, 1]` (recognizer, arity 2) and `OR_3 = [0, 1, 1, 1]` (generator, arity 3).
+
+```bash
+$ holant solve examples/01_cai_lu_5_1.json --modulus 7
+SRP: FEASIBLE
+  Witness basis: u = 2, v = 3
+  Branch combination: [even, even]
+  solved over F_7 (tried 1 branch combination(s))
+```
+
+The same problem is infeasible over the algebraic closure of $\mathbf{Q}$ (no rational/algebraic basis works) — the mod-7 specificity is the "$\#_7$" in the problem name, and it falls out of the algorithm.
+
+Programmatic API:
+
+```python
+from holant_tools import from_symmetric, srp_solve
+
+sigs = [
+    from_symmetric([1, 0, 1], name="EQ_2"),
+    from_symmetric([0, 1, 1, 1], name="OR_3", kind="generator"),
+]
+result = srp_solve(sigs, modulus=7)
+print(result.feasible)   # True
+print(result.witness)    # {U: 2, V: 3}
+```
+
+## What it does
+
+Given a list of matchgate signatures, the tool answers:
+
+- Is this set of constraints jointly realizable on some basis? (Cai–Lu's Simultaneous Realizability Problem; polynomial-time decidable per their 2011 Theorem 4.1.)
+- If yes, what is the basis? (Provides the witness.)
+- Over which field — algebraic closure of $\mathbf{Q}$, or a specific finite field $\mathbf{F}_p$?
+- Is this a candidate for $\#\mathsf{P}$-hardness? (Screening: if no realising basis exists across $\overline{\mathbf{Q}}$ + multiple small primes, the matchgate / holographic-algorithm route is unavailable — a necessary condition for hardness in the Cai–Lu–Xia dichotomy framework.)
+
+## CLI
+
+```
+holant signature "[1, 0, 1]"             # Individual realizability (Cai–Lu Thm 2.5)
+holant check    sigs.json                 # Necessary-condition SRP check
+holant solve    sigs.json [--modulus p]   # Full SRP (intersection on M)
+holant hardness sigs.json [--primes ...]  # Hardness-candidate screening
+```
+
+JSON input format (`sigs.json`):
+
+```json
+[
+  {"values": [1, 0, 1],    "kind": "recognizer", "name": "EQ_2"},
+  {"values": [0, 1, 1, 1], "kind": "generator",  "name": "OR_3"}
+]
+```
+
+- `values`: signature entries by Hamming weight, length = arity + 1.
+- `kind`: `"recognizer"` or `"generator"`.
+- `name`: optional display string.
+
+See `examples/` for four worked walkthroughs (Cai–Lu §5.1, single signature, hardness-candidate short-circuit, arity-4).
+
+## Scope (v0.1)
+
+Shipped:
+
+- Symmetric matchgate signatures, **any arity**. Cai–Lu Theorem 2.5 (necessary) + Theorem 4.1 (sufficient, polynomial-time SRP).
+- Non-symmetric matchgate signatures, **arity ≤ 4**, both parity branches, with the full Grassmann–Plücker matchgate identities at arity 4.
+- Galluccio–Loebl Holant evaluator for **genus-$g$ matchgate networks** (signed Pfaffian sum over $2^{2g}$ spin structures).
+- Hardness-candidate screening across $\overline{\mathbf{Q}}$ + small finite fields.
+
+Not yet shipped (the v0.2+ roadmap):
+
+- Non-symmetric arity ≥ 5.
+- Multi-chart coverage of the basis manifold $\mathcal{M}$ (currently a single open chart $u \ne v$).
+- Holant$^*$ / Holant$^c$ variants (auxiliary signatures available).
+- Translation layers from SAT / CSP / MILP common formats.
+- Automatic Kasteleyn-orientation construction from rotation-system input.
+
+## Why is this useful?
+
+Where Holant-tractable structure shows up in practice:
+
+- **Counting #SAT instances with planar matchgate structure** — preprocessing layer that detects when a problem admits Valiant's holographic-algorithm route.
+- **Classical simulation of matchgate quantum circuits** — Valiant 2002; classical simulability of free-fermion quantum dynamics.
+- **Statistical mechanics on planar / bounded-genus lattices** — dimer counting, Ising and Potts models, free-fermion lattice models.
+- **Counting perfect matchings on planar and bounded-genus graphs** — the FKT theorem and its Galluccio–Loebl extension are the canonical algorithms.
+- **Designing tractable counting CSP variants** — the framework lets you check, ahead of time, whether your designed problem class lies in the polynomial-time matchgate corner.
+
+See `holant-tools-applications.md` for the full discussion of where matchgate tractability genuinely applies, where it could apply with further development, and where it honestly doesn't.
+
+## Math
+
+`holant-tools-theory.md` contains the theory: matchgate signatures, the Cai–Lu basis manifold $\mathcal{M} = \mathrm{GL}_2/\!\sim$, the parity-pullback construction in a chart of $\mathcal{M}$, the Grassmann–Plücker matchgate identities for arity 4 (both parity branches, the latter via augmented-Pfaffian), and the Galluccio–Loebl Holant formula for genus-$g$ networks.
+
+## Tests
+
+```bash
+git clone https://github.com/pcoz/holant-tools.git
+cd holant-tools
+pip install -e .
+python tests/test_holant_tools.py
+# All v0.1 + v0.2 + v0.3-alpha + v0.3-beta + v0.3-beta-followon + hardness tests pass.
+```
+
+47 tests across all subsystems.
+
+## License
+
+`LICENSE` — modeled on the MIT License with an explicit attribution clause. Use is free; attribution to *Edward Chalk (sapientronic.ai)* is required for publications, presentations, derivative works, and products that build on this software.
+
+## References
+
+- [CL11] J.-Y. Cai, P. Lu. *Holographic Algorithms: From Art to Science.* J. Comput. Syst. Sci. **77** (1) (2011) 41–61.
+- [Val08] L. G. Valiant. *Holographic Algorithms.* SIAM J. Comput. **37** (5) (2008) 1565–1594.
+- [GL99] A. Galluccio, M. Loebl. *On the theory of Pfaffian orientations.* J. Algebraic Combin. **9** (1999).
+- [Tes00] G. Tesler. *Matchings in graphs on non-orientable surfaces.* J. Combin. Theory B **78** (2000).
+- [Nor08] S. Norine. *Matching structure and Pfaffian orientations of graphs.* PhD thesis, Georgia Tech, 2005.

holant_tools-0.1.0/README.md

@@ -0,0 +1,133 @@
+# holant-tools
+
+**Decision procedures for matchgate-Holant tractability.**
+
+`holant-tools` decides, in polynomial time, whether a set of matchgate constraint functions admits a polynomial-time holographic-algorithm route — and if so, gives you the basis on which to construct it. The kernel implementation of a tractability-routing layer that could sit on top of general-purpose constraint solvers.
+
+To the author's knowledge, this is the first published runnable implementation of Cai–Lu 2011's polynomial-time Simultaneous Realizability Problem solver — a result that has stood as paper-only since 2011.
+
+## Install
+
+```bash
+pip install holant-tools
+```
+
+Requires Python ≥ 3.9 and `sympy`.
+
+## 30-second example: Cai–Lu §5.1 reproduced
+
+The canonical published example is `#_7 Pl-Rtw-Mon-3CNF` — a $\#\mathsf{P}$-complete counting problem that is tractable mod 7. Two signatures: `EQ_2 = [1, 0, 1]` (recognizer, arity 2) and `OR_3 = [0, 1, 1, 1]` (generator, arity 3).
+
+```bash
+$ holant solve examples/01_cai_lu_5_1.json --modulus 7
+SRP: FEASIBLE
+  Witness basis: u = 2, v = 3
+  Branch combination: [even, even]
+  solved over F_7 (tried 1 branch combination(s))
+```
+
+The same problem is infeasible over the algebraic closure of $\mathbf{Q}$ (no rational/algebraic basis works) — the mod-7 specificity is the "$\#_7$" in the problem name, and it falls out of the algorithm.
+
+Programmatic API:
+
+```python
+from holant_tools import from_symmetric, srp_solve
+
+sigs = [
+    from_symmetric([1, 0, 1], name="EQ_2"),
+    from_symmetric([0, 1, 1, 1], name="OR_3", kind="generator"),
+]
+result = srp_solve(sigs, modulus=7)
+print(result.feasible)   # True
+print(result.witness)    # {U: 2, V: 3}
+```
+
+## What it does
+
+Given a list of matchgate signatures, the tool answers:
+
+- Is this set of constraints jointly realizable on some basis? (Cai–Lu's Simultaneous Realizability Problem; polynomial-time decidable per their 2011 Theorem 4.1.)
+- If yes, what is the basis? (Provides the witness.)
+- Over which field — algebraic closure of $\mathbf{Q}$, or a specific finite field $\mathbf{F}_p$?
+- Is this a candidate for $\#\mathsf{P}$-hardness? (Screening: if no realising basis exists across $\overline{\mathbf{Q}}$ + multiple small primes, the matchgate / holographic-algorithm route is unavailable — a necessary condition for hardness in the Cai–Lu–Xia dichotomy framework.)
+
+## CLI
+
+```
+holant signature "[1, 0, 1]"             # Individual realizability (Cai–Lu Thm 2.5)
+holant check    sigs.json                 # Necessary-condition SRP check
+holant solve    sigs.json [--modulus p]   # Full SRP (intersection on M)
+holant hardness sigs.json [--primes ...]  # Hardness-candidate screening
+```
+
+JSON input format (`sigs.json`):
+
+```json
+[
+  {"values": [1, 0, 1],    "kind": "recognizer", "name": "EQ_2"},
+  {"values": [0, 1, 1, 1], "kind": "generator",  "name": "OR_3"}
+]
+```
+
+- `values`: signature entries by Hamming weight, length = arity + 1.
+- `kind`: `"recognizer"` or `"generator"`.
+- `name`: optional display string.
+
+See `examples/` for four worked walkthroughs (Cai–Lu §5.1, single signature, hardness-candidate short-circuit, arity-4).
+
+## Scope (v0.1)
+
+Shipped:
+
+- Symmetric matchgate signatures, **any arity**. Cai–Lu Theorem 2.5 (necessary) + Theorem 4.1 (sufficient, polynomial-time SRP).
+- Non-symmetric matchgate signatures, **arity ≤ 4**, both parity branches, with the full Grassmann–Plücker matchgate identities at arity 4.
+- Galluccio–Loebl Holant evaluator for **genus-$g$ matchgate networks** (signed Pfaffian sum over $2^{2g}$ spin structures).
+- Hardness-candidate screening across $\overline{\mathbf{Q}}$ + small finite fields.
+
+Not yet shipped (the v0.2+ roadmap):
+
+- Non-symmetric arity ≥ 5.
+- Multi-chart coverage of the basis manifold $\mathcal{M}$ (currently a single open chart $u \ne v$).
+- Holant$^*$ / Holant$^c$ variants (auxiliary signatures available).
+- Translation layers from SAT / CSP / MILP common formats.
+- Automatic Kasteleyn-orientation construction from rotation-system input.
+
+## Why is this useful?
+
+Where Holant-tractable structure shows up in practice:
+
+- **Counting #SAT instances with planar matchgate structure** — preprocessing layer that detects when a problem admits Valiant's holographic-algorithm route.
+- **Classical simulation of matchgate quantum circuits** — Valiant 2002; classical simulability of free-fermion quantum dynamics.
+- **Statistical mechanics on planar / bounded-genus lattices** — dimer counting, Ising and Potts models, free-fermion lattice models.
+- **Counting perfect matchings on planar and bounded-genus graphs** — the FKT theorem and its Galluccio–Loebl extension are the canonical algorithms.
+- **Designing tractable counting CSP variants** — the framework lets you check, ahead of time, whether your designed problem class lies in the polynomial-time matchgate corner.
+
+See `holant-tools-applications.md` for the full discussion of where matchgate tractability genuinely applies, where it could apply with further development, and where it honestly doesn't.
+
+## Math
+
+`holant-tools-theory.md` contains the theory: matchgate signatures, the Cai–Lu basis manifold $\mathcal{M} = \mathrm{GL}_2/\!\sim$, the parity-pullback construction in a chart of $\mathcal{M}$, the Grassmann–Plücker matchgate identities for arity 4 (both parity branches, the latter via augmented-Pfaffian), and the Galluccio–Loebl Holant formula for genus-$g$ networks.
+
+## Tests
+
+```bash
+git clone https://github.com/pcoz/holant-tools.git
+cd holant-tools
+pip install -e .
+python tests/test_holant_tools.py
+# All v0.1 + v0.2 + v0.3-alpha + v0.3-beta + v0.3-beta-followon + hardness tests pass.
+```
+
+47 tests across all subsystems.
+
+## License
+
+`LICENSE` — modeled on the MIT License with an explicit attribution clause. Use is free; attribution to *Edward Chalk (sapientronic.ai)* is required for publications, presentations, derivative works, and products that build on this software.
+
+## References
+
+- [CL11] J.-Y. Cai, P. Lu. *Holographic Algorithms: From Art to Science.* J. Comput. Syst. Sci. **77** (1) (2011) 41–61.
+- [Val08] L. G. Valiant. *Holographic Algorithms.* SIAM J. Comput. **37** (5) (2008) 1565–1594.
+- [GL99] A. Galluccio, M. Loebl. *On the theory of Pfaffian orientations.* J. Algebraic Combin. **9** (1999).
+- [Tes00] G. Tesler. *Matchings in graphs on non-orientable surfaces.* J. Combin. Theory B **78** (2000).
+- [Nor08] S. Norine. *Matching structure and Pfaffian orientations of graphs.* PhD thesis, Georgia Tech, 2005.

holant_tools-0.1.0/holant_tools/__init__.py

@@ -0,0 +1,210 @@
+"""holant-tools: decision procedures for matchgate-Holant tractability.
+
+This package implements a polynomial-time decision procedure for whether a set
+of matchgate signatures admits a polynomial-time holographic-algorithm route
+(Cai-Lu 2011's Simultaneous Realizability Problem, plus extensions). It is
+designed as the analysis kernel of a tractability-routing layer that could
+sit on top of general-purpose constraint solvers; the kernel itself is the
+v0.1 release.
+
+Quick start
+-----------
+
+    >>> from holant_tools import from_symmetric, srp_solve
+    >>> sigs = [from_symmetric([1, 0, 1], "EQ_2"),
+    ...         from_symmetric([0, 1, 1, 1], "OR_3", kind="generator")]
+    >>> srp_solve(sigs, modulus=7)
+    SRPResult(feasible=True, witness={u: 2, v: 3}, ...)
+
+The above reproduces Cai-Lu 2011 sec 5.1's `#_7 Pl-Rtw-Mon-3CNF` decision:
+SRP is feasible over the finite field F_7 with witness basis (u, v) = (2, 3).
+The mod-7 phenomenon falls out from the algorithm; it is not configured.
+
+Public API
+----------
+
+Constructors:
+    from_symmetric(values, name="", kind="recognizer")
+    from_non_symmetric(values, arity, name="", kind="recognizer")
+
+Decision procedures:
+    srp_solve(signatures, modulus=None)          # full SRP
+    hardness_candidate(signatures, primes=...)   # screen for hardness candidates
+    is_realizable_somewhere(sig)                 # Cai-Lu Theorem 2.5 (individual)
+    classify_form(sig)                           # Cai-Lu Form 1/2/3 classification
+
+Lower-level building blocks:
+    realizability_subvariety(sig)                # symmetric
+    realizability_subvariety_non_symmetric(sig)  # 2^n-valued
+    intersect_subvarieties(subvarieties, modulus=None)
+
+Holant evaluation (genus-g matchgate networks):
+    holant_planar(M)                             # FKT planar Pfaffian
+    holant_genus_g(matrices, genus)              # Galluccio-Loebl signed sum
+
+CLI: `holant solve`, `holant check`, `holant hardness`, `holant signature`.
+
+Scope
+-----
+
+Shipped in v0.1:
+- Symmetric matchgate signatures of any arity (Cai-Lu Theorem 2.5 + 4.1).
+- Non-symmetric matchgate signatures of arity <= 4, both parity branches,
+  with the full Grassmann-Plucker matchgate identities at arity 4.
+- Galluccio-Loebl Holant evaluator for genus-g matchgate networks.
+- Hardness-candidate screening across Q-bar + small finite fields.
+- Single chart of the basis manifold M = GL_2/~.
+
+Not yet shipped (v0.2+ roadmap):
+- Non-symmetric arity >= 5 (general Grassmann-Plucker; multiple independent
+  matchgate identities per arity).
+- Multi-chart coverage of M (second chart for bases with the first row of
+  the basis matrix having a zero entry).
+- Holant* and Holant^c variants (auxiliary signature seeding).
+- Translation layers from SAT / CSP / MILP common formats to Holant
+  signatures.
+- Automatic Kasteleyn-orientation construction from rotation-system input.
+
+See `paper.md` for the theory and `APPLICATIONS.md` for where Holant
+problems show up in practice.
+
+References
+----------
+
+[CL11] J.-Y. Cai, P. Lu. *Holographic Algorithms: From Art to Science.*
+       J. Comput. Syst. Sci. 77 (1) (2011) 41-61.
+[Val08] L. G. Valiant. *Holographic Algorithms.* SIAM J. Comput. 37 (5)
+        (2008) 1565-1594.
+[GL99] A. Galluccio, M. Loebl. *On the theory of Pfaffian orientations.*
+       J. Algebraic Combin. 9 (1999).
+"""
+
+__version__ = "0.1.0"
+
+from .signatures import (
+    Signature,
+    Recurrence,
+    find_recurrence,
+    is_realizable_somewhere,
+    srp_necessary_check,
+)
+from .realizability import (
+    Form,
+    FormClassification,
+    Subvariety,
+    classify_form,
+    realizability_subvariety,
+    U,
+    V,
+)
+from .intersection import (
+    IntersectionResult,
+    intersect_subvarieties,
+)
+from .srp_solver import (
+    SRPResult,
+    srp_solve,
+)
+from .holant import (
+    pfaffian,
+    arf_invariant,
+    arf_invariant_genus_1,
+    spin_structures_genus,
+    holant_genus_g,
+    holant_planar,
+)
+from .non_symmetric import (
+    NonSymmetricSignature,
+    pullback_tau_non_symmetric,
+    realizability_subvariety_non_symmetric,
+    matchgate_identity_arity_4_even,
+    matchgate_identity_arity_4_odd,
+)
+from .hardness import (
+    HardnessReport,
+    hardness_candidate,
+)
+from . import examples
+
+
+# ---------------------------------------------------------------------------
+# Ergonomic constructors (the recommended entry points for new users)
+# ---------------------------------------------------------------------------
+
+def from_symmetric(values, name="", kind="recognizer"):
+    """Construct a symmetric matchgate Signature.
+
+    Args:
+        values: iterable of n+1 field values, indexed by Hamming weight.
+            For arity n, supply n+1 entries.
+        name: optional display name for the signature.
+        kind: "recognizer" (default) or "generator".
+
+    Example:
+        >>> sig = from_symmetric([1, 0, 1], name="EQ_2")
+        >>> sig
+        Signature([1, 0, 1], recognizer, arity 2, name='EQ_2')
+
+    Equivalent to `Signature(values=tuple(values), kind=kind, name=name)`.
+    """
+    return Signature(values=tuple(values), kind=kind, name=name)
+
+
+def from_non_symmetric(values, arity, name="", kind="recognizer"):
+    """Construct a non-symmetric matchgate NonSymmetricSignature.
+
+    Args:
+        values: dict mapping bit-string tuples of length `arity` to field values.
+            Missing entries default to 0.
+        arity: matchgate arity (number of wires).
+        name: optional display name.
+        kind: "recognizer" (default) or "generator".
+
+    Example:
+        >>> # Non-symmetric arity-2: tau_{01} = 1, tau_{10} = -1, rest 0.
+        >>> sig = from_non_symmetric({(0, 1): 1, (1, 0): -1}, arity=2, name="asym")
+    """
+    return NonSymmetricSignature(values=dict(values), arity=arity, kind=kind, name=name)
+
+
+__all__ = [
+    "__version__",
+    # Ergonomic constructors
+    "from_symmetric",
+    "from_non_symmetric",
+    # Dataclasses + result types
+    "Signature",
+    "NonSymmetricSignature",
+    "Recurrence",
+    "Form",
+    "FormClassification",
+    "Subvariety",
+    "IntersectionResult",
+    "SRPResult",
+    "HardnessReport",
+    "U",
+    "V",
+    # Decision procedures
+    "srp_solve",
+    "hardness_candidate",
+    "is_realizable_somewhere",
+    "classify_form",
+    "find_recurrence",
+    "srp_necessary_check",
+    # Lower-level building blocks
+    "realizability_subvariety",
+    "realizability_subvariety_non_symmetric",
+    "intersect_subvarieties",
+    "pullback_tau_non_symmetric",
+    "matchgate_identity_arity_4_even",
+    "matchgate_identity_arity_4_odd",
+    # Holant evaluation
+    "pfaffian",
+    "arf_invariant",
+    "arf_invariant_genus_1",
+    "spin_structures_genus",
+    "holant_genus_g",
+    "holant_planar",
+    # Examples module
+    "examples",
+]