microsoft/qdk
Publicmirrored fromhttps://github.com/microsoft/qdkAvailable
source/qdk_package/README.md
97lines · modecode
| 1 | # qdk |
| 2 | |
| 3 | The Quantum Development Kit (QDK) provides a single, cohesive Python entry point for compiling, simulating, and estimating resources for quantum programs (Q# and OpenQASM), with optional extras for visualization, cloud workflows, and Qiskit interoperability. |
| 4 | |
| 5 | ## Install |
| 6 | |
| 7 | To install the core functionality, which include Q\# \& OpenQASM simulation, compilation, and resource estimation support: |
| 8 | |
| 9 | ```bash |
| 10 | pip install qdk |
| 11 | ``` |
| 12 | |
| 13 | To include the Jupyter extra, which adds visualizations using Jupyter Widgets in the `qdk.widgets` submodule and syntax highlighting for Jupyter notebooks in the browser: |
| 14 | |
| 15 | ```bash |
| 16 | pip install "qdk[jupyter]" |
| 17 | ``` |
| 18 | |
| 19 | To add the Azure Quantum extra, which includes functionality for working with the Azure Quantum service in the `qdk.azure` submodule: |
| 20 | |
| 21 | ```bash |
| 22 | pip install "qdk[azure]" |
| 23 | ``` |
| 24 | |
| 25 | For Qiskit integration, which exposes Qiskit interop utilities in the `qdk.qiskit` submodule: |
| 26 | |
| 27 | ```bash |
| 28 | pip install "qdk[qiskit]" |
| 29 | ``` |
| 30 | |
| 31 | To easily install all the above extras: |
| 32 | |
| 33 | ```bash |
| 34 | pip install "qdk[all]" |
| 35 | ``` |
| 36 | |
| 37 | ## Quick Start |
| 38 | |
| 39 | ```python |
| 40 | from qdk import qsharp |
| 41 | |
| 42 | result = qsharp.run("{ use q = Qubit(); H(q); return MResetZ(q); }", shots=100) |
| 43 | print(result) |
| 44 | ``` |
| 45 | |
| 46 | To use widgets (installed via `qdk[jupyter]` extra): |
| 47 | |
| 48 | ```python |
| 49 | from qdk.qsharp import eval, run |
| 50 | from qdk.widgets import Histogram |
| 51 | |
| 52 | eval(""" |
| 53 | operation BellPair() : Result[] { |
| 54 | use qs = Qubit[2]; |
| 55 | H(qs[0]);CX(qs[0], qs[1]); |
| 56 | MResetEachZ(qs) |
| 57 | } |
| 58 | """) |
| 59 | results = run("BellPair()", shots=1000, noise=(0.005, 0.0, 0.0)) |
| 60 | Histogram(results) |
| 61 | ``` |
| 62 | |
| 63 | ## Public API Surface |
| 64 | |
| 65 | Submodules: |
| 66 | |
| 67 | - `qdk.qsharp` – exports the same APIs as the `qsharp` Python package |
| 68 | - `qdk.openqasm` – exports the same APIs as the `openqasm` submodule of the `qsharp` Python package. |
| 69 | - `qdk.estimator` – exports the same APIs as the `estimator` submodule of the `qsharp` Python package. |
| 70 | - `qdk.widgets` – exports the Jupyter widgets available from the `qsharp-widgets` Python package (requires the `qdk[jupyter]` extra to be installed). |
| 71 | - `qdk.azure` – exports the Python APIs available from the `azure-quantum` Python package (requires the `qdk[azure]` extra to be installed). |
| 72 | - `qdk.qiskit` – exports the same APIs as the `interop.qiskit` submodule of the `qsharp` Python package (requires the `qdk[qiskit]` extra to be installed). |
| 73 | |
| 74 | ### Top level exports |
| 75 | |
| 76 | For convenience, the following helpers and types are also importable directly from the `qdk` root (e.g. `from qdk import code, Result`). Algorithm execution APIs (like `run` / `estimate`) remain under `qdk.qsharp` or `qdk.openqasm`. |
| 77 | |
| 78 | | Symbol | Type | Origin | Description | |
| 79 | | -------------------- | -------- | --------------------------- | ------------------------------------------------------------------- | |
| 80 | | `code` | module | `qsharp.code` | Exposes operations defined in Q\# or OpenQASM | |
| 81 | | `init` | function | `qsharp.init` | Initialize/configure the QDK interpreter (target profile, options). | |
| 82 | | `set_quantum_seed` | function | `qsharp.set_quantum_seed` | Deterministic seed for quantum randomness (simulators). | |
| 83 | | `set_classical_seed` | function | `qsharp.set_classical_seed` | Deterministic seed for classical host RNG. | |
| 84 | | `dump_machine` | function | `qsharp.dump_machine` | Emit a structured dump of full quantum state (simulator dependent). | |
| 85 | | `Result` | class | `qsharp.Result` | Measurement result token. | |
| 86 | | `TargetProfile` | class | `qsharp.TargetProfile` | Target capability / profile descriptor. | |
| 87 | | `StateDump` | class | `qsharp.StateDump` | Structured state dump object. | |
| 88 | | `ShotResult` | class | `qsharp.ShotResult` | Multi-shot execution results container. | |
| 89 | | `PauliNoise` | class | `qsharp.PauliNoise` | Pauli channel noise model spec. | |
| 90 | | `DepolarizingNoise` | class | `qsharp.DepolarizingNoise` | Depolarizing noise model spec. | |
| 91 | | `BitFlipNoise` | class | `qsharp.BitFlipNoise` | Bit-flip noise model spec. | |
| 92 | | `PhaseFlipNoise` | class | `qsharp.PhaseFlipNoise` | Phase-flip noise model spec. | |
| 93 | |
| 94 | ## Telemetry |
| 95 | |
| 96 | This library sends telemetry. Minimal anonymous data is collected to help measure feature usage and performance. |
| 97 | All telemetry events can be seen in the source file [telemetry_events.py](https://github.com/microsoft/qdk/tree/main/source/pip/qsharp/telemetry_events.py). |
| 98 | |