# Capabilities and status

CUDA-Q Logical reports its own status the way it reports evidence: three-way,
and only against executable artifacts. A capability is **shipped** when it is
part of the installed `cudaq.logical` package, and **exercised** only when a
shipped test or example executes it — the `lit`/`FileCheck` suites and the
`pytest` suite (which runs every Python example under
`preview/logical/examples/`) are the evidence. A capability that is neither is
**out of scope**: a deliberate boundary, stated here, that fails closed instead
of approximating past an implemented edge.

## What the product is

CUDA-Q Logical is a resource-estimation toolkit for fault-tolerant quantum
computing. A program is refined through four strict semantic stages — **P0**
unplaced logical, **P1** placed logical, **P2** QEC realization, and **P3**
physical event graph and schedule. The estimation ladder has four tiers:
`Tier.LOGICAL`, `Tier.STATIC`, `Tier.ANALYTICAL`, and `Tier.SCHEDULE`. Stim
circuit text is the interchange emission target from a verified P2 gadget.

## Subsystem status

Every row cites its exercising evidence in this repository.

| Subsystem                                                                                                                                               | Status             | Exercised by                                                                                                           |
| ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| Compiler foundation — immutable `Build`, typed stages/facets, serialization and clean-process replay                                                    | shipped, exercised | `examples/standalone/01_logical_placement.py`; provenance fail-closed tests                                             |
| P0 authoring and logical estimation — `@program`, linear values, `Tier.LOGICAL`                                                                         | shipped, exercised | `examples/standalone/00_logical_program.py`, `examples/00_logical_resource_estimate.py`                                 |
| P1 placement — `@machine`, regions/capabilities, constraints, and witnesses                                                                             | shipped, exercised | `examples/standalone/01_logical_placement.py`; placement tests                                                          |
| P2 codes and gadgets — `@code` validation, catalog, `@gadget` with `implements=`, typed records                                                         | shipped, exercised | `examples/standalone/02_code_and_gadget.py`, `examples/04_carbon_code.py`; record-boundary tests                        |
| Gadget verification — code-automorphism and kernel-backed objective matching, fail-closed claims                                                       | shipped, exercised | `examples/04_carbon_code.py`; verifier-error lit suites                                                                |
| Protocols — `@protocol`, typed resources, postselection, bounded retry, 15-to-1 distillation                                                            | shipped, exercised | `examples/standalone/03_magic_state_distillation.py`, `examples/standalone/05_gidney_ekera_lookup_addition.py`; tests   |
| Clifford+T synthesis — rotation lowering with provenance                                                                                                | shipped, exercised | `examples/01_clifford_t_resource_estimate.py`, `examples/03_fermi_hubbard.py`                                           |
| CUDA-Q ingress — `@cudaq.kernel` programs through CUDA-Q Logical targets                                                                                | shipped, exercised | all six top-level numbered examples                                                                                    |
| Static P2 estimation — gadget/operation counts with folding                                                                                             | shipped, exercised | `examples/02_surface_code_resource_estimate.py`, `examples/standalone/03_magic_state_distillation.py`                   |
| P3 physical lowering, routing, native legalization, and scheduling                                                                                      | shipped, exercised | `examples/04_carbon_code.py`, `examples/standalone/04_physical_schedule.py`, `examples/standalone/05_gidney_ekera_lookup_addition.py` |
| Analytical and schedule estimation                                                                                                                      | shipped, exercised | `examples/02_surface_code_resource_estimate.py`, `examples/standalone/04_physical_schedule.py`, `examples/standalone/05_gidney_ekera_lookup_addition.py` |
| Paper-specific Gidney–Ekerå RSA-2048 projection                                                                                                         | shipped, exercised | `examples/05_gidney_ekera.py`                                                                                          |
| Stim text emission — the `--fabric-to-stim` translation                                                                                                 | shipped, exercised | `examples/mlir/stim_memory.mlir` via `qlx-translate`; Stim-emission tests                                               |

## Present but not yet exercised

These APIs exist in the package but carry no executed test or example in this
release, so the documentation does not teach them yet: dynamic codes
(`MeasurementPhase`, `EncodingEpoch`), code switching (`PatchTransform`),
concatenation (`cudaq.logical.codes.Concatenated`), meta-checks
(`cudaq.logical.codes.MetaChecks`), and P2 block requests
(`cudaq.logical.codes.qec_block`). Treat them as preview surface: use them at
your own risk until exercised evidence lands.

## Documented boundaries (all fail closed)

**There are no detector, observable, detector-error-model, decoder, or sampling
semantics.** P3 retains typed physical error and timing *assumptions* so that
`Tier.ANALYTICAL` and `Tier.SCHEDULE` can cost a realization — that is a
parameter surface, not a noise model. CUDA-Q Logical does not annotate
detectors or observables, generate or compose detector error models, sample
circuits, or decode results. Those studies begin downstream of the emitted
Stim text, in the Stim ecosystem.

**Stages stop at P3.** P3 represents physical carriers, routing, native events,
and schedules. It remains a compiler and estimation artifact: CUDA-Q Logical
does not submit a physical schedule to hardware or provide a runtime execution
service for it.

**No simulator plugin surface.** Nothing in the package consumes or executes
physical simulations.

**The native P1 placer is a subset.** `qlx-to-lvm` is a deterministic first-fit
placement for explicitly machine-scoped, inlined programs; the Python placement
solver (`cudaq.logical.compiler.place`) is the rich path. The native pass fails
on inputs outside the shared supported subset rather than approximating.

**Stim emission is terminal and checked.** The `--fabric-to-stim` translation
accepts a verified P2 entry gadget. Emission never invents an implementation
that selection did not link.

**Rotation synthesis is explicit, not automatic.**
`cudaq.logical.compiler.synthesize` legalizes a logical program to a named gate
set (Clifford+T, example 01) under an operator-norm `precision=` bound;
unsupported gate sets are rejected with a `ValueError` rather than
approximated.

**Paper-specific projections are labeled as such.** Example 05's default
Gidney–Ekerå path combines compiler-counted logical resources with explicit
paper equations. Its `--physical` path instead performs P3 compilation and
scheduling. Neither path simulates or executes the workload.