User guide¶
Introduction¶
The ising package allows to find a ground state (or, more generally, low energy spectrum) of an arbitrary Ising model. That is, it allows you to find the minimum of the following energy function
where \(J_{ij}\) and \(h_i\) are arbitrary real coefficients and variables \(s_i\) under optimization are either \(-1\) or \(1\).
Basic usage¶
The main functionallity of ising package is wrapped in ising.search
function. As an example, suppose you want to find 4 lowest energy states of the following Ising model
In that case you could run ising.search
as follows
import ising
graph = {(0, 1): 2, (1, 2): -3, (2, 3): 2.5, (0, 0): 1}
result = ising.search(graph, num_states=4)
print(result.energies)
Note how the above model is specified as a dictionary:
- \(J_{ij}\) are specified as entries with key
(i, j)
. - \(h_i\) are specified as entries with key
(i, i)
.
Read further to learn other input formats that ising can handle.
Supported input formats¶
There are three formats supported by ising:
- The dictionary format already presented in previous section.
- The coefficients list format. In this format coefficients are specified as a list of lists, in hich each row is of the form
[i, j, J_ij]
or ``[i, i, h_i]`.` - The matrix format. In this format you specify your coefficients as a matrix in which diagonal elements correspond to \(h_i\) and off-diagonal elements correspond to \(J_{ij}\). The matrix can either be a list of lists or a numpy array.
Putting it in another way, here are equivalent ways of specifying graph from the above basic example
# coefficients list format
graph = [[0, 1, 2], [1, 2, -3], [0, 0, 1], [2, 3, 2.5]],
# matrix format: as list of lists or numpy array
graph = [[1, 2, 0, 0], [0, 0, -3, 0], [0, 0, 0, 2.5], [0, 0, 0, 0]],
graph = np.array([[1, 2, 0, 0], [0, 0, -3, 0], [0, 0, 0, 2.5], [0, 0, 0, 0]]),
Note that the matrix format requires your spins to be labelled with \(0, \ldots, n\), other two formats are not restricted in this way.
Also note that since both \(J_{ij}\) and \(J_{ji}\) can be specified in all the formats it does not matter which one you choose. In fact, if you choose to specify both coefficients, both of them will be used. Therefore, using the following graphs would yield the same result as the previous example:
# coefficient list format
graph = [[0, 1, 1], [1, 0, 1], [1, 2, -3], [0, 0, 1], [2, 3, 2.5]],
# matrix format
graph = [[1, 1, 0, 0], [1, 0, -3, 0], [0, 0, 0, 2.5], [0, 0, 0, 0]]
Tweaking execution¶
You can use the following keyword arguments to ising.search
to tweak its execution:
num_states
: integer specifying how many low-energy states should be found.method
: indicating whether CPU (method='CPU'
) or GPU (method='GPU'
) implementation should be used. If not given, CPU implementation is used by default.energies_only
: boolean indicating whether to return only energies (True
) or also states corresponding to those energies (False
). Default isFalse
, set it toTrue
if you don’t need states, as it should shorten the execution time.chunk_size
: ising performs search in chunks of the size \(2^k\), where \(k\) is choosen as a largest number such that computations are feasible on the host. You can tweak this value to use other exponent if you choose so.
In addition, for CPU implementation, you can specify how many OMP threads will be used for computations using OMP_NUM_THREADS
environmental variable.