kaiwu.core package#

Module contents#

Module: core

Function: Definition of Baseses

class kaiwu.core.IsingSolver#

Bases: object

Bases for Ising solvers

set_matrix(ising_matrix)#: Set matrix and update related content

on_matrix_change()#: Update matrix-related information; can be implemented when inheriting from IsingSolver. When the Ising matrix being processed changes, the implementation of this function will be called to allow corresponding actions.

solve(ising_matrix=None, negtail_flip=True, sort_solutions=False)#

Solve the Ising matrix

Parameters:

ising_matrix (np.ndarray) – Isingmatrix
negtail_flip (bool) – Whether to perform negative-tail flipping
sort_solutions (bool) – Whether to sort solutions

Returns:

solution vector

Return type:

output (np.ndarray)

get_hamiltonian()#

Returns:: Hamiltonian value of the current solution
Return type:: hamiltonian (np.ndarray)

class kaiwu.core.QuboSolver#

Bases: object

Bases for Solvers

Parameters:: optimizer (IsingSolver) – Ising solver

solve_qubo(*args, **kwargs)#

kaiwu.core.get_sorted_solutions(matrix, solutions, bias=0.0, negtail_ff=True, sort_solutions=True)#

Optimal solution sampling.

Parameters:

matrix (np.ndarray) – Ising matrix.
solutions (np.ndarray) – variable configurations.
bias (float) – constant term.
negtail_ff (bool) – negtail_flip flag for negative-tail flipping; matrices produced by quadratizing linear terms in an Ising model require negative-tail flipping.

Returns:

variable configurations sorted by energy, and energy values.

Return type:

output (np.ndarray, np.ndarray)

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. ]])
>>> solutions = np.array([[ 1, -1,  1, -1, -1],
...                   [-1, -1,  1, -1, -1],
...                   [-1, -1, -1,  1,  1],
...                   [ 1,  1,  1, -1, -1],
...                   [ 1,  1,  1, -1, -1],
...                   [ 1,  1,  1, -1, -1]])
>>> kw.core.get_sorted_solutions(matrix, solutions, 0)
(array([[-1, -1, -1,  1,  1],
       [-1, -1, -1,  1,  1],
       [-1, -1, -1,  1,  1],
       [-1, -1, -1,  1,  1],
       [-1,  1, -1,  1,  1],
       [ 1,  1, -1,  1,  1]]), array([-8., -8., -8., -8., -4.,  8.]))

class kaiwu.core.Expression(coefficient: dict | None = None, offset: float = 0)#

Bases: object

Universal Bases for QUBO/Ising expressions (provides default quadratic expression implementation)

clear() → None#: Set the expression to 0

get_variables()#

Get the set of variable names

Returns:: return expression variable
Return type:: dict

get_max_deltas()#: Calculate the upper bound of the objective function change caused by flipping each variable. The return values negative_delta and positive_delta are the maximum changes caused by flipping the variable from 1->0 and 0->1, respectively.

get_average_coefficient()#: Return the average value of coefficients

get_val(sol_dict)#

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

Parameters:: sol_dict (dict) – Result dictionary generated by get_sol_dict.
Returns:: Value obtained after substituting into the QUBO
Return type:: float

Examples

>>> import kaiwu as kw
>>> import numpy as np
>>> a = kw.core.Binary("a")
>>> b = kw.core.Binary("b")
>>> c = kw.core.Binary("c")
>>> d = a + 2 * b + 4 * c
>>> sol_dict = {"a": 1, "b": 0, "c": 1}
>>> d.get_val(sol_dict)
5

class kaiwu.core.BinaryModel(objective=None)#

Bases: object

Binary model class

Parameters:: objective (BinaryExpression, optional) – Objective function. Defaults to None

set_constraint_handler(constraint_handler)#

Set the unconstrained conversion method for constraint terms

Parameters:: constraint_handler – Set the unconstrained conversion method for constraint terms

set_objective(objective)#

Set the objective function

Parameters:: objective (BinaryExpression) – Objective function expression

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

Add constraint terms; single or multiple constraints are supported

Parameters:

