open-standards/wai/extensions/quantum-landscape-2.md

# WAI Extension: Energy-Landscape Jobs, Second Version (`wai.quantum.landscape/2`)

Status: **Draft.** Reference: the `quantum_landscape` feature of `wai-quantum`
(`wai_quantum::quantum_landscape`, its reader `program::read_2` and its set
`conformance2`), the command `wai-quantum landscape … --protocol 2`, and
`QuantumEngine.landscape` in the browser build with the request's `protocol`. Answer schema:
`wai-quantum/schemas/landscape.v2.json`. Conformance set:
`quantum-conformance/landscape/v2/vectors.json`.

Keywords **MUST**, **MUST NOT**, **SHOULD** and **MAY** are RFC 2119/8174.

## 0. What this version changes

The second version is the first ([quantum-landscape](quantum-landscape.md)) with four
changes, and everything that text says holds here unless a section below says otherwise:
the request and its limits (§2, §2.0 there), the grammar and its weights (§2.1, §2.2), the
answer, its verdict and its replay digest (§3), the schedule, the draws, the cut points and the
exponential (§4.2, Appendix A), the members, their checks and the audit (§5, §7.3), and the
comparison (§6).

1. **A cost for each variable, of either sign** (§1, §2). The first version has one cost
   `c ≥ 0`, so a variable is always free to be 0 at no cost, and a constraint over a group's
   count cannot be written: colouring with interchangeable colours, assignment above a 2×2
   grid and cardinality do not run there (its §8). A cost below 0 keeps a variable out of 0 in
   every state of lowest energy, and with it one-hot, at-most-one and exactly-K constraints are
   written with couplings of one sign and whole-number fields (§2.2).
2. **Kernels of its own** (§4): `wai.quantum.landscape2/settle` and
   `wai.quantum.landscape2/sample`, which read each cell's cost.
3. **Joules priced only at a rate with evidence in this repository** (§4.3), never below what
   this project's own hardware measured; a run above temperature 0, for which no such rate
   exists, is stated `unpriced`, with why, and no figure.
4. **A rule for its vectors the reference keeps** (§7): the set is frozen, its digest pinned in
   the code, and any change to it is a new version of the protocol. The first version's set is
   frozen the same way, as it stood on 2026-11-10.

The reference is a classical emulation, as the first version's is. Its cells are three-state
values sampled with classical random draws. Nothing here is a quantum effect, and no run of the
reference involves any device but the machine it runs on.

## 1. The energy

```text
E(s) = − Σ_{i<j} W_ij s_i s_j − Σ_i b_i s_i + Σ_i c_i · |s_i|,    s_i ∈ {−1, 0, +1}
```

The couplings and fields are the first version's. Each variable has its own cost `c_i`, a whole
number of either sign, at most 2⁴⁰ in size. This is the spin-1 model with a single-ion term on
each site, of either sign.

A variable whose cost is below 0 is never 0 in a state of lowest energy: from a state where it
is 0, taking the sign of its field `h_i` (or + where the field is 0) changes the energy by
`c_i − |h_i| ≤ −1`.

## 2. The job

A request is the first version's (its §2), and its `protocol` is required and MUST be
`wai.quantum.landscape/2`. A request that gives no `protocol`, or the first version's, is a job
of the first version; a host that reads both versions reads it so, and its answer is that
version's, its bytes unchanged. A host MUST refuse any other `protocol`.

### 2.1. The program

The first version's grammar (its §2.1), with `cost` widened and three statements added:

```text
cost C             every variable's cost, a whole number of either sign
cost I C           variable I's own cost, a whole number of either sign; set twice, a warning, and the last holds
exactly K I J …    of these variables, exactly K hold +, and the others −
atmost 1 I J …     of these variables, at most one holds +, and the others −
```

`K` is a count (`[0-9]+`), from 0 to the number of variables named; the variables of a
constraint are two or more, each named once. The checks gain two forms, each holding groups
written as variables joined by `-`:

