Move in more preprocessing composites

README.rst

@@ -32,9 +32,8 @@ solving binary quadratic models (BQM).
 
     import dwave.preprocessing
 
-Currently, this package contains an implementation of roof duality, an algorithm 
-used for finding minimizing assignments of a polynomial's variables. For details 
-on the algorithm and how to use it, see the package's 
+Currently, this package contains several preprocessing composites. For details on
+underlying algorithms and usage, see the package's 
 `Reference Documentation <https://docs.ocean.dwavesys.com/en/stable/docs_preprocessing/reference/index.html>`_.
 
 .. index-end-marker

docs/reference/composites.rst

@@ -0,0 +1,164 @@
+.. _preprocessing_composites:
+
+==========
+Composites
+==========
+
+The `dwave-preprocessing` package includes several composites:
+
+.. automodule:: dwave.preprocessing.composites
+
+....
+
+Connected Components Composite
+------------------------------
+
+Class
+~~~~~
+
+.. autoclass:: ConnectedComponentsComposite
+
+Properties
+~~~~~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   ~ConnectedComponentsComposite.child
+   ~ConnectedComponentsComposite.children
+   ~ConnectedComponentsComposite.parameters
+   ~ConnectedComponentsComposite.properties
+
+Methods
+~~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   ~ConnectedComponentsComposite.sample
+   ~ConnectedComponentsComposite.sample_ising
+   ~ConnectedComponentsComposite.sample_qubo
+
+....
+
+Clip Composite
+--------------
+
+Class
+~~~~~
+
+.. autoclass:: ClipComposite
+
+Properties
+~~~~~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   ~ClipComposite.child
+   ~ClipComposite.children
+   ~ClipComposite.parameters
+   ~ClipComposite.properties
+
+Methods
+~~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   ~ClipComposite.sample
+   ~ClipComposite.sample_ising
+   ~ClipComposite.sample_qubo
+
+....
+
+Fix Variables Composite
+------------------------
+
+Class
+~~~~~
+
+.. autoclass:: FixVariablesComposite
+
+Properties
+~~~~~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   ~FixVariablesComposite.child
+   ~FixVariablesComposite.children
+   ~FixVariablesComposite.parameters
+   ~FixVariablesComposite.properties
+
+Methods
+~~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   ~FixVariablesComposite.sample
+   ~FixVariablesComposite.sample_ising
+   ~FixVariablesComposite.sample_qubo
+
+....
+
+Scale Composite
+---------------
+
+Class
+~~~~~
+
+.. autoclass:: ScaleComposite
+
+Properties
+~~~~~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   ~ScaleComposite.child
+   ~ScaleComposite.children
+   ~ScaleComposite.parameters
+   ~ScaleComposite.properties
+
+Methods
+~~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   ~ScaleComposite.sample
+   ~ScaleComposite.sample_ising
+   ~ScaleComposite.sample_qubo
+
+....
+
+Spin Reversal Transform Composite
+---------------------------------
+
+Class
+~~~~~
+
+.. autoclass:: SpinReversalTransformComposite
+
+Properties
+~~~~~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   ~SpinReversalTransformComposite.child
+   ~SpinReversalTransformComposite.children
+   ~SpinReversalTransformComposite.parameters
+   ~SpinReversalTransformComposite.properties
+
+Methods
+~~~~~~~
+
+.. autosummary::
+   :toctree: generated/
+
+   ~SpinReversalTransformComposite.sample
+   ~SpinReversalTransformComposite.sample_ising
+   ~SpinReversalTransformComposite.sample_qubo

docs/reference/index.rst

@@ -5,6 +5,7 @@ Reference Documentation
 
 .. toctree::
    :maxdepth: 2
-
-   roof_duality
+
+   composites
+   lower_bounds
    cpp

docs/reference/lower_bounds.rst