constraint_in – Constraint expression, supports two input types: 1. Single constraint: BinaryExpression or Constraint object. For example: quicksum(x) - 1 or Constraint(quicksum(x) - 1, "==", 1) 2. Multiple constraints: list/tuple/np.ndarray, automatically iterates and adds them. For example: [constraint1, constraint2, constraint3]
name (str or list, optional) – constraint name, automatically named by default. when multiple constraints are provided,
penalty (float, optional) – default penalty coefficient
constr_type (str, optional) – Constraint type, can be set to “soft” or “hard”, defaults to “hard”
slack_var_expr (BinaryExpression, optional) – slack variable expression, used only in inequality constraints,

Examples

Example1 (Single BinaryExpression):

>>> import kaiwu as kw
>>> model = kw.core.QuboModel()
>>> x = [kw.core.Binary(f"x{i}") for i in range(3)]
>>> model.add_constraint(kw.core.quicksum(x) - 1)

Example2 (Constraint with relation operator):

>>> from kaiwu.core._constraint import Constraint
>>> model.add_constraint(Constraint(kw.core.quicksum(x) - 1, "==", 1))

Examples3 (Multiple Constraints):

>>> constraints = [x[i] - 1 for i in range(3)]
>>> model.add_constraint(constraints, name="my_constraints")

get_value(solution_dict)#

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

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

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

Verify whether constraints are satisfied

Parameters:

solution_dict (dict) – QUBO model solution dictionary
constr_type (str, optional) – Constraint type, can be set to “soft” or “hard”, defaults to “hard”

Returns:

Constraint satisfaction information - int: Number of unsatisfied constraints - dict: Dictionary containing constraint values

Return type:

tuple

initialize_penalties()#: Automatically initialize all penalty coefficients

get_constraints_expr_list()#

Get all current constraints.

Returns:: list of all constraints.
Return type:: list

compile_constraints()#: Convert constraint terms to Expression according to different styles

class kaiwu.core.BinaryExpression(coefficient: dict | None = None, offset: float = 0)#

Bases: Expression

Basic data structure for QUBO expressions

feed(feed_dict)#

Assign values to placeholders and return a new expression object after assignment

Parameters:: feed_dict (dict) – Values for placeholders to be assigned

Examples

>>> import kaiwu as kw
>>> p = kw.core.Placeholder('p')
>>> a = kw.core.Binary('a')
>>> y = p * a
>>> str(y)  
'(p)*a'
>>> y= y.feed({'p': 2})
>>> str(y)  
'2*a'

clear() → None#: Set the expression to 0

get_average_coefficient()#: Return the average value of coefficients

get_max_deltas()#: Calculate the upper bound of the objective function change caused by flipping each variable. The return values negative_delta and positive_delta are the maximum changes caused by flipping the variable from 1->0 and 0->1, respectively.

get_val(sol_dict)#

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

Parameters:: sol_dict (dict) – Result dictionary generated by get_sol_dict.
Returns:: Value obtained after substituting into the QUBO
Return type:: float

Examples

>>> import kaiwu as kw
>>> import numpy as np
>>> a = kw.core.Binary("a")
>>> b = kw.core.Binary("b")
>>> c = kw.core.Binary("c")
>>> d = a + 2 * b + 4 * c
>>> sol_dict = {"a": 1, "b": 0, "c": 1}
>>> d.get_val(sol_dict)
5

get_variables()#

Get the set of variable names

Returns:: return expression variable
Return type:: dict

class kaiwu.core.Binary(name: str = '')#

Bases: BinaryExpression

Binary variable: only stores the variable name, does not inherit QuboExpression

clear()#: Set the expression to 0

feed(feed_dict)#

Assign values to placeholders and return a new expression object after assignment

Parameters:: feed_dict (dict) – Values for placeholders to be assigned

Examples

>>> import kaiwu as kw
>>> p = kw.core.Placeholder('p')
>>> a = kw.core.Binary('a')
>>> y = p * a
>>> str(y)  
'(p)*a'
>>> y= y.feed({'p': 2})
>>> str(y)  
'2*a'

get_average_coefficient()#: Return the average value of coefficients

