qamomile.optimization.qrao

Quantum Random Access Optimization (QRAO) module.

This module provides QRAC-based encoders and converters for quantum optimization.

Overview¶

Classes¶

BaseQRACEncoder [source]¶

class BaseQRACEncoder(abc.ABC)

Abstract base for all QRAC encoders.

Provides:

• Input validation (spin vartype, no HUBO terms).

• Common pauli_encoding property and get_pauli_for_variable method.

• Abstract hooks for _perform_encoding and num_qubits.

Subclasses must implement _perform_encoding and num_qubits.

Constructor¶

def __init__(self, spin_model: BinaryModel) -> None

Attributes¶

• num_qubits: int Number of qubits after QRAC encoding.

• pauli_encoding: dict[int, tuple[int, PauliType]] Mapping from variable index to (qubit, pauli_type).

• spin_model

Methods¶

get_pauli_for_variable¶

def get_pauli_for_variable(self, var_idx: int) -> tuple[int, PauliType]

Get Pauli operator for a variable.

Parameters:

Returns:

tuple[int, PauliType] — Tuple of (qubit_index, pauli_type)

GraphColoringQRACEncoder [source]¶

class GraphColoringQRACEncoder(BaseQRACEncoder, abc.ABC)

Base for graph-coloring-based QRAC encoders (21, 31, 32).

Subclasses only need to set max_color_group_size and paulis.

The encoding process:

1. Graph coloring on the interaction graph.

2. Adds linear-only variables to color groups.

3. Assigns Pauli operators to variables within each qubit.

Constructor¶

def __init__(self, spin_model: BinaryModel) -> None

Attributes¶

• color_group: dict[int, list[int]] Mapping from qubit index to list of variable indices.

• max_color_group_size: int Maximum number of variables per qubit.

• num_logical_qubits: int Number of logical qubits (color groups) after QRAC encoding.

• paulis: list[PauliType] Pauli types to assign within each color group (in order).

Methods¶

encode_ising¶

def encode_ising(
    self,
    ising: BinaryModel,
) -> tuple[qm_o.Hamiltonian, dict[int, qm_o.PauliOperator]]

Encode a spin model into a relaxed QRAC Hamiltonian.

Uses the encoding determined by _perform_encoding and delegates operator/scale computation to _get_operator_and_scale.

Parameters:

Returns:

tuple[qm_o.Hamiltonian, dict[int, qm_o.PauliOperator]] — Tuple of (relaxed Hamiltonian, encoding map).

QRAC21Converter [source]¶

class QRAC21Converter(QRACConverterBase[QRAC21Encoder])

QRAC(2,1,p) Converter for Quantum Random Access Optimization.

Converts optimization problems into QRAC-encoded form with reduced qubit count. Up to 2 variables are encoded into a single qubit using X and Z Pauli operators.

Example:

>>> converter = QRAC21Converter(instance)
>>> hamiltonian = converter.get_cost_hamiltonian()

Attributes¶

• num_qubits: int

Methods¶

get_cost_hamiltonian¶

def get_cost_hamiltonian(self) -> qm_o.Hamiltonian

Generate the cost Hamiltonian for the QRAC-encoded problem.

Returns:

qm_o.Hamiltonian — Hamiltonian representing the cost function in QRAC form.

get_encoded_pauli_list¶

def get_encoded_pauli_list(self) -> list[qm_o.Hamiltonian]

Get the encoded Pauli operators as a list of Hamiltonians.

Returns:

list[qm_o.Hamiltonian] — list[Hamiltonian]: List of Hamiltonians for each variable’s Pauli operator.

QRAC21Encoder [source]¶

class QRAC21Encoder(GraphColoringQRACEncoder)

(2,1,p)-QRAC Encoder.

Encodes Ising model variables into Pauli operators using 2-coloring. Up to 2 variables per qubit, using Z and X Paulis.

The relaxed Hamiltonian is:

H̃ = Σ_{ij} √k_i·√k_j·J_{ij}·P_{f(i)}·P_{f(j)} + Σ_i √k_i·h_i·P_{f(i)}

where k_i is the number of variables encoded on the qubit containing variable i.

Attributes¶

• max_color_group_size: int

• num_qubits: int

• paulis: list[PauliType]

QRAC31Converter [source]¶

class QRAC31Converter(QRACConverterBase[QRAC31Encoder])

QRAC(3,1,p) Converter for Quantum Random Access Optimization.

Converts optimization problems into QRAC-encoded form with reduced qubit count. Up to 3 variables are encoded into a single qubit using Pauli operators.

Example:

>>> converter = QRAC31Converter(instance)
>>> hamiltonian = converter.get_cost_hamiltonian()

Attributes¶

• num_qubits: int

Methods¶

get_cost_hamiltonian¶

def get_cost_hamiltonian(self) -> qm_o.Hamiltonian

Generate the cost Hamiltonian for the QRAC-encoded problem.

Returns:

qm_o.Hamiltonian — Hamiltonian representing the cost function in QRAC form.

get_encoded_pauli_list¶

def get_encoded_pauli_list(self) -> list[qm_o.Hamiltonian]

Get the encoded Pauli operators as a list of Hamiltonians.

Returns:

list[qm_o.Hamiltonian] — list[Hamiltonian]: List of Hamiltonians for each variable’s Pauli operator.

QRAC31Encoder [source]¶

class QRAC31Encoder(GraphColoringQRACEncoder)

