|
| 1 | +--- |
| 2 | +name: write-model-in-paper |
| 3 | +description: Use when writing or improving a problem-def entry in the Typst paper (docs/paper/reductions.typ) |
| 4 | +--- |
| 5 | + |
| 6 | +# Write Problem Model in Paper |
| 7 | + |
| 8 | +Full authoring guide for writing a `problem-def` entry in `docs/paper/reductions.typ`. Covers formal definition, background, examples with visualization, and verification. |
| 9 | + |
| 10 | +## Prerequisites |
| 11 | + |
| 12 | +Before using this skill, ensure: |
| 13 | +- The problem model is implemented (`src/models/<category>/<name>.rs`) |
| 14 | +- The problem is registered with schema and variant metadata |
| 15 | +- JSON exports are up to date (`make rust-export && make export-schemas`) |
| 16 | + |
| 17 | +## Reference Example |
| 18 | + |
| 19 | +**MaximumIndependentSet** in `docs/paper/reductions.typ` is the gold-standard model example. Search for `problem-def("MaximumIndependentSet")` to see the complete entry. Use it as a template for style, depth, and structure. |
| 20 | + |
| 21 | +## The `problem-def` Function |
| 22 | + |
| 23 | +```typst |
| 24 | +#problem-def("ProblemName")[ |
| 25 | + Formal definition... // parameter 1: def |
| 26 | +][ |
| 27 | + Background, example, figure... // parameter 2: body |
| 28 | +] |
| 29 | +``` |
| 30 | + |
| 31 | +**Three parameters:** |
| 32 | +- `name` (string) — problem name matching `display-name` dictionary key |
| 33 | +- `def` (content) — formal mathematical definition |
| 34 | +- `body` (content) — background, examples, figures, algorithm list |
| 35 | + |
| 36 | +**Auto-generated between `def` and `body`:** |
| 37 | +- Variant complexity table (from Rust `declare_variants!` metadata) |
| 38 | +- Reduction links (from reduction graph JSON) |
| 39 | +- Schema field table (from problem schema JSON) |
| 40 | + |
| 41 | +## Step 1: Register Display Name |
| 42 | + |
| 43 | +Add to the `display-name` dictionary near the top of `reductions.typ`: |
| 44 | + |
| 45 | +```typst |
| 46 | +"ProblemName": [Display Name], |
| 47 | +``` |
| 48 | + |
| 49 | +## Step 2: Write the Formal Definition (`def` parameter) |
| 50 | + |
| 51 | +One self-contained sentence or short paragraph. Requirements: |
| 52 | + |
| 53 | +1. **Introduce all inputs first** — graph, weights, sets, variables with their domains |
| 54 | +2. **State the objective or constraint** — what is being optimized or satisfied |
| 55 | +3. **Define all notation before use** — every symbol must be introduced before it appears |
| 56 | + |
| 57 | +### Pattern for optimization problems |
| 58 | + |
| 59 | +```typst |
| 60 | +Given [inputs with domains], find [solution variable] [maximizing/minimizing] [objective] such that [constraints]. |
| 61 | +``` |
| 62 | + |
| 63 | +### Pattern for satisfaction problems |
| 64 | + |
| 65 | +```typst |
| 66 | +Given [inputs with domains], find [solution variable] such that [constraints]. |
| 67 | +``` |
| 68 | + |
| 69 | +### Example (MIS) |
| 70 | + |
| 71 | +```typst |
| 72 | +Given $G = (V, E)$ with vertex weights $w: V -> RR$, find $S subset.eq V$ |
| 73 | +maximizing $sum_(v in S) w(v)$ such that no two vertices in $S$ are |
| 74 | +adjacent: $forall u, v in S: (u, v) in.not E$. |
| 75 | +``` |
| 76 | + |
| 77 | +## Step 3: Write the Body |
| 78 | + |
| 79 | +The body goes AFTER the auto-generated sections (complexity, reductions, schema). It contains four parts in order: |
| 80 | + |
| 81 | +### 3a. Background & Motivation |
| 82 | + |
| 83 | +1-3 sentences covering: |
| 84 | +- Historical context (e.g., "One of Karp's 21 NP-complete problems") |
| 85 | +- Applications (e.g., "appears in wireless network scheduling, register allocation") |
| 86 | +- Notable structural properties (e.g., "Solvable in polynomial time on bipartite graphs, interval graphs, chordal graphs") |
| 87 | + |
| 88 | +If the user provides specific justification or motivation, incorporate it here. |
| 89 | + |
| 90 | +### 3b. Best Known Algorithms |
| 91 | + |
| 92 | +Must clearly state which algorithm gives the best complexity and cite reference. Add a warning as footnote if no reliable reference is found. |
| 93 | + |
| 94 | +Integrate algorithm complexity naturally into the background prose — do NOT append a terse "Best known: $O^*(...)$" at the end: |
| 95 | + |
| 96 | +```typst |
| 97 | +% Good: names the algorithm, cites reference |
| 98 | +The best known algorithm runs in $O^*(1.1996^n)$ time via measure-and-conquer |
| 99 | +branching @xiao2017. |
| 100 | +
|
| 101 | +% Good: brute-force with footnote when no better algorithm is known |
| 102 | +The best known algorithm runs in $O^*(2^n)$ by brute-force |
| 103 | +enumeration#footnote[No algorithm improving on brute-force is known for ...]. |
| 104 | +
|
| 105 | +% Bad: terse appendage, no algorithm name, no reference |
| 106 | +Best known: $O^*(2^n)$. |
| 107 | +``` |
| 108 | + |
| 109 | +For problems with multiple notable algorithms or special cases, weave them into the text: |
| 110 | +```typst |
| 111 | +Solvable in $O(n+m)$ for $k=2$ via bipartiteness testing. For $k=3$, the best |
| 112 | +known algorithm runs in $O^*(1.3289^n)$ @beigel2005; in general, inclusion-exclusion |
| 113 | +achieves $O^*(2^n)$ @bjorklund2009. |
| 114 | +``` |
| 115 | + |
| 116 | +**Citation rules:** |
| 117 | +- Every complexity claim MUST have a citation (`@key`) identifying the algorithm |
| 118 | +- If the best known is brute-force enumeration with no specialized algorithm, add footnote: `#footnote[No algorithm improving on brute-force enumeration is known for ...]` |
| 119 | +- If a reference exists but has not been independently verified, add footnote: `#footnote[Complexity not independently verified from literature.]` |
| 120 | +- Include approximation results where relevant (e.g., "0.878-approximation @goemans1995") |
| 121 | + |
| 122 | +**Consistency note:** The auto-generated complexity table (from `declare_variants!`) also shows complexity per variant. The written text and the auto-generated table may overlap. Keep both — the written text provides references and context; the auto-generated table provides per-variant detail. A future verification step will check consistency between them. |
| 123 | + |
| 124 | +### 3c. Example with Visualization |
| 125 | + |
| 126 | +A concrete small instance that illustrates the problem. Requirements: |
| 127 | + |
| 128 | +1. **Small enough to verify by hand** — readers should be able to check the solution |
| 129 | +2. **Include a diagram/graph** using the paper's visualization helpers |
| 130 | +3. **Show a valid/optimal solution** and explain why it is valid/optimal |
| 131 | +4. **Walk through evaluation** — show how the objective/verifier computes the solution value |
| 132 | + |
| 133 | +Structure: |
| 134 | + |
| 135 | +```typst |
| 136 | +*Example.* Consider [instance description with concrete numbers]. |
| 137 | +[Describe the solution and why it's valid/optimal]. |
| 138 | +
|
| 139 | +#figure({ |
| 140 | + // visualization code — see MaximumIndependentSet for graph rendering pattern |
| 141 | +}, |
| 142 | +caption: [Caption describing the figure with key parameters], |
| 143 | +) <fig:problem-example> |
| 144 | +``` |
| 145 | + |
| 146 | +**For graph problems**, use the paper's existing graph helpers: |
| 147 | +- `petersen-graph()`, `house-graph()` or define custom vertex/edge lists |
| 148 | +- `canvas(length: ..., { ... })` with `g-node()` and `g-edge()` |
| 149 | +- Highlight solution elements with `graph-colors.at(0)` (blue) and use `white` fill for non-solution |
| 150 | + |
| 151 | +Refer to the **MaximumIndependentSet** entry for the complete graph rendering pattern. Adapt it to your problem. |
| 152 | + |
| 153 | +### 3d. Evaluation Explanation |
| 154 | + |
| 155 | +Explain how a configuration is evaluated — this maps to the Rust `evaluate()` method: |
| 156 | +- For optimization: show the cost function computation on the example solution |
| 157 | +- For satisfaction: show the verifier check on the example solution |
| 158 | + |
| 159 | +This can be woven into the example text (as MIS does: "$w(S) = sum_(v in S) w(v) = 4 = alpha(G)$"). |
| 160 | + |
| 161 | +## Step 4: Build and Verify |
| 162 | + |
| 163 | +```bash |
| 164 | +# Regenerate exports (if not already done) |
| 165 | +make rust-export && make export-schemas |
| 166 | + |
| 167 | +# Build the paper |
| 168 | +make paper |
| 169 | +``` |
| 170 | + |
| 171 | +### Verification Checklist |
| 172 | + |
| 173 | +- [ ] **Display name registered**: entry exists in `display-name` dictionary |
| 174 | +- [ ] **Notation self-contained**: every symbol in `def` is defined before first use |
| 175 | +- [ ] **Background present**: historical context, applications, or structural properties |
| 176 | +- [ ] **Algorithms cited**: every complexity claim has `@citation` or footnote warning |
| 177 | +- [ ] **Example present**: concrete small instance with visualization |
| 178 | +- [ ] **Evaluation shown**: objective/verifier computed on the example solution |
| 179 | +- [ ] **Diagram included**: figure with caption and label for graph/matrix/set visualization |
| 180 | +- [ ] **Paper compiles**: `make paper` succeeds without errors |
| 181 | +- [ ] **Complexity consistency**: written complexity and auto-generated variant table are compatible (note any discrepancies for later review) |
0 commit comments