kaiwu.qubo package

kaiwu.qubo package#

Module Contents#

Module: qubo

Features: Provides a series of pre-processing tools for QUBO

class kaiwu.qubo.Binary(name: str)#

Bases: QuboExpression

Binary variable with possible values of 0,1.

Args:

name (str): The unique identifier of the variable.

Returns:

dict: Binary variable named name.

Examples:

>>> import kaiwu as kw
>>> b = kw.qubo.Binary('z2')
>>> b
z2

class kaiwu.qubo.HoboReducer#

Bases: object

完成建模后，进行QUBO表达式的降阶

Examples:

>>> import kaiwu as kw
>>> kw.qubo.QuboExpression.auto_hobo_reduce = False
>>> x = kw.qubo.ndarray(10, "x", kw.qubo.Binary)
>>> y1 = x[0]*x[1] + x[2]*x[3] + x[8]
>>> y2 = x[3]*x[4] + x[5]*x[6] + x[7]
>>> y3 = y1 * y2
>>> print(y3)  
'x[2]*x[3]*x[5]*x[6]+x[2]*x[3]*x[3]*x[4]+x[2]*x[3]*x[7]+x[0]*x[1]*x[5]*x[6]+x[0]*x[1]*x[3]*x[4]+'         'x[0]*x[1]*x[7]+x[5]*x[6]*x[8]+x[3]*x[4]*x[8]+x[7]*x[8]'
>>> reducer = kw.qubo.HoboReducer()
>>> y4 = reducer.reduce(y3)
>>> kw.qubo.details(y4)
QUBO Details:
  Variables(Binary):_x[0]_x[1], _x[2]_x[3], _x[3]_x[4], _x[5]_x[6], x[4], x[7], x[8]
  QUBO offset:      0
  QUBO coefficients:
    _x[2]_x[3], _x[5]_x[6] : 1
    _x[2]_x[3], x[4]       : 1
    _x[2]_x[3], x[7]       : 1
    _x[0]_x[1], _x[5]_x[6] : 1
    _x[0]_x[1], _x[3]_x[4] : 1
    _x[0]_x[1], x[7]       : 1
    _x[5]_x[6], x[8]       : 1
    _x[3]_x[4], x[8]       : 1
    x[7], x[8]             : 1
  HOBO Constraint:
    _x[2]_x[3] : x[2], x[3]
    _x[5]_x[6] : x[5], x[6]
    _x[0]_x[1] : x[0], x[1]
    _x[3]_x[4] : x[3], x[4]

reduce(qubo_expr, pairs=None)#

对QUBO表达式进行降阶

Args:

qubo_expr (QuboExpression): QUBO表达式

pairs (list): 预先定义要合并的变量, 通过元组的列表传入

Returns:

qubo_expr (QuboExpression): 降阶后的QUBO表达式

class kaiwu.qubo.Integer(name: str, min_value=0, max_value=127)#

Bases: QuboExpression

Returns a QUBO polynomial representing an integer variable such that min_value<= x <= min_value

$x = a+\sum_{i=0}^{\lfloor \log_2 (b-a) \rfloor -1}{2^i*t_i} + (b-a-2^{\lfloor \log_2 (b-a) \rfloor}+1)*y$

Args:

name (str): The unique identifier of the variable.

min_value: Minimum value of integer variable

max_value: Maximum value of integer variable

Returns:

dict: Integer variable named name.

Examples:

>>> import kaiwu as kw
>>> var_i = kw.qubo.Integer("x", 1, 2)
>>> var_i
x[0]+1

class kaiwu.qubo.Placeholder(name: str)#

Bases: QuboExpression

Placeholder

Args:

name (str): Unique identifier of a placeholder.

Returns:

dict: Placeholder named name.

Examples:

>>> import kaiwu as kw
>>> p = kw.qubo.Placeholder("p")
>>> p
p

class kaiwu.qubo.QUBOArray#

Bases: ndarray

QUBO container based on np.ndarray. The container supports various vectorization operations native to numpy

dot(b, out=None)#