(3,1,p)-QRAC Encoder.

Encodes Ising model variables into Pauli operators on qubits using graph coloring to ensure that interacting variables are assigned to different qubits.

The relaxed Hamiltonian is:

H̃ = Σ_{ij} √k_i·√k_j·J_{ij}·P_{f(i)}·P_{f(j)} + Σ_i √k_i·h_i·P_{f(i)}

where f(i) = (qubit_index, pauli_type) maps variable i to a Pauli operator, and k_i is the number of variables encoded on the qubit containing variable i.

Attributes¶

• max_color_group_size: int

• num_qubits: int

• paulis: list[PauliType]

QRAC32Converter [source]¶

class QRAC32Converter(QRACConverterBase[QRAC32Encoder])

QRAC(3,2,p) Converter for Quantum Random Access Optimization.

Converts optimization problems into QRAC-encoded form. Color groups with k>=2 variables use 2-local prime operators (X’, Y’, Z’) on 2 physical qubits. Groups with k=1 use a regular Pauli on 1 physical qubit.

Example:

>>> converter = QRAC32Converter(instance)
>>> hamiltonian = converter.get_cost_hamiltonian()

Attributes¶

• num_qubits: int

Methods¶

get_cost_hamiltonian¶

def get_cost_hamiltonian(self) -> qm_o.Hamiltonian

Generate the cost Hamiltonian for the QRAC-encoded problem.

Returns:

qm_o.Hamiltonian — Hamiltonian representing the cost function in QRAC form.

get_encoded_pauli_list¶

def get_encoded_pauli_list(self) -> list[qm_o.Hamiltonian]

Get the encoded Pauli operators as a list of Hamiltonians.

Returns:

list[qm_o.Hamiltonian] — list[Hamiltonian]: List of Hamiltonians for each variable’s Pauli operator.

QRAC32Encoder [source]¶

class QRAC32Encoder(GraphColoringQRACEncoder)

(3,2,p)-QRAC Encoder.

Same graph coloring as (3,1,p) but uses 2-local prime operators for color groups with k>=2 variables. Groups with k=1 use a single physical qubit with a regular Pauli operator.

Physical qubit allocation per color group:

k=1: 1 physical qubit (regular Pauli, scale=1) k=2: 2 physical qubits (prime operators, scale=√(2·2)=2) k=3: 2 physical qubits (prime operators, scale=√(2·3)=√6)

Attributes¶

• max_color_group_size: int

• num_qubits: int Number of physical qubits (1 per k=1 group, 2 per k>=2 group).

• paulis: list[PauliType]

QRACSpaceEfficientConverter [source]¶

class QRACSpaceEfficientConverter(QRACConverterBase[QRACSpaceEfficientEncoder])

Space Efficient QRAC Converter for Quantum Random Access Optimization.

Uses sequential numbering with constant 2:1 compression ratio. No graph coloring is performed.

Example:

>>> converter = QRACSpaceEfficientConverter(instance)
>>> hamiltonian = converter.get_cost_hamiltonian()

Attributes¶

• num_qubits: int

Methods¶

get_cost_hamiltonian¶

def get_cost_hamiltonian(self) -> qm_o.Hamiltonian

Generate the cost Hamiltonian for the space-efficient QRAC-encoded problem.

Returns:

qm_o.Hamiltonian — Hamiltonian representing the cost function in QRAC form.

get_encoded_pauli_list¶

def get_encoded_pauli_list(self) -> list[qm_o.Hamiltonian]

Get the encoded Pauli operators as a list of Hamiltonians.

Returns:

list[qm_o.Hamiltonian] — list[Hamiltonian]: List of Hamiltonians for each variable’s Pauli operator.

QRACSpaceEfficientEncoder [source]¶

class QRACSpaceEfficientEncoder(BaseQRACEncoder)

Space Efficient QRAC Encoder.

No graph coloring. Uses sequential numbering: variable i -> qubit i//2, Pauli X (even index) or Y (odd index).

Always maintains a 2:1 compression ratio.

Attributes¶

• num_qubits: int

SignRounder [source]¶

class SignRounder

Simple sign-based rounding.

Rounds Pauli expectation values to spin values using the sign function:

• <P_i> >= 0 → s_i = +1

• <P_i> < 0 → s_i = -1

Example:

>>> rounder = SignRounder()
>>> expectations = [0.8, -0.3, 0.1]  # Pauli expectation values
>>> spins = rounder.round(expectations)
>>> print(spins)  # [1, -1, 1]

Methods¶

round¶

def round(self, expectations: list[float]) -> list[int]

Round Pauli expectations to spin values.

Parameters:

Returns:

list[int] — List of spin values (+1 or -1) for each variable

qamomile.optimization.qrao.base_converter¶

Base class for QRAC-based converters.

This module provides the QRACConverterBase class that implements shared functionality across all QRAC converter variants.

Overview¶

Classes¶

MathematicalProblemConverter [source]¶

class MathematicalProblemConverter(abc.ABC)

Constructor¶

def __init__(self, instance: ommx.v1.Instance | BinaryModel) -> None

Attributes¶

• instance

• original_vartype

• spin_model

Methods¶

decode¶

def decode(self, samples: SampleResult[list[int]]) -> BinarySampleSet

Decode quantum measurement results.

Returns results in the original vartype (BINARY or SPIN) that was provided when constructing the converter.

get_cost_hamiltonian¶

def get_cost_hamiltonian(self) -> qm_o.Hamiltonian

