restrain deprecation

Author: cadenmyers13

docs/examples/crystalpdftwophase.py

@@ -123,18 +123,18 @@ def makeRecipe(niciffile, siciffile, datname):
     # derived has no uncertainty. Thus, we will tell the recipe to scale the
     # residual, which means that it will be weighted as much as the average
     # data point during the fit.
-    recipe.restrain("a_ni", lb=3.527, ub=3.527, scaled=True)
+    recipe.add_restraint("a_ni", lb=3.527, ub=3.527, scaled=True)
     # Now we do the same with the delta2 and Biso parameters (remember that
     # Biso = 8*pi**2*Uiso)
-    recipe.restrain("delta2_ni", lb=2.22, ub=2.22, scaled=True)
-    recipe.restrain("Biso_0_ni", lb=0.454, ub=0.454, scaled=True)
+    recipe.add_restraint("delta2_ni", lb=2.22, ub=2.22, scaled=True)
+    recipe.add_restraint("Biso_0_ni", lb=0.454, ub=0.454, scaled=True)
     #
     # We can do the same with the silicon values. We haven't done a thorough
     # job of measuring the uncertainties in the results, so we'll scale these
     # as well.
-    recipe.restrain("a_si", lb=5.430, ub=5.430, scaled=True)
-    recipe.restrain("delta2_si", lb=3.54, ub=3.54, scaled=True)
-    recipe.restrain("Biso_0_si", lb=0.645, ub=0.645, scaled=True)
+    recipe.add_restraint("a_si", lb=5.430, ub=5.430, scaled=True)
+    recipe.add_restraint("delta2_si", lb=3.54, ub=3.54, scaled=True)
+    recipe.add_restraint("Biso_0_si", lb=0.645, ub=0.645, scaled=True)
 
     # Give the recipe away so it can be used!
     return recipe

docs/examples/debyemodel.py

@@ -152,7 +152,7 @@ def makeRecipe():
     # breaking the restraint by the point-average chi^2 value so that the
     # restraint is roughly as significant as any other data point throughout
     # the fit.
-    recipe.restrain(recipe.offset, lb=0, scaled=True)
+    recipe.add_restraint(recipe.offset, lb=0, scaled=True)
 
     # We're done setting up the recipe. We can now do other things with it.
     return recipe

docs/examples/simplepdftwophase.py

@@ -82,18 +82,18 @@ def makeRecipe(niciffile, siciffile, datname):
     # derived has no uncertainty. Thus, we will tell the recipe to scale the
     # residual, which means that it will be weighted as much as the average
     # data point during the fit.
-    recipe.restrain("a_ni", lb=3.527, ub=3.527, scaled=True)
+    recipe.add_restraint("a_ni", lb=3.527, ub=3.527, scaled=True)
     # Now we do the same with the delta2 and Biso parameters (remember that
     # Biso = 8*pi**2*Uiso)
-    recipe.restrain("delta2_ni", lb=2.22, ub=2.22, scaled=True)
-    recipe.restrain("Biso_0_ni", lb=0.454, ub=0.454, scaled=True)
+    recipe.add_restraint("delta2_ni", lb=2.22, ub=2.22, scaled=True)
+    recipe.add_restraint("Biso_0_ni", lb=0.454, ub=0.454, scaled=True)
     #
     # We can do the same with the silicon values. We haven't done a thorough
     # job of measuring the uncertainties in the results, so we'll scale these
     # as well.
-    recipe.restrain("a_si", lb=5.430, ub=5.430, scaled=True)
-    recipe.restrain("delta2_si", lb=3.54, ub=3.54, scaled=True)
-    recipe.restrain("Biso_0_si", lb=0.645, ub=0.645, scaled=True)
+    recipe.add_restraint("a_si", lb=5.430, ub=5.430, scaled=True)
+    recipe.add_restraint("delta2_si", lb=3.54, ub=3.54, scaled=True)
+    recipe.add_restraint("Biso_0_si", lb=0.645, ub=0.645, scaled=True)
 
     # Give the recipe away so it can be used!
     return recipe

src/diffpy/srfit/fitbase/fitrecipe.py

@@ -1756,7 +1756,7 @@ def convert_bounds_to_restraints(self, sig=1, scaled=False):
         if not hasattr(sig, "__iter__"):
             sig = [sig] * len(pars)
         for par, x in zip(pars, sig):
-            self.restrain(
+            self.add_restraint(
                 par, par.bounds[0], par.bounds[1], sig=x, scaled=scaled
             )
         return

src/diffpy/srfit/fitbase/recipeorganizer.py

@@ -139,6 +139,13 @@
     removal_version,
 )
 
+restrain_deprecation_msg = build_deprecation_message(
+    recipeorganizer_base,
+    "restrain",
+    "add_restraint",
+    removal_version,
+)
+
 
 class RecipeContainer(Observable, Configurable, Validatable):
     """Base class for organizing pieces of a FitRecipe.
@@ -1122,7 +1129,7 @@ def clearConstraints(self, recurse=False):
         """
         return self.clear_all_constraints(recurse=recurse)
 
