Solver Core - Give "epsilon" tolerance values better names.

david-cattermole · david-cattermole · commit 2df15c65792b · 2025-01-26T15:00:47.000+11:00
These names are inline with the Ceres solver tolerance variable names.

Also, this change actually fixes a bug where the function tolerence
(epsilon1) was being incorrectly set as the grdient tolerance
(epsilon3).
diff --git a/docs/source/commands_solve.rst b/docs/source/commands_solve.rst
@@ -14,27 +14,27 @@ The command can be run in both MEL and Python.
 
 Here is a table of command flags, as currently specified in the command.
 
-======================== ========================================== ======================================================================= ==============
-Flag                     Type                                       Description                                                             Default Value
-======================== ========================================== ======================================================================= ==============
--camera (-c)             string, string                             Camera transform and shape nodes                                        None
--marker (-m)             string, string, string                     Marker, Camera, Bundle                                                  None
--attr (-a)               string, string, string, string, string     Node attribute, min value, max value, offset and scale                  None
--frame (-f)              long int                                   Frame number to solve with                                              1
--attrStiffness (-asf)    string, string, string, string             Node attribute, weight plug name, variance plug name, value plug name.  None
--attrSmoothness (-asm)   string, string, string, string             Node attribute, weight plug name, variance plug name, value plug name.  None
--solverType (-st)        unsigned int                               Type of solver to use.                                                  <auto detected>
--sceneGraphMode (-sgm)   unsigned int                               The Scene Graph used; 0=Maya DAG, 1=MM Scene Graph                      0 (Maya DAG)
--timeEvalMode (-tem)     unsigned int                               How to evalulate values at different times, 0=DG Context 1=Set TIme     0 (DG Context)
--iterations (-it)        unsigned int                               Maximum number of iterations                                            20
--tauFactor (-t)          double                                     Initial Damping Factor                                                  1E-03
--epsilon1 (-e1)          double                                     Acceptable gradient change                                              1E-06
--epsilon2 (-e2)          double                                     Acceptable parameter change                                             1E-06
--epsilon3 (-e3)          double                                     Acceptable error                                                        1E-06
--delta (-dt)             double                                     Change to the guessed parameters each iteration                         1E-04
--autoDiffType (-adt)     unsigned int                               Auto-differencing type 0=forward 1=central                              0 (forward)
--verbose (-v)            bool                                       Prints more information                                                 False
-======================== ========================================== ======================================================================= ==============
+======================== ===================== ========================================== ======================================================================= ==============
+Command Flag             Command Flag (short)  Type                                       Description                                                             Default Value
+======================== ===================== ========================================== ======================================================================= ==============
+-camera                  -c                    string, string                             Camera transform and shape nodes.                                       None
+-marker                  -m                    string, string, string                     Marker, Camera, Bundle.                                                 None
+-attr                    -a                    string, string, string, string, string     Node attribute, min value, max value, offset and scale.                 None
+-frame                   -f                    long int                                   Frame number to solve with.                                             1
+-attrStiffness           -asf                  string, string, string, string             Node attribute, weight plug name, variance plug name, value plug name.  None
+-attrSmoothness          -asm                  string, string, string, string             Node attribute, weight plug name, variance plug name, value plug name.  None
+-solverType              -st                   unsigned int                               Type of solver to use.                                                  <auto detected>
+-sceneGraphMode          -sgm                  unsigned int                               The Scene Graph used; 0=Maya DAG, 1=MM Scene Graph.                     0 (Maya DAG)
+-timeEvalMode            -tem                  unsigned int                               How to evalulate values at different times, 0=DG Context 1=Set Time.    0 (DG Context)
+-iterations              -it                   unsigned int                               Maximum number of iterations.                                           20
+-tauFactor               -t                    double                                     Initial Damping Factor.                                                 1E-03
+-functionTolerance       -ftl                  double                                     Acceptable function change.                                             1E-06
+-parameterTolerance      -ptl                  double                                     Acceptable parameter change.                                            1E-06
+-gradientTolerance       -gtl                  double                                     Acceptable gradient error.                                              1E-06
+-delta                   -dt                   double                                     Change to the guessed parameters each iteration.                        1E-04
+-autoDiffType            -adt                  unsigned int                               Auto-differencing type 0=forward 1=central.                             0 (forward)
+-verbose                 -v                    bool                                       Prints more information.                                                False
+======================== ===================== ========================================== ======================================================================= ==============
 
 Return
 ------
