API Reference

Qonscious combines backend adapters, figures of merits, merit compliance checks, and actions to abstract what it means to perform resource aware conditional quantum computation in the NISQ era.

Adapters

A BackendAdapter is the abstraction layer in Qonscious that standardizes access to quantum backends, whether they are real devices, cloud simulators, or local emulators. It exposes a uniform interface for executing quantum circuits and retrieving results in a consistent format, including counts, backend characteristics, and execution metadata. This allows Qonscious to remain agnostic to the specifics of backend APIs (such as IBM Sampler or Aer), while still supporting resource introspection, circuit execution, measurement, and runtime resource checks. Developers are free to implement custom adapters to integrate other platforms.

You can create an adapter on Qiskit's SamplerV2 as follows:

from qonscious.adapters import AerSamplerAdapter
backend = AerSamplerAdapter()

You can create an adapter to work with one of IBM's fake (simulated computers) as follows:

from qiskit_ibm_runtime.fake_provider import FakeManilaV2
from qonscious.adapters import IBMSamplerAdapter
adapter = IBMSamplerAdapter(FakeManilaV2()) # edit as needed

You can create an adapter on IBM's least bussy (real) quantum computer as follows:

import os
from qonscious.adapters import IBMSamplerAdapter
ibm_token = os.getenv("IBM_QUANTUM_TOKEN") # edit as needed
adapter = IBMSamplerAdapter.least_busy_backend(ibm_token)

You can create an adapter that simulates one of IBM's real computers (using Aer's Simulator, and the real noise models)

import os
from qonscious.adapters import AerSimulatorAdapter
ibm_token = os.getenv("IBM_QUANTUM_TOKEN") # edit as needed
adapter = AerSimulatorAdapter.based_on(ibm_token, backend_name="ibm_brisbane") # you can choose a different one

You can even create an adapter on IonQ's QPU. This example shows how to work with the simulator of Aria-1 (including its noise model).

import os
from qonscious.adapters import IonQBackendAdapter
api_key = os.getenv("IONQ_API_KEY")
adapter = IonQBackendAdapter.simulated_aria(api_key)

BackendAdapter

Bases: Protocol

Source code in src/qonscious/adapters/backend_adapter.py

class BackendAdapter(Protocol):
    def run(self, circuit: QuantumCircuit, **kwargs) -> ExperimentResult: ...

    @property
    def n_qubits(self) -> int:
        """
        Returns:
            int: The number of qubits of the backend.
        """
        ...

    @property
    def t1s(self) -> dict[int, float]:
        """
        Returns:
            dict[int, float]: The T1 (relaxation time) for each qubit.
        """
        ...

    @property
    def t2s(self) -> dict[int, float]:
        """
        Returns:
            dict[int, float]: The T2 (dephasing time) for each qubit.
        """
        ...

n_qubits property

Returns:

Name	Type	Description
int	int	The number of qubits of the backend.

t1s property

Returns:

Type	Description
dict[int, float]	dict[int, float]: The T1 (relaxation time) for each qubit.

t2s property

Returns:

Type	Description
dict[int, float]	dict[int, float]: The T2 (dephasing time) for each qubit.

Figures of merit

A Figure of Merit in Qonscious represents a measurable property of a quantum backend (device or simulator) that is relevant to the quality or feasibility of circuit execution. Examples include physical metrics such as average T₁ time, CHSH score, or backend connectivity, as well as derived quantities like estimated circuit error after transpilation. When a figure of merit is evaluated, it produces a structured object called a Figure of Merit Result, which contains the computed value (or outcome), relevant metadata (such as backend name, timestamps, or raw introspection data), and any additional fields needed to interpret the result. These results are in merit checks to determine whether the backend conditions meet the criteria required for executing a quantum task.

You can use Figures of Merit as stand-alone objects, to analyse a backend but you normally used them in merit checks of the run_conditional() function.

You can get an aggregate figure of merit (T1, T2, numer of qubits, etc) of IBM's least bussy computer as follows:

import os
from qonscious.adapters import IBMSamplerAdapter
from qonscious.foms.aggregate_qpu_fom import AggregateQPUFigureOfMerit

