# Solver Notes

## Formula Notes

The training formulas are Brent-equation encodings for 3x3 matrix
multiplication over GF(2).  The visible structure is comment-independent:
binary/ternary triples encode `x <-> a AND b`, and 8 four-literal clauses
encode `x <-> a XOR b XOR c`.  The four-clause count is
`8 * 729 * ((r - 1) / 2)`, giving the Brent rank parameter `r`.

The unstreamlined instances have 729 unit clauses for the target tensor
coefficients.  Streamlined instances add many units and simplify some gates,
but the XOR-3 four-clause count remains a stable rank detector.  Large
training ranks (51, 63, 65, 67, 69, 71) are satisfiable and are solved very
quickly by the current search.  Ranks 9, 13, and 15 are below the supported
SAT-construction/search range; the solver returns `UNKNOWN` for them.

## Techniques Used

- Parses sanitized DIMACS only; comments and filenames are ignored.
- Detects the Brent rank from the repeated XOR-3 Tseitin block count.
- Runs a from-scratch stochastic local-search engine on the CNF.
- Treats unit clauses as fixed assignments.
- Maintains clause satisfaction counts and an explicit unsatisfied-clause list.
- Chooses flips with make/break scoring plus low random noise and restarts.
- Independently verifies every clause before printing `SATISFIABLE`.
- Contains an experimental proof-producing CDCL/RUP refuter for rank 9, but
  it is disabled by default because local full-budget tests did not close the
  training rank-9 formula.

## Remaining Things To Try

- Recover the original alpha/beta/gamma variables and solve Brent equations
  directly instead of searching the Tseitin CNF.
- Add a proof-producing lower-bound argument for low ranks, if it can be
  expressed compactly enough for VeriPB.
- Improve or replace the experimental rank-9 CDCL path.  Tested variants
  included primary-only decisions, all-variable decisions, phase changes,
  restarts, failed-literal probing, learned-clause minimization, and aggressive
  database reduction.  The best search-only run reached about 9.8M conflicts
  in 588s on the rank-9 training instance without deriving UNSAT.
- Use the recovered gate graph to initialize all auxiliary variables from a
  constructed high-level schoolbook solution for high-rank unstreamlined cases.
- Tune SLS scoring for any hidden medium-rank instances that do not solve from
  the current all-zero-plus-noise start.

## Known Limitations

- No UNSAT claims are made.  Low-rank instances are conservatively `UNKNOWN`
  because no VeriPB proof is generated.
- The search is a SAT-model finder, not a complete solver.
- The rank detector assumes the observed Brent 3x3 family with 729 equations
  and odd rank encoded by chained XOR-3 blocks.
- Setting `SOLVER_ENABLE_CDCL_UNSAT=1` enables the experimental rank-9 CDCL
  refuter for local experiments only; it is intentionally not part of the
  default broker path.

## Changelog

- 2026-05-06: Added `tools/profile.py` for clause-size and polarity profiling.
- 2026-05-06: Replaced the scaffold with a compiled C++ local-search solver.
- 2026-05-06: Added fixed-unit handling, incremental unsat maintenance,
  make/break variable scoring, restarts, and full model verification.
- 2026-05-06: Fixed model output so the assignment is terminated by a single
  final `0`.
- 2026-05-06: Added Brent rank detection from four-literal XOR block counts
  and quick `UNKNOWN` for ranks below 19.
- 2026-05-06: Updated metadata and this notebook before broker submission.
- 2026-05-09: Implemented an experimental VeriPB/RUP CDCL refuter for rank 9,
  including watched propagation, first-UIP learning, root-level preservation,
  restarts, failed-literal probing, clause minimization, and learned-clause
  reduction.  Left it disabled by default after full-budget local runs failed
  to prove the rank-9 training formula.
- 2026-05-09: Kept the default low-rank behavior conservative: ranks below 19
  return `UNKNOWN` unless `SOLVER_ENABLE_CDCL_UNSAT` is explicitly set for
  local experiments.
