Skip to content

Commit dd1fe1a

Browse files
tamaskistamaskis
committed
major function simplification, updated documentation
1 parent d530d60 commit dd1fe1a

5 files changed

Lines changed: 69 additions & 124 deletions

File tree

‎EXAMPLES.mlx‎

540 Bytes
Binary file not shown.

‎Fixed_Point_Iteration.pdf‎

-174 KB
Binary file not shown.

‎README.md‎

Lines changed: 13 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,26 +1,30 @@
11
# `fixed_point_iteration` [![View Fixed Point Iteration (fixed_point_iteration) on File Exchange](https://www.mathworks.com/matlabcentral/images/matlab-file-exchange.svg)](https://www.mathworks.com/matlabcentral/fileexchange/86992-fixed-point-iteration-fixed_point_iteration)
22

3-
Calculates the fixed point of a univariate, scalar-valued function using fixed-point iteration.
3+
Fixed-point iteration for finding the fixed point of a univariate, scalar-valued function.
44

55

66
## Syntax
77

88
`c = fixed_point_iteration(f,x0)`\
9-
`c = fixed_point_iteration(f,x0,opts)`
9+
`c = fixed_point_iteration(f,x0,opts)`\
10+
`[c,k] = fixed_point_iteration(__)`\
11+
`[c,k,c_all] = fixed_point_iteration(__)`
1012

1113

1214
## Description
1315

14-
`c = fixed_point_iteration(f,x0)` returns the fixed point of a function <img src="https://latex.codecogs.com/svg.latex?\inline&space;f(x)" title="f(x)" /> specified by the function handle `f`, where `x0` is an initial guess of the fixed point. The default tolerance and maximum number of iterations are `TOL = 1e-12` and `imax = 1e6`, respectively.
16+
`c = fixed_point_iteration(f,x0)` returns the fixed point of a function <img src="https://latex.codecogs.com/svg.latex?\inline&space;f(x)" title="f(x)" /> specified by the function handle `f`, where `x0` is an initial guess of the fixed point.
1517

16-
`c = fixed_point_iteration(f,x0,opts)` does the same as the syntax above, but allows for the specification of optional solver parameters. `opts` is a structure that has the following fields:
17-
- `imax` &rightarrow; maximum number of iterations (defaults to <img src="https://latex.codecogs.com/svg.latex?\inline&space;10^{6}" title="" />)
18-
- `return_all` &rightarrow; all intermediate fixed point estimates are returned if set to `true`; otherwise, only the converged fixed point is returned (defaults to `false`)
19-
- `TOL` &rightarrow; tolerance (defaults to <img src="https://latex.codecogs.com/svg.latex?\inline&space;10^{-12}" title="" />)
20-
- `warnings` &rightarrow; `true` if any warnings should be displayed, `false` if not (defaults to `true`)
18+
`c = fixed_point_iteration(f,x0,opts)` does the same as the syntax above, but allows for the specification of optional solver parameters. `opts` is a structure with the following fields:
19+
- `k_max` &rightarrow; maximum number of iterations (defaults to 200)
20+
- `return_all` &rightarrow; returns estimates at all iteration if set to `true` (defaults to `false`)
21+
- `TOL` &rightarrow; tolerance (defaults to <img src="https://latex.codecogs.com/svg.latex?\inline&space;10^{-10}" title="" />)
2122

23+
`[c,k] = fixed_point_iteration(__)` also returns the number of iterations (`k`) performed of fixed-point iteration.
24+
25+
`[c,k,c_all] = fixed_point_iteration(__)` does the same as the previous syntaxes, but also returns an array (`c_all`) storing the fixed point estimates at each iteration. This syntax requires that `opts.return_all` be set to true.
2226

2327
## Examples and Additional Documentation
2428

