jiuzhang-sdk 0.1.0__tar.gz

jiuzhang_sdk-0.1.0/.gitignore

@@ -0,0 +1,112 @@
+# ---------- Python ----------
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Build & dist
+build/
+dist/
+release/
+*.egg-info/
+*.egg
+*.whl
+*.tar.gz
+wheels/
+pip-wheel-metadata/
+share/python-wheels/
+
+# Virtual envs
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv/
+uv.lock.bak
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+
+# Type checkers & linters
+.mypy_cache/
+.ruff_cache/
+.pytype/
+.dmypy.json
+dmypy.json
+
+# Docs build
+docs/_build/
+site/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# ---------- IDE ----------
+.idea/
+.vscode/
+.claude/
+*.swp
+*.swo
+*~
+
+# ---------- OS ----------
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# ---------- 项目私密 ----------
+群聊记录/
+*.local.md
+.env
+.env.*
+!.env.example
+doc/~$*
+*.pptx
+Claude Conversations/
+
+# Python
+.eggs/
+
+# IDE
+remote/
+
+# Claude Code local settings
+.claude/settings.local.json
+# Python-generated files
+*.py[oc]
+*.egg-info
+
+# IDE
+
+# Database
+*.db
+*.sqlite
+*.sqlite3
+
+# Logs
+logs/
+*.log
+*.log.*
+
+# OS
+dataset/
+.claude
+
+debug/
+debug.ipynb
+.agents/
+.codex/
+
+# user
+/remote
+/daily_report

