Skip to content

Commit c4b3379

Browse files
tamaskistamaskis
committed
finished documentation for vector Hessians, updated typos in documentation, and finished draft of Differentiator class
1 parent 3546d43 commit c4b3379

File tree

107 files changed

+1940
-9
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

107 files changed

+1940
-9
lines changed

‎docs/cvechessian_doc.html

+255
Large diffs are not rendered by default.

‎docs/cvechessian_doc_eq01060674047448903387.png

48 KB

‎docs/cvechessian_doc_eq02325986776153964256.png

13.9 KB

‎docs/cvechessian_doc_eq03403988016607310992.png

1.21 KB

‎docs/cvechessian_doc_eq08278739518609541210.png

2.2 KB

‎docs/cvechessian_doc_eq11635579214614771104.png

33.8 KB

‎docs/cvechessian_doc_eq12407751216247896965.png

3.1 KB

‎docs/cvechessian_doc_eq13769496404156091705.png

1.16 KB

‎docs/cvechessian_doc_eq13794615980392037191.png

321 Bytes

‎docs/cvechessian_doc_eq15898890414513100043.png

367 Bytes

‎docs/cvechessian_doc_eq16152409469914233053.png

2.83 KB

‎docs/cvechessian_doc_eq16410644637423230129.png

488 Bytes

‎docs/cvechessian_doc_eq17274866754917724950.png

374 Bytes

‎docs/cvechessian_doc_eq17601453130965439182.png

5.15 KB

‎docs/fvechessian_doc.html

+251
Large diffs are not rendered by default.

‎docs/fvechessian_doc_eq01060674047448903387.png

48 KB

‎docs/fvechessian_doc_eq02325986776153964256.png

13.9 KB

‎docs/fvechessian_doc_eq03403988016607310992.png

1.21 KB

‎docs/fvechessian_doc_eq08278739518609541210.png

2.2 KB

‎docs/fvechessian_doc_eq11635579214614771104.png

33.8 KB

‎docs/fvechessian_doc_eq12407751216247896965.png

3.1 KB

‎docs/fvechessian_doc_eq13769496404156091705.png

1.16 KB

‎docs/fvechessian_doc_eq13794615980392037191.png

321 Bytes

‎docs/fvechessian_doc_eq15898890414513100043.png

367 Bytes

‎docs/fvechessian_doc_eq16152409469914233053.png

2.83 KB

‎docs/fvechessian_doc_eq16410644637423230129.png

488 Bytes

‎docs/fvechessian_doc_eq17274866754917724950.png

374 Bytes

‎docs/fvechessian_doc_eq17601453130965439182.png

5.15 KB

‎docs/index.html

+5-2
Large diffs are not rendered by default.

‎docs/ivechessian_doc.html

+268
Large diffs are not rendered by default.

‎docs/ivechessian_doc_eq00208253058106614172.png

630 Bytes

‎docs/ivechessian_doc_eq00614864613708429844.png

2.62 KB

‎docs/ivechessian_doc_eq00748322523295720176.png

1.74 KB

‎docs/ivechessian_doc_eq01060674047448903387.png

48 KB

‎docs/ivechessian_doc_eq02051583311403081987.png

668 Bytes

‎docs/ivechessian_doc_eq02325986776153964256.png

13.9 KB

‎docs/ivechessian_doc_eq03403988016607310992.png

1.21 KB

‎docs/ivechessian_doc_eq05820341115329729410.png

2.14 KB

‎docs/ivechessian_doc_eq07094463994910309546.png

4.38 KB

‎docs/ivechessian_doc_eq11635579214614771104.png

33.8 KB

‎docs/ivechessian_doc_eq12407751216247896965.png

3.1 KB

‎docs/ivechessian_doc_eq13769496404156091705.png

1.16 KB

‎docs/ivechessian_doc_eq13794615980392037191.png

321 Bytes

‎docs/ivechessian_doc_eq13811186797923839656.png

5.62 KB

‎docs/ivechessian_doc_eq15898890414513100043.png

367 Bytes

‎docs/ivechessian_doc_eq16535241617762935742.png

27.5 KB

‎docs/ivechessian_doc_eq16722916995600574714.png

13.1 KB

‎docs/ivechessian_doc_eq17274866754917724950.png

374 Bytes

‎docs/ivechessian_doc_eq17601453130965439182.png

5.15 KB

‎docs/thumbnail_resized.png

0 Bytes

‎toolbox/Differentiator.m

