qamomile.optimization.binary_model

Overview¶

Function	Description
`binary`	Create a binary variable expression.
`spin`	Create a spin variable expression.

Class	Description
`BinaryExpr`
`BinaryModel`
`BinarySampleSet`
`VarType`

Functions¶

`binary` [source]¶

def binary(index: int) -> BinaryExpr[VarType]

Create a binary variable expression.

Parameters:

Name	Type	Description
`index`	`int`	The index of the binary variable.

Returns:

BinaryExpr[VarType] — BinaryExpr[VarType.BINARY]: The binary variable expression.

`spin` [source]¶

def spin(index: int) -> BinaryExpr[VarType]

Create a spin variable expression.

Parameters:

Name	Type	Description
`index`	`int`	The index of the spin variable.

Returns:

BinaryExpr[VarType] — BinaryExpr[VarType.SPIN]: The spin variable expression.

Classes¶

`BinaryExpr` [source]¶

class BinaryExpr(Generic[VT])

Constructor¶

def __init__(
    self,
    vartype: VT = VarType.BINARY,
    constant: float = 0.0,
    coefficients: dict[tuple[int, ...], float] = dict(),
) -> None

Attributes¶

coefficients: dict[tuple[int, ...], float]
constant: float
vartype: VT

Methods¶

`copy`¶

def copy(self) -> BinaryExpr[VT]

`BinaryModel` [source]¶

class BinaryModel(Generic[VT])

Constructor¶

def __init__(self, expr: BinaryExpr[VT]) -> None

Attributes¶

coefficients: dict[tuple[int, ...], float] All coefficients as a single flat dictionary using sequential indices.
constant: float
higher: dict[tuple[int, ...], float]
index_new_to_origin
index_origin_to_new
linear: dict[int, float]
num_bits: int
order
quad: dict[tuple[int, int], float]
vartype: VT

Methods¶

`calc_energy`¶

def calc_energy(self, state: list[int]) -> float

Calculate the energy for a given variable assignment.

Parameters:

Name	Type	Description
`state`	`list[int]`	Variable values indexed by sequential (zero-origin) indices. For SPIN: values must be +1 or -1. For BINARY: values must be 0 or 1.

Returns:

float — The energy value.

Raises:

ValueError — If state values are invalid for the vartype.

`change_vartype`¶

def change_vartype(self, vartype: VarType) -> 'BinaryModel'

`decode_from_sampleresult`¶

def decode_from_sampleresult(self, result: SampleResult[list[int]]) -> BinarySampleSet[VT]

Decode quantum measurement results into samples with energies.

Converts raw measurement bitstrings (0/1 from quantum hardware) into the model’s variable domain and calculates energies.

Parameters:

Name	Type	Description
`result`	`SampleResult[list[int]]`	Measurement results with sequential bit indices

Returns:

BinarySampleSet[VT] — BinarySampleSet with samples in expression domain, using original indices

`from_hubo`¶

@classmethod
def from_hubo(
    cls,
    hubo: dict[tuple[int, ...], float],
    constant: float = 0.0,
    simplify: bool = False,
) -> 'BinaryModel'

Create a BINARY BinaryModel from HUBO coefficients.

Parameters:

Name	Type	Description
`hubo`	`dict[tuple[int, ...], float]`	HUBO coefficients mapping index tuples to values. Index tuples are sorted and deduplicated. Duplicate indices in a single term (e.g., `(0, 0, 2)`) emit a warning and are normalized to unique indices (`(0, 2)`). Empty tuples (`()`) are accumulated into the constant term.
`constant`	`float`	Constant offset term.
`simplify`	`bool`	If True, remove near-zero coefficients.

Returns:

'BinaryModel' — BinaryModel with BINARY vartype.

`from_ising`¶

@classmethod
def from_ising(
    cls,
    linear: dict[int, float],
    quad: dict[tuple[int, int], float],
    constant: float = 0.0,
    simplify: bool = False,
) -> 'BinaryModel'

`from_qubo`¶

@classmethod
def from_qubo(
    cls,
    qubo: dict[tuple[int, int], float],
    constant: float = 0.0,
    simplify: bool = False,
) -> 'BinaryModel'

`normalize_by_abs_max`¶

def normalize_by_abs_max(self, replace: bool = False) -> BinaryModel[VT]

Normalize the BinaryModel by its absolute maximum coefficient.

Returns:

BinaryModel[VT] — BinaryModel[VT]: The normalized binary model.