Matrix multiplication using quicksum

Args:: b (QUBOArray): Another matrix
Returns:: QUBOArray: Product

is_array_equal = <numpy.vectorize object>#

is_array_greater = <numpy.vectorize object>#

is_array_greater_equal = <numpy.vectorize object>#

is_array_less = <numpy.vectorize object>#

is_array_less_equal = <numpy.vectorize object>#

sum(axis=None, dtype=None, out=None, keepdims=False, initial=0, where=True)#

Return the sum of the array elements over the given axis.

Refer to numpy.sum for full documentation.

See Also#

numpy.sum : equivalent function

class kaiwu.qubo.QuboExpression#

Bases: _Expression

The basic data structure for QUBO expressions

auto_hobo_reduce = True#

feed(feed_dict)#

Assign values to placeholders and return a new expression object with the values assigned.

Args:

feed_dict(dict): The values to be assigned to the placeholders

Examples:

>>> import kaiwu as kw
>>> p = kw.qubo.Placeholder('p')
>>> a = kw.qubo.Binary('a')
>>> y = p * a
>>> kw.qubo.details(y)  
QUBO Details:
  Variables(Binary):a
  Placeholders:     p
  QUBO offset:      0
  QUBO coefficients:
    a, : p
>>> y= y.feed({'p': 2})
>>> kw.qubo.details(y)  
QUBO Details:
  Variables(Binary):a
  QUBO offset:      0
  QUBO coefficients:
    a, : 2

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

Bases: object

A QUBO model class that supports adding constraints

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

add_constraint(constraint, name, penalty: float | None = None, constr_type: Literal['soft', 'hard'] = 'hard', expected_value=0, slack_expr=None)#

Add a constraint

Args:

constraint (QuboExpression): Constraint expression

name (str, optional): Constraint name, defaults to naming sequentially as “constraint1”, “constraint2”, etc.

penalty (float, optional): Penalty coefficient for the constraint term. Defaults to auto-generated

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

expected_value (float, optional): The expected value of the constraint, i.e., when the constraint value is considered satisfied, defaults to 0

slack_expr (QuboExpression): QUBO expression of the slack variable

get_qubo_matrix(bit_width=None)#

Get the QUBO matrix and adjust the precision

Args:: bit_width (int, optional): Precision of the matrix
Returns:: numpy.ndarray: QUBO matrix

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

get_value(solution_dict)#

Substitute the variable values into the qubo variable according to the result dictionary.

Args:: solution_dict (dict): The result dictionary generated by get_sol_dict.
Returns:: float: The value obtained after substituting into qubo

make(hobo_constraint_strength=None)#

Return the merged QUBO expression

Args:: hobo_constraint_strength (float, optional): Automatic down-order penalty coefficient. Defaults to auto-generated
Returns:: QuboExpression: Merged constraint expression

set_objective(objective)#

Set the objective function

Args:: objective (QuboExpression): Objective function expression

to_ising_model()#: Convert to Ising model

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

Verify whether the constraint is 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.adjust_qubo_matrix_precision(qubo_matrix, bit_width=8)#

Adjust matrix precision, which may result in significant precision loss after adjustment, such as when one number in the matrix is much larger than the others, resulting in severe precision loss that makes the matrix unusable.

Args:

qubo_matrix (np.ndarray): Target matrix

bit_width (int): Precision range, currently only supports 8 bits, one bit is the sign bit

Returns:

np.ndarray: QUBO matrix that meets 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.]])

kaiwu.qubo.binary(name: str)#

Binary variable with possible values of 0,1.

Args:

name (str): The unique identifier of the variable.

Returns:

dict: Binary variable named name.

Examples:

>>> import kaiwu as kw
>>> b = kw.qubo.binary("b")
>>> b
b

Deprecated since version 1.0.0: You can use the standard function kw.qubo.Binary().

kaiwu.qubo.bisection(qubo_expr_list, func)#

The binary method can be used for continuous calculations, such as continuous multiplication or continuous XOR operations. Using the binary method may reduce the number of variables generated by downgrading.