ibm_token = os.getenv("IBM_QUANTUM_TOKEN")
adapter = IBMSamplerAdapter.least_busy_backend(ibm_token)
agg_fom = AggregateQPUFigureOfMerit()
agg_fom.evaluate(adapter)

You can see what the CHSH (a figure of merit) looks like in IBM's FakeKawasaki() as follows. Pay attention to the properties attribute of the result object.

from qiskit_ibm_runtime.fake_provider import FakeKawasaki
from qonscious.adapters import IBMSamplerAdapter
from qonscious.foms import PackedCHSHTest

adapter = IBMSamplerAdapter(FakeKawasaki())
chsh_test = PackedCHSHTest()
chsh_test.evaluate(adapter)

AggregateQPUFigureOfMerit

Bases: FigureOfMerit

I aggregate various properties common to all backends in a single FOM. I aggregate: n_qubits, T1 average, T2 average, ... For multivalued figures such as T1, I provide a dict with descriptive statistics

Source code in src/qonscious/foms/aggregate_qpu_fom.py

class AggregateQPUFigureOfMerit(FigureOfMerit):
    """
    I aggregate various properties common to all backends in a single FOM.
    I aggregate: n_qubits, T1 average, T2 average, ...
    For multivalued figures such as T1, I provide a dict with  descriptive statistics
    """

    def evaluate(self, backend_adapter: BackendAdapter, **kwargs) -> FigureOfMeritResult:
        result: FigureOfMeritResult = {
            "timestamp": datetime.now(timezone.utc).isoformat(),
            "figure_of_merit": self.__class__.__name__,
            "properties": {
                "n_qubits": backend_adapter.n_qubits,
                "T1": describe(list(backend_adapter.t1s.values()), "cap", cap_value=1),
                "T2": describe(list(backend_adapter.t2s.values()), "cap", cap_value=1),
            },
            "experiment_result": None,
        }
        return result

PackedCHSHTest

Bases: FigureOfMerit

I represent a CHSH test, run on 8 qubits (the four Bell pairs), in parallel.

Source code in src/qonscious/foms/packed_chsh.py

class PackedCHSHTest(FigureOfMerit):
    """
    I represent a CHSH test, run on 8 qubits (the four Bell pairs), in parallel.
    """

    def evaluate(self, backend_adapter: BackendAdapter, **kwargs) -> FigureOfMeritResult:
        """
        Returns:
            a FigureOfMeritResult with the following properties:
                figure_of_merit: "PackedCHSHTest" (a str).
                properties: a dict with keys "E00", "E01", "E10", "E11", representing the individual
                counts of each observed pait, and "score", computed as E00 + E01 + E10 - E11.
                experiment_result: an instance of ExperimentResult; the result of the experiment.
        """
        qc = self._build_circuit()
        run_result: ExperimentResult = backend_adapter.run(qc, shots=kwargs.get("shots", 1024))
        CHSH_Scores: dict = compute_parallel_CHSH_scores(run_result["counts"])
        evaluation_result: FigureOfMeritResult = {
            "timestamp": datetime.now(timezone.utc).isoformat(),
            "figure_of_merit": self.__class__.__name__,
            "properties": CHSH_Scores,
            "experiment_result": run_result,
        }
        return evaluation_result

    def _build_circuit(self) -> QuantumCircuit:
        qc = QuantumCircuit(8, 8)

        for i in range(0, 8, 2):
            qc.h(i)
            qc.cx(i, i + 1)

        # Measurement settings
        qc.ry(-np.pi / 4, 1)
        qc.ry(np.pi / 4, 3)
        qc.ry(-np.pi / 2, 4)
        qc.ry(-np.pi / 4, 5)
        qc.ry(-np.pi / 2, 6)
        qc.ry(np.pi / 4, 7)

        qc.measure(range(8), range(8))
        return qc

evaluate(backend_adapter, **kwargs)

Returns:

Type	Description
FigureOfMeritResult	a FigureOfMeritResult with the following properties: figure_of_merit: "PackedCHSHTest" (a str). properties: a dict with keys "E00", "E01", "E10", "E11", representing the individual counts of each observed pait, and "score", computed as E00 + E01 + E10 - E11. experiment_result: an instance of ExperimentResult; the result of the experiment.