`normalize_by_factor`¶

def normalize_by_factor(self, factor: float, replace: bool = False) -> BinaryModel[VT]

Normalize the BinaryModel by a given factor.

Parameters:

Name	Type	Description
`factor`	`float`	The normalization factor.

Returns:

BinaryModel[VT] — BinaryModel[VT]: The normalized binary model.

`normalize_by_rms`¶

def normalize_by_rms(self, replace: bool = False) -> BinaryModel[VT]

Normalize the BinaryModel by its root mean square.

Returns:

BinaryModel[VT] — BinaryModel[VT]: The normalized binary model.

`BinarySampleSet` [source]¶

class BinarySampleSet(Generic[VT])

Constructor¶

def __init__(
    self,
    samples: list[dict[int, int]],
    num_occurrences: list[int],
    energy: list[float],
    vartype: VT = VarType.BINARY,
) -> None

Attributes¶

energy: list[float]
num_occurrences: list[int]
samples: list[dict[int, int]]
vartype: VT

Methods¶

`energy_mean`¶

def energy_mean(self) -> float

`lowest`¶

def lowest(self) -> tuple[dict[int, int], float, int]

`VarType` [source]¶

class VarType(enum.StrEnum)

Attributes¶

BINARY
SPIN

qamomile.optimization.binary_model.expr¶

Overview¶

Function	Description
`binary`	Create a binary variable expression.
`is_close_zero`	Check if a given floating-point value is close to zero within a small tolerance.
`spin`	Create a spin variable expression.

Class	Description
`BinaryExpr`
`VarType`

Functions¶

`binary` [source]¶

def binary(index: int) -> BinaryExpr[VarType]

Create a binary variable expression.

Parameters:

Name	Type	Description
`index`	`int`	The index of the binary variable.

Returns:

BinaryExpr[VarType] — BinaryExpr[VarType.BINARY]: The binary variable expression.

