jiuzhang-sdk ✨

Python SDK for the JiuZhang photonic quantum cloud platform.

The SDK provides two separate capability groups:

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:

pip install jiuzhang-sdk

The default installation includes cloud task submission, local GBS math and sampling, and local Blackbird / XIR serialization.

🔐 Cloud Credentials

Before submitting a cloud task, prepare these values from the JiuZhang cloud workspace:

Recommended environment variables:

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

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:

result = client.run_gbs(params, poll_interval=2.0, timeout=300.0)
print(result.status_name)

🌐 Cloud API Methods

🧾 Cloud Parameter Object

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",
)

Helper methods:

📊 Parsed Result Object

GBSResult is returned by run_gbs() or by parse_gbs_result(raw_result).

🧮 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.

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)

🧩 Local Math and IR Helpers

from jiuzhang.local.gbs import (
    GBSProgram,
    dumps_ir,
    hafnian,
    loop_hafnian,
    threshold_probability,
    to_blackbird,
    to_xir,
    torontonian,
)

📄 License

Proprietary. Copyright 2026 JiuZhang Quantum. All rights reserved.