jiuzhang-sdk ✨

Python SDK for the JiuZhang photonic quantum cloud platform, with cloud GBS task submission, result retrieval, local GBS math, sampling, IR serialization, and local handwritten digit recognition helpers.

The SDK provides three core capability groups:

Cloud GBS tasks are executed by the JiuZhang cloud platform. Python scripts and Jupyter notebooks submit requests, poll task status, and read results.

Local GBS sampling runs entirely on the local machine and does not call the cloud API. Results are generated by The Walrus numerical backend from the provided matrix and sampling parameters.

Local handwritten digit recognition also runs without the cloud API. Results are generated from local PCA features, a GBS-style feature layer, and a closed-form classifier.

📦 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 local 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,
)

🧠 Local Handwritten Digit Recognition

from jiuzhang.local.mnist import run_mnist_recognition

result = run_mnist_recognition(
    train_size=1200,
    test_size=300,
    source="digits",
    n_components=32,
    feature_count=256,
    combine=True,
    random_state=7,
)

print(result.train)
print(result.accuracy)
print(result.confusion_matrix)

Manual training:

from jiuzhang.local.mnist import GBSMNISTClassifier, load_mnist_data

dataset = load_mnist_data(train_size=1200, test_size=300, source="digits")
classifier = GBSMNISTClassifier(n_components=32, feature_count=256)

classifier.fit(dataset.train_data, dataset.train_labels, combine=True)
predictions = classifier.predict(dataset.test_data)
evaluation = classifier.evaluate(dataset.test_data, dataset.test_labels, reuse=True)

📄 License

Proprietary. Copyright 2026 JiuZhang Quantum. All rights reserved.