Potts Model Constructor

class PottsPlayground.PottsModel

Provides a framework for creating, storing, and manipulating Potts models. Provides a bridge between the semantic structure of various combinatorial problems and a Potts-model format used by the Potts annealing engine. Usually instantiated as a base class, but can also be used alone to create arbitrary Potts model tasks.

AddBias(spin, bias)

Modify the bias vector on the given spin, by adding to it’s existing value. Allows taking a “superpositional” approach to building up the model.

Parameters:

  • spin – Name or index of the spin to add to.

  • bias – Numpy array of bias values (one bias for each of the spin’s possible states).

Returns:

None

AddKernel(creator, i, j, weight=1)

Adds a directed connection from spin i to spin j. The connection is a weight matrix unto itself, with size [qSizes[i], qSizes[j]]. ‘creator’ is a function that accepts a single boolean arguement; when true, it returns a string identifier for the weight kernel between spins i and j. If false, it returns the actual weight kernel. This is designed to balance ease of use and efficiency: if the same weight kernel is used between many pairs of Potts spins, the weight kernel will only be generated once (which may not be trivial depending on how it is generated), but the user does not need to keep track of how many times a given weight kernel was used.

Parameters:

  • creator – A lambda function that takes a single boolean arguement.

  • i (str, int) – Name/Index of first spin.

  • j (str, int) – Name/Index of second spin.

  • weight (float) – Scales the entire weight kernel for this connection only.

Returns:

None

AddSpins(qSizes, names=None)

Add Spins to the model by specifying their size (how many states each spin has). Spins may be assigned semantic names, otherwise the spins are given an index identifier.

Parameters:

  • qSizes – A list or numpy array of integers, one for each spin being added.

  • names – (optional) A mixed list of str or int, by which each of the spins is identified. Must have the same number of elements as qSizes.

Returns:

None

AddWeight(creator, i, j, weight=1)

Adds an undirected connection between spin i and spin j. The connection is a weight matrix unto itself, with size [qSizes[i], qSizes[j]]. This weight matrix is automatically transposed to create the reverse j to i connection. ‘creator’ is a function that accepts a single boolean arguement; when true, it returns a string identifier for the weight kernel between spins i and j. If false, it returns the actual weight kernel. This is designed to balance ease of use and efficiency: if the same weight kernel is used between many pairs of Potts spins, the weight kernel will only be generated once (which may not be trivial depending on how it is generated), but the user does not need to keep track of how many times a given weight kernel was used.

Parameters:

  • creator – A lambda function that takes a single boolean arguement.

  • i (str, int) – Name/Index of first spin.

  • j (str, int) – Name/Index of second spin.

  • weight (float) – Scales the entire weight kernel for this connection only.

Returns:

None

Compile()

After all of the connections in a model have been added via AddKernel, the weight kernels are assembled into Numpy arrays with specific formats, tailored for use in the C++/CUDA sampling code. The results are stored in the Task object.

The weight kernels are stored in a dense format in a 3-D Numpy array. The first dimension is the kernel index, while the second and third dimensions correspond to the magnetization states of the connected spins.

A second 3-D NUmpy array, the kernel map, specifies which kernel connects any given pair of spins. It is stored in a sparse format.

Returns:

None

EnergyBands()

Calculates the energy of every possible state. Since the number of states grows eponentially, this can only be used with very small problem instances, and has been used just for illustrative purposes.

Return valid_energies:

A list of energies that correspond to valid model states. Validity is defined by child classes.

Return invalid_energies:

A list of energies that correspond to invalid model states.

EvalCost(state)

Python-domain calculation of the energy of a state, based on compiled kernels and sparse kernel map.

Parameters:

state (1-D numpy array of ints, or a dict where keys are spin names and values are the spin states.) – Magnetization values for each of the spins in the model.

Returns:

Energy/Cost of the model when in the given state.

Return type:

float

EvalDDE(i, m_old, m_new)

Calculates the delta-delta-energy of all possible magnetizations of all spins. DDE is how much the DE of each action changes, when an action is taken.

Parameters:

  • i (int) – Index of changing spin that creates the DDE.

  • m_old (int) – new value of spin i

  • m_new (int) – new value of spin i

Returns:

DDE value for the all magnetizations of all spins.

Return type:

2-D Numpy float array, N_{spins}X N_{magnetizations}

EvalDE(state, i, m_new)

Calculates how much the total energy would change if spin i had magnetization m_new.

Parameters:

  • state (1-D numpy array of ints.) – Magnetization values for each of the spins in the model.

  • i (int) – Spin index of interest.

  • m_new (int) – new value of spin i

Returns:

Change in energy if spin i had magnetization m_new.

Return type:

float

EvalPE(state, i, m)

Calculates the potential energy of state m of node i, given state.

Parameters:

  • state (1-D numpy array of ints.) – Magnetization values for each of the spins in the model.

  • i (int) – Spin index of interest.

  • m (int) – value of spin i

Returns:

The energy that would potentially be added to the total if spin i was in state m.

Return type:

float

GetSpinBias(spin)

Returns a numpy vector of the biases acting on the spin.

GetSpinFromState(spin, state)

Given a spin identifier, extract that spin’s value from a densely stored state.

IndexOf(spin)

Converts from a Spin name used during model construction to the corresponding spin index used for computation.

Parameters:

spin – Spin name used during model construction.

Returns:

Spin index in a model state.

Return type:

int

InitKernelManager()

(Re)Initializes the kernel manager system, which is used for building up weight matrices piece by piece, by initializing a few empty variables.

Returns:

None

ListSpins()

Returns a list of spin names/identifiers currently in the model.

PinSpin(spin, values, weight=100)

Restrict a spin to a subset of its possible states.

For example, model.PinSpin(“A”, [2,3]) will force spin “A” to be in state 2 or 3.

Parameters:

  • spin – Name or index of the spin to add to.

  • values (list(int)) – Spin indexes to keep. All others will be excluded.

  • weight – optional, the magntude of the bias used to pin the spin.

Returns:

None

SetBias(spin, bias)

Modify the bias vector on the given spin, by setting it to a new value.

Parameters:

  • spin – Name or index of the spin to add to.

  • bias – Numpy array of bias values (one bias for each of the spin’s possible states).

Returns:

None

SetSpinInState(spin, state, value)

Given a spin identifier, set that spin’s value in a densely stored state.

SpinSize(spin)

Returns the number of states that the given spin can have.

TotalWeight(spin_i, spin_j)

Returns a numpy array of the weight values between spin i and spin j. If there are multiple kernels, they will be added together.

__init__()