Args:

qubo_expr_list (QUBO list): QUBO list.

func (binary function): Used for the computation of two QUBO elements.

Returns:

QuboExpression: Constrained QUBO.

Example1:

>>> import kaiwu as kw
>>> qubo_list = [kw.qubo.Binary("b"+str(i)) for i in range(10)] # 变量也是QUBO
>>> output = kw.qubo.bisection(qubo_list, lambda a,b: a+b)
>>> output
b9+b8+b7+b6+b5+b4+b3+b2+b1+b0

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

Check the bit width of QUBO matrix elements.

Convert the QUBO matrix to an Ising matrix, and validate the QUBO matrix by checking the bit width of the Ising matrix elements.

Args:

qubo_matrix (np.ndarray): QUBO matrix

bit_width (int): Bit width

Examples1:

>>> 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)

Examples2 (meets the 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)

Examples3 (does not meet the 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.cim_ising_model(qubo)#

Convert QUBO to CIM Ising model.

Args:

qubo (QUBO): QUBO.

Returns:

CimIsing: CIM Ising model.

Examples:

>>> import kaiwu as kw
>>> b1, b2 = kw.qubo.Binary("b1"), kw.qubo.Binary("b2")
>>> q = b1 + b2 + 2 * b1 * b2
>>> ci = kw.qubo.cim_ising_model(q)
>>> kw.qubo.details(ci)
CIM Ising Details:
  CIM Ising Matrix:
    [[-0.   -0.25 -0.5 ]
     [-0.25 -0.   -0.5 ]
     [-0.5  -0.5  -0.  ]]
  CIM Ising Bias: 1.5
  CIM Ising Variables: b1, b2, __spin__
  Variable type: binary
  QUBO Matrix:
    [[1. 2.]
     [0. 1.]]
  QUBO Offset: 0
  QUBO Variables: b1, b2

Deprecated since version 1.0.0: You can use the standard function kw.qubo.qubo_model_to_ising_model().

kaiwu.qubo.constraint(qubo, name: str, strength=0)#

QUBO constraint.

Args:

qubo (QUBO): QUBO expression.

name (str): The unique identifier of the variable.

strength (float): Constraint strength

Returns:

QuboExpression: Constrained QUBO.

Examples:

>>> import kaiwu as kw
>>> b1, b2 = kw.qubo.Binary("b1"), kw.qubo.Binary("b2")
>>> cons1 = kw.qubo.constraint(2.1*b1*b2 + b2 - b1 + 2, "cons1")
>>> kw.qubo.details(cons1)
QUBO Details:
  Variables(Binary):b1, b2
  QUBO offset:      2
  QUBO coefficients:
    b2,    : 1
    b1, b2 : 2.1
    b1,    : -1

kaiwu.qubo.details(model, file_name='')#

Detail viewer.

Args:

model: The model to be inspected.

file_name (str): File path and name; if empty, print directly to the console.

Returns:

QuboExpression: Constrained QUBO.

Examples:

>>> import kaiwu as kw
>>> qubo_list = [kw.qubo.Binary("b"+str(i)) for i in range(10)] # Variables are also QUBO
>>> output = kw.qubo.quicksum(qubo_list)
>>> kw.qubo.details(output)
QUBO Details:
  Variables(Binary):b0, b1, b2, b3, b4, b5, b6, b7, b8, b9
  QUBO offset:      0
  QUBO coefficients:
    b0, : 1
    b1, : 1
    b2, : 1
    b3, : 1
    b4, : 1
    b5, : 1
    b6, : 1
    b7, : 1
    b8, : 1
    b9, : 1

kaiwu.qubo.dot(mat_left, mat_right)#

Matrix multiplication

Args:

mat_left (numpy.array): Matrix 1

mat_right (numpy.array): Matrix 2

Raises:

ValueError: Both inputs must be np.ndarray ValueError: The dimensions of both inputs must match

Returns:

np.ndarray: Product matrix

kaiwu.qubo.get_array_val(array, sol_dict)#

Substitute the spin values into the qubo array variable according to the result dictionary.

Args:

array (QUBOArray): QUBO数组

sol_dict (dict): The result dictionary generated by get_sol_dict.

Returns:

np.ndarray: The array of values obtained after entering the qubo array

Examples:

>>> import kaiwu as kw
>>> import numpy as np
>>> x = kw.qubo.ndarray((2, 2), "x", kw.qubo.Binary)
>>> y = x.sum()
>>> y = kw.qubo.make(y)
>>> y_ising = kw.qubo.qubo_model_to_ising_model(y)
>>> vars = y_ising.get_variables()
>>> s = np.array([1, -1, 1, -1])
>>> sol_dict = kw.qubo.get_sol_dict(s, vars)
>>> kw.qubo.get_array_val(x, sol_dict)
array([[1., 0.],
       [1., 0.]])

kaiwu.qubo.get_min_penalty(obj, cons)#

Returns the minimum penalty coefficient corresponding to the constraint term cons, with the penalty term being satisfied first.

Args:

obj: The original qubo expression of the objective function.

cons: The qubo expression of the constraint term

Returns:

float: Returns the minimum penalty coefficient corresponding to the constraint term cons.

Examples:

>>> import kaiwu as kw
>>> x = [kw.qubo.Binary("b"+str(i)) for i in range(3)]
>>> cons = kw.qubo.quicksum(x) - 1
>>> obj = x[1] + 2 * x[2]
>>> kw.qubo.get_min_penalty(obj, cons)
2.0

kaiwu.qubo.get_min_penalty_for_equal_constraint(obj, cons)#

Returns the minimum penalty coefficient corresponding to the linear equality constraint term cons: the worst case of flipping a certain bit of the solution that satisfies this constraint. The effectiveness of this penalty coefficient means that it can ensure that the feasible solution to the original problem is the local optimum of the objective function (in the local sense of one bit flip).

Args:

obj: The original qubo expression of the objective function.

cons: The linear expression in the linear equality constraint cons=0.

Returns:

float: The minimum penalty coefficient corresponding to the linear equality constraint term cons.

Examples:

>>> import kaiwu as kw
>>> x = [kw.qubo.Binary("b"+str(i)) for i in range(3)]
>>> cons = kw.qubo.quicksum(x)-1
>>> obj = x[1]+2*x[2]
>>> kw.qubo.get_min_penalty_for_equal_constraint(obj,cons)
2.0

kaiwu.qubo.get_sol_dict(solution, vars_dict)#

Generate a result dictionary based on the solution vector and variable dictionary.

Args:

solution (np.ndarray): Solution vector (spin).

vars_dict (dict): Variable dictionary, generated with cim_ising_model.get_variables().

Returns:

dict: Result dictionary. The key is the variable name, and the value is the corresponding spin value.

Examples:

>>> import kaiwu as kw
>>> import numpy as np
>>> a = kw.qubo.Binary("a")
>>> b = kw.qubo.Binary("b")
>>> c = kw.qubo.Binary("c")
>>> d = a + 2 * b + 4 * c
>>> d = kw.qubo.make(d)
>>> d_ising = kw.qubo.qubo_model_to_ising_model(d)
>>> vars = d_ising.get_variables()
>>> s = np.array([1, -1, 1])
>>> kw.qubo.get_sol_dict(s, vars)
{'a': 1.0, 'b': 0.0, 'c': 1.0}

kaiwu.qubo.get_val(qubo, sol_dict)#

Substitute the spin value into the qubo variable according to the result dictionary.

Args:

qubo (QUBO expression): QUBO expression

sol_dict (dict): The result dictionary generated by get_sol_dict.

Returns:

float: The value obtained after substituting into qubo

Examples:

>>> import kaiwu as kw
>>> import numpy as np
>>> a = kw.qubo.Binary("a")
>>> b = kw.qubo.Binary("b")
>>> c = kw.qubo.Binary("c")
>>> d = a + 2 * b + 4 * c
>>> d = kw.qubo.make(d)
>>> d_ising = kw.qubo.qubo_model_to_ising_model(d)
>>> vars = d_ising.get_variables()
>>> s = np.array([1, -1, 1])
>>> sol_dict = kw.qubo.get_sol_dict(s, vars)
>>> kw.qubo.get_val(d, sol_dict)
5.0

kaiwu.qubo.hobo_verify(reduced_hobo, sol_dict)#

Verify that all HOBO auxiliary variables are satisfied.

Args:

reduced_hobo (QUBO): QUBO.

sol_dict (dict): The result dictionary generated by get_sol_dict.

Returns:

int: Number of auxiliary variables not satisfied dict: Records whether each auxiliary variable is satisfied

Examples:

>>> import kaiwu as kw
>>> x1, x2, x3 = kw.qubo.Binary("x1"), kw.qubo.Binary("x2"), kw.qubo.Binary("x3")
>>> y1, y2, y3 = kw.qubo.Binary("y1"), kw.qubo.Binary("y2"), kw.qubo.Binary("y3")
>>> p1 = x1 * x2 + 2* y1 * y1
>>> p2 = x1 * y1 + y3
>>> result = p1 * p2
>>> kw.qubo.details(result)
QUBO Details:
  Variables(Binary):_x1_x2, _x1_y1, y1, y3
  QUBO offset:      0
  QUBO coefficients:
    y1, y3         : 2
    _x1_y1, y1     : 2
    _x1_x2, y3     : 1
    _x1_x2, _x1_y1 : 1
  HOBO Constraint:
    _x1_y1 : x1, y1
    _x1_x2 : x1, x2
>>> p = x1*x2*x3
>>> err_cnt, result_dic = kw.qubo.hobo_verify(p, {"x1":1,"x2":1,"x3":0,"_x1_x2":1})
>>> print(err_cnt)
0

kaiwu.qubo.ising_matrix_to_qubo_matrix(ising_mat, remove_linear_bit=True)#

Ising matrix to QUBO matrix

Args:

ising_mat (np.ndarray): Ising matrix

remove_linear_bit (bool): When converting QUBO to Ising, an auxiliary variable will be added to represent the linear term. Whether to remove the last spin variable. Defaults to True.

Returns:

tuple: QUBO matrix and bias

qubo_mat (np.ndarray): QUBO matrix

bias (float): The constant term difference between QUBO and Ising

Examples:

>>> import numpy as np
>>> import kaiwu as kw
>>> matrix = -np.array([[ 0. ,  1. ,  0. ,  1. ,  1. ],
...                     [ 1. ,  0. ,  0. ,  1.,   1. ],
...                     [ 0. ,  0. ,  0. ,  1.,   1. ],
...                     [ 1. ,  1.,   1. ,  0. ,  1. ],
...                     [ 1. ,  1.,   1. ,  1. ,  0. ]])
>>> _qubo_mat, _ = kw.qubo.ising_matrix_to_qubo_matrix(matrix)
>>> _qubo_mat
array([[-4.,  8.,  0.,  8.],
       [-0., -4.,  0.,  8.],
       [-0., -0., -0.,  8.],
       [-0., -0., -0., -8.]])

kaiwu.qubo.make(qubo, q_check=True, hobo_constraint_strength=None)#

For parsing QUBO with placeholders.

Args:

qubo (QUBO): QUBO.

q_check (bool): Whether to check, True will check QUBO errors

hobo_constraint_strength(float): Coefficient for the down-order penalty term

Returns:

QuboExpression: QUBO or QUBO with placeholders.

Examples:

>>> import kaiwu as kw
>>> p1, p2 = kw.qubo.placeholder("p1"), kw.qubo.placeholder("p2")
>>> b1, b2 = kw.qubo.Binary("b1"), kw.qubo.Binary("b2")
>>> q = p1*b1 + p2*b2 + (p1+p2)*b1*b2 + p1
>>> q = q.feed({'p1': 0, 'p2': 1})
>>> qm = kw.qubo.make(q)
>>> kw.qubo.details(qm)
QUBO Details:
  Variables(Binary):b1, b2
  QUBO offset:      0
  QUBO coefficients:
    b2,    : 1
    b1,    : 0
    b1, b2 : 1

>>> kw.qubo.details(q)
QUBO Details:
  Variables(Binary):b1, b2
  QUBO offset:      0
  QUBO coefficients:
    b2,    : 1
    b1,    : 0
    b1, b2 : 1

kaiwu.qubo.ndarray(shape: int | Tuple[int, ...] | List[int], name, var_func, var_func_param=None)#

QUBO container based on np.ndarray. The container supports various vectorization operations native to numpy

Args:

shape (Union[int, Tuple[int, …]]): shape

name (str): Identifier for the generated variable.

var_func (class for func): A method or class used to generate elements. The first argument must be name.

var_func_param (tuple): Parameters for var_func other than name.

Returns:

np.ndarray: Multidimensional container.

Examples:

>>> import numpy as np
>>> import kaiwu as kw
>>> A = kw.qubo.ndarray((2,3,4), "A", kw.qubo.Binary)
>>> A
QUBOArray([[[A[0][0][0], A[0][0][1], A[0][0][2], A[0][0][3]],
            [A[0][1][0], A[0][1][1], A[0][1][2], A[0][1][3]],
            [A[0][2][0], A[0][2][1], A[0][2][2], A[0][2][3]]],

           [[A[1][0][0], A[1][0][1], A[1][0][2], A[1][0][3]],
            [A[1][1][0], A[1][1][1], A[1][1][2], A[1][1][3]],
            [A[1][2][0], A[1][2][1], A[1][2][2], A[1][2][3]]]],
          dtype=object)
>>> A[1,2]
QUBOArray([A[1][2][0], A[1][2][1], A[1][2][2], A[1][2][3]], dtype=object)
>>> A[:, [0,2]]
QUBOArray([[[A[0][0][0], A[0][0][1], A[0][0][2], A[0][0][3]],
            [A[0][2][0], A[0][2][1], A[0][2][2], A[0][2][3]]],

           [[A[1][0][0], A[1][0][1], A[1][0][2], A[1][0][3]],
            [A[1][2][0], A[1][2][1], A[1][2][2], A[1][2][3]]]],
          dtype=object)
>>> B = kw.qubo.ndarray(3, "B", kw.qubo.Binary)
>>> B
QUBOArray([B[0], B[1], B[2]], dtype=object)
>>> C = kw.qubo.ndarray([3,3], "C", kw.qubo.Binary)
>>> C
QUBOArray([[C[0][0], C[0][1], C[0][2]],
           [C[1][0], C[1][1], C[1][2]],
           [C[2][0], C[2][1], C[2][2]]], dtype=object)
>>> D = 2 * B.dot(C) + 2
>>> kw.qubo.details(D[0])
QUBO Details:
  Variables(Binary):B[0], B[1], B[2], C[0][0], C[1][0], C[2][0]
  QUBO offset:      2
  QUBO coefficients:
    B[0], C[0][0] : 2
    B[1], C[1][0] : 2
    B[2], C[2][0] : 2

>>> E = B.sum()
>>> kw.qubo.details(E)
QUBO Details:
  Variables(Binary):B[0], B[1], B[2]
  QUBO offset:      0
  QUBO coefficients:
    B[0], : 1
    B[1], : 1
    B[2], : 1

>>> F = np.diag(C)
>>> F
QUBOArray([C[0][0], C[1][1], C[2][2]], dtype=object)

kaiwu.qubo.placeholder(name: str)#

Placeholder.

Args:

name (str): Unique identifier of a placeholder.

Returns:

dict: Placeholder named name.

Examples:

>>> import kaiwu as kw
>>> p = kw.qubo.placeholder("p")
>>> p
p

Deprecated since version 1.0.0: You can use the standard function kw.qubo.Placeholder().

kaiwu.qubo.qubo_matrix_to_ising_matrix(qubo_mat)#

Convert QUBO matrix to Ising matrix

Args:

qubo_mat (np.ndarray): QUBO matrix

Returns:

tuple: Ising matrix and bias

ising_mat (np.ndarray): Ising matrix
bias (float): The constant term difference between QUBO and Ising

Examples:

>>> import numpy as np
>>> import kaiwu as kw
>>> matrix = -np.array([[-4.,  8.,  0.,  8.],
...                     [-0., -4.,  0.,  8.],
...                     [-0., -0., -0.,  8.],
...                     [-0., -0., -0., -8.]])
>>> _ising_mat, _ = kw.qubo.qubo_matrix_to_ising_matrix(matrix)
>>> _ising_mat
array([[-0.,  1., -0.,  1.,  1.],
       [ 1., -0., -0.,  1.,  1.],
       [-0., -0., -0.,  1.,  1.],
       [ 1.,  1.,  1., -0.,  1.],
       [ 1.,  1.,  1.,  1., -0.]])

kaiwu.qubo.qubo_matrix_to_qubo_model(qubo_mat)#

Convert QUBO matrix to QUBO model

Args:

qubo_mat (np.ndarray): QUBO matrix

Returns:

QuboExpression: 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)
-8*b[0]*b[1]

