Reference Documentation#

This package implements the generation and caching of penalty models.

The main function for penalty models is:

get_penalty_model(samples_like, graph_like: int | Sequence[int] | Graph | None = None, *, linear_bound: Tuple[float, float] = (-2, 2), quadratic_bound: Tuple[float, float] = (-1, 1), min_classical_gap: float = 2, use_cache: bool = True) → Tuple[BinaryQuadraticModel, float][source]#

Get a penalty model for a specific graph and set of target states.

Parameters:

  • samples_like –

    The set of feasible states that form the ground states of the generated binary quadratic model.

    samples_like is an extension of NumPy’s array_like. See dimod.as_samples().

  • graph_like –

    Defines the structure of the desired binary quadratic model. Each node in the graph represents a variable and each edge defines an interaction between two variables. Can be given as a networkx.Graph, a int, or as a sequence of variable labels.

    If given as a sequence of labels, the structure will be fully-connected, with the variables labelled according to the sequence.

    If given as an int, the structure will be fully-connected with the variables labelled range(n).

    The nodes of the graph must be a superset of the labels of samples_like.

    If not provided, defaults to a fully connected graph with nodes that are the variables of samples_like.

  • linear_bound – The range allowed for the linear biases of the binary quadratic model.

  • quadratic_bound – The range allowed for the quadratic biases of the binary quadratic model.

  • min_classical_gap – This is a threshold value for the classical gap. It describes the minimum energy gap between the highest feasible state and the lowest infeasible state.

  • use_cache – Whether to attempt to retrieve models from the cache. If False, a new model will always be generated.

Returns:

A 2-tuple of the binary quadratic model and the classical gap. Note that the binary quadratic model always has vartype 'SPIN'.

Raises:

ImpossiblePenaltyModel – If it is not possible to construct a penalty model for the given structure and feasible states.

Examples

>>> import dimod
>>> import penaltymodel

This example generates a penalty model for an AND gate.

>>> bqm, gap = penaltymodel.get_penalty_model([[0, 0, 0],
...                                            [0, 1, 0],
...                                            [1, 0, 0],
...                                            [1, 1, 1]])

We can then solve the generated binary quadratic model using a brute-force solver to confirm that we have the expected ground states.

>>> print(dimod.ExactSolver().sample(bqm))
   0  1  2 energy num_oc.
0 -1 -1 -1    0.0       1
1 +1 -1 -1    0.0       1
3 -1 +1 -1    0.0       1
5 +1 +1 +1    0.0       1
2 +1 +1 -1    2.0       1
4 -1 +1 +1    2.0       1
6 +1 -1 +1    2.0       1
7 -1 -1 +1    6.0       1
['SPIN', 8 rows, 8 samples, 3 variables]

In addition to get_penalty_model(), there are some more advanced interfaces available.

Cache#

class PenaltyModelCache(database: str | PathLike | None = None)[source]#

Manage a database of penalty models.

Penalty models are stored in an sqlite3 database.

This class can be used as a context manager to automatically close the database connection on exit.

Parameters:

database – The path to the database the user wishes to connect to. The default path will depend on the operating system, certain environmental variables and whether it is being run inside a virtual environment. See homebase. If the special database name ‘:memory:’ is given, then a temporary database is created in memory.

Methods#

PenaltyModelCache.close()

Close the database connection.

PenaltyModelCache.insert_binary_quadratic_model(bqm)

Insert a binary quadratic model into the database.

PenaltyModelCache.insert_graph(graph_like)

Insert a graph into the database.

PenaltyModelCache.insert_penalty_model(bqm, ...)

Insert a penalty model into the database.

PenaltyModelCache.insert_sampleset(samples_like)

Insert a sample set into the database.

PenaltyModelCache.iter_binary_quadratic_models()

Iterate over all of the binary quadratic models in the database.

PenaltyModelCache.iter_graphs()

Iterate over all of the graphs in the database.

PenaltyModelCache.iter_penalty_models()

Iterate over all of the penalty models in the database.

PenaltyModelCache.iter_samplesets()

Iterate over all of the sample sets in the database.

PenaltyModelCache.retrieve(samples_like, ...)

Retrieve a penalty model from the database.

Exceptions#

ImpossiblePenaltyModel

PenaltyModel is impossible to build.

MissingPenaltyModel

PenaltyModel is missing from the cache or otherwise unavailable.

Utilities#

as_graph(graph_like)

Create a NetworkX graph from a graph-like.