API Reference#

Deprecated since version 1.3.0: penaltymodel is deprecated and will be removed in Ocean 10. For solving problems with constraints, we recommend using the hybrid solvers in the Leap service.

This package implements the generation and caching of penalty models. The main function for penalty models is get_penalty_model(). In addition, the package provides some more-advanced interfaces.

Function#

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]

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.