Metadata-Version: 2.4
Name: flagquantum-compiler-qsteed
Version: 0.2.0
Summary: QSteed circuit compiler plugin for FlagQuantum
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/FlagQuantum/FlagQuantum-Compiler-QSteed
Project-URL: Issues, https://github.com/FlagQuantum/FlagQuantum-Compiler-QSteed/issues
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: flagquantum>=0.2
Requires-Dist: networkx>=2.6.3
Requires-Dist: numpy<2,>=1.20.3
Requires-Dist: pyquafu==0.4.4
Requires-Dist: scipy>=1.8.1
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Dynamic: license-file

# FlagQuantum Compiler QSteed

`flagquantum-compiler-qsteed` is an independently installed circuit compiler
plugin for FlagQuantum. It translates FlagQuantum `CircuitIR` to a PyQuafu
`QuantumCircuit`, invokes the vendored QSteed compiler core, and translates the
compiled circuit back to `CircuitIR`.

The first release deliberately supports one closed, testable slice:

- static `h`, `x`, `rx`, `ry`, `rz`, and `cx` instructions with numeric angles;
- basis lowering to a selected subset of those gates, with topology routing on
  the fixed six-gate basis;
- an optional undirected coupling map over the circuit's existing wires;
- deterministic QSteed basis lowering and SABRE routing;
- restoration of QSteed's final physical layout to FlagQuantum's logical wire
  order.
- Quafu calibration targets with automatic or explicitly ordered physical
  subgraph selection and a `target_qubits` result; physical identifiers never
  replace logical QASM wires.

Measurements, observables, symbolic parameters, custom matrices, dynamic
operations, additional target fields, and larger physical topologies are
rejected. There is no compiler substitution or fallback. Omitting
`coupling_map` explicitly requests basis compilation without topology routing.
For a Quafu `chip_info` target, omitting `target_qubits` lets QSteed choose the
subgraph. Supplying it locks the logical-to-physical order after existence,
uniqueness, and connectivity validation; the plugin never substitutes another
mapping.

## Installation

Install the plugin directly; pip resolves FlagQuantum and the compiler's small
runtime dependency set automatically:

```bash
python -m pip install flagquantum-compiler-qsteed==0.2.0
```

The plugin requires FlagQuantum `>=0.2`. It privately vendors the verified
compiler-only closure of QSteed `0.2.3+quafu.sqc`; users do not install QSteed,
QuarkCircuit, QuarkStudio, a database, or a web service. The copied source,
upstream commit, license, and local namespace changes are recorded in
[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) and the packaged provenance
file.

Python 3.10–3.12 are the supported release range and are checked in CI against
the oldest supported FlagQuantum release and current FlagQuantum `main`.

For development from this repository, install FlagQuantum as above, then run:

```bash
python -m pip install -e ".[test]"
python -m pytest -q
```

Version 0.2.0 removes the external QSteed installation step while retaining the
same compiler behavior and provenance.

## Compile a circuit

This offline example needs no provider credentials and submits no hardware job:

```python
import flagquantum as fq

circuit = fq.Circuit(3).h(0).cx(0, 2)
compiled = fq.compile(
    circuit,
    compiler="qsteed",
    target={
        "basis_gates": ("h", "x", "rx", "ry", "rz", "cx"),
        "coupling_map": ((0, 1), (1, 2)),
    },
)
print(compiled.instructions)
```

See [release preparation](RELEASING.md) for publication prerequisites and
artifact checks.

## Advanced extension lifecycle

```python
from flagquantum.ecosystem.extensions import (
    CapabilityRequest,
    ExtensionConfig,
    discover_extensions,
)

import flagquantum as fq

source_ir = fq.Circuit(3).h(0).cx(0, 2).to_ir()
registry = discover_extensions("compiler")
handle = registry.negotiate(
    "compiler",
    "qsteed",
    CapabilityRequest(required=frozenset({"circuit_ir"})),
)
handle.start(ExtensionConfig())
try:
    compiled = handle.invoke(
        "compile",
        source_ir,
        target={
            "basis_gates": ("h", "x", "rx", "ry", "rz", "cx"),
            "coupling_map": ((0, 1), (1, 2)),
        },
    )
finally:
    handle.close()
```

QSteed treats the coupling graph as bidirectional in this compiler path. The
plugin therefore validates two-wire instructions against undirected edges.