jiuzhang_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,269 @@
+Metadata-Version: 2.4
+Name: jiuzhang-sdk
+Version: 0.1.0
+Summary: Python SDK for the JiuZhang photonic quantum cloud platform
+Author: JiuZhang Quantum SDK Team
+License: Proprietary
+Keywords: gbs,jiuzhang,photonic,quantum,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.12
+Requires-Dist: httpx<0.29,>=0.27
+Requires-Dist: numpy>=1.26
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest-mock>=3; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: jupyter
+Requires-Dist: ipython>=8; extra == 'jupyter'
+Provides-Extra: local-gbs
+Requires-Dist: numpy<2,>=1.26; extra == 'local-gbs'
+Requires-Dist: scipy<1.14,>=1.10; extra == 'local-gbs'
+Requires-Dist: thewalrus==0.21.0; extra == 'local-gbs'
+Provides-Extra: local-ir
+Requires-Dist: numpy<2,>=1.26; extra == 'local-ir'
+Requires-Dist: quantum-blackbird==0.5.0; extra == 'local-ir'
+Requires-Dist: quantum-xir==0.2.2; extra == 'local-ir'
+Requires-Dist: scipy<1.14,>=1.10; extra == 'local-ir'
+Requires-Dist: thewalrus==0.21.0; extra == 'local-ir'
+Description-Content-Type: text/markdown
+
+# jiuzhang-sdk
+
+Python SDK for the JiuZhang photonic quantum cloud platform.
+
+The SDK provides two separate capability groups:
+
+| Capability | Uses the JiuZhang cloud platform | Result source | Typical use |
+| --- | --- | --- | --- |
+| Cloud GBS tasks | Yes | Executed by the JiuZhang cloud platform | Submit GBS experiments, poll status, parse returned results |
+| Local GBS sampling | No | Generated locally by numerical libraries | Teaching, prototyping, local validation, notebook demos |
+
+Cloud tasks can be submitted from local Python scripts or Jupyter notebooks. In this case, "local" only describes where the user runs the client code; the task itself is executed by the cloud platform.
+
+Local GBS sampling runs entirely on the user's machine and does not call the cloud API. Its results are generated by the local The Walrus numerical backend from the provided matrix and sampling parameters.
+
+## Installation
+
+Install the SDK:
+
+```bash
+pip install jiuzhang-sdk
+```
+
+Install local GBS math and sampling extras:
+
+```bash
+pip install "jiuzhang-sdk[local-gbs]"
+```
+
+Install local IR serialization extras:
+
+```bash
+pip install "jiuzhang-sdk[local-ir]"
+```
+
+## Cloud Credentials
+
+Before submitting a cloud task, prepare these values from the JiuZhang cloud workspace:
+
+| Value | Description |
+| --- | --- |
+| `api_key` | Authentication credential used in the `X-Jiuzhang-API-Key` request header |
+| `project_id` | Cloud project identifier used to associate tasks with a project |
+| `quantum_computer_id` | Cloud device code, for example `PH_QC_04` |
+
+Recommended environment variables:
+
+```bash
+export JIUZHANG_API_KEY="your-api-key"
+export JIUZHANG_PROJECT_ID="your-project-id"
+export JIUZHANG_QUANTUM_COMPUTER_ID="PH_QC_04"
+export JIUZHANG_BASE_URL="https://cloud.jiuzhangqt.com/api/v1"
+```
+
+## Cloud GBS Workflow
+
+```python
+from jiuzhang import CloudClient, GBSParams, parse_gbs_result
+
+client = CloudClient(
+    base_url="https://cloud.jiuzhangqt.com/api/v1",
+    api_key="your-api-key",
+)
+
+params = GBSParams(
+    project_id="EXP-demo-project",
+    quantum_computer_id="PH_QC_04",
+    mt=500,
+    pump_energy_nj=4.6,
+    squeezing_param=0.35,
+    task_name="GBS experiment",
+)
+
+estimate = client.estimate_runtime(
+    quantum_computer_id=params.quantum_computer_id,
+    mt_value=params.mt,
+    pump_energy_nj=params.pump_energy_nj,
+)
+
+task = client.submit_task(
+    project_id=params.project_id,
+    task_name=params.task_name,
+    quantum_computer_id=params.quantum_computer_id,
+    mt_value=params.mt,
+    pump_energy_nj=params.pump_energy_nj,
+    squeezing_param=params.squeezing_param,
+)
+
+task_id = task["data"]["task_id"]
+raw_result = client.get_result(task_id)
+result = parse_gbs_result(raw_result)
+
+print(result.status_name)
+print(result.sample_count)
+print(result.experimental_distribution)
+
+client.close()
+```
+
+One-call helper:
+
+```python
+result = client.run_gbs(params, poll_interval=2.0, timeout=300.0)
+print(result.status_name)
+```
+
+## Cloud API Methods
+
+| Method | Purpose |
+| --- | --- |
+| `CloudClient(base_url, api_key, timeout=30.0)` | Create an authenticated cloud API client |
+| `CloudClient.from_env()` | Create a client from `JIUZHANG_*` environment variables |
+| `estimate_runtime(quantum_computer_id, mt_value, pump_energy_nj)` | Estimate runtime before submitting a task |
+| `submit_task(project_id, task_name, quantum_computer_id, mt_value, pump_energy_nj, squeezing_param=None)` | Submit a cloud GBS task |
+| `get_result(task_id)` | Query a task result |
+| `run_experiment(...)` | Estimate, submit, poll, and return raw responses |
+| `estimate_gbs(params)` | Estimate using `GBSParams` |
+| `submit_gbs(params)` | Submit using `GBSParams` |
+| `run_gbs(params)` | Run the full workflow and return `GBSResult` |
+| `close()` | Close the underlying HTTP client |
+
+## Cloud Parameter Object
+
+```python
+from jiuzhang import GBSParams
+
+params = GBSParams(
+    project_id="EXP-demo-project",
+    quantum_computer_id="PH_QC_04",
+    mt=500,
+    pump_energy_nj=4.6,
+    squeezing_param=0.35,
+    task_name="GBS experiment",
+)
+```
+
+| Field | Description |
+| --- | --- |
+| `project_id` | Cloud project ID |
+| `quantum_computer_id` | Cloud device code |
+| `mt` | Pump pulse time-bin count, validated as `1..500` |
+| `pump_energy_nj` | Pump energy in nJ |
+| `squeezing_param` | Optional squeezing parameter |
+| `shots` | Optional shot count field |
+| `task_name` | Display name for the task |
+
+Helper methods:
+
+| Method | Purpose |
+| --- | --- |
+| `validate()` | Validate fields locally |
+| `input_mode_count()` | Return `3 * mt` |
+| `output_mode_count()` | Return `9 * (mt + 80)` |
+| `to_cloud_payload()` | Build a cloud payload dictionary |
+| `summary()` | Build a compact parameter summary |
+
+## Parsed Result Object
+
+`GBSResult` is returned by `run_gbs()` or by `parse_gbs_result(raw_result)`.
+
+| Field or property | Description |
+| --- | --- |
+| `task_id` | Cloud task ID |
+| `status_name` | Normalized task status |
+| `sample_count` | Returned sample count |
+| `result_map_points` | Probability distribution curves |
+| `experimental_distribution` | Experimental distribution points |
+| `ground_truth_distribution` | Reference distribution points |
+| `download_url` | Raw result download URL |
+| `raw` | Original response dictionary |
+
+## Local GBS Sampling
+
+Local GBS sampling does not call the cloud API. Results are generated on the user's machine by The Walrus from the adjacency matrix and sampling parameters.
+
+```python
+from jiuzhang.local.gbs import (
+    random_adjacency_matrix,
+    sample_gbs,
+    samples_to_distribution,
+)
+
+graph = random_adjacency_matrix(8, scale=0.16, seed=7)
+samples = sample_gbs(
+    graph,
+    shots=24,
+    mean_photon_count=1.0,
+    detector="pnr",
+    cutoff=4,
+    max_photons=12,
+    seed=123,
+)
+distribution = samples_to_distribution(samples)
+print(distribution)
+```
+
+| Function | Purpose |
+| --- | --- |
+| `random_adjacency_matrix(modes, scale=0.2, seed=None)` | Generate a symmetric adjacency matrix |
+| `sample_gbs(adjacency, shots=10, mean_photon_count=1.0, detector="pnr", cutoff=5, max_photons=30, seed=None, parallel=False)` | Generate local GBS samples |
+| `samples_to_distribution(samples)` | Convert samples into a normalized pattern distribution |
+
+## Local Math and IR Helpers
+
+```python
+from jiuzhang.local.gbs import (
+    GBSProgram,
+    dumps_ir,
+    hafnian,
+    loop_hafnian,
+    threshold_probability,
+    to_blackbird,
+    to_xir,
+    torontonian,
+)
+```
+
+| Function | Purpose |
+| --- | --- |
+| `hafnian(matrix, loop=False, approx=False, num_samples=1000, method="glynn")` | Compute the Hafnian of a square matrix |
+| `loop_hafnian(matrix, diagonal=None, reps=None, glynn=True)` | Compute the loop Hafnian |
+| `torontonian(matrix, recursive=True)` | Compute the Torontonian |
+| `threshold_probability(mean, covariance, pattern, hbar=2.0, atol=1e-10, rtol=1e-10)` | Compute a threshold detection probability |
+| `GBSProgram(modes, operations=(), name="gbs_program")` | Build a local GBS program |
+| `dumps_ir(program, format="json")` | Serialize a program to JSON, Blackbird, or XIR text |
+| `loads_ir(payload)` | Parse JSON local IR |
+| `to_blackbird(program)` | Serialize to Blackbird text |
+| `to_xir(program)` | Serialize to XIR text |
+
+## License
+
+Proprietary. Copyright 2026 JiuZhang Quantum. All rights reserved.

