Warn and rescue sysid parameters that start at a box bound.

ParameterDict.move_off_bounds() shifts at-bound values into the interior;
optimize() warns when any non-frozen component starts at a bound.

python/mujoco/sysid/_src/optimize.py

@@ -179,6 +179,24 @@ def optimize(
         extras={},
     )
 
+  # Warn if any non-frozen parameter component starts at (or essentially at)
+  # a box bound. Optimization can stall in that corner on ill-conditioned or
+  # rank-deficient problems; both the mujoco and scipy backends are affected.
+  lo, hi = bounds
+  rng = hi - lo
+  safe_rng = np.where(rng > 0, rng, 1.0)
+  at_bound = ((x0 - lo) <= 1e-3 * safe_rng) | ((hi - x0) <= 1e-3 * safe_rng)
+  at_bound &= rng > 0
+  if at_bound.any():
+    logging.warning(
+        "%d of %d non-frozen parameter components start at (or essentially "
+        "at) a box bound. Optimization can stall in that corner on "
+        "ill-conditioned problems; consider calling "
+        "initial_params.move_off_bounds() before optimize().",
+        int(at_bound.sum()),
+        x0.size,
+    )
+
   def optimized_residual_fn(x):
     residuals, _, _ = residual_fn(x, opt_params)
     return np.concatenate(residuals)

python/mujoco/sysid/_src/parameter.py

@@ -139,6 +139,19 @@ class Parameter:
       rng = np.random.default_rng()
     return rng.uniform(self.min_value.flatten(), self.max_value.flatten())
 
+  def move_off_bound(self, fraction: float = 0.05) -> None:
+    """Shift values within 0.1% of a bound to ``lo + fraction*(hi-lo)`` (or
+    symmetric for the upper bound). Interior components are unchanged."""
+    lo, hi = self.get_bounds()
+    rng = hi - lo
+    safe_rng = np.where(rng > 0, rng, 1.0)
+    v = self.as_vector().copy()
+    at_lo = (v - lo) <= 1e-3 * safe_rng
+    at_hi = (hi - v) <= 1e-3 * safe_rng
+    v = np.where(at_lo, lo + fraction * rng, v)
+    v = np.where(at_hi, hi - fraction * rng, v)
+    self.update_from_vector(v)
+
   def __str__(self) -> str:
     """Return a string representation of the parameter."""
     if self.size == 1:
@@ -293,6 +306,15 @@ class ParameterDict:
         param.update_from_vector(vector[start : start + size])
         start += size
 
+  def move_off_bounds(self, fraction: float = 0.05) -> Self:
+    """Call :meth:`Parameter.move_off_bound` on every non-frozen parameter,
+    returning ``self`` so calls can be chained before
+    :func:`optimize`."""
+    for param in self.parameters.values():
+      if not param.frozen:
+        param.move_off_bound(fraction=fraction)
+    return self
+
   def save_to_disk(self, path: str | pathlib.Path) -> None:
     """Save the parameter dictionary to disk (schema and data).