OCCT

# MathOpt Package

The MathOpt package provides optimization and minimization algorithms for scalar and vector functions in the OCCT mathematical library.

## Overview

This package contains template-based implementations of various optimization algorithms for finding minima of functions. The algorithms are designed to be flexible and work with user-defined function objects.

## Algorithms

### 1D Minimization (MathOpt_Brent.hxx)

- **Brent**: Combines golden-section search with parabolic interpolation for bounded 1D minimization
- **Golden**: Contracts a bounded 1D interval using golden-section steps
- **BrentWithBracket**: Automatic bracket search followed by Brent's method

### Gradient-Free N-D Optimization

- **Powell** (MathOpt_Powell.hxx): Conjugate direction method without derivatives
- **PSO** (MathOpt_PSO.hxx): Particle Swarm Optimization for global search
- **DifferentialEvolution** (MathOpt_GlobOpt.hxx): Evolutionary algorithm for global optimization
- **MultiStart** (MathOpt_GlobOpt.hxx): Multiple local searches from random starts

### Gradient-Based N-D Optimization

- **BFGS** (MathOpt_BFGS.hxx): Quasi-Newton method with Armijo backtracking
- **L-BFGS** (MathOpt_BFGS.hxx): Limited-memory BFGS for large-scale problems
- **FRPR** (MathOpt_FRPR.hxx): Fletcher-Reeves-Polak-Ribiere conjugate gradient
- **Newton** (MathOpt_Newton.hxx): Hessian-based method with line search

### Constrained Optimization

- **Uzawa** (MathOpt_Uzawa.hxx): Constrained least squares with equality/inequality constraints

## Usage

All algorithms are implemented as template functions in the `MathOpt` namespace:

```cpp
#include <MathOpt_BFGS.hxx>

// Define function with Value and Gradient methods
class MyFunction
{
public:
  bool Value(const math_Vector& theX, double& theF);
  bool Gradient(const math_Vector& theX, math_Vector& theGrad);
};

// Use BFGS optimization
MyFunction aFunc;
math_Vector aStart(size_t{2});
aStart[0] = 0.0;
aStart[1] = 0.0;

MathOpt::VectorResult aResult = MathOpt::BFGS(aFunc, aStart);
if (aResult.IsDone())
{
  const math_Vector& aSolution = *aResult.Solution;
  double aMinValue = *aResult.Value;
}
```

## Dependencies

- MathUtils_Types.hxx - Common types (Status, Config, Result structs)
- MathUtils_Config.hxx - Configuration structures
- MathUtils_Core.hxx - Core utilities
- MathUtils_LineSearch.hxx - Line search algorithms
- MathUtils_Deriv.hxx - Numerical differentiation
- MathUtils_Bracket.hxx - Bracket finding utilities
- MathLin_*.hxx - Linear algebra solvers

MathOpt reads input vectors positionally, regardless of their lower bounds, and returns zero-based
result vectors. Dimensions and indices use `size_t`; bounded iteration counters stored in
configurations and results use `uint32_t`.

`PSO`, `DifferentialEvolution`, `MultiStart`, and `PSOHybrid` treat lower and upper vectors as
inclusive box bounds; objective callbacks are evaluated only inside that box. Stochastic candidate
evaluations that report failure are rejected without invalidating an existing finite best candidate.
If PSO or Differential Evolution exhausts `MaxIterations` before its stopping criterion, the result
has status `MaxIterations` while retaining the best-so-far `Solution` and `Value`. A seed particle's
optional `Value` is advisory only: PSO always evaluates the callback at the clamped seed position.

`Config::Tolerance`, `Config::XTolerance`, and `Config::FTolerance` are independent after
construction. Assigning one field does not update the others.

For BFGS, `FTolerance` is the absolute gradient-norm tolerance. If the coordinate step reaches
`XTolerance`, `RelativeTolerance` additionally scales the initial gradient norm; a small objective
change alone is not treated as convergence because it depends on the arbitrary objective offset.