Skip to content

Results are limited to QUBO Solver v0.8.2

Product news
You are reading QUBO Solver v0.8.2, an older version of this documentation. Go to the latest version (v0.10.0)

QUBOInstance

QUBOInstance(coefficients=None, device='cpu', dtype=torch.float32)

Section titled “ QUBOInstance(coefficients=None, device='cpu', dtype=torch.float32) ”

Represents a single instance of a Quadratic Unconstrained Binary Optimization (QUBO) problem.

ATTRIBUTE DESCRIPTION
coefficients

Tensor of shape (size, size), representing the QUBO coefficients.

TYPE: Tensor

device

Device where tensors are allocated (e.g., "cpu" or "cuda").

TYPE: str

dtype

Data type of the tensors (e.g., torch.float32).

TYPE: dtype

solution

Solution to the QUBO problem, if available.

TYPE: QUBOSolution | None

density

Fraction of non-zero entries in the coefficient matrix.

TYPE: float | None

density_type

Classification of the density (e.g., sparse, dense).

TYPE: DensityType | None

Initializes a QUBOInstance.

PARAMETER DESCRIPTION
coefficients

Coefficients of the QUBO problem. Can be a dictionary, array-like object, or None.

TYPE: dict | ArrayLike | None DEFAULT: None

device

Device where tensors are allocated (default: "cpu").

TYPE: str DEFAULT: 'cpu'

dtype

Data type of the tensors (default: torch.float32).

TYPE: dtype DEFAULT: float32

Source code in qubosolver/qubo_instance.py
def __init__(
self,
coefficients: dict | ArrayLike | None = None,
device: str = "cpu",
dtype: torch.dtype = torch.float32,
):
"""
Initializes a QUBOInstance.
Args:
coefficients (dict | ArrayLike | None):
Coefficients of the QUBO problem. Can be a dictionary, array-like object, or None.
device (str):
Device where tensors are allocated (default: "cpu").
dtype (torch.dtype):
Data type of the tensors (default: torch.float32).
"""
self._coefficients: torch.Tensor = torch.zeros([0, 0], dtype=dtype, device=device)
self.solution: QUBOSolution | None = None
self.density: float | None = None
self.density_type: DensityType | None = None
if coefficients is None:
self.coefficients = self._coefficients
else:
self.coefficients = coefficients

Getter for the QUBO coefficient matrix.

RETURNS DESCRIPTION
Tensor

torch.Tensor: Tensor of shape (size, size) representing the QUBO coefficients.

Get the device on which the coefficient tensor is stored.

RETURNS DESCRIPTION
device

torch.device: The device (e.g., device("cpu") or device("cuda:0")).

Get the data type of the coefficient tensor.

RETURNS DESCRIPTION
dtype

torch.dtype: The dtype (e.g., torch.float32).

Return the coefficient matrix normalised by the maximum off-diagonal value.

All coefficients are divided by _max_off_diag so that the largest off-diagonal entry becomes 1.0. Useful for embedding algorithms that require unit-scaled interactions.

RETURNS DESCRIPTION
Tensor

torch.Tensor: Normalised coefficient matrix of shape (size, size).

Get the size of the QUBO matrix (number of variables).

RETURNS DESCRIPTION
int

Size of the QUBO matrix.

TYPE: int

Returns a string representation of the QUBOInstance.

RETURNS DESCRIPTION
str

A dictionary-like string summarizing the instance.

TYPE: str

Source code in qubosolver/qubo_instance.py
def __repr__(self) -> str:
"""
Returns a string representation of the QUBOInstance.
Returns:
str: A dictionary-like string summarizing the instance.
"""
return repr(
f"QUBOInstance of size = {self.size},"
f"density = {round(self.density, 2) if self.density else None},"
)

Evaluates a solution for the QUBO problem.

PARAMETER DESCRIPTION
solution

Solution vector to evaluate.

TYPE: list | tuple | ArrayLike

RETURNS DESCRIPTION
float

The cost of the given solution.

TYPE: float

RAISES DESCRIPTION
ValueError

If the solution size does not match the QUBO size.

Source code in qubosolver/qubo_instance.py
def evaluate_solution(self, solution: list | tuple | ArrayLike) -> float:
"""
Evaluates a solution for the QUBO problem.
Args:
solution (list | tuple | ArrayLike):
Solution vector to evaluate.
Returns:
float:
The cost of the given solution.
Raises:
ValueError: If the solution size does not match the QUBO size.
"""
solution_tensor = convert_to_tensor(solution, device=self.device, dtype=self.dtype) # type: ignore[arg-type]
if solution_tensor.size(0) != self.size:
raise ValueError("Solution size does not match the QUBO problem size.")
cost = torch.matmul(
solution_tensor, torch.matmul(self._coefficients, solution_tensor)
).item()
solution = solution_tensor
return float(cost)