+144
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
%==========================================================================
2+
%
3+
% Differentiator Class defining a differentiator.
4+
%
5+
% Copyright © 2022 Tamas Kis
6+
% Last Update: 2022-08-31
7+
% Website: https://tamaskis.github.io
8+
% Contact: [email protected]
9+
%
10+
% TOOLBOX DOCUMENTATION:
11+
% https://tamaskis.github.io/Numerical_Differentiation_Toolbox-MATLAB/
12+
%
13+
% TECHNICAL DOCUMENTATION:
14+
% https://tamaskis.github.io/files/Numerical_Differentiation.pdf
15+
%
16+
%==========================================================================
17+
18+
classdef Differentiator
19+
20+
% -----------
21+
% Properties.
22+
% -----------
23+
24+
properties
25+
method % (char) differentiation method
26+
hi % (1×1 double) step size for complex-step approximation
27+
hc % (1×1 double) relative step size for central difference approximation
28+
hf % (1×1 double) relative step size for forward difference approximation
29+
hf2 % (1×1 double) relative step size for calculating Hessian using forward difference approximation
30+
derivative % (1×1 function_handle) derivative of a univariate, vector-valued function
31+
partial % (1×1 function_handle) partial derivative of a multivariate, vector-valued function
32+
gradient % (1×1 function_handle) gradient of a multivariate, scalar-valued function
33+
directional % (1×1 function_handle) directional derivative of a multivariate, scalar-valued function
34+
jacobian % (1×1 function_handle) Jacobian of a multivariate, vector-valued function
35+
hessian % (1×1 function_handle) Hessian of a multivariate, scalar-valued function
36+
vechessian % (1×1 function_handle) vector Hessian of a multivariate, vector-valued function
37+
end
38+
39+
% --------
40+
% Methods.
41+
% --------
42+
43+
methods
44+
45+
% ------------
46+
% Constructor.
47+
% ------------
48+
49+
function obj = Differentiator(method,hi,hc,hf,hf2)
50+
% obj = Differentiator(method,hi,hc,hf,hf2)
51+
%
52+
% Constructor.
53+
%--------------------------------------------------------------
54+
%
55+
% ------
56+
% INPUT:
57+
% ------
58+
% method - (OPTIONAL) (char) differentiation method;
59+
% 'central difference', 'complex-step', or
60+
% 'forward difference' (defaults to
61+
% 'central difference')
62+
% hi - (OPTIONAL) (1×1 double) step size for
63+
% complex-step approximation (defaults to 10⁻²⁰⁰)
64+
% hc - (OPTIONAL) (1×1 double) relative step size for
65+
% central difference approximation (defaults to
66+
% ε¹ᐟ³)
67+
% hf - (OPTIONAL) (1×1 double) relative step size for
68+
% forward difference approximation (defaults to √ε)
69+
% hf2 - (OPTIONAL) (1×1 double) relative step size for
70+
% calculating Hessian using forward difference
71+
% approximation (defaults to ε¹ᐟ³)
72+
%
73+
% -------
74+
% OUTPUT:
75+
% -------
76+
% obj - (1×1 Differentiator) differentiator object
77+
%
78+
%--------------------------------------------------------------
79+
80+
% defaults "method" to 'central difference' if not input
81+
if (nargin < 1) || isempty(method)
82+
method = 'central difference';
83+
end
84+
85+
% defaults "hi" to 10⁻²⁰⁰ if not input
86+
if (nargin < 2) || isempty(hi)
87+
hi = 1e-200;
88+
end
89+
90+
% defaults "hc" to ε¹ᐟ³ if not input
91+
if nargin == 2 || isempty(hc)
92+
hc = eps^(1/3);
93+
end
94+
95+
% defaults "hf" to √ε if not input
96+
if nargin == 2 || isempty(hf)
97+
hf = sqrt(eps);
98+
end
99+
100+
% defaults "hf2" to ε¹ᐟ³ if not input
101+
if nargin == 2 || isempty(hf2)
102+
hf2 = eps^(1/3);
103+
end
104+
105+
% sets up differentiation functions
106+
if strcmpi(method,'central difference')
107+
obj.derivative = @(f,x) cderivative(f,x,hc);
108+
obj.partial = @(f,x,k) cpartial(f,x,k,hc);
109+
obj.gradient = @(f,x) cgradient(f,x,hc);
110+
obj.directional = @(f,x,v) cdirectional(f,x,v,hc);
111+
obj.jacobian = @(f,x) cjacobian(f,x,hc);
112+
obj.hessian = @(f,x) chessian(f,x,hc);
113+
obj.vechessian = @(f,x) cvechessian(f,x,hc);
114+
elseif strcmpi(method,'complex-step')
115+
obj.derivative = @(f,x) iderivative(f,x,hi);
116+
obj.partial = @(f,x,k) ipartial(f,x,k,hi);
117+
obj.gradient = @(f,x) igradient(f,x,hi);
118+
obj.directional = @(f,x,v) idirectional(f,x,v,hi);
119+
obj.jacobian = @(f,x) ijacobian(f,x,hi);
120+
obj.hessian = @(f,x) ihessian(f,x,hi,hc);
121+
obj.vechessian = @(f,x) ivechessian(f,x,hi,hc);
122+
elseif strcmpi(method,'forward difference')
123+
obj.derivative = @(f,x) fderivative(f,x,hf);
124+
obj.partial = @(f,x,k) fpartial(f,x,k,hf);
125+
obj.gradient = @(f,x) fgradient(f,x,hf);
126+
obj.directional = @(f,x,v) fdirectional(f,x,v,hf);
127+
obj.jacobian = @(f,x) fjacobian(f,x,hf);
128+
obj.hessian = @(f,x) fhessian(f,x,hf2);
129+
obj.vechessian = @(f,x) fvechessian(f,x,hf2);
130+
end
131+
132+
% sets method and step sizes as properties so they may be
133+
% queried/edited
134+
obj.method = method;
135+
obj.hc = hc;
136+
obj.hi = hi;
137+
obj.hf = hf;
138+
obj.hf2 = hf2;
139+
140+
end
141+
142+
end
143+
144+
end

