# Solver Notes

## Formula Notes

- Training formulas are sanitized DIMACS k-CNF with clause sizes 3 or 4.
- Clauses are not independent random clauses. Many share the same absolute
  variable tuple; each such tuple is a small forbidden-table constraint.
- Observed examples:
  - k=3, large l=3 instances: one absolute tuple per nominal variable count,
    with multiplicity 2 or 3.
  - k=4, l=4 instances: exactly about n absolute tuples, each with 6 or 7
    forbidden sign patterns.
  - k=3, l=4/l=5 smaller instances: many singleton tuple constraints plus a
    tail of repeated tuples.
- The solver does not depend on comments, filenames, hashes, or the parameter
  strings embedded in names.

## Techniques Used

- Parse DIMACS directly after comment stripping.
- SAT phase: probSAT-style stochastic local search over original clauses.
  Candidate flips are sampled from a weighted break-count distribution, with a
  small make/break greedy perturbation.
- Exact phase: from-scratch watched-literal CDCL with first-UIP conflict
  analysis, restarts, and VeriPB RUP proof logging for learned clauses.
- Soundness gates:
  - Every SAT assignment is checked against every original clause before
    printing `s SATISFIABLE`.
  - UNSAT output writes a PB proof with one `rup` line per learned clause and a
    final empty RUP contradiction.

## Remaining Things To Try

- Add clause deletion and LBD-style restart heuristics to make the CDCL fallback
  competitive on the hard k=4 UNSAT cases.
- Lift repeated absolute variable tuples into explicit table constraints for a
  stronger min-conflicts score.
- Investigate whether the repeated-tuple patterns correspond to a named locked
  occupation problem with a direct graph/CSP algorithm.

## Known Limitations

- Local search is much stronger than the current CDCL fallback. Large SAT cases
  can be found, but not yet at Kissat speed.
- Some k=4 UNSAT training cases exceed short local smoke-test limits; they may
  need better learned-clause database management.
- Proofs are intentionally simple RUP logs and can grow if the exact search runs
  for a long time.

## Changelog

- Initial scaffold replaced with a C++20 solver.
- Added DIMACS parser and complete model checker.
- Added probSAT-style local search for SAT model generation.
- Added watched-literal CDCL fallback with first-UIP learning.
- Added VeriPB proof writer using RUP constraints and verified it locally on a
  toy UNSAT instance plus an easy k=3 UNSAT training instance.
- Updated metadata and notes for broker submission.
- Added best-assignment tracking in local search, adaptive extension for close
  k=4 SAT runs, failed-literal probing for k=4 exact search, and CDCL phase
  seeding/saving from the best local-search assignment.
- Reworked CDCL watch lists to carry blocker literals so propagation can skip
  clauses that are already satisfied by the blocker.
- Added a profiling helper under `tools/` and changed large-instance local
  search to use shorter deterministic restarts, avoiding single bad basins that
  can consume the full SAT-search budget.
- Added `LKSAT_LS_LIMIT` as a local testing override for separating local-search
  and CDCL behavior; evaluator defaults are unchanged when the variable is not
  set.
- Retuned the default time policy after local sweeps: small/medium formulas now
  get a 5s SAT-search probe before CDCL, large k=3 formulas get 60s, and close
  k=4 local-search extensions are capped at 90s rather than 300s.
- Stopped seeding CDCL phases from failed local-search best assignments. Local
  tests showed one-clause-away assignments could trap CDCL badly on k=3 l=4
  SAT/UNSAT cases; CDCL now falls back to polarity-majority initial phases.
- Added conservative learned-clause database reduction to CDCL. Deleted clauses
  remain in the proof log, while binary clauses and currently locked reason
  clauses stay active in the search.
- Mirrored learned-clause deletion in the VeriPB proof stream with chronological
  `del id ... ;` events, reducing the active checker database for large RUP
  proofs.
- Added a local `LKSAT_DEBUG` instrumentation switch for CDCL conflict and
  learned-clause growth measurements; it is inactive in evaluator runs.
- Tried a local first-UIP learned-clause minimization pass, but reverted it
  after a RUP proof check caught an unsound minimized clause on a k=3 l=5
  UNSAT instance.
- Added local `LKSAT_PHASE` experimentation for CDCL initial polarity
  (`true`, `false`, or deterministic `random`); default remains polarity
  majority.
- Added local `LKSAT_REDUCE_INTERVAL` experimentation for learned-clause
  database reduction cadence; default is still every 10k conflicts.
- Added tuple-local table resolution closure before CDCL. Repeated absolute
  variable tuples are interpreted as forbidden-row tables; whenever two active
  child clauses differ on one tuple variable, the shorter resolvent is added as
  a root RUP clause. This yields thousands of ternary/binary clauses on k=4
  instances without relying on comments or filenames.
- Kept k=4 failed-literal probing as a bounded fixpoint pass, with a default
  60s window and local `LKSAT_PROBE_WINDOW` override. Longer probing did not
  improve the hard k=4 case after LBD retention and risked the 600s solver cap.
- Added LBD/glue tracking for learned clauses and changed database reduction to
  preserve binary and low-LBD clauses while preferentially deleting high-LBD,
  low-activity clauses.
- Optimized local search occurrence lists to store literal signs directly,
  avoiding repeated scans of short clauses during flip, make, and break-count
  calculations.
- Added local `LKSAT_K4_EXTEND_LIMIT` experimentation for the close k=4
  local-search extension cap.
- Shortened k=4 local-search tries so short SAT probes sample more restarts
  instead of spending most of the budget in one timing-sensitive walk.
- Disabled the default k=4 local-search extension after short restarts made the
  representative k=4 SAT case solve inside the initial probe; this preserves
  CDCL wall time for the hard k=4 UNSAT proofs.
- Replaced iostream PB proof writing with a buffered `FILE*` writer to reduce
  wall time on multi-gigabyte UNSAT proofs.
- Reduced the initial small k=4 SAT probe to 4s after shorter restarts made the
  representative k=4 SAT solve in about one second, adding margin for the
  hardest k=4 UNSAT proof.
