lqcloud 0.4.2__tar.gz

lqcloud-0.4.2/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

lqcloud-0.4.2/MANIFEST.in

@@ -0,0 +1,17 @@
+# sdist 内容策略：仅打包 lqcloud 源码 + 必要元数据（LICENSE / README）。
+# 完整 SDK 文档已发布在云平台网站（backend/docs_sdk）；examples/、docs/、
+# CHANGELOG.md（含后端/服务端内部开发信息）、CONTRIBUTING.md、QUICKSTART.md
+# 仅保留在仓库中，不随 sdist 发布。
+prune server
+prune tests
+prune logs
+prune plans
+prune examples
+prune docs
+
+global-exclude __pycache__
+global-exclude *.py[cod]
+
+include LICENSE
+include README.md
+include README.en.md

lqcloud-0.4.2/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: lqcloud
+Version: 0.4.2
+Summary: A Cloud Quantum Computing SDK
+Author: Lianming LQ
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: requests>=2.31.0
+Provides-Extra: visualization
+Requires-Dist: matplotlib>=3.3.0; extra == "visualization"
+Provides-Extra: qiskit
+Requires-Dist: qiskit>=1.0.0; extra == "qiskit"
+Requires-Dist: qiskit-aer>=0.13.0; extra == "qiskit"
+Provides-Extra: full
+Requires-Dist: matplotlib>=3.3.0; extra == "full"
+Requires-Dist: qiskit>=1.0.0; extra == "full"
+Requires-Dist: qiskit-aer>=0.13.0; extra == "full"
+Requires-Dist: networkx>=2.5; extra == "full"
+Provides-Extra: pennylane
+Requires-Dist: pennylane>=0.30.0; extra == "pennylane"
+Provides-Extra: ci
+Requires-Dist: pytest>=7.0.0; extra == "ci"
+Requires-Dist: pytest-timeout>=2.0.0; extra == "ci"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: pytest-timeout>=2.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
+Requires-Dist: black>=22.0.0; extra == "dev"
+Requires-Dist: flake8>=4.0.0; extra == "dev"
+Requires-Dist: mypy>=0.950; extra == "dev"
+Dynamic: license-file
+
+# LQCloud SDK
+
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+![Version](https://img.shields.io/badge/version-0.4.2-brightgreen.svg)
+
+LQCloud SDK 是连接 LQCloud 量子云平台的 Python 开发工具包。通过本 SDK，您可以构建量子线路、提交云端任务（线路 / 波形 / 脚本），并获取执行结果。
+
+> **关于 API 风格**：LQCloud SDK 的线路编排接口（`QuantumCircuit` / `h` / `cx` / `measure_all` / `Parameter` / …）在命名与用法上**借鉴 Qiskit 风格**，便于熟悉 Qiskit 的用户上手；但 SDK 自身**不依赖 Qiskit**——核心运行时只需 `numpy` 与 `requests` 两个轻量依赖。`qiskit` 仅作为可选互操作组件存在。
+
+---
+
+## 核心功能
+
+### 量子线路构建
+
+- **Native 门**（QPU 原生门，一对一映射硬件）
+  - Pauli / Hadamard 族：`H`, `HY`, `X`, `Y`, `Z`, `MX`, `MY`, `MZ`, `I`
+  - 半角旋转：`XHalf`, `YHalf`, `MXHalf`, `MYHalf`, `XYHalf`, `MXYHalf`, `MXMYHalf`, `XMYHalf`
+  - Z 旋转族：`S`, `Sdg`, `T`, `RZ(θ)`
+  - 两比特：`CZ`（原生）
+  - 2 态读出脉冲：`X21`, `X21Half`（`|1⟩↔|2⟩` 子空间）
+  - 测量 / 重置 / 控制：`Measure`, `Reset`, `Barrier`, `Delay`
+  - 手动 DD 门：`timeanchor` / `dd`（在成对时间锚点间精确插入 DD 脉冲）
+- **Composite 门**（便捷门，**提交前自动分解为 native 门**）
+  - 单比特：`RX(θ)`, `RY(θ)`, `U(θ,φ,λ)`, `P(θ)`, `Tdg`, `SX`, `SXdg`
+  - 两比特：`CX`(CNOT), `CY`, `CH`, `SWAP`, `iSWAP`, `CRZ(θ)`, `CRX(θ)`, `CRY(θ)`, `CP(θ)`
+  - 三比特：`CCX`(Toffoli), `CCZ`
+  - 任意单比特 SU(2) 门：`qc.su2(matrix, q)` / `qc.unitary(matrix, q)`
+- **统一测量接口**：使用 `measure` / `measure_all`，SDK 按后端能力自动改写（必要时展开为 `X21 + Measure`）
+- **多重测量（Multi-Window）**：同一 qubit 可被多次测量，每次结果独立映射到不同 clbit，支持重复码 / 表面码 stabilizer 线路
+- **参数化线路**：`Parameter` + `assign_parameters()`；提交时仍有未绑定参数会在客户端立即抛 `CircuitError`
+- **线路工具**：`qc.decompose()`、`qc.depth()`、`qc.draw()`（ASCII 绘图，支持经典寄存器与多比特门连线）
+
+### 云端任务提交
+
+- **线路模式**：提交 `QuantumCircuit` 到云端 QPU，序列化时自动 `decompose()`
+- **波形模式**：`backend.run_wave(waves, shots=..., result_format="counts"|"memory"|"raw")` 直接上传原始脉冲波形；`raw` 返回未经态判别的原始 IQ 数据
+- **批量线路**：`backend.run([qc1, qc2, ...], shots=...)` 把多条线路作为同一云端任务提交，单次最多 64 条（`MAX_BATCH_CIRCUITS`）
+- **shots 上限**：单次提交 `shots ≤ 50_000`，由**服务端**校验拦截（SDK 本身不做该范围强校验）
+- **指定物理比特**：`initial_layout=[3, 4]`（语义同 Qiskit）
+- **读出矫正（Readout Correction）**：`qc.set_readout_correction(True)` / `backend.run(..., readout_correction=True)`，矫正失败自动降级
+- **动态解耦（DD）**：空闲窗口自动插入 CPMG / CP π 脉冲；线路级与提交级写法均支持
+- **网络健壮性**：瞬态错误自动指数退避重试；自动携带 `Idempotency-Key` 防重复入队
+- **提交前本地校验**：缺测量 / 缺 barrier / 测量类型混用等会直接抛 `CircuitError`
+- 自动按测量比特数切换 counts / memory 结果格式
+
+### 任务管理
+
+- 状态查询（`JobStatus`：`QUEUED` / `RUNNING` / `COMPLETED` / `FAILED` / `CANCELLED`）
+- 阻塞等待并获取结果（支持 `timeout` / 静默模式）
+- 队列位置查询、任务取消 `job.cancel()`
+- 失败任务携带 `error_type`，便于编程化重试
+
+### 结果访问
+
+`get_counts()` · `get_memory()` · `get_iq_data()`（波形 raw）· `get_probabilities()` · `get_dynamic_decoupling_info()`；Jupyter 自动渲染结果表格（`_repr_html_()`）
+
+### 异常体系
+
+`LQCloudError`（基类）、`AuthenticationError`、`BackendNotFoundError`、`JobError`、`JobTimeoutError`、`CircuitError`，支持精确与粗粒度捕获
+
+### 轻量依赖 & 日志
+
+核心依赖仅 `numpy` + `requests`，`qiskit` / `matplotlib` / `networkx` 均为可选；库内统一使用 `logging.getLogger("lqcloud")`，可自行配置日志级别。
+
+---
+
+## 安装
+
+```bash
+pip install lqcloud
+```
+
+可选依赖：
+
+```bash
+pip install lqcloud[visualization]   # matplotlib 直方图可视化
+pip install lqcloud[qiskit]          # Qiskit 互操作
+pip install lqcloud[full]            # matplotlib + qiskit + networkx
+```
+
+验证安装：
+
+```bash
+python -c "import lqcloud; print(lqcloud.__version__)"
+```
+
+---
+
+## 快速开始
+
+### 1. 配置认证
+
+```python
+from lqcloud import save_account
+
+save_account(
+    api_key="your_api_key_here",
+    url="https://cloud.logicalqubit.com",   # 或替换为实际服务器地址
+)
+```
+
+配置保存在 `~/.lqcloud/config.json`，之后无需重复配置。也可改用环境变量 `LQCLOUD_API_KEY`（或 `LQCLOUD_TOKEN`）+ `LQCLOUD_URL`；无终端环境（CI / Docker）可传 `LQCloudProvider(interactive=False)`，无凭证时直接抛 `AuthenticationError`。
+
+### 2. 提交量子线路任务
+
+```python
+from lqcloud import LQCloudProvider, QuantumCircuit
+
+provider = LQCloudProvider()
+backend = provider.get_backend("QZ02")
+
+qc = QuantumCircuit(2, 2)
+qc.h(0)
+qc.cx(0, 1)        # CX 会被自动分解为 native 门
+qc.barrier()       # 计算与读出窗口的分隔
+qc.measure_all()
+
+job = backend.run(qc, shots=1000)
+result = job.result()
+print(result.get_counts())   # {'00': 503, '11': 497}
+```
+
+### 3. 批量线路提交
+
+```python
+jobs = backend.run([qc1, qc2, qc3], shots=2000)   # 单次最多 64 条
+results = jobs.result()
+results[0].get_counts()       # 每个子项仍是 Result，全部老 API 可用
+```
+
+### 4. 异常处理
+
+```python
+from lqcloud import LQCloudError, JobError, JobTimeoutError
+
+try:
+    result = job.result(timeout=300)
+except JobTimeoutError:
+    job.cancel()
+except JobError as e:
+    print(f"Job failed: {e}")
+except LQCloudError as e:
+    print(f"SDK error: {e}")
+```
+
+> 完整的 API 文档、快速入门与示例代码发布在 **LQCloud 云平台文档中心**。
+
+---
+
+## 依赖
+
+| 包 | 用途 |
+|----|------|
+| `numpy`, `requests` | 必需（核心运行时） |
+| `matplotlib` | 可选，直方图可视化 |
+| `qiskit`, `qiskit-aer` | 可选，Qiskit 互操作 |
+| `networkx` | 可选，拓扑可视化 |
+
+Python 版本要求：**≥ 3.10**
+
+---
+
+## 许可证
+
+本项目采用 Apache License 2.0（见随包附带的 LICENSE 文件）。

lqcloud-0.4.2/README.en.md

@@ -0,0 +1,167 @@
+# LQCloud SDK
+
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+![Version](https://img.shields.io/badge/version-0.4.2-brightgreen.svg)
+
+LQCloud SDK is the Python client library for the LQCloud quantum cloud platform. With it you can build quantum circuits, submit cloud jobs (circuit / waveform / script), and retrieve execution results.
+
+> **API style**: LQCloud SDK's circuit-building API (`QuantumCircuit` / `h` / `cx` / `measure_all` / `Parameter` / …) **follows Qiskit conventions** so Qiskit users feel at home — yet the SDK **does not depend on Qiskit**. The core runtime needs only `numpy` and `requests`. `qiskit` is an optional interop component.
+
+---
+
+## Features
+
+### Circuit construction
+
+- **Native gates** (map 1:1 to hardware)
+  - Pauli / Hadamard family: `H`, `HY`, `X`, `Y`, `Z`, `MX`, `MY`, `MZ`, `I`
+  - Half-angle rotations: `XHalf`, `YHalf`, `MXHalf`, `MYHalf`, `XYHalf`, `MXYHalf`, `MXMYHalf`, `XMYHalf`
+  - Z-rotation family: `S`, `Sdg`, `T`, `RZ(θ)`
+  - Two-qubit: `CZ` (native)
+  - 2-state readout pulses: `X21`, `X21Half` (`|1⟩↔|2⟩` subspace)
+  - Measure / reset / control: `Measure`, `Reset`, `Barrier`, `Delay`
+  - Manual DD gates: `timeanchor` / `dd` (precise DD pulses between paired time anchors)
+- **Composite gates** (**auto-decomposed into native gates before submission**)
+  - Single-qubit: `RX(θ)`, `RY(θ)`, `U(θ,φ,λ)`, `P(θ)`, `Tdg`, `SX`, `SXdg`
+  - Two-qubit: `CX`(CNOT), `CY`, `CH`, `SWAP`, `iSWAP`, `CRZ(θ)`, `CRX(θ)`, `CRY(θ)`, `CP(θ)`
+  - Three-qubit: `CCX`(Toffoli), `CCZ`
+  - Arbitrary single-qubit SU(2): `qc.su2(matrix, q)` / `qc.unitary(matrix, q)`
+- **Unified measure interface**: use `measure` / `measure_all`; the SDK rewrites per backend capability (expanding to `X21 + Measure` when needed)
+- **Multi-window measurement**: a single qubit can be measured multiple times, each mapped to a distinct clbit — enables repetition-code / surface-code stabiliser circuits
+- **Parametrised circuits**: `Parameter` + `assign_parameters()`; unbound parameters raise `CircuitError` at submission
+- **Circuit tools**: `qc.decompose()`, `qc.depth()`, `qc.draw()` (ASCII drawer, supports classical registers and multi-qubit wiring)
+
+### Cloud job submission
+
+- **Circuit mode**: submit a `QuantumCircuit` to the cloud QPU; `decompose()` runs automatically on serialisation
+- **Waveform mode**: `backend.run_wave(waves, shots=..., result_format="counts"|"memory"|"raw")` uploads raw pulse waveforms; `raw` returns unclassified IQ data
+- **Batch circuits**: `backend.run([qc1, qc2, ...], shots=...)` submits multiple circuits as one cloud job, up to 64 per submission (`MAX_BATCH_CIRCUITS`)
+- **Shots ceiling**: `shots ≤ 50_000`, enforced **server-side** (the SDK does not strongly validate this range)
+- **Pin physical qubits**: `initial_layout=[3, 4]` (Qiskit semantics)
+- **Readout correction (RC)**: `qc.set_readout_correction(True)` / `backend.run(..., readout_correction=True)`, with graceful fallback
+- **Dynamic decoupling (DD)**: auto-inserts CPMG / CP π-pulses in idle windows; circuit-level and submission-level forms both supported
+- **Network resilience**: automatic exponential back-off retry; `Idempotency-Key` prevents duplicate enqueuing
+- **Pre-submission local validation**: missing measurement / barrier or mixed measure kinds raise `CircuitError`
+- Auto-selects counts / memory result format based on the number of measured qubits
+
+### Job management
+
+- Status query (`JobStatus`: `QUEUED` / `RUNNING` / `COMPLETED` / `FAILED` / `CANCELLED`)
+- Blocking wait + result retrieval (supports `timeout` / quiet mode)
+- Queue-position query and cancellation via `job.cancel()`
+- Failed jobs carry `error_type` for programmatic retries
+
+### Result access
+
+`get_counts()` · `get_memory()` · `get_iq_data()` (waveform raw) · `get_probabilities()` · `get_dynamic_decoupling_info()`; Jupyter auto-renders result tables (`_repr_html_()`)
+
+### Exception hierarchy
+
+`LQCloudError` (base), `AuthenticationError`, `BackendNotFoundError`, `JobError`, `JobTimeoutError`, `CircuitError` — supports precise and coarse-grained catching
+
+### Lightweight deps & logging
+
+Core dependencies are just `numpy` + `requests`; `qiskit` / `matplotlib` / `networkx` are optional. Logging uses `logging.getLogger("lqcloud")` and is user-configurable.
+
+---
+
+## Installation
+
+```bash
+pip install lqcloud
+```
+
+Optional extras:
+
+```bash
+pip install lqcloud[visualization]   # matplotlib histogram plotting
+pip install lqcloud[qiskit]          # Qiskit interop
+pip install lqcloud[full]            # matplotlib + qiskit + networkx
+```
+
+Verify:
+
+```bash
+python -c "import lqcloud; print(lqcloud.__version__)"
+```
+
+---
+
+## Quick start
+
+### 1. Configure authentication
+
+```python
+from lqcloud import save_account
+
+save_account(
+    api_key="your_api_key_here",
+    url="https://cloud.logicalqubit.com",   # or your actual server
+)
+```
+
+Credentials are stored in `~/.lqcloud/config.json`. You can also use environment variables `LQCLOUD_API_KEY` (or `LQCLOUD_TOKEN`) + `LQCLOUD_URL`; in headless environments (CI / Docker) pass `LQCloudProvider(interactive=False)` to raise `AuthenticationError` instead of blocking on input.
+
+### 2. Submit a circuit job
+
+```python
+from lqcloud import LQCloudProvider, QuantumCircuit
+
+provider = LQCloudProvider()
+backend = provider.get_backend("QZ02")
+
+qc = QuantumCircuit(2, 2)
+qc.h(0)
+qc.cx(0, 1)        # CX is auto-decomposed into native gates
+qc.barrier()       # separates compute and readout windows
+qc.measure_all()
+
+job = backend.run(qc, shots=1000)
+result = job.result()
+print(result.get_counts())   # {'00': 503, '11': 497}
+```
+
+### 3. Batch circuit submission
+
+```python
+jobs = backend.run([qc1, qc2, qc3], shots=2000)   # up to 64 per submission
+results = jobs.result()
+results[0].get_counts()       # each child is still a Result with the full API
+```
+
+### 4. Exception handling
+
+```python
+from lqcloud import LQCloudError, JobError, JobTimeoutError
+
+try:
+    result = job.result(timeout=300)
+except JobTimeoutError:
+    job.cancel()
+except JobError as e:
+    print(f"Job failed: {e}")
+except LQCloudError as e:
+    print(f"SDK error: {e}")
+```
+
+> Full API docs, the quick-start guide, and example code are published in the **LQCloud cloud platform docs center**.
+
+---
+
+## Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `numpy`, `requests` | required (core runtime) |
+| `matplotlib` | optional, histogram plotting |
+| `qiskit`, `qiskit-aer` | optional, Qiskit interop |
+| `networkx` | optional, topology plotting |
+
+Python version: **≥ 3.10**
+
+---
+
+## License
+
+This project is licensed under the Apache License 2.0 (see the LICENSE file bundled with the package).