get_max_deltas()#: Calculate the upper bound of the objective function change caused by flipping each variable. The return values negative_delta and positive_delta are the maximum changes caused by flipping the variable from 1->0 and 0->1, respectively.

get_val(sol_dict)#

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

Parameters:: sol_dict (dict) – Result dictionary generated by get_sol_dict.
Returns:: Value obtained after substituting into the QUBO
Return type:: float

Examples

>>> import kaiwu as kw
>>> import numpy as np
>>> a = kw.core.Binary("a")
>>> b = kw.core.Binary("b")
>>> c = kw.core.Binary("c")
>>> d = a + 2 * b + 4 * c
>>> sol_dict = {"a": 1, "b": 0, "c": 1}
>>> d.get_val(sol_dict)
5

get_variables()#

Get the set of variable names

Returns:: return expression variable
Return type:: dict

kaiwu.core.quicksum(qubo_expr_list: list)#

High-performance QUBO summator.

Parameters:: qubo_expr_list (QUBO列表) – List of QUBO expressions for summation.
Returns:: Constraint QUBO.
Return type:: BinaryExpression

Examples

>>> import kaiwu as kw
>>> qubo_list = [kw.core.Binary(f"b{i}") for i in range(10)] # Variables are also QUBO
>>> output = kw.core.quicksum(qubo_list)
>>> str(output)
'b0+b1+b2+b3+b4+b5+b6+b7+b8+b9'

class kaiwu.core.Placeholder(name: str = '')#

Bases: BinaryExpression

Placeholder variable: only stores the variable name, for decision-making

get_placeholder_set()#: Get the set of placeholders

clear() → None#: Set the expression to 0

feed(feed_dict)#

Assign values to placeholders and return a new expression object after assignment

Parameters:: feed_dict (dict) – Values for placeholders to be assigned

Examples

>>> import kaiwu as kw
>>> p = kw.core.Placeholder('p')
>>> a = kw.core.Binary('a')
>>> y = p * a
>>> str(y)  
'(p)*a'
>>> y= y.feed({'p': 2})
>>> str(y)  
'2*a'

get_average_coefficient()#: Return the average value of coefficients

get_max_deltas()#: Calculate the upper bound of the objective function change caused by flipping each variable. The return values negative_delta and positive_delta are the maximum changes caused by flipping the variable from 1->0 and 0->1, respectively.

get_val(sol_dict)#

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

Parameters:: sol_dict (dict) – Result dictionary generated by get_sol_dict.
Returns:: Value obtained after substituting into the QUBO
Return type:: float

Examples

>>> import kaiwu as kw
>>> import numpy as np
>>> a = kw.core.Binary("a")
>>> b = kw.core.Binary("b")
>>> c = kw.core.Binary("c")
>>> d = a + 2 * b + 4 * c
>>> sol_dict = {"a": 1, "b": 0, "c": 1}
>>> d.get_val(sol_dict)
5

get_variables()#

Get the set of variable names

Returns:: return expression variable
Return type:: dict

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

Bases: BinaryExpression

Integer variable: only stores the variable name and range, does not inherit QuboExpression

clear() → None#: Set the expression to 0

feed(feed_dict)#

Assign values to placeholders and return a new expression object after assignment

Parameters:: feed_dict (dict) – Values for placeholders to be assigned

Examples

>>> import kaiwu as kw
>>> p = kw.core.Placeholder('p')
>>> a = kw.core.Binary('a')
>>> y = p * a
>>> str(y)  
'(p)*a'
>>> y= y.feed({'p': 2})
>>> str(y)  
'2*a'

get_average_coefficient()#: Return the average value of coefficients

get_max_deltas()#: Calculate the upper bound of the objective function change caused by flipping each variable. The return values negative_delta and positive_delta are the maximum changes caused by flipping the variable from 1->0 and 0->1, respectively.

get_val(sol_dict)#

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

Parameters:: sol_dict (dict) – Result dictionary generated by get_sol_dict.
Returns:: Value obtained after substituting into the QUBO
Return type:: float

Examples

>>> import kaiwu as kw
>>> import numpy as np
>>> a = kw.core.Binary("a")
>>> b = kw.core.Binary("b")
>>> c = kw.core.Binary("c")
>>> d = a + 2 * b + 4 * c
>>> sol_dict = {"a": 1, "b": 0, "c": 1}
>>> d.get_val(sol_dict)
5

