# fdmus Relation-Proof Solver

## Instance Family
The fdmus instances in the train split are UNSAT Tseitin encodings of three copied AIG-style Boolean circuits.

Observed structural invariants, detected from clauses only:
- The variable count is exactly three equal blocks.
- Each block has the same two-input AND-gate circuit, with signed input edges and increasing gate-output variable ids.
- A primary output variable `N` is linked to the final gate `B` by `N <-> not B` in each block.
- Units force the shared first primary input true and force the output pattern `N0=true`, `N1=false`, `N2=false`, which means the final gates are forced to `(B0,B1,B2)=(false,true,true)`.
- Cross-block binary equivalences link most primary variables between block 0 and block 1, and between block 0 and block 2. The two copy pairs leave different primary variables free.

The detector does not use comments, filenames, hashes, or memorized instances. If any structural check fails, the relation path is skipped.

## Solver Approach
The current solver has a structural RUP proof layer before the inherited CDCL solver.

### Ternary Relation Reasoning
For every corresponding variable/gate across the three circuit copies, the solver computes the possible truth triples `(block0, block1, block2)`.

- Primary-variable triples come from unit clauses and cross-block equality clauses.
- Gate triples are propagated through the copied AND gates, including signed input edges.
- For each relation, the solver emits all prime implicate clauses over the three corresponding variables as VeriPB `rup` lines.
- If the final gate relation excludes the forced triple `(false,true,true)`, the solver writes the relation proof plus an empty RUP contradiction and exits UNSAT immediately.
- If the final relation is not strong enough to close the proof, the same relation clauses are still added as RUP-derived constraints before preprocessing and CDCL. This is a large speedup on the inherited fallback path.

### Fallback CDCL
If the structural detector fails or relation reasoning does not close the instance outright, the solver runs the inherited proof-producing CDCL pipeline on the strengthened formula:

1. Binary/unit propagation and simplification.
2. Bounded variable elimination, with RUP resolvents written to the proof.
3. Binary self-subsumption, also proof logged.
4. Hand-written CDCL with watched literals, VSIDS, Luby restarts, recursive clause minimization, LBD-aware deletion, and VeriPB RUP learned clauses.

## Local Results
On the full 800-instance train split:

- Previous inherited solver: 800/800 UNSAT, average solver time ~0.184s, median ~0.178s.
- Relation proof plus strengthened fallback: 800/800 UNSAT, average solver time ~0.024s, median ~0.008s, max ~0.53s.
- Full local VeriPB sweep: 800/800 proofs verified. Average solver time during the sweep was ~0.024s and average VeriPB time was ~0.203s.
- This beats the listed train VBS solver-time average of 0.053s on the train split.

## Notes And Limitations
- Direct relation proofs close roughly 500/800 train instances. The remaining instances use relation clauses to accelerate BVE/CDCL.
- Relation propagation is intentionally conservative: it uses per-node triple relations and does not try to build a full BDD or exact multi-node relation.
- If a future instance has the same broad family but reordered variables, non-contiguous gate ids, non-AND Tseitin gates, or missing copied-gate structure, the detector should skip the relation path and use the fallback.
- The solver remains proof-first: every added relation clause is emitted as a RUP line before it is used by BVE/CDCL.

## Potential Future Improvements
- Strengthen the relation abstraction with selected multi-node relations for the remaining fallback-heavy cases.
- Generate fewer relation prime implicates while preserving the propagation that helps CDCL.
- Use relation-derived final clauses to guide variable elimination order.
- Remove inherited experimental source/binary artifacts from the archive once no longer useful for comparison.

## Changelog
- v1: Basic CDCL. 793/800 (7 OOM).
- v2: GC. 800/800, PAR-2 ~1.96s.
- v6: Glucose restarts. 800/800, PAR-2 0.914s.
- v9: Clause minimization + VSIDS 0.85. ~60% faster than v6.
- v10: BVE preprocessing. Avg 0.375s eval.
- v13: Binary self-subsumption. Avg 0.355s.
- v14: Pre-BVE binary BCP, Luby restarts, aggressive reduce. Avg 0.345s.
- v15: LBD updating, second BVE pass. Avg 0.344s.
- v17: Probing with common implications. Avg 0.366s (regression).
- v19: VSIDS decay 0.90, Luby base 16, full BCP, BVE relaxation. Expected ~0.34s.
- v20: LBD<=6, VSIDS decay 0.90 in code, BCP prefetch, int8_t seen. Local train avg ~0.184s in this run.
- v21: Added clause-structural analyzer under `tools/analyze_family.py`.
- v22: Added ternary relation proof fast path for copied AIG blocks. Directly proves about 500 train instances with VeriPB RUP.
- v23: Reuses relation prime implicates as RUP-derived fallback constraints before BVE/CDCL. Full train local result: 800/800, avg solver time ~0.024s, all proofs locally verified.
