Skip to content

QCentroid Loaders#

Introduction#

QCentroid Loaders are lightweight helper packages that let a solver run on third-party quantum hardware providers with minimal changes to the solver source code.

When a job runs in the QCentroid Platform, the platform already knows which provider, device, backend, access token, and provider-specific options the user selected from the dashboard or API. A loader makes that runtime configuration available to your solver code without hardcoding credentials or provider targets in your repository.

Use a loader when your solver needs to submit work to a supported provider such as IBM Quantum through Qiskit, Amazon Braket, or Azure Quantum.

What loaders provide#

Loaders are designed to keep provider configuration outside your algorithm code:

  • Secure token injection: access tokens and credentials are provided by the platform at runtime.
  • Selected target resolution: the loader returns the backend, device, or target selected for the job.
  • Provider parameters: supported provider hyperparameters can be passed through the platform job configuration.
  • Minimal footprint: solver code only imports the loader and requests the configured target when it needs to submit the job.
  • Local fallback: when a loader is used locally without platform initialization, it returns a local simulator or local development target when one is available.

The solver remains responsible for building the algorithm, preparing circuits or programs, submitting the provider job, reading the result, and returning the expected QCentroid output.

Package and API#

The Python package is named QCentroidLoaders.

The public imports for the currently documented providers are:

from QCentroidLoaders import AzureLoader
from QCentroidLoaders import AzureQiskitLoader
from QCentroidLoaders import BraketLoader
from QCentroidLoaders import QiskitLoader

All loaders follow the same minimal pattern:

target = Loader.get_target()

The platform initializes the corresponding loader before your solver calls run(). Your solver normally only needs to call get_target().

Loaders are implemented as singletons per loader class. Once a loader has been initialized in a runtime, subsequent calls to get_target() return the same configured target for that class.

Runtime behavior#

In the QCentroid Platform, the QCentroidLoaders package is installed automatically in the solver runtime. The user does not need to add provider credentials to the repository.

For local development, QCentroid will provide a public GitHub repository containing the local version of the loaders. Once available, install it in your development environment from that repository:

pip install git+<loaders-repository-url>

During local execution, uninitialized loaders return local fallbacks where supported:

  • QiskitLoader and AzureQiskitLoader return a local Qiskit simulator.
  • BraketLoader returns the Amazon Braket LocalSimulator.
  • AzureLoader returns a lightweight local Azure development target.

These fallbacks are intended for development and validation. They do not replace the provider credentials and targets injected by the QCentroid Platform during remote job execution.

Solver entrypoint#

Loaders are used inside the standard qcentroid.py entrypoint:

qcentroid.py
from typing import Any

def run(
    input_data: dict[str, Any],
    solver_params: dict[str, Any],
    extra_arguments: dict[str, Any],
) -> dict[str, Any]:
    # Build your algorithm, resolve the provider target with a loader,
    # submit the job, and return the result.
    return {"status": "ok"}

The platform calls run() with:

  • input_data: the dataset or inline input selected for the job.
  • solver_params: solver parameters configured by the user.
  • extra_arguments: additional execution arguments passed by the platform or API.

Supported loaders#

QCentroid currently supports these loader integrations:

Best practices#

  • Do not commit provider access tokens, cloud credentials, or workspace secrets to your solver repository.
  • Request the provider target through the loader at runtime instead of hardcoding a backend or device.
  • Keep provider-specific hyperparameters in solver_params or platform job configuration when they are intended to be changed by users.
  • Add execution logs with logging.getLogger("qcentroid-user-log") so users can inspect provider submission and result handling in the job details page.

What’s next#

Use the Qiskit loader

Create a solver