```text
#! check exactly K 0-1-2 3-4-5    each group holds exactly K +, and its other members −
#! check atmost K 0-3 1-4         each group holds at most K +, and its other members −
```

A group with a member at 0 fails either check.

A reader MUST refuse, with one plain sentence and the line:

- a cost above 2⁴⁰ in size;
- `atmost` with a count other than 1 (§8 says why);
- a constraint of fewer than two variables, one that names a variable twice, and `exactly K`
  over fewer than `K` variables;
- two constraints that join one pair, a constraint over a pair that `agree`, `oppose` or
  `couple` sets, and either of those over a pair a constraint joins: a pair holds one coupling
  of ±1;
- a variable in a constraint whose own cost (`cost I C`) is 0 or more;
- `pin` on a variable in a constraint, in either order;
- `weight` together with a constraint, a variable's own cost or a cost below 0: quantisation
  (the first version's §2.2) has one cost of 0 or more, and is unchanged here;
- a field above 2⁴⁰ in size once its constraints' fields are added (§2.2).

### 2.2. Constraints

A variable named in a constraint takes only + and −. Its cost is its own where the program gives
one, which is below 0; else the program's `cost C` where that is below 0; else −1, the least
that keeps it out of 0 in every state of lowest energy (§1).

With `x = (1 + s)/2` for each such variable (1 for +, 0 for −), the constraints lower to
couplings and fields, exactly:

| statement | couplings | each variable's field gains | energy, on states of + and − |
|---|---|---|---|
| `exactly K` over `g` variables | −1 on every pair | `2K − g` | `½(Σ s − (2K − g))²` and a constant: `2(K′ − K)²`, `K′` the + it holds |
| `atmost 1` over `g` variables | −1 on every pair | `−(g − 1)` | `4 Σ_{i<j} x_i x_j` and a constant: `2K′(K′ − 1)` |

So a group that holds what its constraint says costs nothing, and one that does not costs 2 for
an `exactly` one step off (8 for two steps), and 4 for an `atmost 1` holding two +. A
constraint's fields are added to the variable's own (`field`, `lean`), all of them after every
line is read. A pin's size (the first version's §2.1) is `D + B + C + 1`, with `B` the largest
`|b_i|` once the constraints' fields are added and `C` the largest cost in size.

A constraint is a term of the energy, not a rule a run is held to: its weight is fixed by its
couplings, so another term on the same variables, a field larger than its step or a coupling
beside it, can outvote it, and then the lowest states do not solve the problem. The worked
examples hold that every lowest state solves theirs (§6), and a program whose own check fails on
a lowest state is `failed`, as in the first version (its §3.1).

## 3. The answer

The first version's (its §3), with:

- `protocol` is `wai.quantum.landscape/2`;
- `member.kernel`, `member.kernels` and each row's `kernel` name this version's kernels (§4);
- `joules` is §4.3's;
- the replay digest (its §3.2) begins with this protocol's name, `wai.quantum.landscape/2`,
  and a zero byte, and is otherwise the first version's;
- `label` is the member's own; the reference's, word for word:

> A classical emulator of the settling model of a planned energy-based processor, running on your machine.
> Energies are computed exactly. The joule line prices a run at temperature 0 at the settle rate
> measured on an FPGA board running this project's open reference design, with a published figure
> for one integer add beside it for scale, and leaves a run above temperature 0 unpriced, saying
> why. No photonic hardware, custom chip or quantum effect is involved in this run.

## 4. The kernels

### 4.1. `wai.quantum.landscape2/settle`

The first version's settle (its §4.1), each cell at its own cost: a cell moves to the state of
lowest energy `−h_i·s + c_i·|s|`, and at a tie to 0, then to +. That is

```text
+1  when  h_i >  max(c_i, −1)
−1  when  h_i < −max(c_i, 0)
 0  otherwise
```

Where `c_i ≥ 0` it is the first version's move exactly. Where `c_i < 0` the cell never rests at
0: it takes the sign of its field, and + at a field of 0, where + and − tie. Everything is
whole-number arithmetic, and a settle kernel MUST give the reference's bits.