@@ -102,7 +102,7 @@ Python Example:
    solvers = maya.cmds.mmSolverType(query=True, list=True)
    default_solver = maya.cmds.mmSolverType(query=True, default=True)
 
-   
+
 ``mmSolverAffects`` Command
 +++++++++++++++++++++++++++
 
diff --git a/python/mmSolver/_api/solverstep.py b/python/mmSolver/_api/solverstep.py
@@ -680,17 +680,17 @@ def compile(self, col, mkr_list, attr_list, withtest=False):
         if tau_factor is not None:
             kwargs['tauFactor'] = tau_factor
 
-        gradient_error_factor = self.get_gradient_error_factor()
-        if gradient_error_factor is not None:
-            kwargs['epsilon1'] = gradient_error_factor
+        function_error_factor = self.get_error_factor()
+        if function_error_factor is not None:
+            kwargs['function_tolerance'] = function_error_factor
 
         parameter_error_factor = self.get_parameter_error_factor()
         if parameter_error_factor is not None:
-            kwargs['epsilon2'] = parameter_error_factor
+            kwargs['parameter_tolerance'] = parameter_error_factor
 
-        error_factor = self.get_error_factor()
-        if error_factor is not None:
-            kwargs['epsilon3'] = error_factor
+        gradient_error_factor = self.get_gradient_error_factor()
+        if gradient_error_factor is not None:
+            kwargs['gradient_tolerance'] = gradient_error_factor
 
         robust_loss_type = self.get_robust_loss_type()
         if robust_loss_type is not None:
diff --git a/share/design/api/api_classes_detail.graphml b/share/design/api/api_classes_detail.graphml
@@ -321,14 +321,14 @@ get_max_iterations()
 set_max_iterations(value)
 
 get_tau_factor()
-get_epsilon1()
-get_epsilon2()
-get_epsilon3()
+get_function_tolerance()
+get_parameter_tolerance()
+get_gradient_tolerance()
 get_delta()
 set_tau_factor(value)
-set_epsilon1(value)
-set_epsilon2(value)
-set_epsilon3(value)
+set_function_tolerance(value)
+set_parameter_tolerance(value)
+set_gradient_tolerance(value)
 set_delta(value)
 
 get_frame_list()
