Skip to content

Results are limited to QUBO Solver v0.6.2

Product news
You are reading QUBO Solver v0.6.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.device = device
self.dtype = dtype
self._coefficients: torch.Tensor = torch.zeros([0, 0], dtype=dtype)
self.solution: QUBOSolution | None = None
self.density: float | None = None
self.density_type: DensityType | None = None
if coefficients is not None:
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 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)

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