jiuzhang_sdk-0.1.0/README.md

@@ -0,0 +1,232 @@
+# jiuzhang-sdk
+
+Python SDK for the JiuZhang photonic quantum cloud platform.
+
+The SDK provides two separate capability groups:
+
+| Capability | Uses the JiuZhang cloud platform | Result source | Typical use |
+| --- | --- | --- | --- |
+| Cloud GBS tasks | Yes | Executed by the JiuZhang cloud platform | Submit GBS experiments, poll status, parse returned results |
+| Local GBS sampling | No | Generated locally by numerical libraries | Teaching, prototyping, local validation, notebook demos |
+
+Cloud tasks can be submitted from local Python scripts or Jupyter notebooks. In this case, "local" only describes where the user runs the client code; the task itself is executed by the cloud platform.
+
+Local GBS sampling runs entirely on the user's machine and does not call the cloud API. Its results are generated by the local The Walrus numerical backend from the provided matrix and sampling parameters.
+
+## Installation
+
+Install the SDK:
+
+```bash
+pip install jiuzhang-sdk
+```
+
+Install local GBS math and sampling extras:
+
+```bash
+pip install "jiuzhang-sdk[local-gbs]"
+```
+
+Install local IR serialization extras:
+
+```bash
+pip install "jiuzhang-sdk[local-ir]"
+```
+
+## Cloud Credentials
+
+Before submitting a cloud task, prepare these values from the JiuZhang cloud workspace:
+
+| Value | Description |
+| --- | --- |
+| `api_key` | Authentication credential used in the `X-Jiuzhang-API-Key` request header |
+| `project_id` | Cloud project identifier used to associate tasks with a project |
+| `quantum_computer_id` | Cloud device code, for example `PH_QC_04` |
+
+Recommended environment variables:
+
+```bash
+export JIUZHANG_API_KEY="your-api-key"
+export JIUZHANG_PROJECT_ID="your-project-id"
+export JIUZHANG_QUANTUM_COMPUTER_ID="PH_QC_04"
+export JIUZHANG_BASE_URL="https://cloud.jiuzhangqt.com/api/v1"
+```
+
+## Cloud GBS Workflow
+
+```python
+from jiuzhang import CloudClient, GBSParams, parse_gbs_result
+
+client = CloudClient(
+    base_url="https://cloud.jiuzhangqt.com/api/v1",
+    api_key="your-api-key",
+)
+
+params = GBSParams(
+    project_id="EXP-demo-project",
+    quantum_computer_id="PH_QC_04",
+    mt=500,
+    pump_energy_nj=4.6,
+    squeezing_param=0.35,
+    task_name="GBS experiment",
+)
+
+estimate = client.estimate_runtime(
+    quantum_computer_id=params.quantum_computer_id,
+    mt_value=params.mt,
+    pump_energy_nj=params.pump_energy_nj,
+)
+
+task = client.submit_task(
+    project_id=params.project_id,
+    task_name=params.task_name,
+    quantum_computer_id=params.quantum_computer_id,
+    mt_value=params.mt,
+    pump_energy_nj=params.pump_energy_nj,
+    squeezing_param=params.squeezing_param,
+)
+
+task_id = task["data"]["task_id"]
+raw_result = client.get_result(task_id)
+result = parse_gbs_result(raw_result)
+
+print(result.status_name)
+print(result.sample_count)
+print(result.experimental_distribution)
+
+client.close()
+```
+
+One-call helper:
+
+```python
+result = client.run_gbs(params, poll_interval=2.0, timeout=300.0)
+print(result.status_name)
+```
+
+## Cloud API Methods
+
+| Method | Purpose |
+| --- | --- |
+| `CloudClient(base_url, api_key, timeout=30.0)` | Create an authenticated cloud API client |
+| `CloudClient.from_env()` | Create a client from `JIUZHANG_*` environment variables |
+| `estimate_runtime(quantum_computer_id, mt_value, pump_energy_nj)` | Estimate runtime before submitting a task |
+| `submit_task(project_id, task_name, quantum_computer_id, mt_value, pump_energy_nj, squeezing_param=None)` | Submit a cloud GBS task |
+| `get_result(task_id)` | Query a task result |
+| `run_experiment(...)` | Estimate, submit, poll, and return raw responses |
+| `estimate_gbs(params)` | Estimate using `GBSParams` |
+| `submit_gbs(params)` | Submit using `GBSParams` |
+| `run_gbs(params)` | Run the full workflow and return `GBSResult` |
+| `close()` | Close the underlying HTTP client |
+
+## Cloud Parameter Object
+
+```python
+from jiuzhang import GBSParams
+
+params = GBSParams(
+    project_id="EXP-demo-project",
+    quantum_computer_id="PH_QC_04",
+    mt=500,
+    pump_energy_nj=4.6,
+    squeezing_param=0.35,
+    task_name="GBS experiment",
+)
+```
+
+| Field | Description |
+| --- | --- |
+| `project_id` | Cloud project ID |
+| `quantum_computer_id` | Cloud device code |
+| `mt` | Pump pulse time-bin count, validated as `1..500` |
+| `pump_energy_nj` | Pump energy in nJ |
+| `squeezing_param` | Optional squeezing parameter |
+| `shots` | Optional shot count field |
+| `task_name` | Display name for the task |
+
+Helper methods:
+
+| Method | Purpose |
+| --- | --- |
+| `validate()` | Validate fields locally |
+| `input_mode_count()` | Return `3 * mt` |
+| `output_mode_count()` | Return `9 * (mt + 80)` |
+| `to_cloud_payload()` | Build a cloud payload dictionary |
+| `summary()` | Build a compact parameter summary |
+
+## Parsed Result Object
+
+`GBSResult` is returned by `run_gbs()` or by `parse_gbs_result(raw_result)`.
+
+| Field or property | Description |
+| --- | --- |
+| `task_id` | Cloud task ID |
+| `status_name` | Normalized task status |
+| `sample_count` | Returned sample count |
+| `result_map_points` | Probability distribution curves |
+| `experimental_distribution` | Experimental distribution points |
+| `ground_truth_distribution` | Reference distribution points |
+| `download_url` | Raw result download URL |
+| `raw` | Original response dictionary |
+
+## Local GBS Sampling
+
+Local GBS sampling does not call the cloud API. Results are generated on the user's machine by The Walrus from the adjacency matrix and sampling parameters.
+
+```python
+from jiuzhang.local.gbs import (
+    random_adjacency_matrix,
+    sample_gbs,
+    samples_to_distribution,
+)
+
+graph = random_adjacency_matrix(8, scale=0.16, seed=7)
+samples = sample_gbs(
+    graph,
+    shots=24,
+    mean_photon_count=1.0,
+    detector="pnr",
+    cutoff=4,
+    max_photons=12,
+    seed=123,
+)
+distribution = samples_to_distribution(samples)
+print(distribution)
+```
+
+| Function | Purpose |
+| --- | --- |
+| `random_adjacency_matrix(modes, scale=0.2, seed=None)` | Generate a symmetric adjacency matrix |
+| `sample_gbs(adjacency, shots=10, mean_photon_count=1.0, detector="pnr", cutoff=5, max_photons=30, seed=None, parallel=False)` | Generate local GBS samples |
+| `samples_to_distribution(samples)` | Convert samples into a normalized pattern distribution |
+
+## Local Math and IR Helpers
+
+```python
+from jiuzhang.local.gbs import (
+    GBSProgram,
+    dumps_ir,
+    hafnian,
+    loop_hafnian,
+    threshold_probability,
+    to_blackbird,
+    to_xir,
+    torontonian,
+)
+```
+
+| Function | Purpose |
+| --- | --- |
+| `hafnian(matrix, loop=False, approx=False, num_samples=1000, method="glynn")` | Compute the Hafnian of a square matrix |
+| `loop_hafnian(matrix, diagonal=None, reps=None, glynn=True)` | Compute the loop Hafnian |
+| `torontonian(matrix, recursive=True)` | Compute the Torontonian |
+| `threshold_probability(mean, covariance, pattern, hbar=2.0, atol=1e-10, rtol=1e-10)` | Compute a threshold detection probability |
+| `GBSProgram(modes, operations=(), name="gbs_program")` | Build a local GBS program |
+| `dumps_ir(program, format="json")` | Serialize a program to JSON, Blackbird, or XIR text |
+| `loads_ir(payload)` | Parse JSON local IR |
+| `to_blackbird(program)` | Serialize to Blackbird text |
+| `to_xir(program)` | Serialize to XIR text |
+
+## License
+
+Proprietary. Copyright 2026 JiuZhang Quantum. All rights reserved.