Qctrl Backend

The Qctrl backend class provides configuration and interface support for submitting quantum tasks via Q-CTRL’s Fire Opal platform. It enables executing on IBM hardware with advanced error mitigation and suppression techniques, greatly improving the results on current days hardware. Furthermore, Fire Opal offers an integrated closed loop QAOA algorithms for combinatorial optimization.

Using Environment Variables

You can set your Q-CTRL API token via environment variables to avoid passing it during initialization:

export LUNA_QCTRL_TOKEN=your_qctrl_token

Initialization

Initialize the Qctrl backend with:

from luna_quantum.solve.parameters.backends import Qctrl

backend = Qctrl(
    organization_slug=None,
    backend_name=None,
    ibm_credentials=Qctrl.IBMQ(
        hub='ibm-q',
        group='open',
        project='main',
        token=None
    ),
    token=None
)

---

API-Reference

Qctrl

Bases: QpuTokenBackend

Configuration parameters for Q-CTRL`s Fire Opal Backend.

QAOA (Quantum Approximate Optimization Algorithm) is a quantum algorithm designed for combinatorial optimization problems. This implementation leverages Q-CTRL's Fire Opal framework, which optimizes QAOA execution on quantum hardware to reduce errors and improve solution quality.

Fire Opal's hardware-tailored optimizations enable solving larger problems with better convergence in fewer iterations, reducing overall execution time on real quantum devices.

Attributes:

Name	Type	Description
organization_slug	str | None, default=None	Organization identifier from your Q-CTRL account. Required only if you belong to multiple organizations. This can be retrieved from your Q-CTRL account settings or dashboard.
backend_name	str | None, default=None	The IBM Quantum backend to use for computations: - Specific backend: e.g., 'ibm_fez', 'ibm_marrakesh' - 'least_busy': Automatically selects the least busy available backend - 'basic_simulator': Uses the basic simulator (default if None) Check your IBM Quantum account for available backends.
ibm_credentials	QCtrl.IBMQ | QCtrl.IBMCloud, default=Qctrl.IBMQ()	The IBM backend credentials, i.e. how to access the IBM service. Q-Ctrl currently supports two mehtods, via the old IBMQ pattern or the new IBMCloud pattern.
token	QpuToken | str | None, default=None	The Q-Ctrl API token.

Notes

For detailed information about Fire Opal's QAOA solver and its capabilities, see Q-CTRL's documentation: https://docs.q-ctrl.com/fire-opal/topics/fire-opals-qaoa-solver

backend_name class-attribute instance-attribute

backend_name: str | None = None

ibm_credentials class-attribute instance-attribute

ibm_credentials: IBMQ | IBMCloud = Field(default=IBMQ())

organization_slug class-attribute instance-attribute

organization_slug: Any = None

provider property

provider: str

Retrieve the name of the provider.

Returns:

Type	Description
str	The name of the provider.

token class-attribute instance-attribute

token: str | QpuToken | None = Field(repr=False, exclude=True, default=None)

IBMCloud

Bases: BaseModel

Configuration parameters for the IBM Cloud backend.

Attributes:

Name	Type	Description
instance	str	The Qiskit runtime instance CRN (Cloud Resource Name).
token	Union[str, None, QpuToken], default=None	The IBM API token.

instance instance-attribute

instance: str

token class-attribute instance-attribute

token: str | QpuToken | None = Field(repr=False, exclude=True, default=None)

IBMQ

Bases: BaseModel

Configuration parameters for the IBM Quantum backend.

Attributes:

Name	Type	Description
hub	str, default="ibm-q"	The IBM Quantum hub to use for accessing quantum resources. This defines your access level and available systems.
group	str, default="open"	The IBM Quantum group within your hub. Groups help organize users and projects within a hub.
project	str, default="main"	The IBM Quantum project within your group. Projects help organize work and resource allocation.
token	Union[str, None, QpuToken], default=None	The IBM API token.

group class-attribute instance-attribute

group: str = 'open'

hub class-attribute instance-attribute

hub: str = 'ibm-q'

project class-attribute instance-attribute

project: str = 'main'

token class-attribute instance-attribute

token: str | QpuToken | None = Field(repr=False, exclude=True, default=None)

_get_token

_get_token() -> TokenProvider | None

get_qpu_tokens

get_qpu_tokens() -> TokenProvider | None

Retrieve a QPU token.

This method is intended to be implemented by subclasses to provide the mechanism for fetching the required Quantum Processing Unit (QPU) tokens, if they are required by the solver implementation. The tokens may either be sourced from a TokenProvider object or result in a None if unavailable.

Returns:

Type	Description
TokenProvider | None:	An object implementing the TokenProvider interface if tokens are available/needed, otherwise None.