Examples

The source repository includes runnable examples in the examples/ folder.

If you installed the SDK from PyPI with pip install qcentroid-sdk, you will typically not have that local examples/ folder available in your environment.

In that case, use the code snippets in this documentation as the starting point for your own scripts.

List jobs

File: examples/list_jobs.py

This example authenticates with QCentroid and prints recent jobs.

from qcentroid_sdk import QCentroidClient

QCENTROID_API_KEY = "-- your api key --"


def main() -> None:
    client = QCentroidClient(
        api_key=QCENTROID_API_KEY,
    )

    jobs_page = client.jobs.list(limit=10)

    print(f"Retrieved {len(jobs_page.value)} jobs")
    if jobs_page.count is not None:
        print(f"Reported count: {jobs_page.count}")

    for job in jobs_page.value:
        print(
            f"- name={job.name} status={job.status} started_at={job.started_at}"
        )


if __name__ == "__main__":
    main()

Run a job with inline data

File: examples/run_job_inline.py

This example launches a job by passing the input payload directly in the request.

from qcentroid_sdk import QCentroidClient

QCENTROID_API_KEY = "-- your api key --"

USE_CASE_NAME = "qcentroid-example-1-sum"
SOLVER_NAME = "QCentroid-OscarSolver-Example1Sum-ClassicalCPU"


def main() -> None:
    client = QCentroidClient(
        api_key=QCENTROID_API_KEY,
    )

    job = client.jobs.run(
        use_case_name=USE_CASE_NAME,
        data={"a": 2, "b": 3},
        solvers=[{"name": SOLVER_NAME}],
        num_shots=1,
        job_description="Run a job with inline data using the QCentroid SDK",
    )

    print(f"Job launched successfully: {job.job_name}")


if __name__ == "__main__":
    main()

Run a job with an existing dataset

File: examples/run_job_dataset.py

This example launches a job using a previously uploaded dataset file identifier.

from qcentroid_sdk import QCentroidClient

QCENTROID_API_KEY = "-- your api key --"

USE_CASE_NAME = "qcentroid-example-1-sum"
SOLVER_NAME = "QCentroid-OscarSolver-Example1Sum-ClassicalCPU"
DATASET_IDENTIFIER = "-- existing dataset file identifier --"
SOLVERS_PROVIDER_PARAMS = {SOLVER_NAME: {}}
MAX_EXEC_TIME_M = 0


def main() -> None:
    client = QCentroidClient(
        api_key=QCENTROID_API_KEY,
    )

    job = client.jobs.run(
        use_case_name=USE_CASE_NAME,
        dataset_id=DATASET_IDENTIFIER,
        solvers=[{"name": SOLVER_NAME}],
        num_shots=1,
        job_description="Run a job with an existing dataset using the QCentroid SDK",
        solvers_provider_params=SOLVERS_PROVIDER_PARAMS,
        max_exec_time_m=MAX_EXEC_TIME_M,
    )

    print(f"Job launched successfully: {job.job_name}")


if __name__ == "__main__":
    main()

Wait for a job to finish

You can also wait for a launched job to reach a terminal state:

job = client.jobs.run(
    use_case_name="qcentroid-example-1-sum",
    data={"a": 2, "b": 3},
    solvers=[{"name": "QCentroid-OscarSolver-Example1Sum-ClassicalCPU"}],
    num_shots=1,
)

finished_job = client.jobs.wait_for_completion(job.job_name)
print(finished_job.name, finished_job.status)

Credential placeholders

The example scripts use placeholders like:

QCENTROID_API_KEY = "-- your api key --"

Replace it with your own API key before running the examples.

Default environment

The examples do not pass an explicit environment, so they use the SDK default:

environment="sandbox"

If you want to target a different environment, pass it when constructing the client:

client = QCentroidClient(
    environment="dev",
    api_key=QCENTROID_API_KEY,
)