# Solver Notes

## Formula Notes

The target is Social Golfer.  The SAT 2023 `TableModel` and `TableSymModel`
instances use the standard schedule table variables:

`table[week][group][player][position]`

The base table block is contiguous at the end of the variable range and has
length `w * (g*p)^2`.  Variables are ordered as:

`position`, then `group * w + week`, then `player`.

The table encodings are detectable without comments or filenames:

- Maximum clause size is `N = g*p`.
- Number of size-`N` clauses is `2*w*N`.
- Number of size-`p+1` clauses is `w*N*g`, which recovers `g` and `p`.
- `TableSymModel` adds exactly `N` positive unit clauses inside the table block;
  these fix one week partition.  The solver decodes those units and relabels a
  generated schedule to match them.

The `ContextModel` formulas are also Social Golfer instances.  They use
week-local pair variables as their primary block:

`same_week_pair[week][player_a][player_b]`

The primary block is the final `w * C(N, 2)` variables.  It is not ordered
lexicographically in a way that should be hard-coded; instead, the `w * N`
long positive clauses identify the two player endpoints of every pair
variable.  The solver derives the pair-to-variable map from those incidence
clauses, applies the embedded Social Golfer schedule, and relabels players so
positive primary unit clauses are honored.

The legacy `sgp_*shuffled*` formulas are older table encodings with shuffled
variable IDs and randomized literal polarities.  Their table-variable graph is
recoverable from the `2*w*N` max-size clauses, and the `p+1` clauses reveal the
player-side group-membership auxiliaries.  The remaining unresolved part is
aligning player identities across shuffled week components, so the solver still
returns UNKNOWN for them.

The `SocialGolfers-*-cp_c18` formulas in this split are UNSAT-family CP
encodings and are left UNKNOWN because no VeriPB proof generator has been
implemented.

## Techniques Used

The submitted solver is SAT-only and conservative.

1. Parse the sanitized DIMACS and compute clause-size statistics.
2. Detect the table encoding shape above.
3. Recover `g`, `p`, `w`, and `N`.
4. Build a high-level Social Golfer schedule for supported parameters:
   - `5-3-w` up to 7 weeks.
   - `6-3-w` up to 8 weeks.
   - `7-3-w` up to 10 weeks.
   - `8-3-w` up to 10 weeks.
   - `6-4-w` up to 7 weeks.
   - `6-5-w` up to 6 weeks.
   - `8-4-w` up to 10 weeks.
5. Map true table variables from the schedule and set all other table variables
   false.
6. Run unit propagation to assign auxiliary variables.
7. Verify every original clause before printing `s SATISFIABLE` and a complete
   model.

For `ContextModel` instances, the solver separately detects the pair-context
shape:

1. Recover `N` as `max_clause_size + 1` and `w` from the count of max-size
   clauses.
2. Recover `p` from the `w*N*N` clauses of size `p` when present, or use `p=3`
   for triple systems.
3. Build the primary pair-variable map from the long-clause incidence pattern,
   not from comments, filenames, or fixed variable order.
4. Decode positive primary units as forced same-week pairs, find a small
   player relabeling of the embedded schedule that satisfies those forced
   pairs, set all pair variables, then unit-propagate and verify the full CNF.

If any step fails, the solver exits `0` with `UNKNOWN`.

## Remaining Things To Try

- Recover the legacy shuffled SAT05 encoding.  Current analysis shows:
  max-size clauses form `w` bipartite `K_{N,N}` components; every table
  variable appears in two long clauses with a consistent polarity; `p+1`
  clauses identify the player side and stable slot-group partitions; all unit
  clauses are true table literals fixing two complete weeks.  The open problem
  is matching player identities across components without using filenames or
  memorized assignments.
- For UNSAT CP instances, design a real VeriPB strategy before returning
  UNSAT.  Current solver intentionally returns UNKNOWN for them.

## Known Limitations

- No UNSAT output is produced.
- No behavior depends on filenames, hashes, or comments.
- The embedded schedules are parameter-level constructions for Social Golfer
  instances, not memorized CNF assignments.  Every produced assignment is checked
  against the original CNF before exit code 10.
- Shuffled SAT05 and CP encodings return UNKNOWN.

## Changelog

- Added repeatable CNF profiling script under `tools/profile_cnf.py`.
- Identified Social Golfer table encoding structure and table variable order.
- Implemented C++ solver for p=3 and p=4 table models with symmetry-unit
  relabeling, auxiliary unit propagation, and full CNF verification.
- Added exploratory high-level schedule tools under `tools/`; these are not used
  by the submitted solver.
- Updated metadata and this README for the first broker submission.
- Added a validated 30-player, size-5, six-round allocation for `6-5-6`
  table instances.  The local exploratory search did not find it, so the
  embedded schedule was taken from the published allocation-correctness archive
  and is still checked by the solver's internal pair and CNF verifiers.
- Added a structural `ContextModel` decoder.  It recovers pair variables from
  long-clause incidence, supports p=3/p=4/p=5 context instances covered by the
  embedded schedules, relabels schedules to satisfy primary pair units, and
  verifies the completed CNF model.  Local train solved count is now 14/20.
- Documented shuffled SAT05 structural findings: recoverable randomized table
  graph, group-membership auxiliaries, and fixed-week unit matchings; no
  shuffled model output is enabled yet because cross-week identity alignment is
  unfinished.