### 4.2. `wai.quantum.landscape2/sample`

The first version's sampling kernel (its §4.2), each cell's cut points at its own cost: the
formula is the same, and holds at a cost of either sign; the order of cells, the schedule, the
draws and the exponential are the first version's, and a sweep at 0 is §4.1's move.

### 4.3. How the joules are stated

`joules` is an object. A run at temperature 0 (a `settle` or a `quench`) is **priced**; a run
above it (a `sample`) is **unpriced**. A host:

- MUST price only at a rate whose evidence is in this repository, named under `evidence` by
  path, and MUST NOT price below what this project's own hardware measured for the same work;
- MUST state a priced figure as priced, and MUST NOT call it measured, read or metered where an
  answer's reader sees it; `rate_source` may say the rate was measured, and on what;
- MUST state an unpriced run with `kind: "unpriced"`, `pj: null` and `why`, and give no figure
  for it, of 0 or any other;
- MUST NOT print an uncertainty it does not have.

**The settle rate, about 0.88 pJ per accumulate.** This project's open FPGA member,
`wai/wai-quantum-landscape-fpga` (its README, *What it measured*, and
`measurements/2026-11-06/`):

| | |
|---|---|
| what ran | the member's engine in its T0 mode (the settle sweep, one sweep a clock), rtl version 2, the EMIO build, on one KV260 board at 100 MHz |
| the job | a dense 64-cell recall, every pair coupled, settled 12.5 million times a second: 1.831 × 10¹¹ accumulates a second (`emio-checks/throughput-emio.txt`) |
| the reading | 162.0 mW over ten passes, run minus halt on one bitstream, the order randomised, the board's input power read by its own sensor (`emio-classes/t0-recall.dat`) |
| the rate | 162.0 mW ÷ 1.831 × 10¹¹ /s = 0.885 pJ an accumulate, 13.0 nJ a settle; given as about 0.88 |
| committed first | the prediction, 160 mW (130 to 200), before the campaign (`PREDICTION.txt`) |
| checks that passed | the same job at 50 MHz drew 0.494 of it; two later builds of the same engine read 158.3 and 166.7 mW |
| what it does not show | one board, one meter, one build; the sensor reads the whole board, its regulators included; one of the campaign's two null controls failed at about 8 mW, so the instrument's floor is not shown below that (this reading is twenty times it); no other board has repeated it |
| left out | the board's own draw, about 3.14 W halted, at every clock: a small job prices low, and the answer says by how much, from at least one clock a sweep |