Construct the cost Hamiltonian.

Subclasses must implement this method to build the appropriate Hamiltonian for their specific algorithm (e.g., Pauli-Z for QAOA, QRAC-encoded for QRAO).

Returns:

qm_o.Hamiltonian — qm_o.Hamiltonian: The cost Hamiltonian.

QRACConverterBase [source]¶

class QRACConverterBase(MathematicalProblemConverter, abc.ABC, Generic[EncoderT])

Abstract base for all QRAC-based converters.

Subclasses must implement:

• num_qubits (property)

• get_encoded_pauli_list()

Ansatz Construction:

This converter does not provide a built-in ansatz, giving users full control over their variational circuit design. Use building blocks from :mod:qamomile.circuit.algorithm.basic to compose your own ansatz:

import qamomile.circuit as qmc
from qamomile.circuit.algorithm.basic import (
    ry_layer, rz_layer, cz_entangling_layer,
)

@qmc.qkernel
def my_ansatz(
    n: qmc.UInt,
    depth: qmc.UInt,
    thetas: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]:
    q = qmc.allocate(n)
    for i in qmc.range(n):
        q[i] = qmc.h(q[i])
    for d in qmc.range(depth):
        offset = d * 2 * n
        q = ry_layer(q, thetas, offset)
        q = rz_layer(q, thetas, offset + n)
        q = cz_entangling_layer(q)
    return q

Available layers in qamomile.circuit.algorithm.basic:

• rx_layer, ry_layer, rz_layer: Single-qubit rotation layers

• cz_entangling_layer: CZ entangling with linear connectivity

The total number of variational parameters depends on the ansatz design. For the example above it is 2 * num_qubits * depth.

Attributes¶

• encoder: EncoderT The QRAC encoder used by this converter.

• num_qubits: int Number of qubits after QRAC encoding.

Methods¶

get_encoded_pauli_list¶

def get_encoded_pauli_list(self) -> list[qm_o.Hamiltonian]

qamomile.optimization.qrao.base_encoder¶

QRAC Encoder base classes and utilities.

This module provides:

• BaseQRACEncoder: Abstract base for all QRAC encoders with validation.

• GraphColoringQRACEncoder: Intermediate base for graph-coloring-based encoders.

• Utility functions for Pauli encoding, occupancy mapping, and physical qubit mapping.

Concrete encoder classes live alongside their converters:

• QRAC21Encoder in qrao21.py

• QRAC31Encoder in qrao31.py

• QRAC32Encoder in qrao32.py

• QRACSpaceEfficientEncoder in qrao_space_efficient.py

Overview¶

Functions¶

check_linear_term [source]¶

def check_linear_term(
    color_group: dict[int, list[int]],
    linear_term_index: Iterable[int],
    max_color_group_size: int,
) -> dict[int, list[int]]

Search for items within the index of linear term that have not been assigned to the color_group, and add them.

Parameters:

Returns:

dict[int, list[int]] — dict[int, list[int]]: color_group which added items within the index of linear term that have not been assigned to the color_group.

color_group_to_qrac_encode [source]¶

def color_group_to_qrac_encode(color_group: dict[int, list[int]]) -> dict[int, qm_o.PauliOperator]

Encode a color group mapping into Pauli operator assignments.

Assigns Z, X, Y Pauli operators (in order) to variables within each qubit’s color group.

Parameters:

Returns:

dict[int, qm_o.PauliOperator] — Mapping from variable index to PauliOperator.

Examples:

>>> color_group = {0: [0, 1, 2], 1: [3, 4], 2: [6,]}
>>> color_group_to_qrac_encode(color_group)
{0: Z0, 1: X0, 2: Y0, 3: Z1, 4: X1, 6: Z2}

greedy_graph_coloring [source]¶

def greedy_graph_coloring(
    graph: Iterable[tuple[int, int]],
    max_color_group_size: int,
    init_coloring: Optional[dict[int, int]] = None,
) -> tuple[dict[int, int], dict[int, list[int]]]

graph coloring for QRAC

Parameters:

Returns:

tuple[dict[int, int], dict[int, list[int]]] — tuple[dict[int, int], dict[int, list[int]]]: coloring, color_group

Examples:

>>> graph = [(0, 1), (1, 2), (2, 0), (0, 4)]
>>> greedy_graph_coloring(graph, 2)
({0: 0, 1: 1, 2: 2, 4: 1}, {0: [0], 1: [1, 4], 2: [2]})

is_close_zero [source]¶

def is_close_zero(value: float, abs_tol = 1e-15) -> bool

Check if a given floating-point value is close to zero within a small tolerance.

Parameters:

Returns:

bool — True if the value is close to zero, False otherwise.

Classes¶

BaseQRACEncoder [source]¶

class BaseQRACEncoder(abc.ABC)

Abstract base for all QRAC encoders.

Provides:

• Input validation (spin vartype, no HUBO terms).

• Common pauli_encoding property and get_pauli_for_variable method.

• Abstract hooks for _perform_encoding and num_qubits.

Subclasses must implement _perform_encoding and num_qubits.

Constructor¶

def __init__(self, spin_model: BinaryModel) -> None

Attributes¶

• num_qubits: int Number of qubits after QRAC encoding.

• pauli_encoding: dict[int, tuple[int, PauliType]] Mapping from variable index to (qubit, pauli_type).

• spin_model

Methods¶

get_pauli_for_variable¶

