kaiwu.ising package#

Module contents#

Module: Ising

Function: Provide Ising model-related functions

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

Bases: dict

Ising model

get_variables()#: Get variables in the model

get_matrix()#: Get Ising matrix

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

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

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

Bases: Expression

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

clear() → None. Remove all items from D.#

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

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_variables()#

Get the set of variable names

Returns:: variables: (tuple) Returns the set of variables composing the expression

kaiwu.ising.calculate_ising_matrix_bit_width(ising_matrix, bit_width=8)#

Calculate the parameter bit width of the Ising matrix

Args:

ising_matrix (np.ndarray): Ising matrix

bit_width (int): Maximum bit width limit

Returns:

dict: Returns the precision and scaling factor of the Ising matrix

precision (int): Ising matrix precision

multiplier (float): Scaling factor

Example 1:

>>> import numpy as np
>>> import kaiwu as kw
>>> _matrix = -np.array([[ -0., 127., -12.,  -5.],
...                      [127.,  -0., -12., -12.],
...                      [-12., -12.,  -0.,  -9.],
...                      [ -5., -12.,  -9.,  -0.]])
>>> kw.ising.calculate_ising_matrix_bit_width(_matrix)
{'precision': 8, 'multiplier': np.float64(1.0)}

Example 2 (Meets requirements after scaling):

>>> import numpy as np
>>> import kaiwu as kw
>>> _matrix = -np.array([[ -0., 12.7, -1.2,  -0.5],
...                      [12.7,  -0., -1.2, -1.2],
...                      [-1.2, -1.2, -0.,   -0.9],
...                      [-0.5, -1.2, -0.9,  -0.]])
>>> kw.ising.calculate_ising_matrix_bit_width(_matrix)
{'precision': 8, 'multiplier': np.float64(10.0)}

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.ising.calculate_ising_matrix_bit_width(_matrix)
{'precision': inf, 'multiplier': inf}

kaiwu.ising.adjust_ising_matrix_precision(ising_matrix, bit_width=8)#

Adjust the precision of the Ising matrix. 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:

ising_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: Ising matrix that meets the precision requirements

Examples:

>>> import numpy as np
>>> import kaiwu as kw
>>> ori_ising_mat1 = np.array([[0, 0.22, 0.198],
...                            [0.22, 0, 0.197],
...                            [0.198, 0.197, 0]])
>>> ising_mat1 = kw.ising.adjust_ising_matrix_precision(ori_ising_mat1)
>>> ising_mat1
array([[  0, 127, 114],
       [127,   0, 114],
       [114, 114,   0]])
>>> ori_ising_mat2 = np.array([[0, 0.22, 0.198],
...                            [0.22, 0, 50],
...                            [0.198, 50, 0]])
>>> ising_mat2 = kw.ising.adjust_ising_matrix_precision(ori_ising_mat2)
>>> ising_mat2  # The solutions obtained by qubo_mat2 and ori_qubo_mat2 matrices are quite different
array([[  0,   1,   1],
       [  1,   0, 127],
       [  1, 127,   0]])

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

Bases: IsingExpression

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

Args:

name (str): Unique identifier of the variable.

Returns:

dict: Spin variable with the name ‘name’.

Examples:

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

clear() → None. Remove all items from D.#

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

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_variables()#

Get the set of variable names

Returns:: variables: (tuple) Returns the set of variables composing the expression