0027371: Regression: BRepExtrema works too much slower in 691 (from 670)
[occt.git] / src / math / math_GlobOptMin.hxx
index 4e65293..e986811 100644 (file)
 #include <NCollection_Sequence.hxx>
 #include <Standard_Type.hxx>
 
-class NCollection_CellFilter_Inspector
-{
-public:
-
-  //! Points and target type
-  typedef math_Vector Point;
-  typedef math_Vector Target;
-
-  NCollection_CellFilter_Inspector(const Standard_Integer theDim,
-                                   const Standard_Real theTol)
-  : myCurrent(1, theDim)
-  {
-    myTol = theTol * theTol;
-    myIsFind = Standard_False;
-    Dimension = theDim;
-  }
-
-  //! Access to co-ordinate
-  static Standard_Real Coord (int i, const Point &thePnt)
-  {
-    return thePnt(i + 1);
-  }
-
-  //! Auxiliary method to shift point by each coordinate on given value;
-  //! useful for preparing a points range for Inspect with tolerance
-  void Shift (const Point& thePnt,
-              const NCollection_Array1<Standard_Real> &theTol,
-              Point& theLowPnt,
-              Point& theUppPnt) const
-  {
-    for(Standard_Integer anIdx = 1; anIdx <= Dimension; anIdx++)
-    {
-      theLowPnt(anIdx) = thePnt(anIdx) - theTol(anIdx - 1);
-      theUppPnt(anIdx) = thePnt(anIdx) + theTol(anIdx - 1);
-    }
-  }
-
-  void ClearFind()
-  {
-    myIsFind = Standard_False;
-  }
-
-  Standard_Boolean isFind()
-  {
-    return myIsFind;
-  }
-
-  //! Set current point to search for coincidence
-  void SetCurrent (const math_Vector& theCurPnt)
-  { 
-    myCurrent = theCurPnt;
-  }
-
-  //! Implementation of inspection method
-  NCollection_CellFilter_Action Inspect (const Target& theObject)
-  {
-    Standard_Real aSqDist = (myCurrent - theObject).Norm2();
-
-    if(aSqDist < myTol)
-    {
-      myIsFind = Standard_True;
-    }
-
-    return CellFilter_Keep;
-  }
-
-private:
-  Standard_Real myTol;
-  math_Vector myCurrent;
-  Standard_Boolean myIsFind;
-  Standard_Integer Dimension;
-};
-
-//! This class represents Evtushenko's algorithm of global optimization based on nonuniform mesh.<br>
-//! Article: Yu. Evtushenko. Numerical methods for finding global extreme (case of a non-uniform mesh). <br>
+//! This class represents Evtushenko's algorithm of global optimization based on non-uniform mesh.
+//! Article: Yu. Evtushenko. Numerical methods for finding global extreme (case of a non-uniform mesh).
 //! U.S.S.R. Comput. Maths. Math. Phys., Vol. 11, N 6, pp. 38-54.
