Add direct residual function support to NonlinearObjectiveModel and related interfaces

Author: diluculo

src/Numerics/Optimization/IObjectiveModel.cs

@@ -3,37 +3,55 @@
 
 namespace MathNet.Numerics.Optimization
 {
+    /// <summary>
+    /// Interface for objective model evaluation, providing access to optimization-related values
+    /// </summary>
     public interface IObjectiveModelEvaluation
     {
+        /// <summary>
+        /// Creates a new instance of the objective model with the same function but not the same state
+        /// </summary>
+        /// <returns>A new instance of an objective model</returns>
         IObjectiveModel CreateNew();
 
         /// <summary>
         /// Get the y-values of the observations.
+        /// May be null when using direct residual functions.
         /// </summary>
         Vector<double> ObservedY { get; }
 
         /// <summary>
         /// Get the values of the weights for the observations.
+        /// May be null when using direct residual functions.
         /// </summary>
         Matrix<double> Weights { get; }
 
         /// <summary>
         /// Get the y-values of the fitted model that correspond to the independent values.
+        /// Only applicable when using model functions, may be null when using direct residual functions.
         /// </summary>
         Vector<double> ModelValues { get; }
 
+        /// <summary>
+        /// Get the residual values at the current parameters.
+        /// For model functions, this is (y - f(x;p)) possibly weighted.
+        /// For direct residual functions, this is the raw output of the residual function.
+        /// </summary>
+        Vector<double> Residuals { get; }
+
         /// <summary>
         /// Get the values of the parameters.
         /// </summary>
         Vector<double> Point { get; }
 
         /// <summary>
-        /// Get the residual sum of squares.
+        /// Get the residual sum of squares, calculated as F(p) = 1/2 * ∑(residuals²).
         /// </summary>
         double Value { get; }
 
         /// <summary>
-        /// Get the Gradient vector. G = J'(y - f(x; p))
+        /// Get the Gradient vector. G = J'(y - f(x; p)) for model functions, 
+        /// or G = J'r for direct residual functions.
         /// </summary>
         Vector<double> Gradient { get; }
 
@@ -54,21 +72,51 @@ public interface IObjectiveModelEvaluation
 
         /// <summary>
         /// Get the degree of freedom.
+        /// For model functions: (number of observations - number of parameters + number of fixed parameters)
+        /// For direct residual functions: uses explicit observation count or residual vector length if not provided.
         /// </summary>
         int DegreeOfFreedom { get; }
 
+        /// <summary>
+        /// Indicates whether gradient information is supported
+        /// </summary>
         bool IsGradientSupported { get; }
+
+        /// <summary>
+        /// Indicates whether Hessian information is supported
+        /// </summary>
         bool IsHessianSupported { get; }
     }
 
+    /// <summary>
+    /// Interface for objective model that can be minimized
+    /// </summary>
     public interface IObjectiveModel : IObjectiveModelEvaluation
     {
+        /// <summary>
+        /// Set parameters and optionally specify which parameters should be fixed
+        /// </summary>
+        /// <param name="initialGuess">The initial values of parameters</param>
+        /// <param name="isFixed">Optional list specifying which parameters are fixed (true) or free (false)</param>
         void SetParameters(Vector<double> initialGuess, List<bool> isFixed = null);
 
+        /// <summary>
+        /// Evaluates the objective model at the specified parameters
+        /// </summary>
+        /// <param name="parameters">Parameters at which to evaluate</param>
         void EvaluateAt(Vector<double> parameters);
 
+        /// <summary>
+        /// Creates a copy of this objective model with the same state
+        /// </summary>
+        /// <returns>A copy of the objective model</returns>
         IObjectiveModel Fork();
 
+        /// <summary>
+        /// Converts this objective model to an objective function for optimization.
+        /// Creates a function that calculates 1/2 * sum(residuals²) to be minimized.
+        /// </summary>
+        /// <returns>An IObjectiveFunction that can be used with general optimization algorithms</returns>
         IObjectiveFunction ToObjectiveFunction();
     }
 }

src/Numerics/Optimization/ObjectiveFunction.cs

@@ -116,9 +116,17 @@ public static IScalarObjectiveFunction ScalarSecondDerivative(Func<double, doubl
         }
 
         /// <summary>
-        /// objective model with a user supplied jacobian for non-linear least squares regression.
+        /// Creates an objective model with a user-supplied model function and Jacobian for non-linear least squares regression.
+        /// Uses the form F(p) = 1/2 * sum(w_i * (y_i - f(x_i; p))^2) where f(x; p) is the model function.
         /// </summary>