diff --git a/src/mmSolver/adjust/adjust_base.cpp b/src/mmSolver/adjust/adjust_base.cpp
@@ -910,9 +910,12 @@ MStatus solveFrames(
         MMSOLVER_MAYA_INFO("Solver Type=" << solverOptions.solverType);
         MMSOLVER_MAYA_INFO("Maximum Iterations=" << solverOptions.iterMax);
         MMSOLVER_MAYA_INFO("Tau=" << solverOptions.tau);
-        MMSOLVER_MAYA_INFO("Epsilon1=" << solverOptions.eps1);
-        MMSOLVER_MAYA_INFO("Epsilon2=" << solverOptions.eps2);
-        MMSOLVER_MAYA_INFO("Epsilon3=" << solverOptions.eps3);
+        MMSOLVER_MAYA_INFO(
+            "Function Tolerance=" << solverOptions.function_tolerance);
+        MMSOLVER_MAYA_INFO(
+            "Parameter Tolerance=" << solverOptions.parameter_tolerance);
+        MMSOLVER_MAYA_INFO(
+            "Gradient Tolerance=" << solverOptions.gradient_tolerance);
         MMSOLVER_MAYA_INFO("Delta=" << fabs(solverOptions.delta));
         MMSOLVER_MAYA_INFO(
             "Auto Differencing Type=" << solverOptions.autoDiffType);
diff --git a/src/mmSolver/adjust/adjust_ceres_lmder.cpp b/src/mmSolver/adjust/adjust_ceres_lmder.cpp
@@ -213,9 +213,9 @@ bool solve_3d_ceres_lmder(SolverOptions& solverOptions,
     options.max_num_consecutive_invalid_steps = 5;  // Allow some invalid steps.
 
     options.max_num_iterations = solverOptions.iterMax;
-    options.function_tolerance = solverOptions.eps1;
-    options.parameter_tolerance = solverOptions.eps2;
-    options.gradient_tolerance = solverOptions.eps3;
+    options.function_tolerance = solverOptions.function_tolerance;
+    options.parameter_tolerance = solverOptions.parameter_tolerance;
+    options.gradient_tolerance = solverOptions.gradient_tolerance;
     options.initial_trust_region_radius = solverOptions.tau;
     options.jacobi_scaling = true;
     options.num_threads = 1;
diff --git a/src/mmSolver/adjust/adjust_ceres_lmdif.cpp b/src/mmSolver/adjust/adjust_ceres_lmdif.cpp
@@ -131,9 +131,9 @@ bool solve_3d_ceres_lmdif(SolverOptions& solverOptions,
     options.max_num_consecutive_invalid_steps = 5;  // Allow some invalid steps.
 
     options.max_num_iterations = solverOptions.iterMax;
-    options.function_tolerance = solverOptions.eps1;
-    options.parameter_tolerance = solverOptions.eps2;
-    options.gradient_tolerance = solverOptions.eps3;
+    options.function_tolerance = solverOptions.function_tolerance;
+    options.parameter_tolerance = solverOptions.parameter_tolerance;
+    options.gradient_tolerance = solverOptions.gradient_tolerance;
     options.initial_trust_region_radius = solverOptions.tau;
     options.jacobi_scaling = true;
     options.num_threads = 1;
diff --git a/src/mmSolver/adjust/adjust_cminpack_lmder.cpp b/src/mmSolver/adjust/adjust_cminpack_lmder.cpp
@@ -99,9 +99,9 @@ bool solve_3d_cminpack_lmder(SolverOptions &solverOptions,
         ldfjac = numberOfParameters;
     }
 
-    double ftol = solverOptions.eps1;
-    double xtol = solverOptions.eps2;
-    double gtol = solverOptions.eps3;
+    double ftol = solverOptions.function_tolerance;
+    double xtol = solverOptions.parameter_tolerance;
+    double gtol = solverOptions.gradient_tolerance;
 
     int mode = 2;  // Off
     if (solverOptions.autoParamScale == 1) {
diff --git a/src/mmSolver/adjust/adjust_cminpack_lmdif.cpp b/src/mmSolver/adjust/adjust_cminpack_lmdif.cpp
@@ -98,9 +98,9 @@ bool solve_3d_cminpack_lmdif(SolverOptions &solverOptions,
         ldfjac = numberOfParameters;
     }
 
-    double ftol = solverOptions.eps1;
-    double xtol = solverOptions.eps2;
-    double gtol = solverOptions.eps3;
+    double ftol = solverOptions.function_tolerance;
+    double xtol = solverOptions.parameter_tolerance;
+    double gtol = solverOptions.gradient_tolerance;
 
     // Change the sign of the delta
     // Note: lmdif only supports auto-diff 'forward' mode.
diff --git a/src/mmSolver/adjust/adjust_data.h b/src/mmSolver/adjust/adjust_data.h
@@ -134,9 +134,9 @@ struct PrintStatOptions {
 struct SolverOptions {
     int iterMax;
     double tau;
-    double eps1;
-    double eps2;
-    double eps3;
+    double function_tolerance;
+    double parameter_tolerance;
+    double gradient_tolerance;
     double delta;
     int autoDiffType;
     int autoParamScale;
@@ -163,9 +163,9 @@ struct SolverOptions {
     SolverOptions()
         : iterMax(0)
         , tau(0.0)
-        , eps1(0.0)
-        , eps2(0.0)
-        , eps3(0.0)
+        , function_tolerance(0.0)
+        , parameter_tolerance(0.0)
+        , gradient_tolerance(0.0)
         , delta(0.0)
         , autoDiffType(AUTO_DIFF_TYPE_FORWARD)
         , autoParamScale(0)
diff --git a/src/mmSolver/adjust/adjust_defines.h b/src/mmSolver/adjust/adjust_defines.h
@@ -113,9 +113,9 @@
 //
 #define CMINPACK_LMDIF_ITERATIONS_DEFAULT_VALUE (100)
 #define CMINPACK_LMDIF_TAU_DEFAULT_VALUE (1.0)
-#define CMINPACK_LMDIF_EPSILON1_DEFAULT_VALUE (1E-6)  // ftol
-#define CMINPACK_LMDIF_EPSILON2_DEFAULT_VALUE (1E-6)  // xtol
-#define CMINPACK_LMDIF_EPSILON3_DEFAULT_VALUE (1E-6)  // gtol
+#define CMINPACK_LMDIF_FUNCTION_TOLERANCE_DEFAULT_VALUE (1E-6)   // ftol
+#define CMINPACK_LMDIF_PARAMETER_TOLERANCE_DEFAULT_VALUE (1E-6)  // xtol
+#define CMINPACK_LMDIF_GRADIENT_TOLERANCE_DEFAULT_VALUE (1E-6)   // gtol
 #define CMINPACK_LMDIF_DELTA_DEFAULT_VALUE (1E-04)
 // cminpack lmdif only supports forward '0=forward' differentiation.
 #define CMINPACK_LMDIF_AUTO_DIFF_TYPE_DEFAULT_VALUE (AUTO_DIFF_TYPE_FORWARD)
@@ -134,9 +134,9 @@
 //
 #define CMINPACK_LMDER_ITERATIONS_DEFAULT_VALUE (100)
 #define CMINPACK_LMDER_TAU_DEFAULT_VALUE (1.0)
-#define CMINPACK_LMDER_EPSILON1_DEFAULT_VALUE (1E-6)  // ftol
-#define CMINPACK_LMDER_EPSILON2_DEFAULT_VALUE (1E-6)  // xtol
-#define CMINPACK_LMDER_EPSILON3_DEFAULT_VALUE (1E-6)  // gtol
+#define CMINPACK_LMDER_FUNCTION_TOLERANCE_DEFAULT_VALUE (1E-6)   // ftol
+#define CMINPACK_LMDER_PARAMETER_TOLERANCE_DEFAULT_VALUE (1E-6)  // xtol
+#define CMINPACK_LMDER_GRADIENT_TOLERANCE_DEFAULT_VALUE (1E-6)   // gtol
 #define CMINPACK_LMDER_DELTA_DEFAULT_VALUE (1E-04)
 // cminpack lmder supports both forward '0=forward' and 'central' auto-diff'ing.
 #define CMINPACK_LMDER_AUTO_DIFF_TYPE_DEFAULT_VALUE (AUTO_DIFF_TYPE_FORWARD)
@@ -156,9 +156,9 @@
 //
 #define CERES_LMDIF_ITERATIONS_DEFAULT_VALUE (100)
 #define CERES_LMDIF_TAU_DEFAULT_VALUE (1E4)
-#define CERES_LMDIF_EPSILON1_DEFAULT_VALUE (1E-6)   // function_tolerance
-#define CERES_LMDIF_EPSILON2_DEFAULT_VALUE (1E-10)  // parameter_tolerance
-#define CERES_LMDIF_EPSILON3_DEFAULT_VALUE (1E-8)   // gradient_tolerance
+#define CERES_LMDIF_FUNCTION_TOLERANCE_DEFAULT_VALUE (1E-6)
+#define CERES_LMDIF_PARAMETER_TOLERANCE_DEFAULT_VALUE (1E-10)
+#define CERES_LMDIF_GRADIENT_TOLERANCE_DEFAULT_VALUE (1E-8)
 #define CERES_LMDIF_DELTA_DEFAULT_VALUE (1E-04)
 // ceres lmder supports both forward '0=forward' and 'central' auto-diff'ing.
 #define CERES_LMDIF_AUTO_DIFF_TYPE_DEFAULT_VALUE (AUTO_DIFF_TYPE_FORWARD)
@@ -178,9 +178,9 @@
 //
 #define CERES_LMDER_ITERATIONS_DEFAULT_VALUE (100)
 #define CERES_LMDER_TAU_DEFAULT_VALUE (1E4)
-#define CERES_LMDER_EPSILON1_DEFAULT_VALUE (1E-6)   // function_tolerance
-#define CERES_LMDER_EPSILON2_DEFAULT_VALUE (1E-10)  // parameter_tolerance
-#define CERES_LMDER_EPSILON3_DEFAULT_VALUE (1E-8)   // gradient_tolerance
+#define CERES_LMDER_FUNCTION_TOLERANCE_DEFAULT_VALUE (1E-6)
+#define CERES_LMDER_PARAMETER_TOLERANCE_DEFAULT_VALUE (1E-10)
+#define CERES_LMDER_GRADIENT_TOLERANCE_DEFAULT_VALUE (1E-8)
 #define CERES_LMDER_DELTA_DEFAULT_VALUE (1E-04)
 // ceres lmder supports both forward '0=forward' and 'central' auto-diff'ing.
 #define CERES_LMDER_AUTO_DIFF_TYPE_DEFAULT_VALUE (AUTO_DIFF_TYPE_FORWARD)
@@ -197,9 +197,9 @@
 //
 #define LEVMAR_ITERATIONS_DEFAULT_VALUE (100)
 #define LEVMAR_TAU_DEFAULT_VALUE (1.0)
-#define LEVMAR_EPSILON1_DEFAULT_VALUE (1E-6)
-#define LEVMAR_EPSILON2_DEFAULT_VALUE (1E-6)
-#define LEVMAR_EPSILON3_DEFAULT_VALUE (1E-6)
+#define LEVMAR_FUNCTION_TOLERANCE_DEFAULT_VALUE (1E-6)
+#define LEVMAR_PARAMETER_TOLERANCE_DEFAULT_VALUE (1E-6)
+#define LEVMAR_GRADIENT_TOLERANCE_DEFAULT_VALUE (1E-6)
 #define LEVMAR_DELTA_DEFAULT_VALUE (1E-04)
 #define LEVMAR_AUTO_DIFF_TYPE_DEFAULT_VALUE (AUTO_DIFF_TYPE_FORWARD)
 // LevMar does not have auto-parameter scaling.
diff --git a/src/mmSolver/adjust/adjust_levmar_bc_dif.cpp b/src/mmSolver/adjust/adjust_levmar_bc_dif.cpp
@@ -85,9 +85,9 @@ bool solve_3d_levmar_bc_dif(SolverOptions &solverOptions,
     }
 
     levmar_opts[0] = solverOptions.tau;
-    levmar_opts[1] = solverOptions.eps1;
-    levmar_opts[2] = solverOptions.eps2;
-    levmar_opts[3] = solverOptions.eps3;
+    levmar_opts[1] = solverOptions.function_tolerance;
+    levmar_opts[2] = solverOptions.parameter_tolerance;
+    levmar_opts[3] = solverOptions.gradient_tolerance;
     levmar_opts[4] = delta_factor;
     userData.solverType = solverType;
 
@@ -145,9 +145,9 @@ bool solve_3d_levmar_bc_dif(SolverOptions &solverOptions,
 
         // Minimisation options (input only)
         // opts[0] = tau      (scale factor for initialTransform mu)
-        // opts[1] = epsilon1 (stopping threshold for ||J^T e||_inf)
-        // opts[2] = epsilon2 (stopping threshold for ||Dp||_2)
-        // opts[3] = epsilon3 (stopping threshold for ||e||_2)
+        // opts[1] = function_tolerance (stopping threshold for ||J^T e||_inf)
+        // opts[2] = parameter_tolerance (stopping threshold for ||Dp||_2)
+        // opts[3] = gradient_tolerance (stopping threshold for ||e||_2)
         // opts[4] = delta    (step used in difference approximation to the
         // Jacobian)
         //
diff --git a/src/mmSolver/cmd/MMSolver2Cmd.cpp b/src/mmSolver/cmd/MMSolver2Cmd.cpp
@@ -87,12 +87,13 @@ MStatus MMSolver2Cmd::parseArgs(const MArgList &args) {
 
     status = parseSolveInfoArguments_v2(
         argData, m_solverOptions.iterMax, m_solverOptions.tau,
-        m_solverOptions.eps1, m_solverOptions.eps2, m_solverOptions.eps3,
-        m_solverOptions.delta, m_solverOptions.autoDiffType,
-        m_solverOptions.autoParamScale, m_solverOptions.robustLossType,
-        m_solverOptions.robustLossScale, m_solverOptions.solverType,
-        m_solverOptions.sceneGraphMode, m_solverOptions.timeEvalMode,
-        m_solverOptions.acceptOnlyBetter, m_solverOptions.frameSolveMode,
+        m_solverOptions.function_tolerance, m_solverOptions.parameter_tolerance,
+        m_solverOptions.gradient_tolerance, m_solverOptions.delta,
+        m_solverOptions.autoDiffType, m_solverOptions.autoParamScale,
+        m_solverOptions.robustLossType, m_solverOptions.robustLossScale,
+        m_solverOptions.solverType, m_solverOptions.sceneGraphMode,
+        m_solverOptions.timeEvalMode, m_solverOptions.acceptOnlyBetter,
+        m_solverOptions.frameSolveMode,
         m_solverOptions.solverSupportsAutoDiffForward,
         m_solverOptions.solverSupportsAutoDiffCentral,
         m_solverOptions.solverSupportsParameterBounds,
diff --git a/src/mmSolver/cmd/MMSolverCmd.cpp b/src/mmSolver/cmd/MMSolverCmd.cpp
diff --git a/src/mmSolver/cmd/MMSolverCmd.h b/src/mmSolver/cmd/MMSolverCmd.h
diff --git a/src/mmSolver/cmd/arg_flags_solve_info.cpp b/src/mmSolver/cmd/arg_flags_solve_info.cpp
diff --git a/src/mmSolver/cmd/arg_flags_solve_info.h b/src/mmSolver/cmd/arg_flags_solve_info.h