Deserialises a QUBOInstance from a binary file-like object.

Reconstructs the instance from a file previously created with QUBOInstance.save.

PARAMETER DESCRIPTION
file_like

A file-like object opened in binary read mode containing the serialised QUBOInstance data.

TYPE: FileLike[bytes]

RETURNS DESCRIPTION
QUBOInstance

A new QUBOInstance reconstructed from the file.

TYPE: QUBOInstance

Example

with open("instance.bin", "rb") as f: ... instance = QUBOInstance.load(f)

Source code in qubosolver/qubo_instance.py
@staticmethod
def load(file_like: io_utils.FileLike[bytes]) -> QUBOInstance:
"""
Deserialises a QUBOInstance from a binary file-like object.
Reconstructs the instance from a file previously created with
`QUBOInstance.save`.
Args:
file_like (io_utils.FileLike[bytes]): A file-like object opened in
binary read mode containing the serialised QUBOInstance data.
Returns:
QUBOInstance: A new QUBOInstance reconstructed from the file.
Example:
>>> with open("instance.bin", "rb") as f:
... instance = QUBOInstance.load(f)
"""
with io_utils.open(file_like, "rb") as f:
# torch.load might consume too much of the src buffer.
# Use a dedicated limited buffer.
buffer = io.BytesIO(io_utils.load_sized_buffer(f))
Q = torch.load(buffer, weights_only=True)
return QUBOInstance(Q)

Serialises a QUBOInstance to a binary file-like object.

Uses torch.save internally to persist the coefficient tensor.

PARAMETER DESCRIPTION
file_like

A file-like object opened in binary write mode (e.g., an open file or a BytesIO buffer).

TYPE: FileLike[bytes]

instance

The QUBOInstance to serialise.

TYPE: QUBOInstance

RETURNS DESCRIPTION
None

None

Example

with open("instance.bin", "wb") as f: ... QUBOInstance.save(f, my_instance)

Source code in qubosolver/qubo_instance.py
@staticmethod
def save(file_like: io_utils.FileLike[bytes], instance: QUBOInstance) -> None:
"""
Serialises a QUBOInstance to a binary file-like object.
Uses `torch.save` internally to persist the coefficient tensor.
Args:
file_like (io_utils.FileLike[bytes]): A file-like object opened in
binary write mode (e.g., an open file or a BytesIO buffer).
instance (QUBOInstance): The QUBOInstance to serialise.
Returns:
None
Example:
>>> with open("instance.bin", "wb") as f:
... QUBOInstance.save(f, my_instance)
"""
with io_utils.open(file_like, "wb") as f:
buffer = io.BytesIO()
torch.save(instance.coefficients, buffer)
io_utils.save_sized_buffer(f, buffer.getbuffer())

Updates the coefficients of the QUBO problem.

PARAMETER DESCRIPTION
new_coefficients

Dictionary of new coefficients to set. Keys are (row, column) tuples.

TYPE: dict[tuple[int, int], float] | None DEFAULT: None

Source code in qubosolver/qubo_instance.py
def set_coefficients(
self, new_coefficients: dict[tuple[int, int], float] | None = None
) -> None:
"""
Updates the coefficients of the QUBO problem.
Args:
new_coefficients (dict[tuple[int, int], float] | None):
Dictionary of new coefficients to set. Keys are (row, column) tuples.
"""
if not new_coefficients:
return
max_index = max(max(i, j) for i, j in new_coefficients.keys())
if max_index >= self.size:
self._expand_size(max_index + 1)
indices = torch.tensor(list(new_coefficients.keys()), dtype=torch.long, device=self.device)
values = torch.tensor(list(new_coefficients.values()), dtype=self.dtype, device=self.device)
self._coefficients[indices[:, 0], indices[:, 1]] = values
off_diagonal_mask = indices[:, 0] != indices[:, 1]
symmetric_indices = indices[off_diagonal_mask]
self._coefficients[symmetric_indices[:, 1], symmetric_indices[:, 0]] = values[
off_diagonal_mask
]
self.update_metrics()

Updates the density metrics of the QUBO problem.

Source code in qubosolver/qubo_instance.py
def update_metrics(self) -> None:
"""
Updates the density metrics of the QUBO problem.
"""
if self.size > 0:
self.density = calculate_density(self._coefficients, self.size)
self.density_type = classify_density(self.density)
else:
self.density = self.density_type = None