Source code in src/qonscious/foms/packed_chsh.py

def evaluate(self, backend_adapter: BackendAdapter, **kwargs) -> FigureOfMeritResult:
    """
    Returns:
        a FigureOfMeritResult with the following properties:
            figure_of_merit: "PackedCHSHTest" (a str).
            properties: a dict with keys "E00", "E01", "E10", "E11", representing the individual
            counts of each observed pait, and "score", computed as E00 + E01 + E10 - E11.
            experiment_result: an instance of ExperimentResult; the result of the experiment.
    """
    qc = self._build_circuit()
    run_result: ExperimentResult = backend_adapter.run(qc, shots=kwargs.get("shots", 1024))
    CHSH_Scores: dict = compute_parallel_CHSH_scores(run_result["counts"])
    evaluation_result: FigureOfMeritResult = {
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "figure_of_merit": self.__class__.__name__,
        "properties": CHSH_Scores,
        "experiment_result": run_result,
    }
    return evaluation_result

Merit checks

You use figures of merit to evaluate whether a quantum computer meets the requirements of your experiment. A merit check consists of computing a figure of merit on a given backend and then deciding, based on the result, whether the device passes or fails your criteria.

The current mechanism for performing such a check is the MeritComplianceCheck, which takes two components:

• a FigureOfMerit that defines what to measure, and
• a decision function that receives the result of the measurement and returns True (pass) or False (fail).

For example, the following code checks whether IBM’s FakeKawasaki simulator is capable of producing a level of entanglement high enough to yield a CHSH score greater than 2.7 (run it a few times; 2.7 is in the limit of that fake computer)

from qiskit_ibm_runtime.fake_provider import FakeKawasaki

from qonscious.adapters import IBMSamplerAdapter
from qonscious.checks import MeritComplianceCheck
from qonscious.foms import PackedCHSHTest

adapter = IBMSamplerAdapter(FakeKawasaki())

# Build the compliance check using a PackedCHSHTest and the score-checking function (a lambda in this case)
chsh_compliance = MeritComplianceCheck(
    figure_of_merit=PackedCHSHTest(),
    decision_function=lambda chsh_result: chsh_result is not None and
        chsh_result["properties"]["score"] > 2.7,
)

chsh_compliance.check(adapter)

This approach lets you define flexible and reusable checks based on any figure of merit supported by Qonscious; not just CHSH, but also qubit count, coherence time, circuit error estimates, or even custom benchmarks.

MeritComplianceCheck

A flexible compliance check based on an optional Figure of Merit and a custom decision function that maps its result to a boolean.

Source code in src/qonscious/checks/merit_compliance_check.py

class MeritComplianceCheck:
    """
    A flexible compliance check based on an optional Figure of Merit
    and a custom decision function that maps its result to a boolean.
    """

    def __init__(
        self,
        figure_of_merit: FigureOfMerit | None = None,
        decision_function: Callable[[FigureOfMeritResult | None], bool] = lambda _: True,
    ):
        self.figure_of_merit = figure_of_merit
        self.decision_function = decision_function

    def check(self, backend_adapter: BackendAdapter, **kwargs) -> dict:
        """
        Evaluate the FOM if present, apply the decision function to its result,
        and return a dict with the compliance outcome and the FOM result (if any).
        """
        fom_result = None

        if self.figure_of_merit is not None:
            fom_result = self.figure_of_merit.evaluate(backend_adapter, **kwargs)

        passed = self.decision_function(fom_result)

        return {"passed": passed, "fom_result": fom_result}

check(backend_adapter, **kwargs)

Evaluate the FOM if present, apply the decision function to its result, and return a dict with the compliance outcome and the FOM result (if any).

Source code in src/qonscious/checks/merit_compliance_check.py

def check(self, backend_adapter: BackendAdapter, **kwargs) -> dict:
    """
    Evaluate the FOM if present, apply the decision function to its result,
    and return a dict with the compliance outcome and the FOM result (if any).
    """
    fom_result = None

    if self.figure_of_merit is not None:
        fom_result = self.figure_of_merit.evaluate(backend_adapter, **kwargs)

    passed = self.decision_function(fom_result)

    return {"passed": passed, "fom_result": fom_result}