def get_pauli_for_variable(self, var_idx: int) -> tuple[int, PauliType]

Get Pauli operator for a variable.

Parameters:

Returns:

tuple[int, PauliType] — Tuple of (qubit_index, pauli_type)

GraphColoringQRACEncoder [source]¶

class GraphColoringQRACEncoder(BaseQRACEncoder, abc.ABC)

Base for graph-coloring-based QRAC encoders (21, 31, 32).

Subclasses only need to set max_color_group_size and paulis.

The encoding process:

1. Graph coloring on the interaction graph.

2. Adds linear-only variables to color groups.

3. Assigns Pauli operators to variables within each qubit.

Constructor¶

def __init__(self, spin_model: BinaryModel) -> None

Attributes¶

• color_group: dict[int, list[int]] Mapping from qubit index to list of variable indices.

• max_color_group_size: int Maximum number of variables per qubit.

• num_logical_qubits: int Number of logical qubits (color groups) after QRAC encoding.

• paulis: list[PauliType] Pauli types to assign within each color group (in order).

Methods¶

encode_ising¶

def encode_ising(
    self,
    ising: BinaryModel,
) -> tuple[qm_o.Hamiltonian, dict[int, qm_o.PauliOperator]]

Encode a spin model into a relaxed QRAC Hamiltonian.

Uses the encoding determined by _perform_encoding and delegates operator/scale computation to _get_operator_and_scale.

Parameters:

Returns:

tuple[qm_o.Hamiltonian, dict[int, qm_o.PauliOperator]] — Tuple of (relaxed Hamiltonian, encoding map).

qamomile.optimization.qrao.graph_coloring¶

Overview¶

Functions¶

check_linear_term [source]¶

def check_linear_term(
    color_group: dict[int, list[int]],
    linear_term_index: Iterable[int],
    max_color_group_size: int,
) -> dict[int, list[int]]

Search for items within the index of linear term that have not been assigned to the color_group, and add them.

Parameters:

Returns:

dict[int, list[int]] — dict[int, list[int]]: color_group which added items within the index of linear term that have not been assigned to the color_group.

greedy_graph_coloring [source]¶

def greedy_graph_coloring(
    graph: Iterable[tuple[int, int]],
    max_color_group_size: int,
    init_coloring: Optional[dict[int, int]] = None,
) -> tuple[dict[int, int], dict[int, list[int]]]

graph coloring for QRAC

Parameters:

Returns:

tuple[dict[int, int], dict[int, list[int]]] — tuple[dict[int, int], dict[int, list[int]]]: coloring, color_group

Examples:

>>> graph = [(0, 1), (1, 2), (2, 0), (0, 4)]
>>> greedy_graph_coloring(graph, 2)
({0: 0, 1: 1, 2: 2, 4: 1}, {0: [0], 1: [1, 4], 2: [2]})

qamomile.optimization.qrao.qrao21¶

QRAC(2,1,p) Converter for Quantum Random Access Optimization.

This module provides the QRAC21Converter class that converts optimization problems into QRAC-encoded quantum circuits using (2,1,p)-QRAC. Up to 2 variables are encoded into a single qubit using X and Z Pauli operators.

Overview¶

Classes¶

GraphColoringQRACEncoder [source]¶

class GraphColoringQRACEncoder(BaseQRACEncoder, abc.ABC)

Base for graph-coloring-based QRAC encoders (21, 31, 32).

Subclasses only need to set max_color_group_size and paulis.

The encoding process:

1. Graph coloring on the interaction graph.

2. Adds linear-only variables to color groups.

3. Assigns Pauli operators to variables within each qubit.

Constructor¶

def __init__(self, spin_model: BinaryModel) -> None

Attributes¶

• color_group: dict[int, list[int]] Mapping from qubit index to list of variable indices.

• max_color_group_size: int Maximum number of variables per qubit.

• num_logical_qubits: int Number of logical qubits (color groups) after QRAC encoding.

• paulis: list[PauliType] Pauli types to assign within each color group (in order).

Methods¶

encode_ising¶

def encode_ising(
    self,
    ising: BinaryModel,
) -> tuple[qm_o.Hamiltonian, dict[int, qm_o.PauliOperator]]

Encode a spin model into a relaxed QRAC Hamiltonian.

Uses the encoding determined by _perform_encoding and delegates operator/scale computation to _get_operator_and_scale.

Parameters:

Returns:

tuple[qm_o.Hamiltonian, dict[int, qm_o.PauliOperator]] — Tuple of (relaxed Hamiltonian, encoding map).

QRAC21Converter [source]¶

class QRAC21Converter(QRACConverterBase[QRAC21Encoder])

QRAC(2,1,p) Converter for Quantum Random Access Optimization.

Converts optimization problems into QRAC-encoded form with reduced qubit count. Up to 2 variables are encoded into a single qubit using X and Z Pauli operators.

Example:

>>> converter = QRAC21Converter(instance)
>>> hamiltonian = converter.get_cost_hamiltonian()

Attributes¶

• num_qubits: int

Methods¶

get_cost_hamiltonian¶

def get_cost_hamiltonian(self) -> qm_o.Hamiltonian

Generate the cost Hamiltonian for the QRAC-encoded problem.

Returns:

qm_o.Hamiltonian — Hamiltonian representing the cost function in QRAC form.

get_encoded_pauli_list¶

def get_encoded_pauli_list(self) -> list[qm_o.Hamiltonian]

