microquantum.adapters.base

Base classes for the domain adapter framework.

The adapter pattern sits between domain applications and the quantum SDK:

Domain Application → DomainAdapter → MicroQuantum SDK → Execution Backend

↑

Domain-specific encoding/decoding Physics validation Result caching

Module Contents

class microquantum.adapters.base.ProblemStatus(*args, **kwds)[source]

Bases: enum.Enum

Status of a quantum problem.

CREATED = 'created'[source]
VALIDATED = 'validated'[source]
ENCODED = 'encoded'[source]
EXECUTED = 'executed'[source]
DECODED = 'decoded'[source]
FAILED = 'failed'[source]
class microquantum.adapters.base.QuantumProblem[source]

A problem formulated for quantum execution.

Encapsulates the parameters, constraints, and metadata needed to encode a problem into a quantum circuit.

Variables:

  • name – Problem identifier (e.g., “binary_optimization”).

  • domain – Problem domain (e.g., “optimization”).

  • parameters – Problem-specific parameters.

  • constraints – Constraints for validation.

  • num_qubits – Requested number of qubits (may be adjusted).

  • metadata – Additional problem metadata.

name: str[source]
domain: str[source]
parameters: dict[str, Any][source]
constraints: dict[str, Any][source]
num_qubits: int | None = None[source]
metadata: dict[str, Any][source]
status: ProblemStatus[source]
created_at: float[source]
property problem_id: str[source]

Unique deterministic ID based on problem content.

Return type:

str

class microquantum.adapters.base.QuantumResult[source]

Result from executing a quantum problem through an adapter.

Contains both the raw quantum execution output and the decoded interpretation.

Variables:

  • problem – The original problem.

  • backend_result – Raw result from the quantum backend.

  • decoded – Decoded result dictionary.

  • fidelity – Solution fidelity (0-1).

  • execution_time – Time spent in quantum execution (seconds).

  • metadata – Additional result metadata.

problem: QuantumProblem[source]
backend_result: microquantum.backends.base.BackendResult | None = None[source]
decoded: dict[str, Any][source]
fidelity: float = 0.0[source]
execution_time: float = 0.0[source]
metadata: dict[str, Any][source]
property most_frequent_state: str[source]

Most frequently measured quantum state.

Return type:

str

property probabilities: dict[str, float][source]

Measurement probability distribution.

Return type:

dict[str, float]

to_dict()[source]

Serialize to a JSON-safe dictionary.

Return type:

dict[str, Any]

to_json()[source]

Serialize to a JSON string.

Return type:

str

class microquantum.adapters.base.DomainAdapter[source]

Bases: abc.ABC

Abstract base class for domain-specific quantum adapters.

Each adapter bridges a physics domain to the quantum SDK by: 1. Validating that a problem has physically realizable parameters 2. Encoding the problem into a parameterized quantum circuit 3. Executing the circuit on a backend 4. Decoding the quantum measurement results back to domain language

Subclasses must implement all abstract methods.

property domain_name: str[source]
Abstractmethod:

Return type:

str

Domain identifier (e.g., ‘optimization’, ‘signal_processing’).

property supported_problems: list[str][source]
Abstractmethod:

Return type:

list[str]

List of problem types this adapter handles.

abstractmethod validate(problem)[source]

Validate a problem’s physics before encoding.

Parameters:

problem (QuantumProblem) – The problem to validate.

Returns:

List of validation error messages. Empty list = valid.

Return type:

list[str]

abstractmethod encode(problem)[source]

Encode a validated problem into a quantum circuit.

Parameters:

problem (QuantumProblem) – The validated problem.

Returns:

Parameterized quantum circuit representing the problem.

Return type:

microquantum.core.circuit.QuantumCircuit

abstractmethod decode(problem, result)[source]

Decode quantum measurement results into domain results.

Parameters:
Returns:

Dictionary of domain-specific decoded results.

Return type:

dict[str, Any]

solve(problem, backend, shots=1024, seed=None)[source]

Full solve pipeline: validate → encode → execute → decode.

Parameters:
Returns:

QuantumResult with decoded domain results.

Raises:

ValueError – If problem fails validation.

Return type:

QuantumResult

can_handle(problem)[source]

Check if this adapter can handle a given problem.

Parameters:

problem (QuantumProblem)

Return type:

bool