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. Seedimod.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
, aint
, or as a sequence of variable labels.If given as a sequence of labels, the structure will be fullyconnected, with the variables labelled according to the sequence.
If given as an int, the structure will be fullyconnected 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 2tuple 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 bruteforce 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#
Close the database connection. 

Insert a binary quadratic model into the database. 


Insert a graph into the database. 

Insert a penalty model into the database. 

Insert a sample set into the database. 
Iterate over all of the binary quadratic models in the database. 

Iterate over all of the graphs in the database. 

Iterate over all of the penalty models in the database. 

Iterate over all of the sample sets in the database. 


Retrieve a penalty model from the database. 
Exceptions#
PenaltyModel is impossible to build. 

PenaltyModel is missing from the cache or otherwise unavailable. 
Utilities#

Create a NetworkX graph from a graphlike. 