Get the encoded Pauli operators as a list of Hamiltonians.

Returns:

list[qm_o.Hamiltonian] — list[Hamiltonian]: List of Hamiltonians for each variable’s Pauli operator.

QRAC21Encoder [source]¶

class QRAC21Encoder(GraphColoringQRACEncoder)

(2,1,p)-QRAC Encoder.

Encodes Ising model variables into Pauli operators using 2-coloring. Up to 2 variables per qubit, using Z and X Paulis.

The relaxed Hamiltonian is:

H̃ = Σ_{ij} √k_i·√k_j·J_{ij}·P_{f(i)}·P_{f(j)} + Σ_i √k_i·h_i·P_{f(i)}

where k_i is the number of variables encoded on the qubit containing variable i.

Attributes¶

• max_color_group_size: int

• num_qubits: int

• paulis: list[PauliType]

QRACConverterBase [source]¶

class QRACConverterBase(MathematicalProblemConverter, abc.ABC, Generic[EncoderT])

Abstract base for all QRAC-based converters.

Subclasses must implement:

• num_qubits (property)

• get_encoded_pauli_list()

Ansatz Construction:

This converter does not provide a built-in ansatz, giving users full control over their variational circuit design. Use building blocks from :mod:qamomile.circuit.algorithm.basic to compose your own ansatz:

import qamomile.circuit as qmc
from qamomile.circuit.algorithm.basic import (
    ry_layer, rz_layer, cz_entangling_layer,
)

@qmc.qkernel
def my_ansatz(
    n: qmc.UInt,
    depth: qmc.UInt,
    thetas: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]:
    q = qmc.allocate(n)
    for i in qmc.range(n):
        q[i] = qmc.h(q[i])
    for d in qmc.range(depth):
        offset = d * 2 * n
        q = ry_layer(q, thetas, offset)
        q = rz_layer(q, thetas, offset + n)
        q = cz_entangling_layer(q)
    return q

Available layers in qamomile.circuit.algorithm.basic:

• rx_layer, ry_layer, rz_layer: Single-qubit rotation layers

• cz_entangling_layer: CZ entangling with linear connectivity

The total number of variational parameters depends on the ansatz design. For the example above it is 2 * num_qubits * depth.

Attributes¶

• encoder: EncoderT The QRAC encoder used by this converter.

• num_qubits: int Number of qubits after QRAC encoding.

Methods¶

get_encoded_pauli_list¶

def get_encoded_pauli_list(self) -> list[qm_o.Hamiltonian]

qamomile.optimization.qrao.qrao31¶

QRAC(3,1,p) Converter for Quantum Random Access Optimization.

This module provides the QRAC31Converter class that converts optimization problems into QRAC-encoded quantum circuits and handles result decoding.

Overview¶

Classes¶

GraphColoringQRACEncoder [source]¶

class GraphColoringQRACEncoder(BaseQRACEncoder, abc.ABC)

Base for graph-coloring-based QRAC encoders (21, 31, 32).

Subclasses only need to set max_color_group_size and paulis.

The encoding process:

1. Graph coloring on the interaction graph.

2. Adds linear-only variables to color groups.

3. Assigns Pauli operators to variables within each qubit.

Constructor¶

def __init__(self, spin_model: BinaryModel) -> None

Attributes¶

• color_group: dict[int, list[int]] Mapping from qubit index to list of variable indices.

• max_color_group_size: int Maximum number of variables per qubit.

• num_logical_qubits: int Number of logical qubits (color groups) after QRAC encoding.

• paulis: list[PauliType] Pauli types to assign within each color group (in order).

Methods¶

encode_ising¶

def encode_ising(
    self,
    ising: BinaryModel,
) -> tuple[qm_o.Hamiltonian, dict[int, qm_o.PauliOperator]]

Encode a spin model into a relaxed QRAC Hamiltonian.

Uses the encoding determined by _perform_encoding and delegates operator/scale computation to _get_operator_and_scale.

Parameters:

Returns:

tuple[qm_o.Hamiltonian, dict[int, qm_o.PauliOperator]] — Tuple of (relaxed Hamiltonian, encoding map).

QRAC31Converter [source]¶

class QRAC31Converter(QRACConverterBase[QRAC31Encoder])

QRAC(3,1,p) Converter for Quantum Random Access Optimization.

Converts optimization problems into QRAC-encoded form with reduced qubit count. Up to 3 variables are encoded into a single qubit using Pauli operators.

Example:

>>> converter = QRAC31Converter(instance)
>>> hamiltonian = converter.get_cost_hamiltonian()

Attributes¶

• num_qubits: int

Methods¶

get_cost_hamiltonian¶

def get_cost_hamiltonian(self) -> qm_o.Hamiltonian

Generate the cost Hamiltonian for the QRAC-encoded problem.

Returns:

qm_o.Hamiltonian — Hamiltonian representing the cost function in QRAC form.

get_encoded_pauli_list¶

def get_encoded_pauli_list(self) -> list[qm_o.Hamiltonian]

Get the encoded Pauli operators as a list of Hamiltonians.

Returns:

list[qm_o.Hamiltonian] — list[Hamiltonian]: List of Hamiltonians for each variable’s Pauli operator.

QRAC31Encoder [source]¶

class QRAC31Encoder(GraphColoringQRACEncoder)

(3,1,p)-QRAC Encoder.

Encodes Ising model variables into Pauli operators on qubits using graph coloring to ensure that interacting variables are assigned to different qubits.

