Skip to content

Commit 18f41df

Browse files
tamaskistamaskis
committed
Updated function input parameters, function header, and documentation.
1 parent 7fa8094 commit 18f41df

4 files changed

Lines changed: 84 additions & 52 deletions

File tree

‎EXAMPLES.mlx‎

-628 Bytes
Binary file not shown.

Fixed-Point Iteration.pdf renamed to Fixed_Point_Iteration.pdf

175 KB
Binary file not shown.

‎README.md‎

Lines changed: 8 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -6,26 +6,21 @@ Calculates the fixed point of a univariate function using fixed-point iteration.
66
## Syntax
77

88
`c = fixed_point_iteration(f,x0)`\
9-
`c = fixed_point_iteration(f,x0,TOL)`\
10-
`c = fixed_point_iteration(f,x0,[],imax)`\
11-
`c = fixed_point_iteration(f,x0,TOL,imax)`\
12-
`c = fixed_point_iteration(__,'all')`
9+
`c = fixed_point_iteration(f,x0,opts)`
1310

1411

1512
## Description
1613

1714
`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.
1815

19-
`c = fixed_point_iteration(f,x0,TOL)` 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 and `TOL` is the tolerance. The default maximum number of iterations is `imax = 1e6`.
20-
21-
`c = fixed_point_iteration(f,x0,[],imax)` 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 and `imax` is the maximum number of iterations. The default tolerance is `TOL = 1e-12`.
22-
23-
`c = fixed_point_iteration(f,x0,TOL,imax)` 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, `TOL` is the tolerance, and `imax` is the maximum number of iterations.
24-
25-
`c = fixed_point_iteration(__,'all')` returns a vector, where the first element of this vector is the initial guess, all intermediate elements are the intermediate estimates of the fixed point, and the last element is the converged fixed point. This identifier 'all' may be appended to any of the syntaxes used above.
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 struct that has the following fields:
17+
- `imax` &rightarrow; maximum number of iterations
18+
- `return_all` &rightarrow; all intermediate fixed point estimates are returned if set to `true`; otherwise, only the converged fixed point is returned
19+
- `TOL` &rightarrow; tolerance
20+
- `warnings` &rightarrow; `true` if any warnings should be displayed, `false` if not
2621

2722

2823
## Examples and Additional Documentation
2924

30-
- See "EXAMPLES.mlx" or the "Examples" tab on the File Exchange page for examples.
31-
- See "Fixed-Point Iteration.pdf" (included with download, also available at https://tamaskis.github.io/documentation/Fixed-Point%20Iteration.pdf) for additional documentation.
25+
- 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.

‎fixed_point_iteration.m‎

Lines changed: 76 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -4,72 +4,87 @@
44
% function using fixed-point iteration.
55
%
66
% c = fixed_point_iteration(f,x0)
7-
% c = fixed_point_iteration(f,x0,TOL)
8-
% c = fixed_point_iteration(f,x0,[],imax)
9-
% c = fixed_point_iteration(f,x0,TOL,imax)
10-
% c = fixed_point_iteration(__,'all')
7+
% c = fixed_point_iteration(f,x0,opts)
118
%
129
% Copyright © 2021 Tamas Kis
13-
% Last Update: 2021-07-25
14-
% Website: tamaskis.github.io
10+
% Last Update: 2021-08-28
11+
% Website: https://tamaskis.github.io
1512
% Contact: tamas.a.kis@outlook.com
1613
%
14+
% TECHNICAL DOCUMENTATION:
15+
% https://tamaskis.github.io/documentation/Fixed_Point_Iteration.pdf
16+
%
1717
% REFERENCES:
18-
% [1] https://tamaskis.github.io/documentation/Fixed-Point%20Iteration.pdf
18+
% [1] Burden and Faires, "Numerical Analysis", 9th Ed. (pp. 56-66)
1919
%
2020
%--------------------------------------------------------------------------
2121
%
2222
% ------
2323
% INPUT:
2424
% ------
2525
% f - (function_handle) f(x)
26-
% x0 - (1×1) initial guess for fixed point
27-
% TOL - (OPTIONAL) (1×1) tolerance
28-
% imax - (OPTIONAL) (1×1) maximum number of iterations
29-
% output - (OPTIONAL) (char) if specified as 'all', function will return
30-
% all intermediate fixed point estimates; otherwise, a faster
31-
% algorithm is used to only return the converged fixed point
26+
% x0 - (1×1 double) initial guess for fixed point
27+
% opts - (OPTIONAL) (struct) solver options structure
28+
% • imax - (1×1 double) maximimum number of iterations
29+
% • return_all - (logical) all intermediate fixed point estimates
30+
% are returned if set to "true"; otherwise, a
31+
% faster algorithm is used to return only the
32+
% converged fixed point
33+
% • TOL - (1×1 double) tolerance
34+
% • warnings - (logical) true if any warnings should be
35+
% displayed, false if not
3236
%
3337
% -------
3438
% OUTPUT:
3539
% -------
36-
% c - (1×1 or n×1) fixed point of f(x)
37-
% --> if "output" is specified as 'all', then "c" will be a
38-
% vector, where the first element is the initial guess,
39-
% the last element is the converged fixed point, and the
40-
% other elements are intermediate estimates of the fixed
41-
% point
42-
% --> otherwise, "c" is a single number storing the converged
43-
% fixed point
40+
% c - (1×1 or n×1 double) fixed point of f(x)
41+
% --> If "return_all" is specified as "true", then "c" will
42+
% be a vector, where the first element is the initial
43+
% guess, the last element is the converged fixed point,
44+
% and the other elements are intermediate estimates of
45+
% the fixed point.
46+
% --> Otherwise, "c" is a single number storing the converged
47+
% fixed point.
4448
%
4549
%==========================================================================
46-
function c = fixed_point_iteration(f,x0,TOL,imax,output)
50+
function c = fixed_point_iteration(f,x0,opts)
4751

48-
% sets default tolerance and maximum number of iterations if not
49-
% specified by user
50-
if (nargin < 3) || isempty(TOL)
51-
TOL = 1e-12;
52-
end
53-
if (nargin < 4) || isempty(imax)
52+
% ----------------------------------
53+
% Sets (or defaults) solver options.
54+
% ----------------------------------
55+
56+
% sets maximum number of iterations (defaults to 1e6)
57+
if (nargin < 3) || isempty(opts) || ~isfield(opts,'imax')
5458
imax = 1e6;
59+
else
60+
imax = opts.imax;
5561
end
5662

57-
% decides which algorithm to use
58-
if nargin < 5
63+
% determines return value (defaults to only return converged root)
64+
if (nargin < 3) || isempty(opts) || ~isfield(opts,'return_all')
5965
return_all = false;
6066
else
61-
if strcmpi(output,'all')
62-
return_all = true;
63-
else
64-
return_all = false;
65-
end
67+
return_all = opts.return_all;
68+
end
69+
70+
% sets tolerance (defaults to 1e-12)
71+
if (nargin < 3) || isempty(opts) || ~isfield(opts,'TOL')
72+
TOL = 1e-12;
73+
else
74+
TOL = opts.TOL;
6675
end
6776

68-
% initializes the error so the loop will be entered
69-
err = 2*TOL;
77+
% determines if warnings should be displayed (defaults to display)
78+
if (nargin < 3) || isempty(opts) || ~isfield(opts,'warnings')
79+
warnings = true;
80+
else
81+
warnings = opts.warnings;
82+
end
83+
84+
% -----------------------------------------------------
85+
% "Return all" implementation of fixed-point iteration.
86+
% -----------------------------------------------------
7087

71-
% implements algorithm for fixed-point iteration where all intermediate
72-
% fixed point estimates are also returned
7388
if return_all
7489

7590
% preallocates x
@@ -78,6 +93,9 @@
7893
% inputs initial guess for fixed point into x vector
7994
x(1) = x0;
8095

96+
% initializes the error so the loop will be entered
97+
err = 2*TOL;
98+
8199
% fixed-point iteration
82100
i = 1;
83101
while (err > TOL) && (i < imax)
@@ -93,10 +111,20 @@
93111

94112
end
95113

114+
% displays warning if maximum number of iterations reached
115+
if (i == imax) && warnings
116+
warning(strcat('The method failed after n=',num2str(imax),...
117+
' iterations.'));
118+
end
119+
96120
% returns converged fixed point along with intermediate fixed point
97121
% estimates
98122
c = x(1:i);
99123

124+
% -----------------------------------------------
125+
% "Fast" implementation of fixed-point iteration.
126+
% -----------------------------------------------
127+
100128
else
101129

102130
% sets fixed point estimate at the first iteration of the fixed
@@ -105,6 +133,9 @@
105133

106134
% initializes x_new so its scope isn't limited to the while loop
107135
x_new = 0;
136+
137+
% initializes the error so the loop will be entered
138+
err = 2*TOL;
108139

109140
% fixed-point iteration
110141
i = 1;
@@ -124,6 +155,12 @@
124155

125156
end
126157

158+
% displays warning if maximum number of iterations reached
159+
if (i == imax) && warnings
160+
warning(strcat('The method failed after n=',num2str(imax),...
161+
' iterations.'));
162+
end
163+
127164
% returns converged fixed point
128165
c = x_new;
129166

0 commit comments

Comments
 (0)