Conditionally running circuits

You use Qoncsious to conditionaly (being aware of the resources on your computing platform) perform actions. This could be running a quantum circuit, reporting results, or running any arbitrary function. We call these actions, qonscious actions. A QonsciousAction is objects that implement the run() method, which receives a backend adapter, the results of figure-of-merit evaluations, and optional keyword arguments. The method returns either an ExperimentResult or None.

This example shows how to use a QonsciousCircuit object, to run a simple quantum circuit. It basically does nothing with the figures of merit it receives (they are important in other scenarios), therefore we send an empty list.

The result is a QonsciousResult object, that provides a uniform way to access the bistrings counts, execution stats, the raw results returned by the real backend.

from qiskit import QuantumCircuit

from qonscious.actions import QonsciousCircuit
from qonscious.adapters import IBMSamplerAdapter

# A simple Bell state
phi_plus = QuantumCircuit(2)
phi_plus.h(0)
phi_plus.cx(0, 1)
phi_plus.measure_all()

q_action = QonsciousCircuit(phi_plus)
adapter = IBMSamplerAdapter(FakeKawasaki())
q_result = q_action.run(adapter,[],shots=2048)

This example shows how to use a QonsciousCallable to wrap a python function that logs the score of the CHSH test (a merit test).

from qiskit_ibm_runtime.fake_provider import FakeKawasaki

from qonscious.actions import QonsciousCallable
from qonscious.adapters import IBMSamplerAdapter
from qonscious.checks import MeritComplianceCheck
from qonscious.foms import PackedCHSHTest

adapter = IBMSamplerAdapter(FakeKawasaki())

chsh_compliance = MeritComplianceCheck(
    figure_of_merit=PackedCHSHTest(),
    decision_function=lambda chsh_result: chsh_result is not None and
        chsh_result["properties"]["score"] > 2.7,
)

chsg_result = chsh_compliance.check(adapter)["fom_result"]

def log_chsh_score(backend_adapter, figureOfMeritResults):
    firstFoMResult = figureOfMeritResults[0]
    print(f"CHSH Score: {firstFoMResult['properties']['score']:.3f}")
    return None

q_callable = QonsciousCallable(log_chsh_score)
q_callable.run(adapter,[chsg_result])

That last example looks a bit cumbersome. Luckily, we use actions via the run_conditionally function.

So, if we put all of that together, we get:

from qiskit_ibm_runtime.fake_provider import FakeKawasaki

from qonscious import run_conditionally
from qonscious.actions import QonsciousCallable
from qonscious.adapters import IBMSamplerAdapter
from qonscious.checks import MeritComplianceCheck
from qonscious.foms import PackedCHSHTest

# Prepare our backend adapter
adapter = IBMSamplerAdapter(FakeKawasaki())

# Prepare our check - CHSH score over 2.7
chsh_compliance = MeritComplianceCheck(
    figure_of_merit=PackedCHSHTest(),
    decision_function=lambda chsh_result: chsh_result is not None and
        chsh_result["properties"]["score"] > 2.7,
)

# Prepare our action for the case CHSH is over 2.7 (A Bell pair)
phi_plus = QuantumCircuit(2)
phi_plus.h(0)
phi_plus.cx(0, 1)
phi_plus.measure_all()
pass_action = QonsciousCircuit(phi_plus)

# Prepare our action for the case CHSH in under 2.7 (report the score)
def log_chsh_score(backend_adapter, figureOfMeritResults):
    firstFoMResult = figureOfMeritResults[0]
    print(f"CHSH score was too low: {firstFoMResult['properties']['score']:.3f}")
    return None
fail_action = QonsciousCallable(log_chsh_score)

# Run either one of the actions conditionally on the CHSH figure of merit of our backend
q_result = run_conditionally(adapter, [chsh_compliance], pass_action, fail_action)

print(q_result)

QonsciousCircuit

Bases: QonsciousAction

A Quantum circuit wrapped as as QonsciousAction

Attributes:

Name	Type	Description
circuit	QuantumCircuit	the quantum circuit to run