The relaxed Hamiltonian is:

H̃ = Σ_{ij} √k_i·√k_j·J_{ij}·P_{f(i)}·P_{f(j)} + Σ_i √k_i·h_i·P_{f(i)}

where f(i) = (qubit_index, pauli_type) maps variable i to a Pauli operator, and k_i is the number of variables encoded on the qubit containing variable i.

Attributes¶

• max_color_group_size: int

• num_qubits: int

• paulis: list[PauliType]

QRACConverterBase [source]¶

class QRACConverterBase(MathematicalProblemConverter, abc.ABC, Generic[EncoderT])

Abstract base for all QRAC-based converters.

Subclasses must implement:

• num_qubits (property)

• get_encoded_pauli_list()

Ansatz Construction:

This converter does not provide a built-in ansatz, giving users full control over their variational circuit design. Use building blocks from :mod:qamomile.circuit.algorithm.basic to compose your own ansatz:

import qamomile.circuit as qmc
from qamomile.circuit.algorithm.basic import (
    ry_layer, rz_layer, cz_entangling_layer,
)

@qmc.qkernel
def my_ansatz(
    n: qmc.UInt,
    depth: qmc.UInt,
    thetas: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]:
    q = qmc.allocate(n)
    for i in qmc.range(n):
        q[i] = qmc.h(q[i])
    for d in qmc.range(depth):
        offset = d * 2 * n
        q = ry_layer(q, thetas, offset)
        q = rz_layer(q, thetas, offset + n)
        q = cz_entangling_layer(q)
    return q

Available layers in qamomile.circuit.algorithm.basic:

• rx_layer, ry_layer, rz_layer: Single-qubit rotation layers

• cz_entangling_layer: CZ entangling with linear connectivity

The total number of variational parameters depends on the ansatz design. For the example above it is 2 * num_qubits * depth.

Attributes¶

• encoder: EncoderT The QRAC encoder used by this converter.

• num_qubits: int Number of qubits after QRAC encoding.

Methods¶

get_encoded_pauli_list¶

def get_encoded_pauli_list(self) -> list[qm_o.Hamiltonian]

qamomile.optimization.qrao.qrao32¶

QRAC(3,2,p) Converter for Quantum Random Access Optimization.

This module provides the QRAC32Converter class that converts optimization problems into QRAC-encoded quantum circuits using (3,2,p)-QRAC.

Color groups with k>=2 variables use 2-local prime operators (X’, Y’, Z’) on 2 physical qubits. Groups with k=1 variable fall back to a regular 1-local Pauli on a single physical qubit.

Overview¶

Functions¶

build_physical_qubit_map [source]¶

def build_physical_qubit_map(color_group: dict[int, list[int]]) -> tuple[dict[int, int], int]

Map color (logical) index to physical qubit start index.

For (3,2,p)-QRAC, color groups with k=1 variable use 1 physical qubit (regular Pauli), while groups with k>=2 variables use 2 physical qubits (prime operators).

Parameters:

Returns:

tuple[dict[int, int], int] — Tuple of (color_to_phys_start mapping, total_physical_qubits).

create_prime_operator [source]¶

def create_prime_operator(pauli_op: qm_o.PauliOperator, phys_start: int) -> qm_o.Hamiltonian

Convert a logical PauliOperator to its prime (2-qubit) form.

Parameters:

Returns:

qm_o.Hamiltonian — Hamiltonian representing the 2-local prime operator.

create_x_prime [source]¶

def create_x_prime(idx: int) -> qm_o.Hamiltonian

Create X’ operator for the given 2-qubit starting index.

X’ = (1/√6) * (1/2 * X₁X₂ + 1/2 * X₁Z₂ + Z₁I₂)

Parameters:

Returns:

qm_o.Hamiltonian — Hamiltonian representing the X’ operator.

create_y_prime [source]¶

def create_y_prime(idx: int) -> qm_o.Hamiltonian

Create Y’ operator for the given 2-qubit starting index.

Y’ = (1/√6) * (1/2 * I₁X₂ + I₁Z₂ + 1/2 * Y₁Y₂)

Parameters:

Returns:

qm_o.Hamiltonian — Hamiltonian representing the Y’ operator.

create_z_prime [source]¶

def create_z_prime(idx: int) -> qm_o.Hamiltonian

Create Z’ operator for the given 2-qubit starting index.

Z’ = (1/√6) * (Z₁Z₂ - 1/2 * X₁I₂ - 1/2 * Z₁X₂)

Parameters:

Returns:

qm_o.Hamiltonian — Hamiltonian representing the Z’ operator.

Classes¶

GraphColoringQRACEncoder [source]¶

class GraphColoringQRACEncoder(BaseQRACEncoder, abc.ABC)

Base for graph-coloring-based QRAC encoders (21, 31, 32).

Subclasses only need to set max_color_group_size and paulis.

The encoding process:

1. Graph coloring on the interaction graph.

2. Adds linear-only variables to color groups.

3. Assigns Pauli operators to variables within each qubit.

Constructor¶

def __init__(self, spin_model: BinaryModel) -> None

Attributes¶

• color_group: dict[int, list[int]] Mapping from qubit index to list of variable indices.

• max_color_group_size: int Maximum number of variables per qubit.

• num_logical_qubits: int Number of logical qubits (color groups) after QRAC encoding.

• paulis: list[PauliType] Pauli types to assign within each color group (in order).

Methods¶