‎toolbox/centraldifference/chessian.m

+1-1
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@
3232
% -------
3333
% OUTPUT:
3434
% -------
35-
% H - (n×1 double) Hessian of f with respect to x, evaluated at
35+
% H - (n×n double) Hessian of f with respect to x, evaluated at
3636
% x = x₀
3737
%
3838
% -----

‎toolbox/centraldifference/cvechessian.m

+75
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
%==========================================================================
2+
%
3+
% cvechessian Vector Hessian of a multivariate, vector-valued function
4+
% using the central difference approximation.
5+
%
6+
% H = cvechessian(f,x0)
7+
% H = cvechessian(f,x0,h)
8+
%
9+
% See also fvechessian, ivechessian.
10+
%
11+
% Copyright © 2021 Tamas Kis
12+
% Last Update: 2022-08-30
13+
% Website: https://tamaskis.github.io
14+
% Contact: [email protected]
15+
%
16+
% TOOLBOX DOCUMENTATION:
17+
% https://tamaskis.github.io/Numerical_Differentiation_Toolbox-MATLAB/
18+
%
19+
% TECHNICAL DOCUMENTATION:
20+
% https://tamaskis.github.io/files/Numerical_Differentiation.pdf
21+
%
22+
%--------------------------------------------------------------------------
23+
%
24+
% ------
25+
% INPUT:
26+
% ------
27+
% f - (1×1 function_handle) multivariate, vector-valued function,
28+
% f(x) (f : ℝⁿ → ℝᵐ)
29+
% x0 - (n×1 double) evaluation point, x₀ ∈ ℝⁿ
30+
% h - (OPTIONAL) (1×1 double) relative step size (defaults to ε¹ᐟ³)
31+
%
32+
% -------
33+
% OUTPUT:
34+
% -------
35+
% H - (n×n×m double) vector Hessian of f with respect to x,
36+
% evaluated at x = x₀
37+
%
38+
% -----
39+
% NOTE:
40+
% -----
41+
% --> This function requires 2mn(n+1)+1 evaluations of f(x).
42+
%
43+
%==========================================================================
44+
function H = cvechessian(f,x0,h)
45+
46+
% defaults relative step size if not input
47+
if nargin == 2 || isempty(h)
48+
h = eps^(1/3);
49+
end
50+
51+
% determines size of vector Hessian
52+
m = length(f(x0));
53+
n = length(x0);
54+
55+
% preallocates array to store vector Hessian
56+
H = zeros(n,n,m);
57+
58+
% evaluates vector Hessian
59+
for k = 1:m
60+
61+
% function for kth component of f(x)
62+
fk = @(x) helper(f,x,k);
63+
64+
% evaluates kth Hessian
65+
H(:,:,k) = chessian(fk,x0,h);
66+
67+
end
68+
69+
% helper function
70+
function fk = helper(f,x,k)
71+
fx = f(x);
72+
fk = fx(k);
73+
end
74+
75+
end