Source code in src/qonscious/actions/qonscious_circuit.py

class QonsciousCircuit(QonsciousAction):
    """
    A Quantum circuit wrapped as as QonsciousAction

    Attributes:
        circuit (QuantumCircuit): the quantum circuit to run
    """

    def __init__(self, circuit: QuantumCircuit):
        self.circuit = circuit

    def run(
        self, backend_adapter: BackendAdapter, fom_results: list[FigureOfMeritResult], **kwargs
    ) -> ExperimentResult:
        return backend_adapter.run(self.circuit, **kwargs)

QonsciousCallable

Bases: QonsciousAction

A callable wraped as QonsciousAction

Attributes:

Name	Type	Description
callable	Callable[[BackendAdapter, list[FigureOfMeritResult]], ExperimentResult | None]	the callable to execute

Source code in src/qonscious/actions/qonscious_callable.py

class QonsciousCallable(QonsciousAction):
    """
    A callable wraped as QonsciousAction

    Attributes:
        callable ( Callable[[BackendAdapter, list[FigureOfMeritResult]], ExperimentResult | None]):
            the callable to execute
    """

    def __init__(
        self,
        callable: Callable[[BackendAdapter, list[FigureOfMeritResult]], ExperimentResult | None],
    ):
        self.callable = callable

    def run(
        self, backend_adapter: BackendAdapter, fom_results: list[FigureOfMeritResult], **kwargs
    ) -> ExperimentResult | None:
        return self.callable(backend_adapter, fom_results, **kwargs)

run_conditionally(backend_adapter, checks, on_pass, on_fail, **kwargs)

Main entry point of the Qonscious framework.

Evaluates a set of merit compliance checks on the given backend and executes the appropriate action depending on whether all checks pass or any check fails.

Parameters:

Name	Type	Description	Default
backend_adapter	BackendAdapter	Adapter to the quantum backend on which figures of merit are evaluated and circuits may be executed.	required
checks	list[MeritComplianceCheck]	The merit compliance checks to perform on the backend.	required
on_pass	QonsciousAction	Action to execute if all checks succeed. Must implement run(backend_adapter, fom_results, **kwargs) and return an ExperimentResult or None.	required
on_fail	QonsciousAction	Action to execute if any check fails. Same contract as on_pass.	required
**kwargs	Any	Additional keyword arguments forwarded to the checks and actions.	{}

Returns:

Name	Type	Description
QonsciousResult	QonsciousResult	A result object containing the list of figure-of-merit results and, if applicable, the experiment result produced by the action.

Source code in src/qonscious/run_conditionally.py

def run_conditionally(
    backend_adapter: BackendAdapter,
    checks: list[MeritComplianceCheck],
    on_pass: QonsciousAction,
    on_fail: QonsciousAction,
    **kwargs: Any,
) -> QonsciousResult:
    """
    Main entry point of the Qonscious framework.

    Evaluates a set of merit compliance checks on the given backend
    and executes the appropriate action depending on whether all
    checks pass or any check fails.

    Args:
        backend_adapter: Adapter to the quantum backend on which figures of merit
            are evaluated and circuits may be executed.
        checks: The merit compliance checks to perform on the backend.
        on_pass:  Action to execute if all checks succeed. Must implement
            `run(backend_adapter, fom_results, **kwargs)` and return an `ExperimentResult` or `None`.
        on_fail: Action to execute if any check fails. Same contract as `on_pass`.
        **kwargs: Additional keyword arguments forwarded to the checks and actions.

    Returns:
        QonsciousResult: A result object containing the list of figure-of-merit results
            and, if applicable, the experiment result produced by the action.
    """

    fom_results: list[FigureOfMeritResult] = []
    passed = True

    for check in checks:
        result = check.check(backend_adapter, **kwargs)
        fom_results.append(result["fom_result"])
        if not result["passed"]:
            passed = False

    if passed:
        run_result = on_pass.run(backend_adapter, fom_results, **kwargs)
    else:
        run_result = on_fail.run(backend_adapter, fom_results, **kwargs)

    return {
        "condition": "pass" if passed else "fail",
        "figures_of_merit_results": fom_results,
        "experiment_result": run_result,
    }