feat: allow soft bound restraints

Author: ycexiao

src/diffpy/apps/refinebase/refinement_server.py

@@ -489,8 +489,8 @@ async def solve(
             "and the second dict is variable-constraint_equation pair."
         ),
     ] = None,
-    restraints: Annotated[
-        list[str], "List of restraints to apply during the refinement"
+    bounds: Annotated[
+        dict, "Dictionary of bounds for variables or equations"
     ] = None,
     name: Annotated[str, "Name of the refinement session"] = None,
     weights: Annotated[
@@ -519,8 +519,24 @@ async def solve(
     constraints : list[dict], optional
         First dict is new_variable-initial value pair,
         and the second dict is variable-constraint_equation pair.
-    restraints : list[str], optional
-        List of restraints to apply during the refinement.
+    bounds : dict, optional
+        Dictionary of bounds for variables or equations.
+        e.g. {"variable_name":
+        {
+            "lower_bound": 0,
+            "upper_bound": 10,
+            "uncertainty": 1,
+            "scaled": False
+        }}
+        # start copied from diffpy.srfit docstring
+        scaled : bool, optional
+            If True, the restraint penalty is scaled by the unrestrained
+            point-average chi^2 (chi^2/numpoints) (default is False).
+        params : dict, optional
+            The dictionary of Parameters, indexed by name, that are used in
+            `param_or_eq` (if an equation string is used) but are not part
+            of the RecipeOrganizer (default is {}).
+        # end copied from diffpy.srfit docstring
     name : str, optional
         Name of the refinement session.
     weights : list[float], optional
@@ -547,7 +563,7 @@ async def solve(
         variable_names,
         residual_equations=residual_equations,
         constraints=constraints,
-        restraints=restraints,
+        bounds=bounds,
         name=name,
         weights=weights,
         metas=metas,

src/diffpy/apps/refinebase/refinement_session.py

@@ -447,19 +447,19 @@ def _solve(
         models,
         variable_names,
         constraints=None,
-        restraints=None,
+        bounds=None,
         weights=None,
         residual_equations=None,
         metas=None,
-        verbose_iterations=0,
     ):
-        # NOTE: restraints to be implemented
         recipe = FitRecipe()
         self.recipes_dict[name] = recipe
         if weights is None:
             weights = numpy.ones(len(profiles))
         if residual_equations is None:
             residual_equations = ["chiv"] * len(profiles)
+        if bounds is None:
+            bounds = {}
         if metas is not None:
             for i in range(len(metas)):
                 profiles[i].meta.update(metas[i])
@@ -494,7 +494,20 @@ def _solve(
             if var in recipe._parameters.values():
                 continue
             recipe.add_variable(var, name=variable_names[i])
-
+        for eq_or_var_name, arg_dict in bounds.items():
+            lb = arg_dict.get("lower_bound", -numpy.inf)
+            ub = arg_dict.get("upper_bound", numpy.inf)
+            use_soft_bounds = arg_dict.get("use_soft_bounds", True)
+            if use_soft_bounds:
+                uncertainty = arg_dict.get("uncertainty", 1)
+                scaled = arg_dict.get("scaled", False)
+                eq_or_var_name = eq_or_var_name.replace(".", "_")
+                recipe.add_soft_bounds(
+                    eq_or_var_name, lb, ub, sig=uncertainty, scaled=scaled
+                )
+            else:
+                par = self.get_variable(eq_or_var_name)["obj"]
+                par.bound_range(lb, ub)
         recipe.free("all")
         leastsq(recipe.residual, recipe.getValues())
         # NOTE: non-scalar value will raise error in `get_results_string`
@@ -511,12 +524,11 @@ def solve(
         variable_names=[],
         residual_equations=None,
         constraints=None,
-        restraints=None,
+        bounds=None,
         name=uuid.uuid4(),
         weights=None,
         metas=None,
         include_sgpars=False,
-        verbose_iterations=0,
     ):
         profiles = []
         for profile_name in profile_names:
@@ -555,11 +567,10 @@ def solve(
             variable_names=variable_names,
             residual_equations=residual_equations,
             constraints=constraints,
-            restraints=restraints,
+            bounds=bounds,
             name=name,
             weights=weights,
             metas=metas,
-            verbose_iterations=verbose_iterations,
         )
 
     def plot(self):

tests/test_refinement_session.py

@@ -13,6 +13,51 @@
 _DATA_DIR = Path(__file__).parent / "data"
 
 
+def test_bonds():
+    # C1: Create a soft bound with an upper limit and high penalty
+    #   Expect the variable to be constrained by the upper bound
+    xarray = numpy.linspace(0, 10, 100)
+    yarray = 2 * xarray
+    session = RefinementSession()
+    session.add_profile_from_arrays(
+        profile_name="linear", xarray=xarray, yarray=yarray
+    )
+    session.add_equation_model(model_name="linear_model", equation_str="m*x")
+    session.set_variables_value(
+        {
+            "linear_model.m": 1,
+        }
+    )
+    session._solve(
+        name="linear_upper_bound",
+        profiles=[session.profiles_dict["linear"]],
+        models=[session.models_dict["linear_model"]],
+        variable_names=["linear_model.m"],
+        bounds={"linear_model.m": {"upper_bound": 1.8, "uncertainty": 1e-4}},
+    )
+    assert numpy.isclose(
+        session.get_variable("linear_model.m")["value"],
+        1.8,
+        rtol=1e-2,
+    )
+    # C2: Create a soft bound with a lower limit and high penalty
+    #   Expect the variable to be constrained by the lower bound
+    session._solve(
+        name="linear_lower_bound",
+        profiles=[session.profiles_dict["linear"]],
+        models=[session.models_dict["linear_model"]],
+        variable_names=["linear_model.m"],
+        bounds={"linear_model.m": {"lower_bound": 2.2, "uncertainty": 1e-4}},
+    )
+    assert numpy.isclose(
+        session.get_variable("linear_model.m")["value"],
+        2.2,
+        rtol=1e-2,
+    )
+    # NOTE: hard bounds are defined but not used by diffpy.srfit
+    #   Skip testing hard bounds.
+
+
 def test_refine_sine(sine_profile):
     # C1: Refinement session without additional calculator or functions
     session = RefinementSession()