diff --git a/src/Numerics/Optimization/ILeastSquaresMinimizer.cs b/src/Numerics/Optimization/ILeastSquaresMinimizer.cs new file mode 100644 index 000000000..4d321f4e3 --- /dev/null +++ b/src/Numerics/Optimization/ILeastSquaresMinimizer.cs @@ -0,0 +1,67 @@ +// +// Math.NET Numerics, part of the Math.NET Project +// https://numerics.mathdotnet.com +// https://github.com/mathnet/mathnet-numerics +// +// Copyright (c) 2009-$CURRENT_YEAR$ Math.NET +// +// Permission is hereby granted, free of charge, to any person +// obtaining a copy of this software and associated documentation +// files (the "Software"), to deal in the Software without +// restriction, including without limitation the rights to use, +// copy, modify, merge, publish, distribute, sublicense, and/or sell +// copies of the Software, and to permit persons to whom the +// Software is furnished to do so, subject to the following +// conditions: +// +// The above copyright notice and this permission notice shall be +// included in all copies or substantial portions of the Software. +// +// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +// EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES +// OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +// NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +// HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, +// WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING +// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR +// OTHER DEALINGS IN THE SOFTWARE. +// + +using MathNet.Numerics.LinearAlgebra; +using System.Collections.Generic; + +namespace MathNet.Numerics.Optimization +{ + /// + /// Interface for solving nonlinear least squares problems. + /// This interface unifies the Levenberg-Marquardt and Trust Region minimization algorithms. + /// + public interface ILeastSquaresMinimizer + { + /// + /// Finds the minimum of a nonlinear least squares problem using the specified objective model and initial guess vector. + /// + /// The objective function model to be minimized. + /// The initial guess vector. + /// Optional lower bound for the parameters. + /// Optional upper bound for the parameters. + /// Optional scales for the parameters. + /// Optional list indicating which parameters are fixed. + /// A containing the results of the minimization. + NonlinearMinimizationResult FindMinimum(IObjectiveModel objective, Vector initialGuess, + Vector lowerBound = null, Vector upperBound = null, Vector scales = null, List isFixed = null); + + /// + /// Finds the minimum of a nonlinear least squares problem using the specified objective model and initial guess array. + /// + /// The objective function model to be minimized. + /// The initial guess array. + /// Optional lower bound array for the parameters. + /// Optional upper bound array for the parameters. + /// Optional scales array for the parameters. + /// Optional array indicating which parameters are fixed. + /// A containing the results of the minimization. + NonlinearMinimizationResult FindMinimum(IObjectiveModel objective, double[] initialGuess, + double[] lowerBound = null, double[] upperBound = null, double[] scales = null, bool[] isFixed = null); + } +} diff --git a/src/Numerics/Optimization/LevenbergMarquardtMinimizer.cs b/src/Numerics/Optimization/LevenbergMarquardtMinimizer.cs index 30b40a93e..87a8f9bc2 100644 --- a/src/Numerics/Optimization/LevenbergMarquardtMinimizer.cs +++ b/src/Numerics/Optimization/LevenbergMarquardtMinimizer.cs @@ -5,25 +5,39 @@ namespace MathNet.Numerics.Optimization { - public class LevenbergMarquardtMinimizer : NonlinearMinimizerBase + /// + /// Implements the Levenberg-Marquardt algorithm for solving nonlinear least squares problems. + /// This class inherits from and implements . + /// + public class LevenbergMarquardtMinimizer : NonlinearMinimizerBase, ILeastSquaresMinimizer { /// /// The scale factor for initial mu /// public double InitialMu { get; set; } + /// + /// Initializes a new instance of the class using the Levenberg-Marquardt algorithm. + /// + /// The initial damping parameter (mu) for the algorithm. Default is 1E-3. + /// The tolerance for the infinity norm of the gradient. Default is 1E-15. + /// The tolerance for the parameter update step size. Default is 1E-15. + /// The tolerance for the function value (residual sum of squares). Default is 1E-15. + /// The maximum number of iterations. Default is -1 (unlimited). public LevenbergMarquardtMinimizer(double initialMu = 1E-3, double gradientTolerance = 1E-15, double stepTolerance = 1E-15, double functionTolerance = 1E-15, int maximumIterations = -1) : base(gradientTolerance, stepTolerance, functionTolerance, maximumIterations) { InitialMu = initialMu; } + /// public NonlinearMinimizationResult FindMinimum(IObjectiveModel objective, Vector initialGuess, Vector lowerBound = null, Vector upperBound = null, Vector scales = null, List isFixed = null) { return Minimum(objective, initialGuess, lowerBound, upperBound, scales, isFixed, InitialMu, GradientTolerance, StepTolerance, FunctionTolerance, MaximumIterations); } + /// public NonlinearMinimizationResult FindMinimum(IObjectiveModel objective, double[] initialGuess, double[] lowerBound = null, double[] upperBound = null, double[] scales = null, bool[] isFixed = null) { diff --git a/src/Numerics/Optimization/TrustRegion/TrustRegionMinimizerBase.cs b/src/Numerics/Optimization/TrustRegion/TrustRegionMinimizerBase.cs index 222b3ccf3..2314d5e81 100644 --- a/src/Numerics/Optimization/TrustRegion/TrustRegionMinimizerBase.cs +++ b/src/Numerics/Optimization/TrustRegion/TrustRegionMinimizerBase.cs @@ -5,7 +5,11 @@ namespace MathNet.Numerics.Optimization.TrustRegion { - public abstract class TrustRegionMinimizerBase : NonlinearMinimizerBase + /// + /// Abstract base class for trust region minimizers that solve nonlinear least squares problems. + /// This class inherits from and implements . + /// + public abstract class TrustRegionMinimizerBase : NonlinearMinimizerBase, ILeastSquaresMinimizer { /// /// The trust region subproblem. @@ -17,6 +21,15 @@ public abstract class TrustRegionMinimizerBase : NonlinearMinimizerBase /// public double RadiusTolerance { get; set; } + /// + /// Initializes a new instance of the class using the specified trust region subproblem. + /// + /// The trust region subproblem to be solved at each iteration. + /// The tolerance for the infinity norm of the gradient. Default is 1E-8. + /// The tolerance for the parameter update step size. Default is 1E-8. + /// The tolerance for the function value (residual sum of squares). Default is 1E-8. + /// The tolerance for the trust region radius. Default is 1E-8. + /// The maximum number of iterations. Default is -1 (unlimited). public TrustRegionMinimizerBase(ITrustRegionSubproblem subproblem, double gradientTolerance = 1E-8, double stepTolerance = 1E-8, double functionTolerance = 1E-8, double radiusTolerance = 1E-8, int maximumIterations = -1) : base(gradientTolerance, stepTolerance, functionTolerance, maximumIterations) @@ -25,6 +38,7 @@ public TrustRegionMinimizerBase(ITrustRegionSubproblem subproblem, RadiusTolerance = radiusTolerance; } + /// public NonlinearMinimizationResult FindMinimum(IObjectiveModel objective, Vector initialGuess, Vector lowerBound = null, Vector upperBound = null, Vector scales = null, List isFixed = null) { @@ -32,6 +46,7 @@ public NonlinearMinimizationResult FindMinimum(IObjectiveModel objective, Vector GradientTolerance, StepTolerance, FunctionTolerance, RadiusTolerance, MaximumIterations); } + /// public NonlinearMinimizationResult FindMinimum(IObjectiveModel objective, double[] initialGuess, double[] lowerBound = null, double[] upperBound = null, double[] scales = null, bool[] isFixed = null) {