-
+//!
+//! This method performs search on non-uniform mesh. The search space is a box in R^n space.
+//! The default behavior is to find all minimums in that box. Computation of maximums is not supported.
+//!
+//! The search box can be split into smaller boxes by discontinuity criteria.
+//! This functionality is covered by SetGlobalParams and SetLocalParams API.
+//!
+//! It is possible to set continuity of the local boxes.
+//! Such option can forcibly change local extrema search.
+//! In other words if theFunc can be casted to the function with Hessian but, continuity is set to 1
+//! Gradient based local optimization method will be used, not Hessian based method.
+//! This functionality is covered by SetContinuity and GetContinuity API.
+//!
+//! It is possible to freeze Lipschitz const to avoid internal modifications on it.
+//! This functionality is covered by SetLipConstState and GetLipConstState API.
+//!
+//! It is possible to perform single solution search.
+//! This functionality is covered by first parameter in Perform method.
+//!
+//! It is possible to set / get minimal value of the functional.
+//! It works well together with single solution search.
+//! This functionality is covered by SetFunctionalMinimalValue and GetFunctionalMinimalValue API.
 class math_GlobOptMin
 {
 public:
 
+  //! Constructor. Perform method is not called from it.
+  //! @param theFunc - objective functional.
+  //! @param theLowerBorder - lower corner of the search box.
+  //! @param theUpperBorder - upper corner of the search box.
+  //! @param theC - Lipschitz constant.
+  //! @param theDiscretizationTol - parameter space discretization tolerance.
+  //! @param theSameTol - functional value space indifference tolerance.
   Standard_EXPORT math_GlobOptMin(math_MultipleVarFunction* theFunc,
                                  const math_Vector& theLowerBorder,
                                  const math_Vector& theUpperBorder,
@@ -111,6 +66,12 @@ public:
                                  const Standard_Real theDiscretizationTol = 1.0e-2,
                                  const Standard_Real theSameTol = 1.0e-7);
 
+  //! @param theFunc - objective functional.
+  //! @param theLowerBorder - lower corner of the search box.
+  //! @param theUpperBorder - upper corner of the search box.
+  //! @param theC - Lipschitz constant.
+  //! @param theDiscretizationTol - parameter space discretization tolerance.
+  //! @param theSameTol - functional value space indifference tolerance.
   Standard_EXPORT void SetGlobalParams(math_MultipleVarFunction* theFunc,
                                        const math_Vector& theLowerBorder,
                                        const math_Vector& theUpperBorder,
@@ -118,47 +79,129 @@ public:
                                        const Standard_Real theDiscretizationTol = 1.0e-2,
                                        const Standard_Real theSameTol = 1.0e-7);
 
+  //! Method to reduce bounding box. Perform will use this box.
+  //! @param theLocalA - lower corner of the local box.
+  //! @param theLocalB - upper corner of the local box.
   Standard_EXPORT void SetLocalParams(const math_Vector& theLocalA,
                                       const math_Vector& theLocalB);
 
+  //! Method to set tolerances.
+  //! @param theDiscretizationTol - parameter space discretization tolerance.
+  //! @param theSameTol - functional value space indifference tolerance.
   Standard_EXPORT void SetTol(const Standard_Real theDiscretizationTol,
                               const Standard_Real theSameTol);
 
+  //! Method to get tolerances.
+  //! @param theDiscretizationTol - parameter space discretization tolerance.
+  //! @param theSameTol - functional value space indifference tolerance.
   Standard_EXPORT void GetTol(Standard_Real& theDiscretizationTol,
                               Standard_Real& theSameTol);
 
-  Standard_EXPORT ~math_GlobOptMin();
-
   //! @param isFindSingleSolution - defines whether to find single solution or all solutions.
   Standard_EXPORT void Perform(const Standard_Boolean isFindSingleSolution = Standard_False);
 
+  //! Return solution theIndex, 1 <= theIndex <= NbExtrema.
+  Standard_EXPORT void Points(const Standard_Integer theIndex, math_Vector& theSol);
+
+  //! Set / Get continuity of local borders splits (0 ~ C0, 1 ~ C1, 2 ~ C2).
+  inline void SetContinuity(const Standard_Integer theCont) { myCont = theCont; }
+  inline Standard_Integer GetContinuity() const {return myCont; }
+
+    //! Set / Get functional minimal value.
+  inline void SetFunctionalMinimalValue(const Standard_Real theMinimalValue)
+  { myFunctionalMinimalValue = theMinimalValue; }
+  inline Standard_Real GetFunctionalMinimalValue() const {return myFunctionalMinimalValue;}
+
+  //! Set / Get Lipchitz constant modification state. 
+  //! True means that the constant is locked and unlocked otherwise.
+  inline void SetLipConstState(const Standard_Boolean theFlag) {myIsConstLocked = theFlag; }
+  inline Standard_Boolean GetLipConstState() const { return myIsConstLocked; }
+
+  //! Return computation state of the algorithm.
+  inline Standard_Boolean isDone() const {return myDone; }
+
   //! Get best functional value.
-  Standard_EXPORT Standard_Real GetF();
+  inline Standard_Real GetF() const {return myF;}
 
   //! Return count of global extremas.
-  Standard_EXPORT Standard_Integer NbExtrema();
+  inline Standard_Integer NbExtrema() const {return mySolCount;}
 
-  //! Return solution theIndex, 1 <= theIndex <= NbExtrema.
-  Standard_EXPORT void Points(const Standard_Integer theIndex, math_Vector& theSol);
+private:
 
-  Standard_EXPORT Standard_Boolean isDone();
+  //! Class for duplicate fast search. For internal usage only.
+  class NCollection_CellFilter_Inspector
+  {
+  public:
 
-  //! Set functional minimal value.
-  Standard_EXPORT void SetFunctionalMinimalValue(const Standard_Real theMinimalValue);
+    //! Points and target type
+    typedef math_Vector Point;
+    typedef math_Vector Target;
 
-  //! Lock/Unlock Lipchitz constant for internal modifications.
-  Standard_EXPORT void SetLipConstState(const Standard_Boolean theFlag);
+    NCollection_CellFilter_Inspector(const Standard_Integer theDim,
+                                     const Standard_Real theTol)
+      : myCurrent(1, theDim)
+    {
+      myTol = theTol * theTol;
+      myIsFind = Standard_False;
+      Dimension = theDim;
+    }
 
-  //! Get functional minimal value.
-  Standard_EXPORT Standard_Real GetFunctionalMinimalValue();
+    //! Access to coordinate.
+    static Standard_Real Coord (int i, const Point &thePnt)
+    {
+      return thePnt(i + 1);
+    }
 
-  //! Get continuity of local borders splits.
-  inline Standard_Integer GetContinuity() const {return myCont; }
+    //! Auxiliary method to shift point by each coordinate on given value;
+    //! useful for preparing a points range for Inspect with tolerance.
+    void Shift (const Point& thePnt,
+                const NCollection_Array1<Standard_Real> &theTol,
+                Point& theLowPnt,
+                Point& theUppPnt) const
+    {
+      for(Standard_Integer anIdx = 1; anIdx <= Dimension; anIdx++)
+      {
+        theLowPnt(anIdx) = thePnt(anIdx) - theTol(anIdx - 1);
+        theUppPnt(anIdx) = thePnt(anIdx) + theTol(anIdx - 1);
+      }
+    }
 
-  //! Set continuity of local borders splits.
-  inline void SetContinuity(const Standard_Integer theCont) { myCont = theCont; }
+    void ClearFind()
+    {
+      myIsFind = Standard_False;
+    }
+
+    Standard_Boolean isFind()
+    {
+      return myIsFind;
+    }
+
+    //! Set current point to search for coincidence
+    void SetCurrent (const math_Vector& theCurPnt)
+    { 
+      myCurrent = theCurPnt;
+    }
+
+    //! Implementation of inspection method
+    NCollection_CellFilter_Action Inspect (const Target& theObject)
+    {
+      Standard_Real aSqDist = (myCurrent - theObject).Norm2();
+
+      if(aSqDist < myTol)
+      {
+        myIsFind = Standard_True;
+      }
+
+      return CellFilter_Keep;
+    }
+
+  private:
+    Standard_Real myTol;
+    math_Vector myCurrent;
+    Standard_Boolean myIsFind;
+    Standard_Integer Dimension;
+  };
 
-private:
 
   // Compute cell size.
   void initCellSize();
@@ -173,14 +216,14 @@ private:
   void computeGlobalExtremum(Standard_Integer theIndex);
 
   //! Check possibility to stop computations.
-  //! Find single solution + in neighbourhood of best possible solution.
+  //! Find single solution + in neighborhood of best possible solution.
   Standard_Boolean CheckFunctionalStopCriteria();
 
   //! Computes starting value / approximation:
   //! myF - initial best value.
   //! myY - initial best point.
   //! myC - approximation of Lipschitz constant.
-  //! to imporve convergence speed.
+  //! to improve convergence speed.
   void computeInitialValues();
 
   //! Check that myA <= thePnt <= myB
@@ -213,7 +256,7 @@ private:
 
   // Algorithm data.
   Standard_Real myZ;
-  Standard_Real myE1; // Border coeff.
+  Standard_Real myE1; // Border coefficient.
   Standard_Real myE2; // Minimum step size.
   Standard_Real myE3; // Local extrema starting parameter.
 
@@ -222,7 +265,6 @@ private:
   math_Vector myV; // Steps array.
   math_Vector myMaxV; // Max Steps array.
   Standard_Real myLastStep; // Last step.
-  math_Vector myExpandCoeff; // Define expand coefficient between neighboring indiced dimensions.
 
   NCollection_Array1<Standard_Real> myCellSize;
   Standard_Integer myMinCellFilterSol;