include/opencascade/MathRoot_Multiple.hxx

0001 // Copyright (c) 2025 OPEN CASCADE SAS
0002 //
0003 // This file is part of Open CASCADE Technology software library.
0004 //
0005 // This library is free software; you can redistribute it and/or modify it under
0006 // the terms of the GNU Lesser General Public License version 2.1 as published
0007 // by the Free Software Foundation, with special exception defined in the file
0008 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
0009 // distribution for complete text of the license and disclaimer of any warranty.
0010 //
0011 // Alternatively, this file may be used under the terms of Open CASCADE
0012 // commercial license or contractual agreement.
0013
0014 #ifndef _MathRoot_Multiple_HeaderFile
0015 #define _MathRoot_Multiple_HeaderFile
0016
0017 #include <MathRoot_MultipleUtils.hxx>
0018
0019 //! @file MathRoot_Multiple.hxx
0020 //! @brief Algorithms for finding all roots of a function in a given range.
0021 //!
0022 //! These algorithms sample the function to find sign changes, then refine
0023 //! each root using Brent's method. They can find multiple roots in a single call.
0024
0025 namespace MathRoot
0026 {
0027
0028 //! Finds all real roots of a function within the range [theLower, theUpper].
0029 //! Uses uniform sampling to detect sign changes, then refines each root using Brent's method.
0030 //!
0031 //! Algorithm:
0032 //! 1. Sample function at NbSamples uniform points
0033 //! 2. Detect all sign changes and zero crossings
0034 //! 3. For each bracket, apply Brent's method to find precise root
0035 //! 4. Check for extrema that might touch zero
0036 //!
0037 //! @tparam Function type with Value(double theX, double& theF) method
0038 //! @param theFunc function object to find roots of
0039 //! @param theLower lower bound of search interval
0040 //! @param theUpper upper bound of search interval
0041 //! @param theConfig configuration parameters
0042 //! @return result containing all found roots
0043 template <typename Function>
0044 MultipleResult FindAllRoots(Function&             theFunc,
0045                             double                theLower,
0046                             double                theUpper,
0047                             const MultipleConfig& theConfig = MultipleConfig())
0048 {
0049   const int   aNbSamples = std::max(2 * theConfig.NbSamples, 20);
0050   math_Vector aSamples(0, aNbSamples);
0051
0052   MultipleSampleValueFn<Function>     aSampleFn{theFunc, aSamples, theConfig.Offset};
0053   MultipleGetValueFn                  aGetValue{aSamples};
0054   MultipleBrentValueWrapper<Function> aWrapper{theFunc, theConfig.Offset};
0055   MultipleGetRootValueFn<Function>    aGetRootValue{theFunc};
0056
0057   return FindAllRootsImpl(theLower,
0058                           theUpper,
0059                           theConfig,
0060                           aSampleFn,
0061                           aGetValue,
0062                           aWrapper,
0063                           aGetRootValue,
0064                           MultipleNoExtraHandler());
0065 }
0066
0067 //! Finds all real roots of a function with derivative within range [theLower, theUpper].
0068 //! Can also detect extrema where function touches zero without crossing.
0069 //!
0070 //! This version uses derivative information for better extrema detection.
0071 //!
0072 //! @tparam Function type with Values(double theX, double& theF, double& theDF) method
0073 //! @param theFunc function object with derivative
0074 //! @param theLower lower bound of search interval
0075 //! @param theUpper upper bound of search interval
0076 //! @param theConfig configuration parameters
0077 //! @return result containing all found roots
0078 template <typename Function>
0079 MultipleResult FindAllRootsWithDerivative(Function&             theFunc,
0080                                           double                theLower,
0081                                           double                theUpper,
0082                                           const MultipleConfig& theConfig = MultipleConfig())
0083 {
0084   return FindAllRootsWithDerivativeImpl(theFunc, theLower, theUpper, theConfig);
0085 }
0086
0087 //! Convenience alias using default configuration.
0088 //! @tparam Function type with Value(double, double&) method
0089 //! @param theFunc function to find roots of
0090 //! @param theLower lower bound
0091 //! @param theUpper upper bound
0092 //! @param theNbSamples number of sample points
0093 //! @return result with all found roots
0094 template <typename Function>
0095 MultipleResult FindAllRoots(Function& theFunc, double theLower, double theUpper, int theNbSamples)
0096 {
0097   MultipleConfig aConfig;
0098   aConfig.NbSamples = theNbSamples;
0099   return FindAllRoots(theFunc, theLower, theUpper, aConfig);
0100 }
0101
0102 } // namespace MathRoot
0103
0104 #endif // _MathRoot_Multiple_HeaderFile