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 application 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 SDK local numerical backend from the provided matrix and sampling parameters.

Local application workflows also run without the cloud API. Results are generated locally from bundled datasets, matrix parameters, and algorithm parameters.

📦 Installation

Install the SDK:

pip install jiuzhang-sdk

The default installation includes cloud task submission, local GBS math and sampling, local program serialization, and local application workflow dependencies.

🔐 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 SDK 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)

🧪 Local Application Workflows

The graph and molecular demos are available through jiuzhang.local.applications, so notebooks can call SDK-level methods only.

from jiuzhang.local.applications import (
    greedy_dense_subgraph,
    load_formic_acid,
    load_mutag_graphs,
    load_planted_dense_graph,
    load_tace_as_graph,
)

adjacency = load_planted_dense_graph()
dense_result = greedy_dense_subgraph(adjacency, size=8)

mutag_graphs = load_mutag_graphs()
docking_graph = load_tace_as_graph()
molecule = load_formic_acid()

📄 License

Proprietary. Copyright 2026 JiuZhang Quantum. All rights reserved.