Metadata-Version: 2.5
Name: quicke-states
Version: 0.1.0
Summary: Verified, hardware-aware Dicke-state circuit synthesis and optimization for Cirq
Project-URL: Homepage, https://github.com/wwwillott/quicke-states
Project-URL: Repository, https://github.com/wwwillott/quicke-states
Project-URL: Issues, https://github.com/wwwillott/quicke-states/issues
Author: DuQuantum
License: BSD 3-Clause License
        
        Copyright (c) 2026, DuQuantum contributors
        
        Redistribution and use in source and binary forms, with or without
        modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice,
           this list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its
           contributors may be used to endorse or promote products derived from
           this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
        ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
        LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
        CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
        SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
        INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
        CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
        ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
        POSSIBILITY OF SUCH DAMAGE.
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Requires-Dist: cirq-core<2,>=1.4
Requires-Dist: numpy>=1.26
Provides-Extra: dev
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: notebooks
Requires-Dist: ipykernel>=6; extra == 'notebooks'
Requires-Dist: jupyter>=1.1; extra == 'notebooks'
Provides-Extra: willow
Requires-Dist: cirq-google<2,>=1.4; extra == 'willow'
Description-Content-Type: text/markdown

# Quicke States

`quicke-states` is a Cirq library for verified Dicke-state circuit synthesis,
optimization, hardware placement, and reproducible benchmarking.

The compiler is deliberately explicit about equivalence:

- **unitary-safe passes** preserve a circuit on every input;
- **state-preparation optimization** may replace a circuit when both prepare
  the same declared Dicke state from the all-zero input;
- unsupported large or arbitrary circuits are reported as unverified rather
  than silently treated as exact.

## Installation

From the public source repository:

```bash
pip install "git+https://github.com/wwwillott/quicke-states.git"
```

PyPI publishing is the next step. After that, the same package will also
install as:

```bash
pip install quicke-states
```

For a source checkout, Willow support and development tools are optional:

```bash
pip install -e ".[willow,dev]"
```

## Compile a Dicke state

```python
from dicke_compiler import compile_dicke

result = compile_dicke(8, 4, objective="depth")

print(result.circuit)
print(result.after_metrics)
print(result.verification)
```

The default output uses `cirq.LineQubit` with full CZ and
`cirq.PhasedXZGate` operations.

## Optimize an existing preparation

```python
from dicke_compiler import DickeTarget, optimize_dicke

result = optimize_dicke(
    existing_circuit,
    DickeTarget(8, 4),
    output_qubits=ordered_output_qubits,
    equivalence="state_preparation",
    objective="cz_depth",
)
```

The result records its selected family, applied passes, before/after metrics,
runtime, and verification evidence.

## Register a research template

`CircuitTemplate` and `TemplateRegistry` let researchers add verified
state-preparation constructions without modifying compiler internals. The
compiler searches bounded graph embeddings, verifies the template when
feasible, and compares it with analytic generators under the selected
objective.

The packaged registry covers all 56 symmetric challenge targets
`2 <= N <= 15`, `1 <= k <= floor(N/2)`. Each compact, offline-generated
template retains its source revision, a SHA-256 provenance hash, and its
known-valid Willow placement. The compiler validates the asset at import,
uses bounded fallback embedding on other coupling graphs, and still compares
templates with analytic generators. These are the best constructions
currently known to this project, not proofs of global optimality.

The analytic generator portfolio includes:

- `line_shallow`, the default reachable-subspace line construction;
- `line_basic`, an independent line baseline without shallow row rewrites;
- `scs_path`, an independent split-and-cyclic-shift reference family;
- topology-aware `w_tree` and `anti_w_tree` families selected automatically
  for one-excitation and one-hole targets.

The SCS family is intentionally opt-in because it is a useful independent
reference but is usually deeper after nearest-neighbor routing:

```python
result = compile_dicke(6, 3, methods=("scs_path",))
```

Current Willow comparison results are stored in
[`benchmarks/incumbent_comparison.csv`](benchmarks/incumbent_comparison.csv).
The reusable compiler matches the incumbent's 7-moment `D(4,2)` and 13-moment
`D(6,3)` circuits. Its selected `D(8,4)` template uses 21 moments instead of
23 at the same CZ count. These are reference results, not claims of global
optimality.

## Use a coupling graph and current calibration

```python
from dicke_compiler import (
    CalibrationData,
    HardwareTarget,
    compile_dicke,
)

calibration = CalibrationData(
    single_qubit=sq_errors,
    two_qubit=cz_errors,
    readout_zero=zero_to_one_errors,
    readout_one=one_to_zero_errors,
)
hardware = HardwareTarget.from_edges(
    device_qubits,
    device_couplers,
    calibration=calibration,
)

result = compile_dicke(
    6,
    3,
    hardware=hardware,
    objective="projected_survival",
)
```

Projected survival is an uncertainty-adjusted independent gate/readout proxy.
It is useful for ranking candidates on current calibration data, but it is not
presented as a measured hardware fidelity or competition score.

For Google Willow:

```python
from dicke_compiler import compile_dicke, willow_target

result = compile_dicke(6, 3, hardware=willow_target())
```

## Command line

```bash
quicke-states 6 3 --objective depth --print-circuit
```

## Guarantees and current limits

- Exact complex128 statevector verification defaults to absolute tolerance
  `1e-8` for up to 15 qubits.
- Built-in analytic generators can return an analytic provenance report above
  the exact-simulation limit.
- Version 0.1 supports deterministic unitary state preparation. Adaptive
  measurement/feed-forward synthesis is not yet part of the stable API.
- Candidate search is bounded and does not claim globally minimum depth.
- State-aware row templates are valid on their documented reachable
  subspaces, not as arbitrary full-unitary replacements.

## Research basis

The line synthesis is based on:

> A. Bärtschi and S. Eidenbenz, “Deterministic Preparation of Dicke States,”
> arXiv:1904.07358 (2019).

The default line constructions follow that paper's split-and-cyclic-shift
structure, then apply unitary-safe compression and hardware placement.

## Development

```bash
pytest
ruff check src tests
python benchmarks/benchmark_compiler.py --max-qubits 15 --domain half
```

Competition submission artifacts remain separate from the package. New
compiler results should be independently benchmarked before being copied into
those artifacts.

## License

BSD 3-Clause. See [`LICENSE`](LICENSE).
