neural_attractor: tighten the README section and module docstring to a plain technical description (energy form, gate gadgets, clamped-subset modes, exactness and NP-hardness of the search modes)

README.md

@@ -457,40 +457,38 @@ noise margins. The processor is no longer *described by* a neural network; it
 
 ---
 
-## neural_attractor — computation as relaxation, run in any direction
-
-`neural_matrix8` still runs a program forward. `neural_attractor` drops the
-last of the von Neumann structure: no program counter, no clock, no forward-only
-execution. A computation is compiled into an energy function `E(s)` whose global
-minimum, with the known wires clamped, is the unique consistent assignment of the
-whole circuit. The program is the coupling matrix `Q` (with linear terms `L`);
-running is relaxation toward the minimum, and the relaxation update is itself a
-threshold neuron, `s_i <- H(-(L[i] + sum_j Q[i,j] s_j))`, so the machine is the
-same substrate, one weight matrix with no controller.
-
-Each gate contributes a gadget that is non-negative and equals zero exactly when
-the gate relation holds (binary variables): `AND` is `3z + xy - 2xz - 2yz`, `OR`
-is `x + y + z + xy - 2xz - 2yz`, `NOT` is `1 - x - z + 2xz`. Those are universal,
-so any circuit compiles and universality is a theorem about the gadgets rather
-than a hope about the dynamics. Forward evaluation is exact: clamp the inputs and
-propagate through the gate relations in topological order, landing on the
-energy-0 fixed point; the canonical form anneals the whole network to the same
-minimum.
-
-What no program counter can do falls out of clamping a different subset of wires:
-
-- **Run circuits backward.** Clamp a multiplier's product and relax over the
-  inputs, and the machine returns factors. The shipped `neural_attractor` is an
-  8x8 multiplier compiled to couplings (913 wires); it multiplies forward
-  bit-exactly and, run in reverse, factors (35 = 5 x 7, 143 = 11 x 13).
-- **Solve.** Clamp a CNF formula's output to 1 and the minimum is a satisfying
-  assignment, so the same object is a circuit evaluator and a SAT solver.
-
-The forward direction is exact and cheap; the backward and open-constraint modes
-are genuine annealed search, and that hardness is the point. Factoring is hard,
-and an exact integer-ternary substrate with structured gadgets, where the ground
-state sits at energy 0 by construction rather than being approximated by an
-analog annealer, is the interesting place to attack it.
+## neural_attractor — computation as energy relaxation
+
+An energy-based threshold network with no program counter, clock, or instruction
+stream. A Boolean circuit compiles to a quadratic energy
+`E(s) = sum_i L[i] s_i + sum_{i<j} Q[i,j] s_i s_j` over binary wire variables such
+that, with any chosen subset of wires clamped, the circuit's consistent
+assignment is the global minimum. The coupling matrix `Q` and linear terms `L`
+are the program; execution is relaxation toward the minimum. The relaxation step
+is a threshold neuron over the same integer weights,
+`s_i <- H(-(L[i] + sum_j Q[i,j] s_j))`.
+
+Each gate adds a gadget that is non-negative and zero exactly on its truth table:
+`AND` `3z + xy - 2xz - 2yz`, `OR` `x + y + z + xy - 2xz - 2yz`, `NOT`
+`1 - x - z + 2xz`. These are functionally complete, so any circuit compiles and
+its evaluation is the ground state by construction. The choice of clamped wires
+selects the mode:
+
+- **Forward evaluation.** Clamp the inputs; propagating the gate relations in
+  topological order reaches the energy-0 fixed point. Checked bit-exact against
+  integer references for ripple-carry adders and array multipliers.
+- **Inversion.** Clamp the outputs and relax over the free wires. The shipped
+  `neural_attractor` compiles an 8x8 array multiplier to 913 wires; it multiplies
+  forward bit-exactly, and clamping the product recovers factors
+  (35 = 5 x 7, 143 = 11 x 13).
+- **Satisfiability.** Clamp a CNF's output wire to 1; a ground state is a
+  satisfying assignment.
+
+Forward evaluation is exact and linear in gate count. Inversion and
+open-constraint solving are ground-state search over the free wires, annealed.
+The target energy is 0 by construction, so a zero-energy state certifies a
+correct assignment, but reaching it is NP-hard in general and not guaranteed
+within a fixed annealing schedule.
 
 ```bash
 python tools/build_attractor.py      # compile a multiplier to variants/neural_attractor.safetensors

src/attractor.py

@@ -1,41 +1,25 @@
-"""Attractor computer: computation as relaxation of a threshold network.
+"""Attractor computer: an energy-based threshold network.
 
-Every other machine in this repository is a stored-program computer whose gates
-happen to be threshold neurons: it has a program counter, a fetch, and an
-instruction stream. This one has none of those. A computation is compiled into
-an energy function E(s) whose global minimum, with the known wires clamped, is
-the unique consistent assignment of the whole circuit. The "program" is the
-coupling matrix Q (with linear terms L); running is relaxation toward the
-minimum. The relaxation update is itself a threshold neuron,
-
-    s_i <- H( -( L[i] + sum_j Q[i,j] s_j ) ),
-
-so the machine is the same substrate as the rest of the repo, one weight matrix
-iterated to a fixed point, with no controller.
-
-Each gate contributes a gadget that is >= 0 and equals 0 exactly when the gate
-relation holds (binary variables in {0,1}):
+A Boolean circuit is compiled to a quadratic pseudo-Boolean energy
+E(s) = sum_i L[i] s_i + sum_{i<j} Q[i,j] s_i s_j over binary wire variables, with
+per-gate gadgets that are non-negative and zero exactly on the gate truth table:
 
     AND z=x&y : 3z + xy - 2xz - 2yz
     OR  z=x|y : x + y + z + xy - 2xz - 2yz
     NOT z=~x  : 1 - x - z + 2xz
 
-AND/OR/NOT are universal, so any circuit compiles, and universality of the
-machine is a theorem about the gadgets rather than a hope about the dynamics.
-
-Two things a program counter cannot do fall out of this:
-
-  * Evaluate in any direction. Clamp inputs and relax to read outputs; or clamp
-    outputs and relax to recover inputs. Running a multiplier backward is
-    integer factoring; running any predicate backward is search.
-  * Solve. Clamp a formula's output to 1 and the minimum is a satisfying
-    assignment, so the same object is a circuit evaluator and a SAT solver.
-
-Forward evaluation (inputs clamped) is exact and cheap: propagate through the
-gate relations in topological order, which lands on the energy-0 fixed point.
-Backward and open-constraint modes are genuine search, annealed over the free
-wires; that hardness is the point (factoring is hard), and an exact integer
-substrate with structured gadgets is the interesting place to attack it.
+AND/OR/NOT are functionally complete, so any circuit compiles and its consistent
+assignment is the global minimum. There is no program counter or clock: the
+coupling matrix Q (with linear terms L) is the program, and execution is
+relaxation toward the minimum. The relaxation step is a threshold neuron over the
+same integer weights, s_i <- H(-(L[i] + sum_j Q[i,j] s_j)).
+
+The clamped wire subset selects the mode. Clamp inputs to evaluate forward (exact
+via topological propagation to the energy-0 fixed point); clamp outputs to invert
+(a multiplier run backward returns factors); clamp a CNF output to 1 to solve
+SAT. Forward evaluation is exact and linear in gate count; inversion and
+open-constraint solving are annealed ground-state search, NP-hard in general,
+with a zero-energy state certifying a correct assignment.
 """
 from __future__ import annotations
 import math