encode_ising¶

def encode_ising(
    self,
    ising: BinaryModel,
) -> tuple[qm_o.Hamiltonian, dict[int, qm_o.PauliOperator]]

Encode a spin model into a relaxed QRAC Hamiltonian.

Uses the encoding determined by _perform_encoding and delegates operator/scale computation to _get_operator_and_scale.

Parameters:

Returns:

tuple[qm_o.Hamiltonian, dict[int, qm_o.PauliOperator]] — Tuple of (relaxed Hamiltonian, encoding map).

QRAC32Converter [source]¶

class QRAC32Converter(QRACConverterBase[QRAC32Encoder])

QRAC(3,2,p) Converter for Quantum Random Access Optimization.

Converts optimization problems into QRAC-encoded form. Color groups with k>=2 variables use 2-local prime operators (X’, Y’, Z’) on 2 physical qubits. Groups with k=1 use a regular Pauli on 1 physical qubit.

Example:

>>> converter = QRAC32Converter(instance)
>>> hamiltonian = converter.get_cost_hamiltonian()

Attributes¶

• num_qubits: int

Methods¶

get_cost_hamiltonian¶

def get_cost_hamiltonian(self) -> qm_o.Hamiltonian

Generate the cost Hamiltonian for the QRAC-encoded problem.

Returns:

qm_o.Hamiltonian — Hamiltonian representing the cost function in QRAC form.

get_encoded_pauli_list¶

def get_encoded_pauli_list(self) -> list[qm_o.Hamiltonian]

Get the encoded Pauli operators as a list of Hamiltonians.

Returns:

list[qm_o.Hamiltonian] — list[Hamiltonian]: List of Hamiltonians for each variable’s Pauli operator.

QRAC32Encoder [source]¶

class QRAC32Encoder(GraphColoringQRACEncoder)

(3,2,p)-QRAC Encoder.

Same graph coloring as (3,1,p) but uses 2-local prime operators for color groups with k>=2 variables. Groups with k=1 use a single physical qubit with a regular Pauli operator.

Physical qubit allocation per color group:

k=1: 1 physical qubit (regular Pauli, scale=1) k=2: 2 physical qubits (prime operators, scale=√(2·2)=2) k=3: 2 physical qubits (prime operators, scale=√(2·3)=√6)

Attributes¶

• max_color_group_size: int

• num_qubits: int Number of physical qubits (1 per k=1 group, 2 per k>=2 group).

• paulis: list[PauliType]

QRACConverterBase [source]¶

class QRACConverterBase(MathematicalProblemConverter, abc.ABC, Generic[EncoderT])

Abstract base for all QRAC-based converters.

Subclasses must implement:

• num_qubits (property)

• get_encoded_pauli_list()

Ansatz Construction:

This converter does not provide a built-in ansatz, giving users full control over their variational circuit design. Use building blocks from :mod:qamomile.circuit.algorithm.basic to compose your own ansatz:

import qamomile.circuit as qmc
from qamomile.circuit.algorithm.basic import (
    ry_layer, rz_layer, cz_entangling_layer,
)

@qmc.qkernel
def my_ansatz(
    n: qmc.UInt,
    depth: qmc.UInt,
    thetas: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]:
    q = qmc.allocate(n)
    for i in qmc.range(n):
        q[i] = qmc.h(q[i])
    for d in qmc.range(depth):
        offset = d * 2 * n
        q = ry_layer(q, thetas, offset)
        q = rz_layer(q, thetas, offset + n)
        q = cz_entangling_layer(q)
    return q

Available layers in qamomile.circuit.algorithm.basic:

• rx_layer, ry_layer, rz_layer: Single-qubit rotation layers

• cz_entangling_layer: CZ entangling with linear connectivity

The total number of variational parameters depends on the ansatz design. For the example above it is 2 * num_qubits * depth.

Attributes¶

• encoder: EncoderT The QRAC encoder used by this converter.

• num_qubits: int Number of qubits after QRAC encoding.

Methods¶

get_encoded_pauli_list¶

def get_encoded_pauli_list(self) -> list[qm_o.Hamiltonian]

qamomile.optimization.qrao.qrao_space_efficient¶

Space Efficient QRAC Converter for Quantum Random Access Optimization.

This module implements Space Efficient QRAO which maintains a constant 2:1 compression ratio by using sequential numbering instead of graph coloring.

Variables are alternately assigned X and Y Pauli operators on consecutive qubits. When interacting variables share the same qubit, a Z operator is used instead of the product of their Paulis.

Overview¶

Functions¶

is_close_zero [source]¶

def is_close_zero(value: float, abs_tol = 1e-15) -> bool

Check if a given floating-point value is close to zero within a small tolerance.

Parameters:

Returns:

bool — True if the value is close to zero, False otherwise.

numbering_space_efficient_encode [source]¶

def numbering_space_efficient_encode(ising: BinaryModel[Literal[VarType.SPIN]]) -> dict[int, qm_o.PauliOperator]

Encode using sequential numbering.

Variable i is assigned to qubit i//2 with Pauli X (even) or Y (odd).

Parameters:

Returns:

dict[int, qm_o.PauliOperator] — Mapping from variable index to PauliOperator.

qrac_space_efficient_encode_ising [source]¶

def qrac_space_efficient_encode_ising(
    ising: BinaryModel[Literal[VarType.SPIN]],
) -> tuple[qm_o.Hamiltonian, dict[int, qm_o.PauliOperator]]