`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:

Name	Type	Description
`value`	`float`	The floating-point value to check.

Returns:

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

`spin` [source]¶

def spin(index: int) -> BinaryExpr[VarType]

Create a spin variable expression.

Parameters:

Name	Type	Description
`index`	`int`	The index of the spin variable.

Returns:

BinaryExpr[VarType] — BinaryExpr[VarType.SPIN]: The spin variable expression.

Classes¶

`BinaryExpr` [source]¶

class BinaryExpr(Generic[VT])

Constructor¶

def __init__(
    self,
    vartype: VT = VarType.BINARY,
    constant: float = 0.0,
    coefficients: dict[tuple[int, ...], float] = dict(),
) -> None

Attributes¶

coefficients: dict[tuple[int, ...], float]
constant: float
vartype: VT

Methods¶

`copy`¶

def copy(self) -> BinaryExpr[VT]

`VarType` [source]¶

class VarType(enum.StrEnum)

Attributes¶

BINARY
SPIN

qamomile.optimization.binary_model.model¶

Overview¶

Function	Description
`is_close_zero`	Check if a given floating-point value is close to zero within a small tolerance.
`normalize_by_abs_max`	Normalize the BinaryExpr by its absolute maximum coefficient.
`normalize_by_factor`	Normalize the BinaryExpr by a given factor.
`normalize_by_rms`	Normalize coefficients by the root mean square.

Class	Description
`BinaryExpr`
`BinaryModel`
`BinarySampleSet`
`SampleResult`	Result of a sample() execution.
`VarType`

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:

Name	Type	Description
`value`	`float`	The floating-point value to check.

Returns:

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

`normalize_by_abs_max` [source]¶

def normalize_by_abs_max(model: BinaryExpr, replace: bool = False) -> BinaryExpr

Normalize the BinaryExpr by its absolute maximum coefficient.

Parameters:

Name	Type	Description
`model`	`BinaryExpr`	The binary expression to be normalized.

Returns:

BinaryExpr — The normalized binary expression.

`normalize_by_factor` [source]¶

def normalize_by_factor(model: BinaryExpr, factor: float, replace: bool = False) -> BinaryExpr

Normalize the BinaryExpr by a given factor.

Parameters:

Name	Type	Description
`model`	`BinaryExpr`	The binary expression to be normalized.
`factor`	`float`	The normalization factor.

Returns:

BinaryExpr — The normalized binary expression.

`normalize_by_rms` [source]¶

def normalize_by_rms(expr: BinaryExpr, replace: bool = False) -> BinaryExpr

Normalize coefficients by the root mean square.

The coefficients for normalized is defined as:

W = \sqrt{\frac{1}{\lvert E_k \rvert} \sum_{\{u_1, \dots, u_k\}} (w_{u_1,...,u_k}^{(k)})^2 + \cdots + \frac{1}{\lvert E_1 \rvert} \sum_u (w_u^{(1)})^2}

(1)

where w are coefficients and their subscriptions imply a term to be applied. E_i are the number of i-th order terms. We normalize the Ising Hamiltonian as

\tilde{H} = \frac{1}{W} \left( C + \sum_i w_i Z_i + \cdots + \sum_{i_0, \dots, i_k} w_{i_0, \dots, i_k} Z_{i_0}\dots Z_{i_k} \right)

(2)

This method is proposed in [Sureshbabu2024parametersettingin]

Classes¶

`BinaryExpr` [source]¶

class BinaryExpr(Generic[VT])

Constructor¶

def __init__(
    self,
    vartype: VT = VarType.BINARY,
    constant: float = 0.0,
    coefficients: dict[tuple[int, ...], float] = dict(),
) -> None

Attributes¶

coefficients: dict[tuple[int, ...], float]
constant: float
vartype: VT

Methods¶

`copy`¶

def copy(self) -> BinaryExpr[VT]

`BinaryModel` [source]¶

class BinaryModel(Generic[VT])

Constructor¶

def __init__(self, expr: BinaryExpr[VT]) -> None

Attributes¶

coefficients: dict[tuple[int, ...], float] All coefficients as a single flat dictionary using sequential indices.
constant: float
higher: dict[tuple[int, ...], float]
index_new_to_origin
index_origin_to_new
linear: dict[int, float]
num_bits: int
order
quad: dict[tuple[int, int], float]
vartype: VT

Methods¶

`calc_energy`¶

def calc_energy(self, state: list[int]) -> float

Calculate the energy for a given variable assignment.

Parameters:

Name	Type	Description
`state`	`list[int]`	Variable values indexed by sequential (zero-origin) indices. For SPIN: values must be +1 or -1. For BINARY: values must be 0 or 1.

Returns:

float — The energy value.

Raises:

ValueError — If state values are invalid for the vartype.

`change_vartype`¶

def change_vartype(self, vartype: VarType) -> 'BinaryModel'

`decode_from_sampleresult`¶

def decode_from_sampleresult(self, result: SampleResult[list[int]]) -> BinarySampleSet[VT]

Decode quantum measurement results into samples with energies.

Converts raw measurement bitstrings (0/1 from quantum hardware) into the model’s variable domain and calculates energies.

Parameters:

Name	Type	Description
`result`	`SampleResult[list[int]]`	Measurement results with sequential bit indices

Returns:

BinarySampleSet[VT] — BinarySampleSet with samples in expression domain, using original indices

`from_hubo`¶

@classmethod
def from_hubo(
    cls,
    hubo: dict[tuple[int, ...], float],
    constant: float = 0.0,
    simplify: bool = False,
) -> 'BinaryModel'

Create a BINARY BinaryModel from HUBO coefficients.

Parameters:

Name	Type	Description
`hubo`	`dict[tuple[int, ...], float]`	HUBO coefficients mapping index tuples to values. Index tuples are sorted and deduplicated. Duplicate indices in a single term (e.g., `(0, 0, 2)`) emit a warning and are normalized to unique indices (`(0, 2)`). Empty tuples (`()`) are accumulated into the constant term.
`constant`	`float`	Constant offset term.
`simplify`	`bool`	If True, remove near-zero coefficients.

Returns:

'BinaryModel' — BinaryModel with BINARY vartype.

`from_ising`¶

@classmethod
def from_ising(
    cls,
    linear: dict[int, float],
    quad: dict[tuple[int, int], float],
    constant: float = 0.0,
    simplify: bool = False,
) -> 'BinaryModel'

`from_qubo`¶

@classmethod
def from_qubo(
    cls,
    qubo: dict[tuple[int, int], float],
    constant: float = 0.0,
    simplify: bool = False,
) -> 'BinaryModel'

`normalize_by_abs_max`¶

def normalize_by_abs_max(self, replace: bool = False) -> BinaryModel[VT]

Normalize the BinaryModel by its absolute maximum coefficient.

Returns:

BinaryModel[VT] — BinaryModel[VT]: The normalized binary model.

`normalize_by_factor`¶

def normalize_by_factor(self, factor: float, replace: bool = False) -> BinaryModel[VT]

Normalize the BinaryModel by a given factor.

Parameters:

Name	Type	Description
`factor`	`float`	The normalization factor.

Returns:

BinaryModel[VT] — BinaryModel[VT]: The normalized binary model.

`normalize_by_rms`¶

def normalize_by_rms(self, replace: bool = False) -> BinaryModel[VT]

Normalize the BinaryModel by its root mean square.

Returns:

BinaryModel[VT] — BinaryModel[VT]: The normalized binary model.

`BinarySampleSet` [source]¶

class BinarySampleSet(Generic[VT])

Constructor¶

def __init__(
    self,
    samples: list[dict[int, int]],
    num_occurrences: list[int],
    energy: list[float],
    vartype: VT = VarType.BINARY,
) -> None

Attributes¶

energy: list[float]
num_occurrences: list[int]
samples: list[dict[int, int]]
vartype: VT

Methods¶

`energy_mean`¶

def energy_mean(self) -> float

`lowest`¶

def lowest(self) -> tuple[dict[int, int], float, int]

`SampleResult` [source]¶

class SampleResult(Generic[T])

Result of a sample() execution.

Contains results as a list of (value, count) tuples.

Example:

result.results  # [(0.25, 500), (0.75, 500)]

Constructor¶

def __init__(self, results: list[tuple[T, int]], shots: int) -> None

Attributes¶

results: list[tuple[T, int]] List of (value, count) tuples.
shots: int Total number of shots executed.

Methods¶

`most_common`¶

def most_common(self, n: int = 1) -> list[tuple[T, int]]

Return the n most common results.

Parameters:

Name	Type	Description
`n`	`int`	Number of results to return.

Returns:

list[tuple[T, int]] — List of (result, count) tuples sorted by count descending.

`probabilities`¶

def probabilities(self) -> list[tuple[T, float]]

Return probability distribution over results.

Returns:

list[tuple[T, float]] — List of (value, probability) tuples.

`VarType` [source]¶

class VarType(enum.StrEnum)

Attributes¶

BINARY
SPIN

qamomile.optimization.binary_model.normalize¶

Overview¶

Function	Description
`normalize_by_abs_max`	Normalize the BinaryExpr by its absolute maximum coefficient.
`normalize_by_factor`	Normalize the BinaryExpr by a given factor.
`normalize_by_rms`	Normalize coefficients by the root mean square.

Class	Description
`BinaryExpr`

Functions¶

`normalize_by_abs_max` [source]¶

def normalize_by_abs_max(model: BinaryExpr, replace: bool = False) -> BinaryExpr

Normalize the BinaryExpr by its absolute maximum coefficient.

Parameters:

Name	Type	Description
`model`	`BinaryExpr`	The binary expression to be normalized.

Returns:

BinaryExpr — The normalized binary expression.

`normalize_by_factor` [source]¶

def normalize_by_factor(model: BinaryExpr, factor: float, replace: bool = False) -> BinaryExpr

Normalize the BinaryExpr by a given factor.

Parameters:

Name	Type	Description
`model`	`BinaryExpr`	The binary expression to be normalized.
`factor`	`float`	The normalization factor.

Returns:

BinaryExpr — The normalized binary expression.

`normalize_by_rms` [source]¶

def normalize_by_rms(expr: BinaryExpr, replace: bool = False) -> BinaryExpr

Normalize coefficients by the root mean square.

The coefficients for normalized is defined as:

W = \sqrt{\frac{1}{\lvert E_k \rvert} \sum_{\{u_1, \dots, u_k\}} (w_{u_1,...,u_k}^{(k)})^2 + \cdots + \frac{1}{\lvert E_1 \rvert} \sum_u (w_u^{(1)})^2}

(3)

where w are coefficients and their subscriptions imply a term to be applied. E_i are the number of i-th order terms. We normalize the Ising Hamiltonian as

\tilde{H} = \frac{1}{W} \left( C + \sum_i w_i Z_i + \cdots + \sum_{i_0, \dots, i_k} w_{i_0, \dots, i_k} Z_{i_0}\dots Z_{i_k} \right)

(4)

This method is proposed in [Sureshbabu2024parametersettingin]

Classes¶

`BinaryExpr` [source]¶

class BinaryExpr(Generic[VT])

Constructor¶

def __init__(
    self,
    vartype: VT = VarType.BINARY,
    constant: float = 0.0,
    coefficients: dict[tuple[int, ...], float] = dict(),
) -> None

Attributes¶

coefficients: dict[tuple[int, ...], float]
constant: float
vartype: VT

Methods¶

`copy`¶

def copy(self) -> BinaryExpr[VT]

qamomile.optimization.binary_model.sampleset¶

Overview¶

Class	Description
`BinarySampleSet`
`VarType`

Classes¶

`BinarySampleSet` [source]¶

class BinarySampleSet(Generic[VT])

Constructor¶

def __init__(
    self,
    samples: list[dict[int, int]],
    num_occurrences: list[int],
    energy: list[float],
    vartype: VT = VarType.BINARY,
) -> None

Attributes¶

energy: list[float]
num_occurrences: list[int]
samples: list[dict[int, int]]
vartype: VT

Methods¶

`energy_mean`¶

def energy_mean(self) -> float

`lowest`¶

def lowest(self) -> tuple[dict[int, int], float, int]

`VarType` [source]¶

class VarType(enum.StrEnum)

Attributes¶

BINARY
SPIN

Overview¶

Functions¶

binary [source]¶

spin [source]¶

Classes¶

BinaryExpr [source]¶

Constructor¶

Attributes¶

Methods¶

copy¶

BinaryModel [source]¶

Constructor¶

Attributes¶

Methods¶

calc_energy¶

change_vartype¶

decode_from_sampleresult¶

from_hubo¶

from_ising¶

from_qubo¶

normalize_by_abs_max¶

normalize_by_factor¶

normalize_by_rms¶

BinarySampleSet [source]¶

Constructor¶

Attributes¶

Methods¶

energy_mean¶

lowest¶

VarType [source]¶

Attributes¶

qamomile.optimization.binary_model.expr¶

Overview¶

Functions¶

binary [source]¶

is_close_zero [source]¶

spin [source]¶

Classes¶

BinaryExpr [source]¶

Constructor¶

Attributes¶

Methods¶

copy¶

VarType [source]¶

Attributes¶

qamomile.optimization.binary_model.model¶

Overview¶

Functions¶

is_close_zero [source]¶

normalize_by_abs_max [source]¶

normalize_by_factor [source]¶

normalize_by_rms [source]¶

Classes¶

BinaryExpr [source]¶

Constructor¶

Attributes¶

Methods¶

copy¶

BinaryModel [source]¶

Constructor¶

Attributes¶

Methods¶

calc_energy¶

change_vartype¶

decode_from_sampleresult¶

from_hubo¶

from_ising¶

from_qubo¶

normalize_by_abs_max¶

normalize_by_factor¶

normalize_by_rms¶

BinarySampleSet [source]¶

Constructor¶

Attributes¶

Methods¶

energy_mean¶

lowest¶

SampleResult [source]¶

Constructor¶

`binary` [source]¶

`spin` [source]¶

`BinaryExpr` [source]¶

`copy`¶

`BinaryModel` [source]¶

`calc_energy`¶

`change_vartype`¶

`decode_from_sampleresult`¶

`from_hubo`¶

`from_ising`¶

`from_qubo`¶

`normalize_by_abs_max`¶

`normalize_by_factor`¶

`normalize_by_rms`¶

`BinarySampleSet` [source]¶

`energy_mean`¶

`lowest`¶

`VarType` [source]¶

`binary` [source]¶

`is_close_zero` [source]¶

`spin` [source]¶

`BinaryExpr` [source]¶

`copy`¶

`VarType` [source]¶

`is_close_zero` [source]¶

`normalize_by_abs_max` [source]¶

`normalize_by_factor` [source]¶

`normalize_by_rms` [source]¶

`BinaryExpr` [source]¶

`copy`¶

`BinaryModel` [source]¶

`calc_energy`¶

`change_vartype`¶

`decode_from_sampleresult`¶

`from_hubo`¶

`from_ising`¶

`from_qubo`¶

`normalize_by_abs_max`¶

`normalize_by_factor`¶

`normalize_by_rms`¶

`BinarySampleSet` [source]¶

`energy_mean`¶

`lowest`¶

`SampleResult` [source]¶

`most_common`¶

`probabilities`¶

`VarType` [source]¶

`normalize_by_abs_max` [source]¶

`normalize_by_factor` [source]¶

`normalize_by_rms` [source]¶

`BinaryExpr` [source]¶

`copy`¶

`BinarySampleSet` [source]¶

`energy_mean`¶

`lowest`¶

`VarType` [source]¶