Merge pull request #532 from JoelPasvolsky/virtualgraph_deprecation

Deprecate `VirtualGraphComposite`

dwave/system/composites/virtual_graph.py

@@ -13,6 +13,11 @@
 #    limitations under the License.
 
 """
+Deprecated. 
+Virtual graphs are deprecated due to improved calibration of newer QPUs; to 
+calibrate chains for residual biases, follow the instructions in the 
+`shimming tutorial <https://github.com/dwavesystems/shimming-tutorial>`_.
+
 A :std:doc:`dimod composite <oceandocs:docs_dimod/reference/samplers>` that 
 uses the D-Wave virtual graph feature for improved 
 :std:doc:`minor-embedding <oceandocs:docs_system/intro>`.
@@ -27,19 +32,26 @@
 for explanations of technical terms in descriptions of Ocean tools.
 """
 
+import warnings
+
 import dimod
 
 from dwave.system.composites.embedding import FixedEmbeddingComposite
 from dwave.system.flux_bias_offsets import get_flux_biases
 
-
 FLUX_BIAS_KWARG = 'flux_biases'
 
 __all__ = ['VirtualGraphComposite']
 
 
 class VirtualGraphComposite(FixedEmbeddingComposite):
-    """Composite to use the D-Wave virtual graph feature for minor-embedding.
+    """Deprecated. Composite to use the D-Wave virtual graph feature for minor-embedding.
+
+    .. deprecated:: 1.25.0
+        This class is deprecated due to improved calibration of newer QPUs and
+        will be removed in 1.27.0; to calibrate chains for residual biases, 
+        follow the instructions in the 
+        `shimming tutorial <https://github.com/dwavesystems/shimming-tutorial>`_.
 
     Calibrates qubits in chains to compensate for the effects of biases and enables easy
     creation, optimization, use, and reuse of an embedding for a given working graph.
@@ -127,6 +139,13 @@ def __init__(self, sampler, embedding,
                  flux_bias_max_age=3600):
 
         super(VirtualGraphComposite, self).__init__(sampler, embedding)
+        warnings.warn(
+                "'VirtualGraphComposite' is deprecated due to improved calibration "
+                "of newer QPUs and in future will raise an exception; if needed, "
+                "follow the instructions in the shimming tutorial at "
+                "https://github.com/dwavesystems/shimming-tutorial instead. ",
+                DeprecationWarning, stacklevel=2
+            )
         self.parameters.update(apply_flux_bias_offsets=[])
 
         # Validate the chain strength, or obtain it from J-range if chain strength is not provided.

tests/test_virtual_graph_composite.py

@@ -28,7 +28,8 @@ def setUp(self):
 
     def test_smoke(self):
         child_sampler = MockDWaveSampler()
-        sampler = VirtualGraphComposite(child_sampler, {'a': [0]}, flux_bias_num_reads=1)
+        with self.assertWarns(DeprecationWarning):
+            sampler = VirtualGraphComposite(child_sampler, {'a': [0]}, flux_bias_num_reads=1)
 
         # depending on how recenlty flux bias data was gathered, this may be true
         child_sampler.flux_biases_flag = False
@@ -38,21 +39,23 @@ def test_smoke(self):
             self.assertTrue(child_sampler.flux_biases_flag)  # true when some have been provided to sample_ising
 
     def test_structure_keyword_setting(self):
-        sampler = VirtualGraphComposite(self.sampler, embedding={'a': set(range(8)),
-                                                                 'b': set(range(8, 16)),
-                                                                 'c': set(range(16, 24))},
-                                        flux_biases=False)
+        with self.assertWarns(DeprecationWarning):
+            sampler = VirtualGraphComposite(self.sampler, embedding={'a': set(range(8)),
+                                                                     'b': set(range(8, 16)),
+                                                                     'c': set(range(16, 24))},
+                                            flux_biases=False)
 
         nodelist, edgelist, adj = sampler.structure
         self.assertEqual(nodelist, ['a', 'b', 'c'])
         self.assertEqual(edgelist, [('a', 'b'), ('b', 'c')])
         self.assertEqual(adj, {'a': {'b'}, 'b': {'a', 'c'}, 'c': {'b'}})
 
         # unlike variable names
-        sampler = VirtualGraphComposite(self.sampler, embedding={'a': set(range(8)),
-                                                                 1: set(range(8, 16)),
-                                                                 'c': set(range(16, 24))},
-                                        flux_biases=False)
+        with self.assertWarns(DeprecationWarning):
+            sampler = VirtualGraphComposite(self.sampler, embedding={'a': set(range(8)),
+                                                                     1: set(range(8, 16)),
+                                                                     'c': set(range(16, 24))},
+                                            flux_biases=False)
         nodelist, edgelist, adj = sampler.structure
         self.assertEqual(set(nodelist), {'a', 1, 'c'})
         self.assertEqual(adj, {'a': {1}, 1: {'a', 'c'}, 'c': {1}})
@@ -75,18 +78,20 @@ def test_embedding_parameter(self):
         __, __, adj = sampler.structure
         embedding = {v: (v,) for v in adj}
 
-        sampler = VirtualGraphComposite(sampler, embedding=embedding, flux_biases=False)
+        with self.assertWarns(DeprecationWarning):
+            sampler = VirtualGraphComposite(sampler, embedding=embedding, flux_biases=False)
 
         self.assertEqual(sampler.embedding, embedding)
 
     def test_simple_complete_graph_sample_ising(self):
         """sample_ising on a K4."""
 
-        K4 = VirtualGraphComposite(self.sampler, embedding={0: {0, 4},
-                                                            1: {1, 5},
-                                                            2: {2, 6},
-                                                            3: {3, 7}},
-                                   flux_biases=False)
+        with self.assertWarns(DeprecationWarning):
+            K4 = VirtualGraphComposite(self.sampler, embedding={0: {0, 4},
+                                                                1: {1, 5},
+                                                                2: {2, 6},
+                                                                3: {3, 7}},
+                                       flux_biases=False)
 
         K4.sample_ising({0: .1, 1: .2}, {(0, 1): 1.5})