-    def restrain(
+    def add_restraint(
         self, param_or_eq, lb=-inf, ub=inf, sig=1, scaled=False, params={}
     ):
         """Restrain an expression to specified bounds.
@@ -1184,6 +1191,21 @@ def restrain(
         self.register_restraint(param_or_eq)
         return param_or_eq
 
+    @deprecated(restrain_deprecation_msg)
+    def restrain(
+        self, param_or_eq, lb=-inf, ub=inf, sig=1, scaled=False, params={}
+    ):
+        """This function has been deprecated and will be removed in
+        version 4.0.0.
+
+        Please use
+        diffpy.srfit.fitbase.recipeorganizer.RecipeOrganizer.add_restraint
+        instead.
+        """
+        return self.add_restraint(
+            param_or_eq, lb=lb, ub=ub, sig=sig, scaled=scaled, params=params
+        )
+
     def register_restraint(self, res):
         """Add a Restraint instance to the RecipeOrganizer.
 

tests/conftest.py

@@ -218,8 +218,8 @@ def build_recipe_two_contributions():
     recipe.constrain_parameter(contribution2.m, "2*k")
     recipe.constrain_parameter(contribution2.d, contribution1.c)
     recipe.constrain_parameter(contribution2.B, "0.5*A")
-    recipe.restrain(contribution1.A, 0.5, 1.5)
-    recipe.restrain(contribution1.k, 0.8, 1.2)
+    recipe.add_restraint(contribution1.A, 0.5, 1.5)
+    recipe.add_restraint(contribution1.k, 0.8, 1.2)
 
     return recipe
 

tests/test_fitrecipe.py

@@ -232,7 +232,7 @@ def testResidual(self):
 
         # Now try some restraints. We want c to be exactly zero. It should give
         # a penalty of (c-0)**2, which is 4 in this case
-        r1 = self.recipe.restrain(self.fitcontribution.c, 0, 0, 1)
+        r1 = self.recipe.add_restraint(self.fitcontribution.c, 0, 0, 1)
         self.recipe._ready = False
         res = self.recipe.residual()
         chi2 = 4 + dot(y - self.profile.y, y - self.profile.y)
@@ -263,7 +263,9 @@ def testResidual(self):
         self.assertTrue(array_equal(y - self.profile.y, res))
 
         # Add a restraint at the fitcontribution level.
-        r1 = self.fitcontribution.restrain(self.fitcontribution.c, 0, 0, 1)
+        r1 = self.fitcontribution.add_restraint(
+            self.fitcontribution.c, 0, 0, 1
+        )
         self.recipe._ready = False
         # The chi2 is the same as above, plus 4
         res = self.recipe.residual()
@@ -361,7 +363,7 @@ def testPrintFitHook(capturestdout):
     recipe.addContribution(fitcontribution)
 
     recipe.add_variable(fitcontribution.c)
-    recipe.restrain("c", lb=5)
+    recipe.add_restraint("c", lb=5)
     (pfh,) = recipe.getFitHooks()
     out = capturestdout(recipe.scalar_residual)
     assert "" == out
@@ -437,7 +439,7 @@ def test_add_contribution(capturestdout):
     recipe.add_contribution(fitcontribution)
 
     recipe.add_variable(fitcontribution.c)
-    recipe.restrain("c", lb=5)
+    recipe.add_restraint("c", lb=5)
     (pfh,) = recipe.get_fit_hooks()
     out = capturestdout(recipe.scalar_residual)
     assert "" == out

tests/test_recipeorganizer.py

@@ -328,7 +328,7 @@ def test_constrain_parameter(self):
 
         return
 
-    def testRestrain(self):
+    def test_add_restraint(self):
         """Test the restrain method."""
 
         p1 = Parameter("p1", 1)
@@ -338,7 +338,7 @@ def testRestrain(self):
         self.m._eqfactory.registerArgument("p2", p2)
 
         self.assertEqual(0, len(self.m._restraints))
-        r = self.m.restrain("p1+p2", ub=10)
+        r = self.m.add_restraint("p1+p2", ub=10)
         self.assertEqual(1, len(self.m._restraints))
         p2.set_value(10)
         self.assertEqual(1, r.penalty())
@@ -402,8 +402,8 @@ def testGetRestraints(self):
         m2._add_parameter(p3)
         m2._add_parameter(p4)
 
-        r1 = self.m.restrain("p1 + p2")
-        r2 = m2.restrain("2*p3 + p4")
+        r1 = self.m.add_restraint("p1 + p2")
+        r2 = m2.add_restraint("2*p3 + p4")
 
         res = self.m._get_restraints()
         self.assertTrue(r1 in res)
@@ -632,7 +632,7 @@ def capture_show(*args, **kwargs):
     assert "Parameters" in lines2
     assert "Constraints" in lines2
     assert "Restraints" not in lines2
-    organizer.restrain("z", lb=2, ub=3, sig=0.001)
+    organizer.add_restraint("z", lb=2, ub=3, sig=0.001)
     out3 = capture_show()
     lines3 = out3.strip().split("\n")
     assert 13 == len(lines3)