-        public static IObjectiveModel NonlinearModel(Func<Vector<double>, Vector<double>, Vector<double>> function,
+        /// <param name="function">The model function f(x; p) that maps from x to y given parameters p</param>
+        /// <param name="derivatives">The Jacobian of the model function with respect to parameters</param>
+        /// <param name="observedX">The observed x values</param>
+        /// <param name="observedY">The observed y values</param>
+        /// <param name="weight">Optional weights for the observations</param>
+        /// <returns>An objective model configured for the specified model and observations</returns>
+        public static IObjectiveModel NonlinearModel(
+            Func<Vector<double>, Vector<double>, Vector<double>> function,
             Func<Vector<double>, Vector<double>, Matrix<double>> derivatives,
             Vector<double> observedX, Vector<double> observedY, Vector<double> weight = null)
         {
@@ -128,9 +136,17 @@ public static IObjectiveModel NonlinearModel(Func<Vector<double>, Vector<double>
         }
 
         /// <summary>
-        /// Objective model for non-linear least squares regression.
+        /// Creates an objective model for non-linear least squares regression with numerical differentiation.
+        /// Uses the form F(p) = 1/2 * sum(w_i * (y_i - f(x_i; p))^2) where f(x; p) is the model function.
         /// </summary>
-        public static IObjectiveModel NonlinearModel(Func<Vector<double>, Vector<double>, Vector<double>> function,
+        /// <param name="function">The model function f(x; p) that maps from x to y given parameters p</param>
+        /// <param name="observedX">The observed x values</param>
+        /// <param name="observedY">The observed y values</param>
+        /// <param name="weight">Optional weights for the observations</param>
+        /// <param name="accuracyOrder">Accuracy order for numerical differentiation (1-6)</param>
+        /// <returns>An objective model configured for the specified model and observations</returns>
+        public static IObjectiveModel NonlinearModel(
+            Func<Vector<double>, Vector<double>, Vector<double>> function,
             Vector<double> observedX, Vector<double> observedY, Vector<double> weight = null,
             int accuracyOrder = 2)
         {
@@ -140,9 +156,18 @@ public static IObjectiveModel NonlinearModel(Func<Vector<double>, Vector<double>
         }
 
         /// <summary>
-        /// Objective model with a user supplied jacobian for non-linear least squares regression.
+        /// Creates an objective model with a user-supplied model function and Jacobian for non-linear least squares regression.
+        /// This overload accepts scalar x values with function f(p, x) and converts them to vector operations internally.
+        /// Uses the form F(p) = 1/2 * sum(w_i * (y_i - f(p, x_i))^2).
         /// </summary>
-        public static IObjectiveModel NonlinearModel(Func<Vector<double>, double, double> function,
+        /// <param name="function">The model function f(p, x) that maps from scalar x to y given parameters p</param>
+        /// <param name="derivatives">The derivatives of the model function with respect to parameters</param>
+        /// <param name="observedX">The observed x values</param>
+        /// <param name="observedY">The observed y values</param>
+        /// <param name="weight">Optional weights for the observations</param>
+        /// <returns>An objective model configured for the specified model and observations</returns>
+        public static IObjectiveModel NonlinearModel(
+            Func<Vector<double>, double, double> function,
             Func<Vector<double>, double, Vector<double>> derivatives,
             Vector<double> observedX, Vector<double> observedY, Vector<double> weight = null)
         {
@@ -174,9 +199,18 @@ Matrix<double> Prime(Vector<double> point, Vector<double> x)
         }
 
         /// <summary>
-        /// Objective model for non-linear least squares regression.
+        /// Creates an objective model for non-linear least squares regression with numerical differentiation.
+        /// This overload accepts scalar x values with function f(p, x) and converts them to vector operations internally.
+        /// Uses the form F(p) = 1/2 * sum(w_i * (y_i - f(p, x_i))^2).
         /// </summary>
-        public static IObjectiveModel NonlinearModel(Func<Vector<double>, double, double> function,
+        /// <param name="function">The model function f(p, x) that maps from scalar x to y given parameters p</param>
+        /// <param name="observedX">The observed x values</param>
+        /// <param name="observedY">The observed y values</param>
+        /// <param name="weight">Optional weights for the observations</param>
+        /// <param name="accuracyOrder">Accuracy order for numerical differentiation (1-6)</param>
+        /// <returns>An objective model configured for the specified model and observations</returns>
+        public static IObjectiveModel NonlinearModel(
+            Func<Vector<double>, double, double> function,
             Vector<double> observedX, Vector<double> observedY, Vector<double> weight = null,
             int accuracyOrder = 2)
         {
@@ -197,9 +231,35 @@ Vector<double> Func(Vector<double> point, Vector<double> x)
         }
 
         /// <summary>
-        /// Objective function with a user supplied jacobian for nonlinear least squares regression.
+        /// Creates an objective model from a direct residual function for non-linear optimization.
+        /// Uses the form F(p) = 1/2 * sum(r_i(p)^2) where r(p) is the residual function.
         /// </summary>
-        public static IObjectiveFunction NonlinearFunction(Func<Vector<double>, Vector<double>, Vector<double>> function,
+        /// <param name="residualFunction">Function that calculates residuals directly from parameters</param>
+        /// <param name="jacobian">Optional Jacobian of the residual function</param>
+        /// <param name="observationCount">Number of observations for degree of freedom calculations (optional)</param>
+        /// <param name="accuracyOrder">Accuracy order for numerical differentiation (1-6)</param>
+        /// <returns>An objective model configured for the specified residual function</returns>
+        public static IObjectiveModel NonlinearModel(
+            Func<Vector<double>, Vector<double>> residualFunction,
+            Func<Vector<double>, Matrix<double>> jacobian = null,
+            int? observationCount = null,
+            int accuracyOrder = 2)
+        {
+            return new NonlinearObjectiveModel(residualFunction, jacobian, accuracyOrder, observationCount);
+        }
+
+        /// <summary>
+        /// Creates an objective function with a user-supplied model function and Jacobian for non-linear least squares regression.
+        /// Uses the form F(p) = 1/2 * sum(w_i * (y_i - f(x_i; p))^2) where f(x; p) is the model function.
+        /// </summary>
+        /// <param name="function">The model function f(x; p) that maps from x to y given parameters p</param>
+        /// <param name="derivatives">The Jacobian of the model function with respect to parameters</param>
+        /// <param name="observedX">The observed x values</param>
+        /// <param name="observedY">The observed y values</param>
+        /// <param name="weight">Optional weights for the observations</param>
+        /// <returns>An objective function configured for the specified model and observations</returns>
+        public static IObjectiveFunction NonlinearFunction(
+            Func<Vector<double>, Vector<double>, Vector<double>> function,
             Func<Vector<double>, Vector<double>, Matrix<double>> derivatives,
             Vector<double> observedX, Vector<double> observedY, Vector<double> weight = null)
         {
@@ -209,16 +269,42 @@ public static IObjectiveFunction NonlinearFunction(Func<Vector<double>, Vector<d
         }
 
         /// <summary>
-        /// Objective function for nonlinear least squares regression.
-        /// The numerical jacobian with accuracy order is used.
+        /// Creates an objective function for non-linear least squares regression with numerical differentiation.
+        /// Uses the form F(p) = 1/2 * sum(w_i * (y_i - f(x_i; p))^2) where f(x; p) is the model function.
         /// </summary>
-        public static IObjectiveFunction NonlinearFunction(Func<Vector<double>, Vector<double>, Vector<double>> function,
+        /// <param name="function">The model function f(x; p) that maps from x to y given parameters p</param>
+        /// <param name="observedX">The observed x values</param>
+        /// <param name="observedY">The observed y values</param>
+        /// <param name="weight">Optional weights for the observations</param>
+        /// <param name="accuracyOrder">Accuracy order for numerical differentiation (1-6)</param>
+        /// <returns>An objective function configured for the specified model and observations</returns>
+        public static IObjectiveFunction NonlinearFunction(
+            Func<Vector<double>, Vector<double>, Vector<double>> function,
             Vector<double> observedX, Vector<double> observedY, Vector<double> weight = null,
             int accuracyOrder = 2)
         {
             var objective = new NonlinearObjectiveModel(function, null, accuracyOrder: accuracyOrder);
             objective.SetObserved(observedX, observedY, weight);
             return objective.ToObjectiveFunction();
         }
+
+        /// <summary>
+        /// Creates an objective function from a direct residual function for non-linear optimization.
+        /// Uses the form F(p) = 1/2 * sum(r_i(p)^2) where r(p) is the residual function.
+        /// </summary>
+        /// <param name="residualFunction">Function that calculates residuals directly from parameters</param>
+        /// <param name="jacobian">Optional Jacobian of the residual function</param>
+        /// <param name="observationCount">Number of observations for degree of freedom calculations (optional)</param>
+        /// <param name="accuracyOrder">Accuracy order for numerical differentiation (1-6)</param>
+        /// <returns>An objective function configured for the specified residual function</returns>
+        public static IObjectiveFunction NonlinearFunction(
+            Func<Vector<double>, Vector<double>> residualFunction,
+            Func<Vector<double>, Matrix<double>> jacobian = null,
+            int? observationCount = null,
+            int accuracyOrder = 2)
+        {
+            var objective = new NonlinearObjectiveModel(residualFunction, jacobian, accuracyOrder, observationCount);
+            return objective.ToObjectiveFunction();
+        }
     }
 }