Included Classes¶
PenaltyModel¶

class
PenaltyModel
(graph, decision_variables, feasible_configurations, vartype, model, classical_gap, ground_energy, ising_linear_ranges=None, ising_quadratic_ranges=None)[source]¶ Container class for the components that make up a penalty model.
A penalty model is a small Ising problem or QUBO that has ground states that match the feasible configurations and excited states that have a classical energy greater than the ground energy by at least the classical gap.
PenaltyModel is a subclass of
Specification
. Parameters
graph (
networkx.Graph
/iterable[edge]) – 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. If given as an iterable of edges, the graph will be constructed by adding each edge to an (initially) empty graph.decision_variables (iterable) – The labels of the penalty model’s decision variables. Each variable label in decision_variables must correspond to a node in graph. Should be an ordered iterable of hashable labels.
feasible_configurations (dict[tuple[int], number]/iterable[tuple[int]]) – The set of feasible configurations. Defines the allowed configurations of the decision variables allowed by the constraint. Each feasible configuration should be a tuple, each element of which must be of a value matching vartype. If given as a dict, the key is the feasible configuration and the value is the desired relative energy. If given as an iterable, it will be case to a dict where the relative energies are all 0.
vartype (
Vartype
/str/set) – The variable type desired for the penalty model. Accepted input values:Vartype.SPIN
,'SPIN'
,{1, 1}
Vartype.BINARY
,'BINARY'
,{0, 1}
model (
dimod.BinaryQuadraticModel
) – A binary quadratic model that has ground states that match the feasible_configurations.classical_gap (numeric) – The difference in classical energy between the ground state and the first excited state. Must be positive.
ground_energy (numeric) – The minimum energy of all possible configurations.
ising_linear_ranges (dict[node, [number, number]], optional, default=None) – When the penalty model is spinvalued, specifies the allowed range for each of the linear biases. If a dict, should be of the form {v: [min, max], …} where v is a variable in the desired penalty model and (min, max) defines the acceptable range for the linear bias associated with v. If None, the default will be set to {v: [1, 1], …} for each v in graph. A partial assignment is allowed.
ising_quadratic_ranges (dict[node, dict[node, [number, number]], optional, default=None) – When the penalty model is spinvalued, specifies the allowed range for each of the quadratic biases. If a dict, should be of the form {v: {u: [min, max], …}, …} where u and v are variables in the desired penalty model and u, v have an interaction  there is an edge between nodes u, v in graph. (min, max) the acceptable range for the quadratic bias associated with u, v. If None, the default will be set to {v: {u: [min, max], …}, u: {v: [min, max], …}, …} for each edge u, v in graph. A partial assignment is allowed.
Examples
The penalty model can be created from its component parts:
>>> import networkx as nx >>> import dimod >>> graph = nx.path_graph(3) >>> decision_variables = (0, 2) # the ends of the path >>> feasible_configurations = {(1, 1), (1, 1)} # we want the ends of the path to agree >>> model = dimod.BinaryQuadraticModel({0: 0, 1: 0, 2: 0}, {(0, 1): 1, (1, 2): 1}, 0.0, dimod.SPIN) >>> classical_gap = 2.0 >>> ground_energy = 2.0 >>> widget = pm.PenaltyModel(graph, decision_variables, feasible_configurations, dimod.SPIN, ... model, classical_gap, ground_energy)
Or it can be created from a specification:
>>> spec = pm.Specification(graph, decision_variables, feasible_configurations, dimod.SPIN) >>> widget = pm.PenaltyModel.from_specification(spec, model, classical_gap, ground_energy)

classical_gap
¶ The difference in classical energy between the ground state and the first excited state. Must be positive.
 Type
numeric

feasible_configurations
¶ The set of feasible configurations. The value is the (relative) energy of each of the feasible configurations.

graph
¶ The graph that defines the relation between variables in the penaltymodel. The node labels will be used as the variable labels in the binary quadratic model.
 Type

ground_energy
¶ The minimum energy of all possible configurations.
 Type
numeric

ising_linear_ranges
¶ Defines the energy ranges available for the linear biases of the penalty model.
 Type
dict[node, (number, number)]

model
¶ A binary quadratic model that has ground states that match the feasible_configurations.

ising_quadratic_ranges
¶ Defines the energy ranges available for the quadratic biases of the penalty model.
 Type
dict[edge, (number, number)]

vartype
¶ The variable type.
 Type

classmethod
from_specification
(specification, model, classical_gap, ground_energy)[source]¶ Construct a PenaltyModel from a Specification.
 Parameters
specification (
Specification
) – A specification that was used to generate the model.model (
dimod.BinaryQuadraticModel
) – A binary quadratic model that has ground states that match the feasible_configurations.classical_gap (numeric) – The difference in classical energy between the ground state and the first excited state. Must be positive.
ground_energy (numeric) – The minimum energy of all possible configurations.
 Returns

relabel_variables
(mapping, inplace=True)[source]¶ Relabel the variables and nodes according to the given mapping.
 Parameters
 Returns
A PenaltyModel with the variables relabeled according to mapping.
 Return type
Examples
>>> spec = pm.Specification(nx.path_graph(3), (0, 2), {(1, 1), (1, 1)}, dimod.SPIN) >>> model = dimod.BinaryQuadraticModel({0: 0, 1: 0, 2: 0}, {(0, 1): 1, (1, 2): 1}, 0.0, dimod.SPIN) >>> penalty_model = pm.PenaltyModel.from_specification(spec, model, 2., 2.) >>> relabeled_penalty_model = penalty_model.relabel_variables({0: 'a'}, inplace=False) >>> relabeled_penalty_model.decision_variables ('a', 2)
>>> spec = pm.Specification(nx.path_graph(3), (0, 2), {(1, 1), (1, 1)}, dimod.SPIN) >>> model = dimod.BinaryQuadraticModel({0: 0, 1: 0, 2: 0}, {(0, 1): 1, (1, 2): 1}, 0.0, dimod.SPIN) >>> penalty_model = pm.PenaltyModel.from_specification(spec, model, 2., 2.) >>> __ = penalty_model.relabel_variables({0: 'a'}, inplace=True) >>> penalty_model.decision_variables ('a', 2)
Specification¶

class
Specification
(graph, decision_variables, feasible_configurations, vartype, ising_linear_ranges=None, ising_quadratic_ranges=None, min_classical_gap=2)[source]¶ Specification for a PenaltyModel.
See
PenaltyModel
documentation for a fuller description of the different components. A specification can be thought of as an incomplete penalty model. Parameters
graph (
networkx.Graph
/iterable[edge]) – 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. If given as an iterable of edges, the graph will be constructed by adding each edge to an (initially) empty graph.decision_variables (iterable) – The labels of the penalty model’s decision variables. Each variable label in decision_variables must correspond to a node in graph. Should be an ordered iterable of hashable labels.
feasible_configurations (dict[tuple[int], number]/iterable[tuple[int]]) – The set of feasible configurations. Defines the allowed configurations of the decision variables allowed by the constraint. Each feasible configuration should be a tuple, each element of which must be of a value matching vartype. If given as a dict, the key is the feasible configuration and the value is the desired relative energy. If given as an iterable, it will be case to a dict where the relative energies are all 0.
vartype (
dimod.Vartype
/str/set) – The variable type desired for the penalty model. Accepted input values:Vartype.SPIN
,'SPIN'
,{1, 1}
Vartype.BINARY
,'BINARY'
,{0, 1}
ising_linear_ranges (dict[node, [number, number]], optional, default=None) – When the penalty model is spinvalued, specifies the allowed range for each of the linear biases. If a dict, should be of the form {v: [min, max], …} where v is a variable in the desired penalty model and (min, max) defines the acceptable range for the linear bias associated with v. If None, the default will be set to {v: [1, 1], …} for each v in graph. A partial assignment is allowed.
ising_quadratic_ranges (dict[node, dict[node, [number, number]], optional, default=None) – When the penalty model is spinvalued, specifies the allowed range for each of the quadratic biases. If a dict, should be of the form {v: {u: [min, max], …}, …} where u and v are variables in the desired penalty model and u, v have an interaction  there is an edge between nodes u, v in graph. (min, max) the acceptable range for the quadratic bias associated with u, v. If None, the default will be set to {v: {u: [min, max], …}, u: {v: [min, max], …}, …} for each edge u, v in graph. A partial assignment is allowed.
Examples
>>> import networkx as nx >>> import dimod >>> graph = nx.path_graph(5) >>> decision_variables = (0, 4) # the ends of the path >>> feasible_configurations = {(1, 1), (1, 1)} # we want the ends of the path to agree >>> vartype = dimod.Vartype.SPIN >>> spec = pm.Specification(graph, decision_variables, feasible_configurations, vartype)
If we want to make the interaction between (0, 1) ferromagnetic (negative):
>>> ising_quadratic_ranges = {0: {1: (1, 0)}} >>> spec = pm.Specification(graph, decision_variables, feasible_configurations, vartype)

decision_variables
¶ The labels of the penalty model’s decision variables. Each variable label in decision_variables must correspond to a node in graph.
 Type

feasible_configurations
¶ The set of feasible configurations. Defines the allowed configurations of the decision variables allowed by the constraint. The key is the allowed configuration, the value is the relative energy of each configuration.

graph
¶ 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.
 Type

ising_linear_ranges
¶ When the penalty model is spinvalued, specifies the allowed range for each of the linear biases. A dict of the form {v: [min, max], …} where v is a variable in the desired penalty model and [min, max] defines the acceptable range for the linear bias associated with v.
 Type
dict[node, [number, number], optional, default=None

ising_quadratic_ranges
¶ When the penalty model is spinvalued, specifies the allowed range for each of the quadratic biases. A dict of the form {v: {u: [min, max], …}, u: {v: [min, max], …}, …} where u and v are variables in the desired penalty model and u, v have an interaction  there is an edge between nodes u, v in graph.

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. Default value is 2.
 Type