**Above temperature 0, no rate.** On the same member, sampling drew 11.0 mW, within that
instrument's floor, and is not relied on (its README says so). The first build of the same
design (`measurements/2026-11-05/`) drew 0.20 and 0.32 nJ a cell draw on one engine and on four,
two figures 2.0 standard deviations apart, from draws of its own rather than the reference's. The
first version's sampling rate was read on a design that updates every cell at once, which does
not sample this model (the first version's §4.2). None of these is a rate for this kernel, so a
run above temperature 0 is unpriced.

**For scale**, beside a priced figure only: a published 2014 figure for one 8-bit integer add in
45 nm logic, about 0.03 pJ, class `Estimator`, which models no processor.

The form:

```text
priced:   { "kind": "priced", "class": "ModelBased", "describes", "line", "rate_pj_per_accumulate": 0.88,
            "rate_source", "evidence": [paths], "pj", "published_add": {…}, "left_out": {…}, "why": null, "metered" }
unpriced: { "kind": "unpriced", "class": null, "describes", "line", "rate_pj_per_accumulate": null,
            "rate_source": null, "evidence": [paths], "pj": null, "published_add": null, "left_out": null,
            "why", "metered" }
```

`metered` is the first version's (its §4.4): a member's reading beside the statement, or null.
A sweep's row gives `priced_per_run` and `left_out_per_run` as the first version's do for a
priced run, and `"not priced"` for an unpriced one.

## 5. Members

A member says which versions of the protocol it runs (`Member::protocols`; the first alone where
it says nothing). A host gives no workload of this version to a member that does not run it, and
passes over such a member for a job of this version, saying so under `refusals`, however it was
reached: placed, or asked for by name.

This version holds no member to a declared capacity: the first version's vectors generated from
a capacity, and its statistical battery, are not defined here. So a member that declares a
capacity is given no job of this version, and no kernel of this version is `statistical`. A
member's kernel is graded:

| parity | granted when |
|---|---|
| `reference` | to the host's own reference kernels, and to nothing else |
| `bit-exact` | it gives every `settle` vector of this version's set (for the settle kernel), or every `chains` vector in one call each (for the sampling kernel), exactly |
| `uncertified` | anything else |

The host audits a kernel graded `bit-exact` as the first version's §7.3 says.

**What runs this version today.** The CPU reference alone. The GPU members (WebGPU, CUDA, Metal)
and the FPGA member read one cost for every cell: they run the first version's kernels only,
are certified on the first version's set only, and are passed over for a job of this version.
The FPGA member's grade names the set it is earned on: the first version's, as frozen on
2026-11-10 (§7). Nothing here claims any of them runs this version.

### 5.4. Verifying an answer

A job is of this version when its result's `protocol` or `schema` is `wai.quantum.landscape/2`.
A verifier holds it to the first version's rules (its §5.4), with:

- rule 2: the result's `protocol` and `schema` are each `wai.quantum.landscape/2`;
- rule 3: the request's `protocol` is `wai.quantum.landscape/2`, present;
- rule 6: each kernel is `wai.quantum.landscape2/settle` or `wai.quantum.landscape2/sample`,
  and no parity is `statistical`;
- rule 8: the member states no `capacity`;
- rule 10: the replay digest begins with this version's name (§3); `joules.kind` is `priced`,
  with `pj` a number of at least 0, for a `settle` or a `quench`, and `unpriced`, with `pj`
  null and `why` a string, not empty, for a `sample`; `metered` as the first version's.

Rule 13, a provider's job, is the first version's: a job of this version that ran on a
provider carries the same `provider`, `job` and `cost`
([quantum-providers §11.3](quantum-providers.md#113-what-the-client-checks-and-what-it-seals)).

A verifier that holds this text's reader reads the program with it, and states whether the
answer's energy and plan are the program's (`landscape.recomputed`), as the first version's
§5.4 says.

## 6. Conformance

`quantum-conformance/landscape/v2/vectors.json` is written by `wai-quantum landscape vectors
--protocol 2`, and a test holds the file to the code and to its digest (§7). Its exponential,
schedule and draws are the first version's, which that version's set pins.

- `settle`: whole workloads, starts and bounds, and the state, sweeps, ending, accumulates and
  state hash: costs of 0 recalling a stored pattern (the first version's move), a cost below 0
  at a field of 0 going to +, costs below 0 taking their fields' signs, each cell at its own
  threshold, a one-hot group and a 3×3 assignment that flip for ever from every cell at 0, an
  assignment at rest, a chain stopped at its bound and arriving, costs and fields at 2⁴⁰, and
  random workloads of mixed costs.
- `cells`: the cut points for fields from −17 to 17 at costs from −17 to 2, at five temperatures.
- `chains`: whole chains of the worked colouring and assignment, cooling and held hot, a quench,
  a one-hot group hot then cold, random workloads of mixed costs cooling and stopping hot, forty
  distinct costs, and costs and fields past 32 bits.
- `jobs`: every worked example at seed 1, with its truth, and requests that pin a rule each,
  refusals among them. Each worked example also states its `reach`: how a hundred seeds, from 1,
  end at the program's own plan.

The sampling kernel of this version is also held to its joint law over every state, on two landscapes of this
version among the eight of the first version's §7.4 (informative; `quantum-conformance/landscape/stage0/`).

The worked examples, at their own plans (each `solve restarts=8 steps=40`, the first version's
plan for its examples, but the settled one):

| example | variables | every arrangement checked | lowest | at lowest, solving it | 100 seeds |
|---|---|---|---|---|---|
| `colour-four`: two triangles sharing a side, three colours | 12 | 531,441 | −35 | 6 of 6 | 100 solved |
| `colour-five-ring`: an odd ring, three colours | 15 | 14,348,907 | −40 | 30 of 30 | 100 solved |
| `colour-six`: the first version's six regions, three colours | 18 | too many | (§2.2) | the 12 colourings | 100 solved |
| `colour-four-all-touching`: four regions, three colours | 12 | 531,441 | −36 | 0 of 24 | 100 failed, as it must |
| `assign-3x3` | 9 | 19,683 | −21 | 6 of 6 | 100 solved |
| `assign-4x4` | 16 | 43,046,721 | −48 | 24 of 24 | 100 solved |
| `assign-5x5` | 25 | too many | (§2.2) | the 120 assignments | 100 solved |
| `two-in-each-row-and-column`: exactly 2 in each row and column of 4×4 | 16 | 43,046,721 | −32 | 90 of 90 | 100 solved |
| `four-queens`: at most one in each row, column and diagonal, each queen worth 1 | 16 | 43,046,721 | −84 | 2 of 2 | 100 solved |
| `assign-3x3-settled`: the 3×3 assignment at temperature 0 | 9 | 19,683 | −21 | 6 of 6 | 100 failed: it never comes to rest |

Where every arrangement is too many to check, the lowest energy is still known: on states of +
and −, the energy above an answer that passes the check is the constraints' penalty (§2.2), 0
exactly where the check passes, and a state that holds a 0 is lowered by one move (§1); a test
holds both on random states. These are a few small instances, run on the reference at one plan
each; they say that these landscapes express their problems and that this plan reached their
lowest states, and nothing of larger instances or of any device's time.

## 7. Versioning, and the rule for the vectors

The protocol's name carries its version. Within `/2`: fields may be added to an answer, never
removed or given another meaning; the kernels' bits, the replay digest and the conformance set
do not change. The set is frozen: the code pins its BLAKE3 digest
(`conformance2::VECTORS_2_BLAKE3`), a test fails on any difference, and a change of any kind,
an entry changed, removed or added, is a new version of the protocol with kernels of its own.
Every grade names the set it was earned on.

The first version's set is held the same way from 2026-11-10 (`conformance2::VECTORS_1_BLAKE3`,
the BLAKE3 of `quantum-conformance/landscape/vectors.json` as it stood on main that day; its
sha256 `1da13d2570eb5b1367d3017b465e1b6a199429210def0c4300dbc403413e3a8e`). The first version's
§9 says how that set changed before then, and why.

The words of a sentence and a host's `label` are not part of the protocol. §4.3's rule is: a
host MAY price at a rate of its own, with its evidence in this repository named, and never below
what this project's own hardware measured for the same work.

## 8. What does not run on this version

- **At most K for K above 1, at least K, and ranges.** An energy of pairs over a group's count
  is a quadratic in that count, which is 0 at no more than two counts. They need extra
  variables, which this version does not add.
- **Weights on choices, and sizes.** A constraint's weight is fixed by its couplings (§2.2), so
  a preference larger than its step outvotes it: an assignment with costs on its cells runs
  only while every cost is below the step. Couplings still keep only a sign, so problems whose
  sizes matter (the first version's two equal piles) still do not run.
- **A constraint at temperature 0.** The deterministic settle still flips between two states
  and never rests (`assign-3x3-settled`).
- **A pair two constraints share**, such as a preference on a pair inside a cardinality group.
- **Any member but the reference** (§5). A provider carries a job of this version where its
  description lists it (the provider protocol's §11.1,
  [quantum-providers](quantum-providers.md#11-energy-landscape-jobs)): a client sends none to
  a device that does not, and says why.