get_variables()#

Get the set of variable names

Returns:: return expression variable
Return type:: dict

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

QUBO container based on np.ndarray. This container supports various native NumPy vectorized operations

Parameters:

shape (Union[int, Tuple[int, ...]]) – Shape
name (str) – Identifier of the generated variable.
var_func (class for func) – Method or class used to generate elements. The first parameter must be ‘name’
var_func_param (tuple) – Parameters of var_func except ‘name’

Returns:

Multidimensional container.

Return type:

np.ndarray

Examples

>>> import numpy as np
>>> import kaiwu as kw
>>> A = kw.core.ndarray((2,3,4), "A", kw.core.Binary)
>>> A
BinaryExpressionNDArray([[[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]
BinaryExpressionNDArray([A[1][2][0], A[1][2][1], A[1][2][2], A[1][2][3]],
                        dtype=object)
>>> A[:, [0,2]]
BinaryExpressionNDArray([[[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.core.ndarray(3, "B", kw.core.Binary)
>>> B
BinaryExpressionNDArray([B[0], B[1], B[2]], dtype=object)
>>> C = kw.core.ndarray([3,3], "C", kw.core.Binary)
>>> C
BinaryExpressionNDArray([[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
>>> str(D[0])
'2*B[0]*C[0][0]+2*B[1]*C[1][0]+2*B[2]*C[2][0]+2'
>>> E = B.sum()
>>> str(E)
'B[0]+B[1]+B[2]'
>>> F = np.diag(C)
>>> F
BinaryExpressionNDArray([C[0][0], C[1][1], C[2][2]], dtype=object)

kaiwu.core.zeros(shape) → BinaryExpressionNDArray#

Create a zero array with the same shape as the input array.

Parameters:: shape (tuple) – matrix
Returns:: QUBOArray: array with the same shape and all elements set to 0.
Return type:: QUBOArray

Examples

>>> import kaiwu as kw
>>> Z = kw.core.zeros((2, 3))
>>> Z
BinaryExpressionNDArray([[0, 0, 0],
                         [0, 0, 0]], dtype=object)

kaiwu.core.dot(mat_left, mat_right)#

Matrix multiplication

Parameters:

mat_left (numpy.array) – First matrix
mat_right (numpy.array) – Second matrix

Raises:

ValueError – Both inputs must be np.ndarray
ValueError – The dimensions of the two inputs must match

Returns:

Product matrix

Return type:

np.ndarray

class kaiwu.core.BinaryExpressionNDArray#

Bases: ndarray

QUBO container based on np.ndarray. This container supports various native NumPy vectorized operations

is_array_less = <numpy.vectorize object>#

is_array_less_equal = <numpy.vectorize object>#

is_array_greater = <numpy.vectorize object>#

is_array_greater_equal = <numpy.vectorize object>#

is_array_equal = <numpy.vectorize object>#

dot(b, out=None)#

Matrix multiplication using quicksum

Parameters:

b (BinaryExpressionNDArray) – Another matrix
out – Optional output array used to store the result. Its shape must match the expected output shape.

Returns:

Product

Return type:

BinaryExpressionNDArray

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

Summation method using quicksum

Parameters:

axis – Axis (dimension) along which to perform the sum. Defaults to None, meaning all elements are summed; if an integer or tuple, the sum is computed along the specified axes.
dtype – Output data type. If not provided, the input array dtype is used by default. Not currently supported.
out – Optional output array used to store the result. Its shape must match the expected output shape.
keepdims – Boolean value. If True, the summed axis is retained as a dimension of length 1. Not currently supported.
initial – Initial value for the sum (scalar); defaults to 0. Not currently supported.
where – Boolean array specifying which elements participate in the sum (supported by NumPy 1.20+). Not currently supported.

Returns:

Product

Return type:

BinaryExpressionNDArray

get_val(sol_dict)#

Substitute spin values into QUBO array variables based on the result dictionary.

Parameters:

array (QUBOArray) – QUBO array
sol_dict (dict) – Result dictionary generated by get_sol_dict.

Returns:

np.ndarray: Value array obtained after substituting into the QUBO array

Return type:

np.ndarray

Examples

>>> import kaiwu as kw
>>> import numpy as np
>>> x = kw.core.ndarray((2, 2), "x", kw.core.Binary)
>>> y = x.sum()
>>> y_vars = y.get_variables()
>>> s = np.array([1, -1, 1, -1])
>>> sol_dict = kw.core.get_sol_dict(s, y_vars)
>>> x.get_val(sol_dict)
array([[1., 0.],
       [1., 0.]])

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

Bases: BinaryModel

QUBO model class that supports adding constraints

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

invalidate_made_state()#: Merged constraint expression

make()#

Return the merged QUBO expression

Returns:: QUBO matrix and bias - qubo_mat (np.ndarray): QUBO matrix - bias (float): Constant offset between QUBO and Ising
Return type:: BinaryExpression

get_matrix()#

Get the QUBO matrix

Returns:: QUBOmatrix
Return type:: numpy.ndarray

get_variables()#: getqubomodelvariables

get_offset()#: getqubomodeloffset

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

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

Add constraint terms; single or multiple constraints are supported

Parameters:

constraint_in – Constraint expression, supports two input types: 1. Single constraint: BinaryExpression or Constraint object. For example: quicksum(x) - 1 or Constraint(quicksum(x) - 1, "==", 1) 2. Multiple constraints: list/tuple/np.ndarray, automatically iterates and adds them. For example: [constraint1, constraint2, constraint3]
name (str or list, optional) – constraint name, automatically named by default. when multiple constraints are provided,
penalty (float, optional) – default penalty coefficient
constr_type (str, optional) – Constraint type, can be set to “soft” or “hard”, defaults to “hard”
slack_var_expr (BinaryExpression, optional) – slack variable expression, used only in inequality constraints,

Examples

Example1 (Single BinaryExpression):

>>> import kaiwu as kw
>>> model = kw.core.QuboModel()
>>> x = [kw.core.Binary(f"x{i}") for i in range(3)]
>>> model.add_constraint(kw.core.quicksum(x) - 1)

Example2 (Constraint with relation operator):

>>> from kaiwu.core._constraint import Constraint
>>> model.add_constraint(Constraint(kw.core.quicksum(x) - 1, "==", 1))

Examples3 (Multiple Constraints):

>>> constraints = [x[i] - 1 for i in range(3)]
>>> model.add_constraint(constraints, name="my_constraints")

compile_constraints()#: Convert constraint terms to Expression according to different styles

get_constraints_expr_list()#

Get all current constraints.

Returns:: list of all constraints.
Return type:: list

get_value(solution_dict)#

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

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

initialize_penalties()#: Automatically initialize all penalty coefficients

set_constraint_handler(constraint_handler)#

Set the unconstrained conversion method for constraint terms

Parameters:: constraint_handler – Set the unconstrained conversion method for constraint terms

set_objective(objective)#

Set the objective function

Parameters:: objective (BinaryExpression) – Objective function expression

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

Verify whether constraints are satisfied

Parameters:

solution_dict (dict) – QUBO model solution dictionary
constr_type (str, optional) – Constraint type, can be set to “soft” or “hard”, defaults to “hard”

Returns:

Constraint satisfaction information - int: Number of unsatisfied constraints - dict: Dictionary containing constraint values

Return type:

tuple

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

Q value calculator.

Parameters:

qubo_matrix (np.ndarray) – QUBOmatrix.
offset (float) – constant term
binary_configuration (np.ndarray) – binary configuration

Returns:

Q value.

Return type:

output (float)

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.core.calculate_qubo_value(matrix, offset, binary_configuration)
>>> print(qubo_value)
2.8

kaiwu.core.qubo_matrix_to_qubo_model(qubo_mat)#

Convert a QUBO matrix to a QUBO model

Parameters:: qubo_mat (np.ndarray) – QUBOmatrix
Returns:: Convert QUBO to a Ising model.
Return type:: QuboModel

Examples

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

kaiwu.core.ising_matrix_to_qubo_matrix(ising_mat, remove_linear_bit=True, decimal=False)#

Convert an Ising matrix to a QUBO matrix

Parameters:

ising_mat (np.ndarray) – Isingmatrix
remove_linear_bit (bool) – An auxiliary variable is added to represent linear terms when converting QUBO to Ising. Whether to remove the last spin variable. Defaults to True.
decimal (bool) – whether to use Decimal for high-precision computation; defaults to False.

Returns:

QUBO matrix and bias

Return type:

tuple

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.core.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.core.qubo_matrix_to_ising_matrix(qubo_mat, decimal=False)#

Convert a QUBO matrix to an Ising matrix

Parameters:

qubo_mat (np.ndarray) – QUBOmatrix
decimal (bool) – whether to use Decimal for high-precision computation; defaults to False.

Returns:

Ising matrix and bias - ising_mat (np.ndarray): Ising matrix - bias (float): Constant offset between QUBO and Ising

Return type:

tuple

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.core.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.core.qubo_model_to_ising_model(qubo_model)#

Convert QUBO to a Ising model.

Parameters:: qubo_model (QuboModel) – QuboModel: QUBO model
Returns:: Ising model
Return type:: CimIsing

Examples

>>> import kaiwu as kw
>>> b1, b2 = kw.core.Binary("b1"), kw.core.Binary("b2")
>>> q = b1 + b2 + b1*b2
>>> q_model = kw.core.QuboModel(q)
>>> ci = kw.core.qubo_model_to_ising_model(q_model)
>>> print(str(ci))
Ising Details:
  Ising Matrix:
    [[-0.    -0.125 -0.375]
     [-0.125 -0.    -0.375]
     [-0.375 -0.375 -0.   ]]
  Ising Bias: 1.25
  Ising Variables: b1, b2, __spin__

class kaiwu.core.IsingModel(variables, ising_matrix, bias)#

Bases: dict

Ising model

get_variables()#: Get variables in the model

get_matrix()#: Get the Ising matrix

get_bias()#: Get the constant offset obtained during QUBO conversion

fromkeys(value=None, /)#: Create a new dictionary with keys from iterable and values set to value.

class kaiwu.core.IsingExpression(variables=None, quadratic=None, linear=None, bias=0)#

Bases: Expression

Base class for Ising expressions; directly inherits Expression and preserves extension points.

clear() → None#: Set the expression to 0

get_average_coefficient()#: Return the average value of coefficients

get_max_deltas()#: Calculate the upper bound of the objective function change caused by flipping each variable. The return values negative_delta and positive_delta are the maximum changes caused by flipping the variable from 1->0 and 0->1, respectively.

get_val(sol_dict)#

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

Parameters:: sol_dict (dict) – Result dictionary generated by get_sol_dict.
Returns:: Value obtained after substituting into the QUBO
Return type:: float

Examples

>>> import kaiwu as kw
>>> import numpy as np
>>> a = kw.core.Binary("a")
>>> b = kw.core.Binary("b")
>>> c = kw.core.Binary("c")
>>> d = a + 2 * b + 4 * c
>>> sol_dict = {"a": 1, "b": 0, "c": 1}
>>> d.get_val(sol_dict)
5

get_variables()#

Get the set of variable names

Returns:: return expression variable
Return type:: dict

class kaiwu.core.Spin(name: str = '')#

Bases: IsingExpression

Spin variable; possible values are only -1 and 1.

Parameters:: name (str) – unique identifier of the variable.
Returns:: spin variable named name.
Return type:: dict

Examples

>>> import kaiwu as kw
>>> s = kw.core.Spin("s")
>>> s
2*s-1

clear() → None#: Set the expression to 0

get_average_coefficient()#: Return the average value of coefficients

get_max_deltas()#: Calculate the upper bound of the objective function change caused by flipping each variable. The return values negative_delta and positive_delta are the maximum changes caused by flipping the variable from 1->0 and 0->1, respectively.

get_val(sol_dict)#

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

Parameters:: sol_dict (dict) – Result dictionary generated by get_sol_dict.
Returns:: Value obtained after substituting into the QUBO
Return type:: float

Examples

>>> import kaiwu as kw
>>> import numpy as np
>>> a = kw.core.Binary("a")
>>> b = kw.core.Binary("b")
>>> c = kw.core.Binary("c")
>>> d = a + 2 * b + 4 * c
>>> sol_dict = {"a": 1, "b": 0, "c": 1}
>>> d.get_val(sol_dict)
5

get_variables()#

Get the set of variable names

Returns:: return expression variable
Return type:: dict

exception kaiwu.core.KaiwuError#

Bases: Exception

Bases for exceptions in this module.

args#

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

class kaiwu.core.PenaltyMethodConstraint(expr, penalty=1, parent_model=None)#

Bases: object

Penalty method for converting constrained problems to unconstrained problems

Parameters:

expr (Expression) – Compiled constraint term expression
penalty (float) – Penalty coefficient of the constraint term

classmethod from_constraint_definition(name, constraint: Constraint, parent_model)#

Prepare QUBO expression for the given constraint, automatically determining slack variables if needed.

Parameters:

name – name: Name of the constraint.
constraint – constraint: The relation constraint to process.
parent_model – parent_model: the model it belongs to.

set_penalty(penalty)#: Set penalty coefficient

penalize_more()#: Increase penalty coefficient

penalize_less()#: Decrease penalty coefficient

is_satisfied(solution_dict)#: Verify constraint satisfaction

kaiwu.core.get_sol_dict(solution, vars_dict)#

Generate result dictionary based on solution vector and variable dictionary.

Parameters:

solution (np.ndarray) – Solution vector (spin).
vars_dict (dict) – Variable dictionary, generated by cim_ising_model.get_variables().

Returns:

Result dictionary. Keys are variable names, values are corresponding spin values.

Return type:

dict

Examples

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

kaiwu.core.get_val(qubo, sol_dict)#

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

Parameters:

qubo (BinaryExpression or BinaryExpressionNDArray) – QUBO expression
sol_dict (dict) – Result dictionary generated by get_sol_dict.

Returns:

Value obtained after substituting into the QUBO

Return type:

float

Examples

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

kaiwu.core.get_min_penalty(obj, cons)#

Return the minimum penalty coefficient corresponding to the constraint term ‘cons’, with the penalty term taking priority.

Parameters:

obj – QUBO expression of the original objective function.
cons – QUBO expression of the constraint term

Returns:

Constraint term

Return type:

float

Examples

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

kaiwu.core.get_min_penalty_from_min_diff(cons, negative_delta, positive_delta)#

Constraint termEstimate the minimum penalty coefficient of the constraint term based on the maximum and minimum values of the objective.

Parameters:

cons – Constraint term
negative_delta – negative_delta: Minimum value of the objective
positive_delta – positive_delta: Maximum value of the objective

Returns:

Found minimum penalty coefficient

kaiwu.core.get_min_penalty_for_equal_constraint(obj, cons)#

Return the minimum penalty coefficient corresponding to the linear equality constraint term ‘cons’: the worst-case scenario when flipping one bit of the solution that satisfies this constraint. This penalty coefficient is valid in the sense that it ensures the feasible solution of the original problem is a local optimum of the objective function (in the local sense of one-bit flip).

Parameters:

obj – QUBO expression of the original objective function.
cons – cons: Linear expression in the linear equality constraint cons=0.

Returns:

Minimum penalty coefficient corresponding to the linear equality constraint term ‘cons’.

Return type:

float

Examples

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

kaiwu.core.get_min_penalty_from_deltas(cons, neg_delta, pos_delta, obj_vars, min_delta_method='diff')#

Return the minimum penalty coefficient corresponding to the constraint term ‘cons’, with the penalty term taking priority.

Parameters:

cons – QUBO expression of the constraint term
neg_delta – Dictionary of maximum changes when each variable is flipped from 1 to 0
pos_delta – Dictionary of maximum changes when each variable is flipped from 0 to 1
obj_vars – The third element is a list of variables
min_delta_method – Declared here. Two methods are provided to find the minimum change value: MIN_DELTA_METHODS = {“diff”: _get_constraint_min_deltas_diff, “exhaust”: _get_constraint_min_deltas_exhaust}

Examples

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