Encode a spin model using space-efficient QRAC.

For quadratic terms:

• Same qubit: √3 * J_{ij} * Z_k

• Different qubit: 3 * J_{ij} * P_{f(i)} * P_{f(j)}

Parameters:

Returns:

tuple[qm_o.Hamiltonian, dict[int, qm_o.PauliOperator]] — Tuple of (relaxed Hamiltonian, encoding map).

Classes¶

BaseQRACEncoder [source]¶

class BaseQRACEncoder(abc.ABC)

Abstract base for all QRAC encoders.

Provides:

• Input validation (spin vartype, no HUBO terms).

• Common pauli_encoding property and get_pauli_for_variable method.

• Abstract hooks for _perform_encoding and num_qubits.

Subclasses must implement _perform_encoding and num_qubits.

Constructor¶

def __init__(self, spin_model: BinaryModel) -> None

Attributes¶

• num_qubits: int Number of qubits after QRAC encoding.

• pauli_encoding: dict[int, tuple[int, PauliType]] Mapping from variable index to (qubit, pauli_type).

• spin_model

Methods¶

get_pauli_for_variable¶

def get_pauli_for_variable(self, var_idx: int) -> tuple[int, PauliType]

Get Pauli operator for a variable.

Parameters:

Returns:

tuple[int, PauliType] — Tuple of (qubit_index, pauli_type)

QRACConverterBase [source]¶

class QRACConverterBase(MathematicalProblemConverter, abc.ABC, Generic[EncoderT])

Abstract base for all QRAC-based converters.

Subclasses must implement:

• num_qubits (property)

• get_encoded_pauli_list()

Ansatz Construction:

This converter does not provide a built-in ansatz, giving users full control over their variational circuit design. Use building blocks from :mod:qamomile.circuit.algorithm.basic to compose your own ansatz:

import qamomile.circuit as qmc
from qamomile.circuit.algorithm.basic import (
    ry_layer, rz_layer, cz_entangling_layer,
)

@qmc.qkernel
def my_ansatz(
    n: qmc.UInt,
    depth: qmc.UInt,
    thetas: qmc.Vector[qmc.Float],
) -> qmc.Vector[qmc.Qubit]:
    q = qmc.allocate(n)
    for i in qmc.range(n):
        q[i] = qmc.h(q[i])
    for d in qmc.range(depth):
        offset = d * 2 * n
        q = ry_layer(q, thetas, offset)
        q = rz_layer(q, thetas, offset + n)
        q = cz_entangling_layer(q)
    return q

Available layers in qamomile.circuit.algorithm.basic:

• rx_layer, ry_layer, rz_layer: Single-qubit rotation layers

• cz_entangling_layer: CZ entangling with linear connectivity

The total number of variational parameters depends on the ansatz design. For the example above it is 2 * num_qubits * depth.

Attributes¶

• encoder: EncoderT The QRAC encoder used by this converter.

• num_qubits: int Number of qubits after QRAC encoding.

Methods¶

get_encoded_pauli_list¶

def get_encoded_pauli_list(self) -> list[qm_o.Hamiltonian]

QRACSpaceEfficientConverter [source]¶

class QRACSpaceEfficientConverter(QRACConverterBase[QRACSpaceEfficientEncoder])

Space Efficient QRAC Converter for Quantum Random Access Optimization.

Uses sequential numbering with constant 2:1 compression ratio. No graph coloring is performed.

Example:

>>> converter = QRACSpaceEfficientConverter(instance)
>>> hamiltonian = converter.get_cost_hamiltonian()

Attributes¶

• num_qubits: int

Methods¶

get_cost_hamiltonian¶

def get_cost_hamiltonian(self) -> qm_o.Hamiltonian

Generate the cost Hamiltonian for the space-efficient QRAC-encoded problem.

Returns:

qm_o.Hamiltonian — Hamiltonian representing the cost function in QRAC form.

get_encoded_pauli_list¶

def get_encoded_pauli_list(self) -> list[qm_o.Hamiltonian]

Get the encoded Pauli operators as a list of Hamiltonians.

Returns:

list[qm_o.Hamiltonian] — list[Hamiltonian]: List of Hamiltonians for each variable’s Pauli operator.

QRACSpaceEfficientEncoder [source]¶

class QRACSpaceEfficientEncoder(BaseQRACEncoder)

Space Efficient QRAC Encoder.

No graph coloring. Uses sequential numbering: variable i -> qubit i//2, Pauli X (even index) or Y (odd index).

Always maintains a 2:1 compression ratio.

Attributes¶

• num_qubits: int

qamomile.optimization.qrao.rounding¶

Rounding algorithms for QRAO.

This module provides rounding algorithms that convert Pauli expectation values into discrete spin values (+1 or -1).

Overview¶

Classes¶

SignRounder [source]¶

class SignRounder

Simple sign-based rounding.

Rounds Pauli expectation values to spin values using the sign function:

• <P_i> >= 0 → s_i = +1

• <P_i> < 0 → s_i = -1

Example:

>>> rounder = SignRounder()
>>> expectations = [0.8, -0.3, 0.1]  # Pauli expectation values
>>> spins = rounder.round(expectations)
>>> print(spins)  # [1, -1, 1]

Methods¶

round¶

def round(self, expectations: list[float]) -> list[int]

Round Pauli expectations to spin values.

Parameters:

Returns:

list[int] — List of spin values (+1 or -1) for each variable