[na] Document the cost_model formula Refs #484

docs/neutral_atom/architecture_model.md

@@ -277,7 +277,7 @@ Units: lengths in µm, times in µs, fidelities as probabilities in [0, 1].
 | `timing` | object | Operation durations (§8.5) | Schedule makespan, decoherence-weighted cost |
 | `fidelity` | object | Operation fidelities + coherence time (§8.5) | Deferred fidelity estimate (future; not #110 — see §11) |
 | `error_model` | object, optional | Explicit physical error probabilities for QEC (ADR-0017; §8.5) | Resource-report `error_budget` (`--emit-resource-report`); `--emit-qec-experiment` (#255). Hard-fail when those emits are requested and the object is absent — never derived as `1 − fidelity`. Experiment JSON schema: [`qec_experiment_schema.md`](./qec_experiment_schema.md). |
-| `cost_model` | object | Linear cost weights (§9) | Scheduler objective, resource report |
+| `cost_model` | object, optional | Four §9 weights. An omitted object or an omitted field uses the §8.6 placeholder | Zoned placement score and the verified `schedule_objective` total |
 
 ### 8.2 Zone
 
@@ -376,7 +376,10 @@ labeled placeholders.
 | `fidelity.coherence_time_us` | 1.5e6 | cited | [OLSQ-DPQA] Sec. 4; [Enola] Sec. 2; [QMAP-docs] (`T: 1.5e6`) |
 | Zone geometry (storage 73 × 101 @ 4 µm pitch; entanglement 10 × 34 pairs, pair gap 2 µm, pair pitch 12 × 10 µm; AOD 100 × 100) | — | cited (as a published artifact, not a physics claim) | [QMAP-repo] `eval/na/zoned/square_architecture.json`, the reference architecture shipped with the [RAP] compiler |
 | `max_parallel_entangling_pairs` | 340 | derived | Entanglement-zone pair capacity of the geometry above |
-| `cost_model` weights | see §9 | **placeholder** | Weights are tuning knobs, not measurements |
+| `cost_model.rydberg_stage_weight` | 1 | **placeholder** | Per Rydberg stage. Default when the field is omitted (§9) |
+| `cost_model.movement_time_weight` | 1 | **placeholder** | Per µs of summed move duration. Default when omitted (§9) |
+| `cost_model.trap_transfer_weight` | 1 | **placeholder** | Per trap transfer. Default when omitted (§9) |
+| `cost_model.idle_time_weight` | 0.000001 | **placeholder** | Per µs of summed idle. Default when omitted (§9) |
 | `error_model.rydberg` | 0.002 | **placeholder** | Illustrative QEC rate; deliberately ≠ `1 − fidelity.cz` (0.005). ADR-0017. |
 | `error_model.measurement` | 0.003 | **placeholder** | Illustrative; not a literature claim. |
 | `error_model.reset` | 0.004 | **placeholder** | Illustrative; not a literature claim. |
@@ -386,37 +389,82 @@ labeled placeholders.
 
 ## 9. Cost model
 
-The v0 cost model is a simple linear functional over a compiled schedule,
-reported by the resource estimator (#110) and minimized greedily by the
-schedulers:
+The v0 `cost_model` is four finite weights. The zoned placer scores with
+them, and the resource report recomputes the same dot product from the
+verified `quantum.na` schedule (`schedule_objective.total` in JSON, and the
+"Schedule objective (verified quantum.na)" table in Markdown). `w_stage`,
+`w_move`, `w_xfer`, and `w_idle` are names for those four fields, in that
+order. That product is the objective expression.
 
 ```
-cost(schedule) = w_stage · n_rydberg_stages
-              + w_move  · Σ_steps t_move(d_max(step))
-              + w_xfer  · n_trap_transfers
-              + w_idle  · Σ_atoms t_idle(atom)
+total = rydberg_stage_weight · rydberg_stages
+      + movement_time_weight · movement_time_us
+      + trap_transfer_weight · trap_transfers
+      + idle_time_weight · idle_time_us
 ```
 
-Rationale per term, each grounded separately:
-
-- `n_rydberg_stages`: the flat-array objective; every stage exposes all
-  illuminated atoms to Rydberg error ([Enola] Secs. 2–3, R4).
-- `Σ √(d_max)` per movement group: the [RAP] Eq. (1) placement cost — duration
-  of a rearrangement step is set by its longest move under the √-law.
-- Transfer count: each transfer is a fidelity-bearing action ([Enola] Sec. 2:
-  99.9% per transfer, 4 per gate; [RAP] reuse analysis exists precisely to
-  save transfers).
-- Idle time: linear decoherence proxy, 1 − t/T ([Enola] Eq. (1) decoherence
-  factor).
-
-The **weights are illustrative placeholders** (Section 8.6): the literature
-optimizes these terms directly rather than a weighted sum, so any particular
-weighting is ours. The shape (which terms exist) is cited; the weights are not.
-Snapshot tests may pin them for regression purposes but must not present them
-as published values.
-
-The resource estimator emits JSON and Markdown reports whose field names and
-table shape are specified in §11.
+`weighted_total` in `quon_na/src/objective.rs` is that product. After
+verification, `objective_from_verified_schedule` reads the four counts off
+the emitted `ScheduleSpec`, not off planner-internal counters:
+
+| Weight | Count it multiplies | Unit of the count |
+| --- | --- | --- |
+| `rydberg_stage_weight` | `rydberg_stages`: layers that contain an entangle | count, per stage |
+| `movement_time_weight` | `movement_time_us`: sum of move `duration_us` already stamped on the schedule | µs |
+| `trap_transfer_weight` | `trap_transfers`: number of transfer actions | count, per transfer |
+| `idle_time_weight` | `idle_time_us`: sum over atoms of wall-clock time outside layers that name that atom. A global `ry` layer names every atom | µs |
+
+The weights are dimensionless multipliers. The total is not a time and not a
+fidelity. Move durations are stamped by the target speed model (§5) before
+this product runs; the total does not recompute them. Under the sqrt speed
+model that stamp is the √-law duration, which is the same quantity [RAP]
+Eq. (1) uses for one movement group, but the objective multiplies the
+stamped microseconds.
+
+Why these counts exist, each grounded separately: a Rydberg stage exposes
+illuminated atoms to Rydberg error ([Enola] Secs. 2–3, R4); each transfer is
+a fidelity-bearing action ([Enola] Sec. 2; [RAP] reuse analysis exists to
+save transfers); idle time is a linear decoherence proxy, 1 − t/T ([Enola]
+Eq. (1)). The literature optimizes those terms directly rather than as a
+weighted sum, so the weights are ours.
+
+The **placeholder vector** is `NeutralAtomCostModel::PLACEHOLDER` and the
+`cost_model` object in `targets/neutral_atom/generic_rna_v0.json` and
+`targets/neutral_atom/rap_table_i.json`: stage 1, movement 1, transfer 1,
+idle `0.000001` (§8.6). Snapshot tests may pin a schedule that was chosen
+under those weights, but must not present the weights as published values.
+
+### 9.1 Schema
+
+There is no `cost_model` schema-version integer. This section is the v0
+object: these four keys and no others (`deny_unknown_fields`). The target
+`id` (`generic_reconfigurable_neutral_atom_v0` on the checked-in file) names
+the descriptor, not a separate weight-schema counter.
+
+- Omitting `cost_model`, or omitting any weight, fills the §8.6 placeholder
+  for each missing field.
+- An explicit finite weight ≥ 0 is kept, including 0.
+- A vector with every weight exactly 0 is rejected when the target is loaded
+  and again when zoned scheduling starts. Every schedule would score the
+  same, so placement would ignore the vector.
+- A non-finite or negative weight is rejected at load.
+- Adding another optional weight later, with a documented default, keeps
+  existing files loading. Renaming a field, removing one, or changing a
+  placeholder default is a breaking change to this v0 object.
+
+### 9.2 CLI modes
+
+`quonc --na-objective time` (the default) and
+`quonc --na-objective error-budget` (`error_budget` and `budget` name the
+same mode) both hand the loaded `cost_model` to the zoned placer as this
+weighted score. `error-budget` still requires `error_model` and fails closed
+when it is absent. Those rates stay on the resource report as `error_budget`
+(`rate × schedule count`). The flat AOD backend leaves placement on its own
+path and does not score with `cost_model`.
+
+The resource estimator's other JSON and Markdown sections are specified in
+§11. The verified objective section is emitted only after `quantum.na`
+verification has run.
 
 ## 10. Code families and overhead formulas
 

website/src/content/docs/architecture/na-model.md

@@ -205,7 +205,7 @@ The top level ties the pieces together:
 | `timing` | object | Operation durations |
 | `fidelity` | object | Operation fidelities + coherence time |
 | `error_model` | object, optional | Explicit physical error probabilities for QEC (never derived as `1 − fidelity`) |
-| `cost_model` | object | Linear cost weights |
+| `cost_model` | object, optional | Four weights. Omitted fields use the placeholder defaults in the source document §9 |
 
 A **Zone** declares a region's capability. A flat-array target is expressed as a
 single `entanglement` zone covering the whole grid, so the zone constraints
@@ -253,22 +253,21 @@ accounting. Per ADR-0017, you must never convert rates as `1 − fidelity.*`.
 
 ### Cost model
 
-The v0 cost model is a simple linear functional over a compiled schedule,
-reported by the resource estimator and minimized greedily by the schedulers:
+The v0 `cost_model` is one dot product. The zoned placer scores with it, and
+the verified resource report recomputes the same total. Field names, units,
+placeholder defaults, schema rules, and the `time` / `error-budget` CLI modes
+are in the [source document §9](https://github.com/arniber21/quon/blob/main/docs/neutral_atom/architecture_model.md).
 
 ```
-cost(schedule) = w_stage · n_rydberg_stages
-              + w_move  · Σ_steps t_move(d_max(step))
-              + w_xfer  · n_trap_transfers
-              + w_idle  · Σ_atoms t_idle(atom)
+total = rydberg_stage_weight · rydberg_stages
+      + movement_time_weight · movement_time_us
+      + trap_transfer_weight · trap_transfers
+      + idle_time_weight · idle_time_us
 ```
 
-Each term is grounded separately: Rydberg stages expose all illuminated atoms to
-error (the flat-array objective); $\sum\sqrt{d_{max}}$ per group is the [RAP]
-placement cost; transfers are fidelity-bearing actions the reuse optimization
-exists to save; idle time is a linear decoherence proxy. The *shape* of the cost
-(which terms exist) is cited; the *weights* are illustrative placeholders, not
-published values.
+`rydberg_stages` and `trap_transfers` are counts. `movement_time_us` and
+`idle_time_us` are microseconds already stamped on the verified schedule. The
+weights are dimensionless placeholders, not published measurements.
 
 ## QEC overlay
 

website/src/content/docs/reference/backend-targets.md

@@ -111,7 +111,10 @@ gate.
 
 The reconfigurable neutral-atom descriptor models a DPQA/zoned array: zones,
 array geometry, AOD movement, Rydberg interaction, timing, fidelity, and a cost
-model. All fields except `error_model` and `atom_loss_model` are **required**.
+model. `error_model`, `atom_loss_model`, and `cost_model` may be omitted.
+An omitted `cost_model` weight loads the placeholder in the
+[architecture model §9](https://github.com/arniber21/quon/blob/main/docs/neutral_atom/architecture_model.md).
+Every other field below is **required**.
 
 | Field | Type | Required | Meaning |
 | --- | --- | --- | --- |
@@ -126,7 +129,7 @@ model. All fields except `error_model` and `atom_loss_model` are **required**.
 | `fidelity` | object | yes | `cz`, `single_qubit`, `atom_transfer`, `coherence_time_us` |
 | `error_model` | object | optional | Explicit physical error probabilities for QEC (sibling to `fidelity`) |
 | `atom_loss_model` | object | optional | Movement-induced heating/loss parameters |
-| `cost_model` | object | yes | Linear cost weights |
+| `cost_model` | object | optional | Four §9 weights. Omitted fields use the placeholder defaults |
 
 A **Zone** declares a region's capability: