Skip to content

Commit 018f99d

Browse files
lformaggialformaggia
committed
added explanations
1 parent 659e3e1 commit 018f99d

4 files changed

Lines changed: 514 additions & 0 deletions

File tree

‎Examples/src/LinearAlgebraUtil/basicOptimization_Explanation.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Basic Optimization Utilities
2+
3+
## Overview
4+
The `basicOptimization.hpp` file provides implementations of optimization algorithms for finding local and global minima of functions. These algorithms are designed for continuous functions and leverage modern C++ features such as concepts and the ranges library. The file includes:
5+
6+
- Golden section search for unimodal functions.
7+
- Bracketing methods to identify intervals containing minima.
8+
- Brent's method for both local and global minimization.
9+
10+
## Key Functions
11+
12+
### 1. `golden_search`
13+
This function implements the golden section search algorithm to find the extremum of a unimodal function within a specified interval.
14+
15+
#### Template Parameters:
16+
- `Function`: A callable object with the signature `double(double)` or `double(const double&)`.
17+
18+
#### Parameters:
19+
- `f`: The function to minimize.
20+
- `a`, `b`: The endpoints of the interval.
21+
- `tol`: Desired tolerance for the result.
22+
- `maxIter`: Maximum number of iterations to safeguard against non-convergence.
23+
24+
#### Returns:
25+
- A tuple containing the estimated extremum and a boolean indicating convergence.
26+
27+
#### Example:
28+
```cpp
29+
auto [min, converged] = golden_search([](double x) { return x * x; }, -1.0, 1.0);
30+
```
31+
32+
### 2. `bracketIntervalMinimum`
33+
This function attempts to find an interval containing a minimum of a continuous function.
34+
35+
#### Template Parameters:
36+
- `Function`: A callable object with the signature `double(double)`.
37+
38+
#### Parameters:
39+
- `f`: The function to analyze.
40+
- `x1`: Initial guess for the minimum.
41+
- `h`: Initial increment.
42+
- `maxIter`: Maximum number of iterations.
43+
44+
#### Returns:
45+
- A tuple containing the bracket points and a status code:
46+
- `0`: Success.
47+
- `1`: Bad initial point.
48+
- `2`: Maximum iterations exceeded.
49+
50+
#### Example:
51+
```cpp
52+
auto [x1, x2, status] = bracketIntervalMinimum([](double x) { return x * x; }, 0.0);
53+
```
54+
55+
### 3. `Brent_glomin`
56+
This function implements Brent's method for global minimization of a function over a specified interval.
57+
58+
#### Parameters:
59+
- `a`, `b`: Endpoints of the interval.
60+
- `c`: Initial guess for the global minimizer.
61+
- `m`: Estimate of the bound on the second derivative.
62+
- `e`: Absolute error tolerance for function evaluation.
63+
- `t`: Absolute error tolerance for the result.
64+
- `f`: The function to minimize.
65+
66+
#### Returns:
67+
- A tuple containing the estimated global minimizer and the function value at that point.
68+
69+
#### Example:
70+
```cpp
71+
auto [x, fx] = Brent_glomin(0.0, 1.0, 0.5, 1.0, 1e-5, 1e-5, [](double x) { return x * x; });
72+
```
73+
74+
### 4. `Brent_local_min`
75+
This function implements Brent's method for local minimization of a function over a specified interval.
76+
77+
#### Parameters:
78+
- `a`, `b`: Endpoints of the interval.
79+
- `t`: Absolute error tolerance for the result.
80+
- `f`: The function to minimize.
81+
82+
#### Returns:
83+
- A tuple containing the estimated local minimizer and the function value at that point.
84+
85+
#### Example:
86+
```cpp
87+
auto [x, fx] = Brent_local_min(0.0, 1.0, 1e-5, [](double x) { return x * x; });
88+
```
89+
90+
## C++ Features Used
91+
92+
### 1. **Concepts**
93+
The file uses concepts to constrain the template parameter for functions. The `TypeTraits::ScalarFunction` concept ensures that the provided callable objects have the correct signature.
94+
95+
### 2. **`std::numbers`**
96+
The `std::numbers` library is used to access mathematical constants like the golden ratio.
97+
98+
### 3. **Modern C++ Style**
99+
The code adopts modern C++ practices, including:
100+
- Use of `constexpr` for compile-time constants.
101+
- Structured bindings for returning multiple values.
102+
- Use of `std::tuple` and `std::array` for returning results.
103+
104+
## Usage Notes
105+
106+
1. **Function Requirements**:
107+
- The functions must be continuous and differentiable.
108+
- For `Brent_glomin`, the second derivative must be bounded.
109+
110+
2. **Convergence**:
111+
- The algorithms assume that the minimum lies within the specified interval.
112+
- No explicit convergence guarantees are provided for `Brent_glomin`.
113+
114+
3. **Performance**:
115+
- The algorithms are efficient for unimodal functions.
116+
- For non-unimodal functions, results may vary.
117+
118+
## Conclusion
119+
The `basicOptimization.hpp` file provides robust and efficient implementations of optimization algorithms, leveraging modern C++ features for clarity and performance. These utilities are suitable for a wide range of applications requiring function minimization.

‎Examples/src/LinearAlgebraUtil/basicZeroFun_Explanation.md‎

Lines changed: 149 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,149 @@
1+
# Basic Zero-Finding Utilities
2+
3+
## Overview
4+
The `basicZeroFun.hpp` file provides implementations of numerical methods for finding zeros of scalar functions. These methods are designed for continuous functions and include classical root-finding algorithms such as:
5+
6+
- Regula Falsi
7+
- Bisection
8+
- Secant
9+
- Newton
10+
- Brent's method
11+
12+
The file also includes a utility for bracketing intervals that contain zeros. Modern C++ features, such as concepts, are used to ensure type safety and flexibility.
13+
14+
## Key Functions
15+
16+
### 1. `regulaFalsi`
17+
This function implements the Regula Falsi method, a bracketing method for finding zeros of a function.
18+
19+
#### Template Parameters:
20+
- `Function`: A callable object with the signature `double(double)` or `double(const double&)`.
21+
22+
#### Parameters:
23+
- `f`: The function to find the zero of.
24+
- `a`, `b`: The endpoints of the initial interval.
25+
- `tol`: Relative tolerance.
26+
- `tola`: Absolute tolerance.
27+
28+
#### Returns:
29+
- The approximated zero of the function.
30+
31+
#### Example:
32+
```cpp
33+
double root = regulaFalsi([](double x) { return x * x - 2; }, 0.0, 2.0);
34+
```
35+
36+
### 2. `bisection`
37+
This function implements the Bisection method, a robust bracketing method for finding zeros.
38+
39+
#### Parameters:
40+
- `f`: The function to find the zero of.
41+
- `a`, `b`: The endpoints of the initial interval.
42+
- `tol`: Tolerance for the result.
43+
44+
#### Returns:
45+
- The approximated zero of the function.
46+
47+
#### Example:
48+
```cpp
49+
double root = bisection([](double x) { return x * x - 2; }, 0.0, 2.0);
50+
```
51+
52+
### 3. `secant`
53+
This function implements the Secant method, which uses linear interpolation to find zeros.
54+
55+
#### Parameters:
56+
- `f`: The function to find the zero of.
57+
- `a`, `b`: Initial points for the method.
58+
- `tol`: Relative tolerance.
59+
- `tola`: Absolute tolerance.
60+
- `maxIt`: Maximum number of iterations.
61+
62+
#### Returns:
63+
- A tuple containing the approximated zero and a boolean indicating convergence.
64+
65+
#### Example:
66+
```cpp
67+
auto [root, converged] = secant([](double x) { return x * x - 2; }, 0.0, 2.0);
68+
```
69+
70+
### 4. `Newton`
71+
This function implements Newton's method, which uses the derivative of the function to find zeros.
72+
73+
#### Parameters:
74+
- `f`: The function to find the zero of.
75+
- `df`: The derivative of the function.
76+
- `a`: Initial guess for the zero.
77+
- `tol`: Relative tolerance.
78+
- `tola`: Absolute tolerance.
79+
- `maxIt`: Maximum number of iterations.
80+
81+
#### Returns:
82+
- A tuple containing the approximated zero and a boolean indicating convergence.
83+
84+
#### Example:
85+
```cpp
86+
auto [root, converged] = Newton([](double x) { return x * x - 2; }, [](double x) { return 2 * x; }, 1.0);
87+
```
88+
89+
### 5. `bracketInterval`
90+
This function attempts to find an interval that brackets a zero of a function.
91+
92+
#### Parameters:
93+
- `f`: The function to analyze.
94+
- `x1`: Initial point.
95+
- `h`: Initial increment for sampling.
96+
- `maxIter`: Maximum number of iterations.
97+
98+
#### Returns:
99+
- A tuple containing the bracketing points and a boolean indicating success.
100+
101+
#### Example:
102+
```cpp
103+
auto [x1, x2, success] = bracketInterval([](double x) { return x * x - 2; }, 1.0);
104+
```
105+
106+
### 6. `brent_search`
107+
This function implements Brent's method, a combination of bisection, secant, and inverse quadratic interpolation.
108+
109+
#### Parameters:
110+
- `f`: The function to find the zero of.
111+
- `a`, `b`: The endpoints of the bracketing interval.
112+
- `tol`: Tolerance for the result.
113+
- `maxIter`: Maximum number of iterations.
114+
115+
#### Returns:
116+
- A tuple containing the approximated zero and a boolean indicating convergence.
117+
118+
#### Example:
119+
```cpp
120+
auto [root, converged] = brent_search([](double x) { return x * x - 2; }, 0.0, 2.0);
121+
```
122+
123+
## C++ Features Used
124+
125+
### 1. **Concepts**
126+
The file uses concepts to constrain the template parameters for functions. The `TypeTraits::ScalarFunction` concept ensures that the provided callable objects have the correct signature.
127+
128+
### 2. **Modern C++ Practices**
129+
- Use of `std::tuple` for returning multiple values.
130+
- Use of `std::swap` for efficient variable swapping.
131+
- Assertions (`SURE_ASSERT`) to enforce preconditions.
132+
133+
## Usage Notes
134+
135+
1. **Function Requirements**:
136+
- The functions must be continuous.
137+
- For Newton's method, the derivative must be provided.
138+
139+
2. **Convergence**:
140+
- The bracketing methods (`regulaFalsi`, `bisection`, `brent_search`) guarantee convergence if the initial interval brackets a zero.
141+
- The open methods (`secant`, `Newton`) may fail to converge if the initial guesses are poor.
142+
143+
3. **Performance**:
144+
- Brent's method is generally efficient and robust.
145+
- Bisection is the most reliable (if the function is continuous and brackets a zero) but slower.
146+
- Newton's method can be very fast (quadratic convergence for C^2 functions) but requires a good initial guess and the derivative.
147+
148+
## Conclusion
149+
The `basicZeroFun.hpp` file provides a comprehensive set of tools for zero-finding of univariate functions, leveraging modern C++ features for robustness and flexibility. These utilities are suitable for a wide range of applications requiring root-finding algorithms.

‎Examples/src/NonLynSys/NonLinSys_Code_Explanation.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# NonLynSys Folder Documentation
2+
3+
## Overview
4+
The `NonLynSys` folder contains utilities for managing nonlinear systems of equations. It provides a flexible framework for defining systems of scalar functions, evaluating them, and extending their functionality through traits and factories.
5+
6+
## Key Components
7+
8+
### 1. `NonLinSys` Class
9+
The `NonLinSys` class represents a nonlinear system $\mathbb{R}^n \to \mathbb{R}^m$. It stores a collection of m scalar functions $\mathbb{R}^n \to \mathbb{R}$ and provides methods to evaluate the system, add functions, and update existing ones.
10+
11+
#### Template Parameters:
12+
- `R`: The scalar type (default: `double`).
13+
- `Traits`: A traits class defining types used in the system (default: `VectorTraits`).
14+
15+
#### Key Methods:
16+
- `addToSystem`: Adds a scalar function to the system.
17+
- `getFunction`: Retrieves a function by index.
18+
- `updateFunction`: Updates a function at a specific index.
19+
- `operator()`: Evaluates the system for a given input.
20+
21+
#### Example:
22+
```cpp
23+
apsc::NonLinSys<double, ScalarTraits> system;
24+
system.addToSystem([](double const &x) { return x * x; });
25+
std::cout << "Function 0(2.0)=" << system.getFunction(0)(2.0) << std::endl;
26+
```
27+
28+
### 2. `NonLinSysTraits` Namespace
29+
This namespace defines traits for customizing the behavior of `NonLinSys`. Traits specify types for arguments, results, and function containers.
30+
31+
#### Available Traits:
32+
- `VectorTraits`: Uses `std::vector` for arguments and results.
33+
- `EigenVectorTraits`: Uses `Eigen::VectorXd` for arguments and results.
34+
- `ScalarTraits`: Uses scalars as arguments and vectors as results.
35+
36+
#### Example:
37+
```cpp
38+
using EigenTraits = apsc::NonLinSysTraits::EigenVectorTraits<double>;
39+
apsc::NonLinSys<double, EigenTraits> system;
40+
```
41+
42+
### 3. `FunctionFactory` Class
43+
The `FunctionFactory` class extends `NonLinSys` to manage functions with unique string identifiers. It ensures that each function has a unique name and provides methods to retrieve functions by their identifiers.
44+
45+
#### Key Methods:
46+
- `addToFactory`: Adds a function with a unique identifier.
47+
- `getFunction`: Retrieves a function by its identifier.
48+
49+
#### Example:
50+
```cpp
51+
apsc::FunctionFactory<double, ScalarTraits> factory;
52+
factory.addToFactory("sin", [](double const &x) { return std::sin(x); });
53+
std::cout << "sin(3.14)=" << factory.getFunction("sin")(3.14) << std::endl;
54+
```
55+
56+
## Usage Examples
57+
The `main_nls.cpp` file demonstrates the usage of `NonLinSys` and `FunctionFactory`:
58+
59+
1. **Creating a System**:
60+
```cpp
61+
apsc::NonLinSys<double, ScalarTraits> system;
62+
system.addToSystem([](double const &x) { return x * x; });
63+
```
64+
65+
2. **Using Eigen Vectors**:
66+
```cpp
67+
apsc::NonLinSys<double, apsc::NonLinSysTraits::EigenVectorTraits> system2;
68+
system2.addToSystem([](Eigen::VectorXd const &x) { return x.norm(); });
69+
```
70+
71+
3. **Function Factory**:
72+
```cpp
73+
apsc::FunctionFactory<double, ScalarTraits> factory;
74+
factory.addToFactory("cos", [](double const &x) { return std::cos(x); });
75+
```
76+
77+
## Dependencies
78+
- **Eigen**: For linear algebra operations.
79+
- **C++20 Concepts**: Used for type constraints.
80+
- **OpenMP**: Optional, for parallel execution.
81+
82+
## Build Instructions
83+
1. Ensure Eigen is installed.
84+
2. Compile with a C++20-compatible compiler:
85+
```bash
86+
g++ -std=c++20 -fopenmp -I/path/to/eigen main_nls.cpp -o main_nls
87+
```
88+
3. Run the executable:
89+
```bash
90+
./main_nls
91+
```
92+
93+
## Conclusion
94+
The `NonLynSys` folder provides a robust framework for nonlinear systems, leveraging modern C++ features for flexibility and performance. The examples in `main_nls.cpp` illustrate its versatility and ease of use.
95+
96+
## Interaction with other codes
97+
`NonLinSys` may be used in conjunction with the code in `NewtonSolver` for the solution of non-linear system of equations.

0 commit comments

Comments
 (0)