2529
- See "EXAMPLES.mlx" or the "Examples" tab on the File Exchange page for examples.
26-
- See ["Fixed_Point_Iteration.pdf"](https://tamaskis.github.io/documentation/Fixed_Point_Iteration.pdf) (also included with download) for the technical documentation.
30+
- See ["Root_Finding_Methods.pdf"](https://tamaskis.github.io/documentation/Root_Finding_Methods.pdf) (also included with download) for the technical documentation.

‎Root_Finding_Methods.pdf‎

287 KB
Binary file not shown.

‎fixed_point_iteration.m‎

Lines changed: 56 additions & 115 deletions
Original file line numberDiff line numberDiff line change
@@ -1,170 +1,111 @@
11
%==========================================================================
22
%
3-
% fixed_point_iteration Calculates the fixed point of a univariate,
4-
% scalar-valued function using fixed-point iteration.
3+
% fixed_point_iteration Fixed-point iteration for finding the fixed point
4+
% of a univariate, scalar-valued function.
55
%
66
% c = fixed_point_iteration(f,x0)
77
% c = fixed_point_iteration(f,x0,opts)
8+
% [c,k] = fixed_point_iteration(__)
9+
% [c,k,c_all] = fixed_point_iteration(__)
810
%
9-
% See also fzero, bisection_method, newtons_method, secant_method.
10-
%
11-
% Copyright © 2021 Tamas Kis
12-
% Last Update: 2021-12-27
11+
% Copyright © 2022 Tamas Kis
12+
% Last Update: 2022-04-20
1313
% Website: https://tamaskis.github.io
1414
% Contact: tamas.a.kis@outlook.com
1515
%
1616
% TECHNICAL DOCUMENTATION:
17-
% https://tamaskis.github.io/documentation/Fixed_Point_Iteration.pdf
18-
%
19-
% REFERENCES:
20-
% [1] Burden and Faires, "Numerical Analysis", 9th Ed. (pp. 56-66)
17+
% https://tamaskis.github.io/documentation/Root_Finding_Methods.pdf
2118
%
2219
%--------------------------------------------------------------------------
2320
%
2421
% ------
2522
% INPUT:
2623
% ------
27-
% f - (1×1 function_handle) univariate, scalar-valued function f(x)
28-
% (f:R->R)
24+
% f - (1×1 function_handle) univariate, scalar-valued function,
25+
% f(x) (f : ℝ → ℝ)
2926
% x0 - (1×1 double) initial guess for fixed point
30-
% opts - (OPTIONAL) (1×1 struct) solver options
31-
% • imax - (1×1 double) maximimum number of iterations
32-
% (defaults to 1e6)
33-
% • return_all - (1×1 logical) all intermediate fixed point estimates
34-
% are returned if set to "true"; otherwise, a faster
35-
% algorithm is used to return only the converged fixed
36-
% point (defaults to false)
37-
% • TOL - (1×1 double) tolerance (defaults to 1e-12)
38-
% • warnings - (1×1 logical) true if any warnings should be
39-
% displayed, false if not (defaults to true)
27+
% opts - (1×1 struct) (OPTIONAL) solver options
28+
% • k_max - (1×1 double) maximimum number of iterations
29+
% (defaults to 200)
30+
% • return_all - (1×1 logical) returns estimates at all iterations if
31+
% set to "true"
32+
% • TOL - (1×1 double) tolerance (defaults to 10⁻¹⁰)
4033
%
4134
% -------
4235
% OUTPUT:
4336
% -------
44-
% c - (1×1 double or 1D double array) fixed point of f(x)
45-
% --> If "return_all" is specified as "true", then "c" will
46-
% be a vector, where the first element is the initial
47-
% guess, the last element is the converged fixed point,
48-
% and the other elements are intermediate estimates of
49-
% the fixed point.
50-
% --> Otherwise, "c" is a single number storing the converged
51-
% fixed point.
37+
% c - (1×1 double) fixed point of f(x)
38+
% k - (1×1 double) number of solver iterations
39+
% c_all - (1×(k+1) double) fixed point estimates at all iterations
5240
%
5341
%==========================================================================
54-
function c = fixed_point_iteration(f,x0,opts)
42+
function [c,k,c_all] = fixed_point_iteration(f,x0,opts)
5543

5644
% ----------------------------------
5745
% Sets (or defaults) solver options.
5846
% ----------------------------------
5947

60-
% sets maximum number of iterations (defaults to 1e6)
61-
if (nargin < 3) || isempty(opts) || ~isfield(opts,'imax')
62-
imax = 1e6;
48+
% sets maximum number of iterations (defaults to 200)
49+
if (nargin < 3) || isempty(opts) || ~isfield(opts,'k_max')
50+
k_max = 200;
6351
else
64-
imax = opts.imax;
52+
k_max = opts.k_max;
6553
end
6654

67-
% determines return value (defaults to only return converged root)
55+
% determines if all intermediate estimates should be returned
6856
if (nargin < 3) || isempty(opts) || ~isfield(opts,'return_all')
6957
return_all = false;
7058
else
7159
return_all = opts.return_all;
7260
end
7361

74-
% sets tolerance (defaults to 1e-12)
62+
% sets tolerance (defaults to 10⁻¹⁰)
7563
if (nargin < 3) || isempty(opts) || ~isfield(opts,'TOL')
76-
TOL = 1e-12;
64+
TOL = 1e-10;
7765
else
7866
TOL = opts.TOL;
7967
end
8068

81-
% determines if warnings should be displayed (defaults to true)
82-
if (nargin < 3) || isempty(opts) || ~isfield(opts,'warnings')
83-
warnings = true;
84-
else
85-
warnings = opts.warnings;
86-
end
69+
% ----------------------
70+
% Fixed-point iteration.
71+
% ----------------------
8772

88-
% -----------------------------------------------------
89-
% "Return all" implementation of fixed-point iteration.
90-
% -----------------------------------------------------
73+
% fixed point estimate at first iteration
74+
x_curr = x0;
9175

76+
% preallocates array
9277
if return_all
93-
94-
% preallocates x
95-
x = zeros(imax,1);
96-
97-
% inputs initial guess for fixed point into x vector
98-
x(1) = x0;
99-
100-
% initializes the error so the loop will be entered
101-
err = 2*TOL;
102-
103-
% fixed-point iteration
104-
i = 1;
105-
while (err > TOL) && (i < imax)
106-
107-
% updates estimate of fixed point
108-
x(i+1) = f(x(i));
109-
110-
% calculates error
111-
err = abs(x(i+1)-x(i));
112-
113-
% increments loop index
114-
i = i+1;
115-
116-
end
117-
118-
% returns converged fixed point along with intermediate fixed point
119-
% estimates
120-
c = x(1:i);
121-
122-
% -----------------------------------------------
123-
% "Fast" implementation of fixed-point iteration.
124-
% -----------------------------------------------
78+
c_all = zeros(1,k_max+1);
79+
end
12580

126-
else
127-
128-
% sets fixed point estimate at the first iteration of the fixed
129-
% point iteration as the initial guess
130-
x_old = x0;
81+
% fixed-point iteration
82+
for k = 1:k_max
13183

132-
% initializes x_new so its scope isn't limited to the while loop
133-
x_new = 0;
134-
135-
% initializes the error so the loop will be entered
136-
err = 2*TOL;
137-
138-
% fixed-point iteration
139-
i = 1;
140-
while (err > TOL) && (i < imax)
141-
142-
% updates estimate of fixed point
143-
x_new = f(x_old);
84+
% stores results in arrays
85+
if return_all
86+
c_all(k) = x_curr;
87+
end
14488

145-
% calculates error
146-
err = abs(x_new-x_old);
147-
148-
% stores current fixed point estimate for next iteration
149-
x_old = x_new;
89+
% updates estimate of fixed point
90+
x_next = f(x_curr);
15091

151-
% increments loop index
152-
i = i+1;
153-
92+
% terminates solver if converged
93+
if (abs(x_next-x_curr) < TOL)
94+
break;
15495
end
15596

156-
% returns converged fixed point
157-
c = x_new;
97+
% stores updated fixed point estimate for next iteration
98+
x_curr = x_next;
15899

159100
end
160-
161-
% ---------------------------------------------------------
162-
% Displays warning if maximum number of iterations reached.
163-
% ---------------------------------------------------------
164-
165-
if (i == imax) && warnings
166-
warning(strcat('The method failed after i=',num2str(imax),...
167-
' iterations.'));
101+
102+
% converged fixed point
103+
c = x_next;
104+
105+
% stores converged result and trims array
106+
if return_all
107+
c_all(k+1) = c;
108+
c_all = c_all(1:(k+1));
168109
end
169-
110+
170111
end

0 commit comments

Comments
 (0)