# Solver Notes

## Formula Notes

- Visible instances are all exact 3-CNF from the Ricci-Tersenghi/Barthel/Hartmann/Leone/Weigt/Zecchina "glassy" planted satisfiable family.
- The common shape is random-regular: almost all visible formulas have exactly 14 literal occurrences per variable and `m = 14n/3`, with sizes including `n=249,300,348,399`.
- Two public benchmark-list formulas contain one binary clause; the parser accepts 1- and 2-literal clauses by repeating the last literal, which is SAT-equivalent and keeps the SLS/verifier path sound.
- Unshuffled `glassy-v*` files have a direct planted-model leak that survives comment stripping: in the first `n` clauses, the first literal uses every variable exactly once, and assigning each variable to satisfy that leading literal satisfies the whole CNF.
- A second leak survives clause-order shuffling for `glassy-v` style instances when literal order inside each clause is preserved. Relative to the planted assignment, the observed positional pattern distribution over literal truth bits is approximately:
  - `100`: 0.3796, `010`: 0.1613, `001`: 0.1641
  - `110`: 0.0326, `101`: 0.0329, `011`: 0.0336
  - `111`: 0.1958, `000`: effectively zero
- Damped belief propagation on this 8-pattern positional likelihood recovered all verified visible unshuffled `glassy-v` planted assignments even when first-block order was ignored. It also directly solves the visible partially shuffled `glassy-v300` instance whose first-block detector fails.
- Shuffled `glassyb*`, `glassybp*`, and `*.shuffled*` instances do not preserve this first-block order. Some partly shuffled `glassy` files still have useful first-position seeds but require repair by search.

## Techniques Used

- Conservative structural detection of the first-block planted model. The detector verifies the complete CNF before printing `SATISFIABLE`.
- Position-aware planted-assignment recovery: a small from-scratch sum-product pass over the fixed 8-pattern likelihood, followed by a greedy pattern-likelihood cleanup. The recovered assignment is used only if it satisfies the original CNF under full verification.
- From-scratch stochastic local search specialized to exact 3-CNF with small fixed occurrence lists. It alternates probSAT-style break weighting, WalkSAT/SKC random-walk choices, clause-weighted PAWS-style repair, polarity-majority seeds, inverse-majority seeds, and first-position seeds.
- The SLS fallback now runs a two-thread portfolio after structural detection: one thread preserves the inherited long-restart probSAT/WalkSAT/weighted schedule, and one thread uses shorter restarts, precomputed occurrence positions, parameterized probSAT exponents (`2.3`, `2.7`, `3.0`), positional-BP seed variants, and a PAWS-like weighted mode.
- Complete model verification is mandatory before exit code 10. The solver never emits UNSAT and therefore writes no VeriPB proof.

## Remaining Things To Try

- Turn the positional BP and pattern-likelihood local optimum into better seeds for the hard `glassyb` and `glassybp` variants. The current implementation keeps this path conservative and only trusts direct verified models.
- Add better focused-search variants such as clause weighting, tabu tenure, and population recombination. Historical results suggest local-search variants can reduce residual false clauses on this family.
- Explore balanced and balanced-pair generators separately; their literal-position signal reduces residual unsat counts but does not directly solve the visible instances.

## Known Limitations

- UNSAT is unsupported; the solver returns `UNKNOWN` if it cannot verify a model before its internal time budget.
- Shuffled `glassyb` and `glassybp` instances are still hard for the current fallback. The implementation is sound but solved count depends on stochastic search success.
- The solver intentionally avoids using comments, filenames, bundled solvers, or training-instance memorization.

## Changelog

- Initial scaffold: placeholder returned `UNKNOWN`.
- Added exact-3-CNF parser, full assignment verifier, SAT model printer, and first-block planted-model detector for unshuffled glassy formulas.
- Added from-scratch stochastic local-search fallback with probSAT/SKC choices and deterministic seeds based on polarity and first-position literals.
- Updated metadata and build notes for the first broker submission.
- Added a clause-weighted local-search mode. Locally this solved the `N210` shuffled instance and one visible `glassyb-v249` case that the first broker submission missed.
- Added a conservative positional-pattern BP detector for shuffled or damaged `glassy-v` instances. It verifies every recovered model before SAT output and locally solves `865f5...-glassy-v300-s1412048940.cnf.xz` in about 0.07s.
- Added precomputed `(clause, position, literal)` occurrence lists and a two-thread SLS portfolio with shorter restarts, parameterized probSAT, positional-BP seed starts, and PAWS-style weighting. A 15s visible sweep improved from 14/31 to 19/31; newly checked local models include `0a19...glassyb-v348`, `bee572...glassybp-v300`, and `b87...glassyb-v300`.
- Mirrored the public benchmark-list CNFs into scratch for broader testing. Added SAT-equivalent binary-clause parsing and increased the internal SLS budget from 585s to 595s; unsupported or unsolved cases still return `UNKNOWN`.