‎toolbox/complexstep/ihessian.m

+3-3
Original file line numberDiff line numberDiff line change
@@ -27,15 +27,15 @@
2727
% f - (1×1 function_handle) multivariate, scalar-valued function,
2828
% f(x) (f : ℝⁿ → ℝ)
2929
% x0 - (n×1 double) evaluation point, x₀ ∈ ℝⁿ
30-
% hi - (OPTIONAL) (1×1 double) relative step size for complex-step
30+
% hi - (OPTIONAL) (1×1 double) step size for complex-step
3131
% approximation (defaults to 10⁻²⁰⁰)
3232
% hc - (OPTIONAL) (1×1 double) relative step size for forward
3333
% difference approximation (defaults to ε¹ᐟ³)
3434
%
3535
% -------
3636
% OUTPUT:
3737
% -------
38-
% H - (n×1 double) Hessian of f with respect to x, evaluated at
38+
% H - (n×n double) Hessian of f with respect to x, evaluated at
3939
% x = x₀
4040
%
4141
% -----
@@ -46,7 +46,7 @@
4646
%==========================================================================
4747
function H = ihessian(f,x0,hi,hc)
4848

49-
% defaults relative step size for complex-step approx. if not input
49+
% defaults step size for complex-step approximation if not input
5050
if nargin < 3 || isempty(hi)
5151
hi = 1e-200;
5252
end

‎toolbox/complexstep/ivechessian.m

+83
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
%==========================================================================
2+
%
3+
% ivechessian Vector Hessian of a multivariate, vector-valued function
4+
% using the complex-step approximation.
5+
%
6+
% H = ivechessian(f,x0)
7+
% H = ivechessian(f,x0,hi,hc)
8+
%
9+
% See also cvechessian, fvechessian.
10+
%
11+
% Copyright © 2021 Tamas Kis
12+
% Last Update: 2022-08-30
13+
% Website: https://tamaskis.github.io
14+
% Contact: [email protected]
15+
%
16+
% TOOLBOX DOCUMENTATION:
17+
% https://tamaskis.github.io/Numerical_Differentiation_Toolbox-MATLAB/
18+
%
19+
% TECHNICAL DOCUMENTATION:
20+
% https://tamaskis.github.io/files/Numerical_Differentiation.pdf
21+
%
22+
%--------------------------------------------------------------------------
23+
%
24+
% ------
25+
% INPUT:
26+
% ------
27+
% f - (1×1 function_handle) multivariate, vector-valued function,
28+
% f(x) (f : ℝⁿ → ℝᵐ)
29+
% x0 - (n×1 double) evaluation point, x₀ ∈ ℝⁿ
30+
% hi - (OPTIONAL) (1×1 double) step size for complex-step
31+
% approximation (defaults to 10⁻²⁰⁰)
32+
% hc - (OPTIONAL) (1×1 double) relative step size for forward
33+
% difference approximation (defaults to ε¹ᐟ³)
34+
%
35+
% -------
36+
% OUTPUT:
37+
% -------
38+
% H - (n×n×m double) vector Hessian of f with respect to x,
39+
% evaluated at x = x₀
40+
%
41+
% -----
42+
% NOTE:
43+
% -----
44+
% --> This function requires mn(n+1)+1 evaluations of f(x).
45+
%
46+
%==========================================================================
47+
function H = ivechessian(f,x0,hi,hc)
48+
49+
% default step size for complex-step approximation if not input
50+
if nargin < 3 || isempty(hi)
51+
hi = 1e-200;
52+
end
53+
54+
% defaults relative step size for forward diff. approx. if not input
55+
if nargin < 4 || isempty(hc)
56+
hc = eps^(1/3);
57+
end
58+
59+
% determines size of vector Hessian
60+
m = length(f(x0));
61+
n = length(x0);
62+
63+
% preallocates array to store vector Hessian
64+
H = zeros(n,n,m);
65+
66+
% evaluates vector Hessian
67+
for k = 1:m
68+
69+
% function for kth component of f(x)
70+
fk = @(x) helper(f,x,k);
71+
72+
% evaluates kth Hessian
73+
H(:,:,k) = ihessian(fk,x0,hi,hc);
74+
75+
end
76+
77+
% helper function
78+
function fk = helper(f,x,k)
79+
fx = f(x);
80+
fk = fx(k);
81+
end
82+
83+
end

0 commit comments

Comments
 (0)