@@ -0,0 +1,26 @@
+.. _preprocessing_lower_bounds:
+
+============
+Lower Bounds
+============
+
+A common preprocessing method for binary quadratic models (BQM) is finding the 
+lower bound of their energy. 
+
+Roof Duality
+------------
+
+`dwave-preprocessing` contains an implementation of roof duality, an 
+algorithm used for finding a lower bound for the minimum of a quadratic polynomial,
+as well as minimizing assignments for some of the polynomial's variables; these 
+fixed variables take the same values in all, or some, optimal solutions 
+[#BHT]_ [#BH]_.
+
+.. [#BHT] Boros, E., P.L. Hammer, G. Tavares. Preprocessing of Unconstraint Quadratic Binary Optimization. Rutcor Research Report 10-2006, April, 2006.
+
+.. [#BH] Boros, E., P.L. Hammer. Pseudo-Boolean optimization. Discrete Applied Mathematics 123, (2002), pp. 155-225.
+
+.. autofunction:: dwave.preprocessing.lower_bounds.roof_duality
+
+The roof duality algorithm may also be accessed through the 
+:class:`~dwave.preprocessing.composites.FixVariablesComposite`.

dwave/preprocessing/composites/__init__.py

@@ -0,0 +1,19 @@
+# Copyright 2021 D-Wave Systems Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from dwave.preprocessing.composites.clip import *
+from dwave.preprocessing.composites.connected_components import *
+from dwave.preprocessing.composites.fix_variables import *
+from dwave.preprocessing.composites.scale import *
+from dwave.preprocessing.composites.spin_reversal_transform import *

dwave/preprocessing/composites/clip.py

@@ -0,0 +1,114 @@
+# Copyright 2021 D-Wave Systems Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from dimod.core.composite import ComposedSampler
+from dimod.sampleset import SampleSet
+
+__all__ = ['ClipComposite']
+
+class ClipComposite(ComposedSampler):
+    """Composite to clip variables of a problem.
+
+    Clips the variables of a binary quadratic model (BQM) and modifies linear
+    and quadratic terms accordingly.
+
+    Args:
+       sampler (:class:`dimod.Sampler`):
+            A dimod sampler.
+
+    Examples:
+       This example uses :class:`.ClipComposite` to instantiate a
+       composed sampler that submits a simple Ising problem to a sampler.
+       The composed sampler clips linear and quadratic biases as
+       indicated by options.
+
+       >>> from dimod import ExactSolver
+       >>> from dwave.preprocessing.composites import ClipComposite
+       >>> h = {'a': -4.0, 'b': -4.0}
+       >>> J = {('a', 'b'): 3.2}
+       >>> sampler = ClipComposite(ExactSolver())
+       >>> response = sampler.sample_ising(h, J, lower_bound=-2.0, upper_bound=2.0)
+
+    """
+
+    def __init__(self, child_sampler):
+        self._children = [child_sampler]
+
+    @property
+    def children(self):
+        return self._children
+
+    @property
+    def parameters(self):
+        param = self.child.parameters.copy()
+        param.update({'lower_bound': [], 'upper_bound': []})
+        return param
+
+    @property
+    def properties(self):
+        return {'child_properties': self.child.properties.copy()}
+
+    def sample(self, bqm, *, lower_bound=None, upper_bound=None, **parameters):
+        """Clip and sample from the provided binary quadratic model.
+
+        If lower_bound and upper_bound are given variables with value above or below are clipped.
+
+        Args:
+            bqm (:class:`dimod.BinaryQuadraticModel`):
+                Binary quadratic model to be sampled from.
+
+            lower_bound (number):
+                Value by which to clip the variables from below.
+
+            upper_bound (number):
+                Value by which to clip the variables from above.
+
+            **parameters:
+                Parameters for the sampling method, specified by the child sampler.
+
+        Returns:
+            :class:`dimod.SampleSet`
+
+        """
+        child = self.child
+        bqm_copy = _clip_bqm(bqm, lower_bound, upper_bound)
+        response = child.sample(bqm_copy, **parameters)
+
+        return SampleSet.from_samples_bqm(response, bqm, info=response.info)
+
+
+def _clip_bqm(bqm, lower_bound, upper_bound):
+    """Helper function for clipping a bqm."""
+
+    bqm_copy = bqm.copy()
+    if lower_bound is not None:
+        linear = bqm_copy.linear
+        for k, v in linear.items():
+            if v < lower_bound:
+                linear[k] = lower_bound
+        quadratic = bqm_copy.quadratic
+        for k, v in quadratic.items():
+            if v < lower_bound:
+                quadratic[k] = lower_bound
+
+    if upper_bound is not None:
+        linear = bqm_copy.linear
+        for k, v in linear.items():
+            if v > upper_bound:
+                linear[k] = upper_bound
+        quadratic = bqm_copy.quadratic
+        for k, v in quadratic.items():
+            if v > upper_bound:
+                quadratic[k] = upper_bound
+    return bqm_copy