kaiwu.qubo.qubo_model_to_ising_model(qubo)#

Convert QUBO to CIM Ising model.

Args:

qubo (QUBO): QUBO.

Returns:

CimIsing: CIM Ising model.

Examples:

>>> import kaiwu as kw
>>> b1, b2 = kw.qubo.Binary("b1"), kw.qubo.Binary("b2")
>>> q = b1 + b2 + b1*b2
>>> ci = kw.qubo.qubo_model_to_ising_model(q)
>>> kw.qubo.details(ci)
CIM Ising Details:
  CIM Ising Matrix:
    [[-0.    -0.125 -0.375]
     [-0.125 -0.    -0.375]
     [-0.375 -0.375 -0.   ]]
  CIM Ising Bias: 1.25
  CIM Ising Variables: b1, b2, __spin__
  Variable type: binary
  QUBO Matrix:
    [[1. 1.]
     [0. 1.]]
  QUBO Offset: 0
  QUBO Variables: b1, b2

kaiwu.qubo.qubo_model_to_qubo_matrix(qubo_expr)#

QUBO outputs QUBO matrix.

Args:

qubo (QUBO): QUBO.

Returns:

dict: QUBO matrix dictionary.

Examples:

>>> import kaiwu as kw
>>> b1, b2 = kw.qubo.Binary("b1"), kw.qubo.Binary("b2")
>>> q = b1 + b2 + b1*b2
>>> qubo_mol = kw.qubo.make(q)
>>> md = kw.qubo.qubo_model_to_qubo_matrix(qubo_mol)
>>> md
{'qubo_matrix': array([[1., 1.],
       [0., 1.]]), 'offset': 0, 'variables': {'bb1': 0, 'bb2': 1}}

kaiwu.qubo.quicksum(qubo_expr_list: list)#

High-performance QUBO summer.

Args:

qubo_expr_list (QUBO list): A list of QUBO expressions used for summing.

Returns:

QuboExpression: Constrained QUBO.

Examples:

>>> import kaiwu as kw
>>> qubo_list = [kw.qubo.Binary("b"+str(i)) for i in range(10)] # Variables are also QUBO
>>> output = kw.qubo.quicksum(qubo_list)
>>> kw.qubo.details(output)
QUBO Details:
  Variables(Binary):b0, b1, b2, b3, b4, b5, b6, b7, b8, b9
  QUBO offset:      0
  QUBO coefficients:
    b0, : 1
    b1, : 1
    b2, : 1
    b3, : 1
    b4, : 1
    b5, : 1
    b6, : 1
    b7, : 1
    b8, : 1
    b9, : 1

kaiwu.qubo.spin(name: str)#

Spin variable, the only possible values are -1, 1.

Args:

name (str): The unique identifier of the variable.

Returns:

dict: Spin variable named name.

Examples:

>>> import kaiwu as kw
>>> s = kw.qubo.spin("s")
>>> s
2*s-1