kaiwu.qubo package#

Module contents#

Module: qubo

Function: QUBO modeling tool

kaiwu.qubo.check_qubo_matrix_bit_width(qubo_matrix, bit_width=8)#

Verify the bit width of QUBO matrix elements

Convert the QUBO matrix to an Ising matrix, and verify the QUBO matrix by checking the element bit width of the Ising matrix

Args:

qubo_matrix (np.ndarray): QUBO matrix

bit_width (int): Bit width

Raises:

ValueError: Raised when the bit width of matrix elements exceeds the specified bit width

Example 1:

>>> import numpy as np
>>> import kaiwu as kw
>>> _matrix = -np.array([[-480., 508., -48.],
...                      [ 508., -508., -48.],
...                      [ -48., -48., 60.]])
>>> kw.qubo.check_qubo_matrix_bit_width(_matrix)

Example 2 (Meets requirements after scaling):

>>> import numpy as np
>>> import kaiwu as kw
>>> _matrix = -np.array([[-512.,  520.,  -48.],
...                      [ 520., -520.,  -48.],
...                      [ -48.,  -48.,   40.]])
>>> kw.qubo.check_qubo_matrix_bit_width(_matrix)

Example 3 (Does not meet requirements even after scaling):

>>> import numpy as np
>>> import kaiwu as kw
>>> _matrix = -np.array([[-488.,  516.,  -48.],
...                      [ 516., -516.,  -48.],
...                      [ -48.,  -48.,   60.]])
>>> kw.qubo.check_qubo_matrix_bit_width(_matrix)
Traceback (most recent call last):
...
ValueError: CIM only supports signed 8-bit number

kaiwu.qubo.adjust_qubo_matrix_precision(qubo_matrix, bit_width=8)#

Adjust the matrix precision. After adjustment through this interface, the matrix may suffer significant precision loss. For example, if the matrix contains a number much larger than others, the adjusted matrix will have severe precision loss and become unusable.

Args:

qubo_matrix (np.ndarray): Target matrix

bit_width (int): Precision range; currently only 8-bit is supported, with one bit as the sign bit

Returns:

np.ndarray: QUBO matrix that meets the precision requirements

Examples:

>>> import numpy as np
>>> import kaiwu as kw
>>> ori_qubo_mat1 = np.array([[0.89, 0.22, 0.198],
...                      [0.22, 0.23, 0.197],
...                      [0.198, 0.197, 0.198]])
>>> qubo_mat1 = kw.qubo.adjust_qubo_matrix_precision(ori_qubo_mat1)
>>> qubo_mat1
array([[348., 168., 152.],
       [ -0.,  92., 152.],
       [ -0.,  -0.,  80.]])
>>> ori_qubo_mat2 = np.array([[0.89, 0.22, 0.198],
...                           [0.22, 0.23, 0.197],
...                           [0.198, 0.197, 100]])
>>> qubo_mat2 = kw.qubo.adjust_qubo_matrix_precision(ori_qubo_mat2)
>>> qubo_mat2  # The solutions obtained by qubo_mat2 and ori_qubo_mat2 matrices are quite different
array([[  8.,  -0.,  -0.],
       [ -0.,   4.,  -0.],
       [ -0.,  -0., 508.]])

class kaiwu.qubo.QuboModel(objective=None)#

Bases: BinaryModel

QUBO model class that supports adding constraints

Args:: objective (QuboExpression, optional): Objective function. Defaults to None

invalidate_made_state()#: Invalidate the made state when the model changes

make()#: Return the merged QUBO expression Returns:

BinaryExpression: Merged constraint expression

get_matrix()#

Get QUBO matrix

Returns:: numpy.ndarray: QUBO matrix

get_variables()#: Get the variables of the QUBO model

get_offset()#: Get the offset of the QUBO model

get_sol_dict(qubo_solution)#: Generate result dictionary based on the solution vector.

add_constraint(constraint_in, name=None, constr_type: Literal['soft', 'hard'] = 'hard', penalty=None)#

Add constraint terms (supports single or multiple constraints)

Args:

constraint_in (ConstraintDefinition or iterable): The constraint expression or its iterable object.

name (str or list, optional): Constraint name or list of names; automatically named by default.

constr_type(str, optional): Constraint type, can be set to “soft” or “hard”, defaults to “hard”

penalty (float): 缺省惩罚系数

compile_constraints()#: Convert constraint terms to Expression according to different styles. For inequality constraints, the penalty function method is currently supported.

get_constraints_expr_list()#

Get all current constraints.

Returns:: List of all constraints.

get_value(solution_dict)#

Substitute variable values into QUBO variables based on the result dictionary.

Args:: solution_dict (dict): Result dictionary generated by get_sol_dict.
Returns:: float: Value obtained after substituting into the QUBO

initialize_penalties()#: Automatically initialize all penalty coefficients

set_constraint_handler(constraint_handler)#

Set the unconstrained conversion method for constraint terms

Args:: constraint_handler: Class for setting the unconstrained representation method of constraint terms

set_objective(objective)#

Set the objective function

Args:: objective (BinaryExpression): Objective function expression

verify_constraint(solution_dict, constr_type: Literal['soft', 'hard'] = 'hard')#

Verify whether constraints are satisfied

Args:

solution_dict (dict): QUBO model solution dictionary

constr_type(str, optional): Constraint type, can be set to “soft” or “hard”, defaults to “hard”

Returns:

tuple: Constraint satisfaction information

int: Number of unsatisfied constraints
dict: Dictionary containing constraint values

kaiwu.qubo.calculate_qubo_value(qubo_matrix, offset, binary_configuration)#

Q value calculator.

Args:

qubo_matrix (np.ndarray): QUBO matrix.

offset (float): Constant term

binary_configuration (np.ndarray): Binary configuration

Returns:

output (float): Q value.

Examples:

>>> import numpy as np
>>> import kaiwu as kw
>>> matrix = np.array([[1., 0., 0.],
...                    [0., 1., 0.],
...                    [0., 0., 1.]])
>>> offset = 1.8
>>> binary_configuration = np.array([0, 1, 0])
>>> qubo_value = kw.qubo.calculate_qubo_value(matrix, offset, binary_configuration)
>>> print(qubo_value)
2.8

kaiwu.qubo.qubo_matrix_to_qubo_model(qubo_mat)#

Convert QUBO matrix to QUBO model

Args:

qubo_mat (np.ndarray): QUBO matrix

Returns:

QuboModel: QUBO model

Examples:

>>> import numpy as np
>>> import kaiwu as kw
>>> matrix = -np.array([[0, 8],
...                     [0, 0]])
>>> kw.qubo.qubo_matrix_to_qubo_model(matrix).objective
-8*b[0]*b[1]

exception kaiwu.qubo.QuboError(error_info)#

Bases: KaiwuError

Exceptions in qubo module.

args#

with_traceback()#: Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.