From 6543913371dc9a8457d483281569f1dcc155dbba Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 1 Oct 2026 20:27:13 +0000 Subject: [PATCH] [na] Document the cost_model formula The architecture note names the four weights, their units, the placeholder defaults, and the v0 schema rules. The verified total is the same dot product the resource report already recomputes. Time and error-budget both score the zoned placer with that vector. Refs #484 Co-authored-by: Arnab Ghosh --- docs/neutral_atom/architecture_model.md | 106 +++++++++++++----- .../src/content/docs/architecture/na-model.md | 25 ++--- .../content/docs/reference/backend-targets.md | 7 +- 3 files changed, 94 insertions(+), 44 deletions(-) diff --git a/docs/neutral_atom/architecture_model.md b/docs/neutral_atom/architecture_model.md index 7664c173..48c7bdcf 100644 --- a/docs/neutral_atom/architecture_model.md +++ b/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 diff --git a/website/src/content/docs/architecture/na-model.md b/website/src/content/docs/architecture/na-model.md index 1d138456..68872411 100644 --- a/website/src/content/docs/architecture/na-model.md +++ b/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 diff --git a/website/src/content/docs/reference/backend-targets.md b/website/src/content/docs/reference/backend-targets.md index ff6cb74c..83cf9b4b 100644 --- a/website/src/content/docs/reference/backend-targets.md +++ b/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: