Skip to content

Commit 8678665

Browse files
tamaskistamaskis
committed
Added section in technical documentation on transposes, as well as warning/disclaimer on toolbox documentation
1 parent 9665d5c commit 8678665

File tree

3 files changed

+7
-2
lines changed

3 files changed

+7
-2
lines changed

‎INSTALL/Numerical Differentiation Toolbox.mltbx

-1 Bytes
Binary file not shown.

‎Technical Documentation/Numerical_Differentiation.pdf

698 Bytes
Binary file not shown.

‎docs/index.html

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
<!--
77
This HTML was auto-generated from MATLAB code.
88
To make changes, update the MATLAB code and republish this document.
9-
--><title>Numerical Differentiation Toolbox Documentation</title><meta name="generator" content="MATLAB 9.11"><link rel="schema.DC" href="http://purl.org/dc/elements/1.1/"><meta name="DC.date" content="2021-12-26"><meta name="DC.source" content="index.m"><style type="text/css">
9+
--><title>Numerical Differentiation Toolbox Documentation</title><meta name="generator" content="MATLAB 9.11"><link rel="schema.DC" href="http://purl.org/dc/elements/1.1/"><meta name="DC.date" content="2021-12-27"><meta name="DC.source" content="index.m"><style type="text/css">
1010
html,body,div,span,applet,object,iframe,h1,h2,h3,h4,h5,h6,p,blockquote,pre,a,abbr,acronym,address,big,cite,code,del,dfn,em,font,img,ins,kbd,q,s,samp,small,strike,strong,tt,var,b,u,i,center,dl,dt,dd,ol,ul,li,fieldset,form,label,legend,table,caption,tbody,tfoot,thead,tr,th,td{margin:0;padding:0;border:0;outline:0;font-size:100%;vertical-align:baseline;background:transparent}body{line-height:1}ol,ul{list-style:none}blockquote,q{quotes:none}blockquote:before,blockquote:after,q:before,q:after{content:'';content:none}:focus{outine:0}ins{text-decoration:none}del{text-decoration:line-through}table{border-collapse:collapse;border-spacing:0}
1111

1212
html { min-height:100%; margin-bottom:1px; }
@@ -67,7 +67,7 @@
6767

6868

6969

70-
</style></head><body><div class="content"><h1>Numerical Differentiation Toolbox Documentation</h1><!--introduction--><p><img vspace="5" hspace="5" src="numerical_differentiation_toolbox.png" alt=""> </p><p>Copyright &copy; 2021 Tamas Kis</p><!--/introduction--><h2>Contents</h2><div><ul><li><a href="#1">Differentiation Using the Complex-Step Approximation</a></li><li><a href="#2">Complexified Functions</a></li><li><a href="#3">Differentiation Using the Backward Difference Approximation</a></li><li><a href="#4">Technical Documentation</a></li><li><a href="#5">Warnings/Disclaimers</a></li><li><a href="#6">Installation</a></li></ul></div><h2 id="1">Differentiation Using the Complex-Step Approximation</h2><div><ul><li><a href="iderivative_doc.html"><b><tt>iderivative</tt></b></a> Derivative of a univariate, scalar or vector-valued function.</li><li><a href="ipartial_doc.html"><b><tt>ipartial</tt></b></a> Partial derivative of a multivariate, scalar or vector-valued function.</li><li><a href="igradient_doc.html"><b><tt>igradient</tt></b></a> Gradient of a multivariate, scalar-valued function.</li><li><a href="idirectional_doc.html"><b><tt>idirectional</tt></b></a> Directional derivative of a multivariate, scalar-valued function.</li><li><a href="ijacobian_doc.html"><b><tt>ijacobian</tt></b></a> Jacobian matrix of a multivariate, vector-valued function.</li><li><a href="ihessian_doc.html"><b><tt>ihessian</tt></b></a> Hessian matrix of a multivariate, scalar-valued function.</li></ul></div><h2 id="2">Complexified Functions</h2><div><ul><li><a href="iabs_doc.html"><b><tt>iabs</tt></b></a> "Complexified" version of the absolute value (<tt>iabs</tt>) function.</li><li><a href="iatan2_doc.html"><b><tt>iatan2</tt></b></a> "Complexified" version of the four quadrant inverse tangent (<tt>atan2</tt>) function (in radians).</li><li><a href="iatan2d_doc.html"><b><tt>iatan2d</tt></b></a> "Complexified" version of the four quadrant inverse tangent (<tt>atan2d</tt>) function (in degrees).</li></ul></div><h2 id="3">Differentiation Using the Backward Difference Approximation</h2><div><ul><li><a href="derivative2_doc.html"><b><tt>derivative2</tt></b></a> Derivative of a univariate, scalar or vector-valued function.</li><li><a href="partial2_doc.html"><b><tt>partial2</tt></b></a> Partial derivative of a multivariate, scalar or vector-valued function.</li><li><a href="gradient2_doc.html"><b><tt>gradient2</tt></b></a> Gradient of a multivariate, scalar-valued function.</li><li><a href="directional2_doc.html"><b><tt>directional2</tt></b></a> Directional derivative of a multivariate, scalar-valued function.</li><li><a href="jacobian2_doc.html"><b><tt>jacobian2</tt></b></a> Jacobian matrix of a multivariate, vector-valued function.</li></ul></div><h2 id="4">Technical Documentation</h2><p>Click <a href="https://tamaskis.github.io/documentation/Numerical_Differentiation.pdf">here</a>.</p><h2 id="5">Warnings/Disclaimers</h2><div><ul><li>There are some special cases of functions where the complex-step approximation will not work directly; for example, trying to differentiate functions using MATLAB's <tt>atan2</tt> or <tt>abs</tt> would result in errors. We can "complexify" these functions to make them suitable for use with the complex-step approximation; in this toolbox, we have included <tt>iabs</tt>, <tt>iatan2</tt>, and <tt>iatan2d</tt> in src/complexified. However, more complexified functions can be found (programmed in Fortran) at <a href="https://mdolab.engin.umich.edu/misc/files/complexify.f90">https://mdolab.engin.umich.edu/misc/files/complexify.f90</a>.</li><li>Most differentiable functions can be used with the various functions of this toolbox. Functions that result in errors (likely due to complexification issues) are summarized in Section 1.3.3 of the <a href="https://tamaskis.github.io/documentation/Numerical_Differentiation.pdf">technical documentation</a>.</li><li>The functions in this toolbox cannot perform higher-order derivatives (this limitation is discussed in Section 1.3.1 of the <a href="https://tamaskis.github.io/documentation/Numerical_Differentiation.pdf">technical documentation</a>).</li><li>All of the functions using the complex-step approximation (these functions can be identified by their prefixed "i") are (generally) accurate to double precision <b>with the exception of</b> <a href="ihessian_doc.html"><tt>ihessian</tt></a>. An alternative that will perform better is the <tt>hessian</tt> function provided by the <a href="https://www.mathworks.com/matlabcentral/fileexchange/13490-adaptive-robust-numerical-differentiation?s_tid=srchtitle">Adaptive Robust Numerical Differentiation</a> toolbox.</li><li>No error estimates are provided.</li></ul></div><h2 id="6">Installation</h2><p>The toolbox can be downloaded from <a href="https://www.mathworks.com/matlabcentral/fileexchange/97267-numerical-differentiation-toolbox">File Exchange</a> or <a href="https://github.com/tamaskis/Numerical_Differentiation_Toolbox-MATLAB">GitHub</a>. The downloaded zip folder contains the following:</p><div><ul><li><b>docs</b> &#8594; Contains the HTML documentation. To open a copy of the HTML documentation locally on your computer (without need of an internet connection), open docs/index.html.</li><li><b>INSTALL</b> &#8594; Contains the toolbox installer (Numerical Differentiation Toolbox.mltbx).</li><li><b>licenses</b> &#8594; Contains the software licenses.</li><li><b>README.md</b> &#8594; Markdown documentation for GitHub repository.</li><li><b>Technical Documentation</b> &#8594; Contains the technical documentation (Numerical_Differentiation_Using_the_Complex-Step_Approximation.pdf) for the various algorithms.</li><li><b>tests</b> &#8594; Code for unit tests.</li><li><b>toolbox</b> &#8594; Contains all the functions specific to this toolbox.</li></ul></div><p><b>To install as a toolbox</b>, simply open "Numerical Differentiation Toolbox.mltbx" in the "INSTALL" folder. MATLAB will automatically perform the installation and add all the functions included in the toolbox to the MATLAB search path.</p><p>Alternatively, all the functions in the "toolbox" folder can be used independently.</p><p class="footer"><br><a href="https://www.mathworks.com/products/matlab/">Published with MATLAB&reg; R2021b</a><br></p></div><!--
70+
</style></head><body><div class="content"><h1>Numerical Differentiation Toolbox Documentation</h1><!--introduction--><p><img vspace="5" hspace="5" src="numerical_differentiation_toolbox.png" alt=""> </p><p>Copyright &copy; 2021 Tamas Kis</p><!--/introduction--><h2>Contents</h2><div><ul><li><a href="#1">Differentiation Using the Complex-Step Approximation</a></li><li><a href="#2">Complexified Functions</a></li><li><a href="#3">Differentiation Using the Backward Difference Approximation</a></li><li><a href="#4">Technical Documentation</a></li><li><a href="#5">Warnings/Disclaimers</a></li><li><a href="#6">Installation</a></li></ul></div><h2 id="1">Differentiation Using the Complex-Step Approximation</h2><div><ul><li><a href="iderivative_doc.html"><b><tt>iderivative</tt></b></a> Derivative of a univariate, scalar or vector-valued function.</li><li><a href="ipartial_doc.html"><b><tt>ipartial</tt></b></a> Partial derivative of a multivariate, scalar or vector-valued function.</li><li><a href="igradient_doc.html"><b><tt>igradient</tt></b></a> Gradient of a multivariate, scalar-valued function.</li><li><a href="idirectional_doc.html"><b><tt>idirectional</tt></b></a> Directional derivative of a multivariate, scalar-valued function.</li><li><a href="ijacobian_doc.html"><b><tt>ijacobian</tt></b></a> Jacobian matrix of a multivariate, vector-valued function.</li><li><a href="ihessian_doc.html"><b><tt>ihessian</tt></b></a> Hessian matrix of a multivariate, scalar-valued function.</li></ul></div><h2 id="2">Complexified Functions</h2><div><ul><li><a href="iabs_doc.html"><b><tt>iabs</tt></b></a> "Complexified" version of the absolute value (<tt>iabs</tt>) function.</li><li><a href="iatan2_doc.html"><b><tt>iatan2</tt></b></a> "Complexified" version of the four quadrant inverse tangent (<tt>atan2</tt>) function (in radians).</li><li><a href="iatan2d_doc.html"><b><tt>iatan2d</tt></b></a> "Complexified" version of the four quadrant inverse tangent (<tt>atan2d</tt>) function (in degrees).</li></ul></div><h2 id="3">Differentiation Using the Backward Difference Approximation</h2><div><ul><li><a href="derivative2_doc.html"><b><tt>derivative2</tt></b></a> Derivative of a univariate, scalar or vector-valued function.</li><li><a href="partial2_doc.html"><b><tt>partial2</tt></b></a> Partial derivative of a multivariate, scalar or vector-valued function.</li><li><a href="gradient2_doc.html"><b><tt>gradient2</tt></b></a> Gradient of a multivariate, scalar-valued function.</li><li><a href="directional2_doc.html"><b><tt>directional2</tt></b></a> Directional derivative of a multivariate, scalar-valued function.</li><li><a href="jacobian2_doc.html"><b><tt>jacobian2</tt></b></a> Jacobian matrix of a multivariate, vector-valued function.</li></ul></div><h2 id="4">Technical Documentation</h2><p>Click <a href="https://tamaskis.github.io/documentation/Numerical_Differentiation.pdf">here</a>.</p><h2 id="5">Warnings/Disclaimers</h2><div><ul><li>Whenever a transpose is used in a function that is being differentiated using the complex-step approximation, special care must be taken to use the non-conjugate transpose (<tt>.'</tt>) instead of the conjugate transpose (<tt>'</tt>) &#8594; see Section 1.4 of the <a href="https://tamaskis.github.io/documentation/Numerical_Differentiation.pdf">technical documentation</a>.</li><li>There are some special cases of functions where the complex-step approximation will not work directly; for example, trying to differentiate functions using MATLAB's <tt>atan2</tt> or <tt>abs</tt> would result in errors. We can "complexify" these functions to make them suitable for use with the complex-step approximation; in this toolbox, we have included <tt>iabs</tt>, <tt>iatan2</tt>, and <tt>iatan2d</tt> in src/complexified. However, more complexified functions can be found (programmed in Fortran) at <a href="https://mdolab.engin.umich.edu/misc/files/complexify.f90">https://mdolab.engin.umich.edu/misc/files/complexify.f90</a>.</li><li>Most differentiable functions can be used with the various functions of this toolbox. Functions that result in errors (likely due to complexification issues) are summarized in Section 1.3.3 of the <a href="https://tamaskis.github.io/documentation/Numerical_Differentiation.pdf">technical documentation</a>.</li><li>The functions in this toolbox cannot perform higher-order derivatives (this limitation is discussed in Section 1.3.1 of the <a href="https://tamaskis.github.io/documentation/Numerical_Differentiation.pdf">technical documentation</a>).</li><li>All of the functions using the complex-step approximation (these functions can be identified by their prefixed "i") are (generally) accurate to double precision <b>with the exception of</b> <a href="ihessian_doc.html"><tt>ihessian</tt></a>. An alternative that will perform better is the <tt>hessian</tt> function provided by the <a href="https://www.mathworks.com/matlabcentral/fileexchange/13490-adaptive-robust-numerical-differentiation?s_tid=srchtitle">Adaptive Robust Numerical Differentiation</a> toolbox.</li><li>No error estimates are provided.</li></ul></div><h2 id="6">Installation</h2><p>The toolbox can be downloaded from <a href="https://www.mathworks.com/matlabcentral/fileexchange/97267-numerical-differentiation-toolbox">File Exchange</a> or <a href="https://github.com/tamaskis/Numerical_Differentiation_Toolbox-MATLAB">GitHub</a>. The downloaded zip folder contains the following:</p><div><ul><li><b>docs</b> &#8594; Contains the HTML documentation. To open a copy of the HTML documentation locally on your computer (without need of an internet connection), open docs/index.html.</li><li><b>INSTALL</b> &#8594; Contains the toolbox installer (Numerical Differentiation Toolbox.mltbx).</li><li><b>licenses</b> &#8594; Contains the software licenses.</li><li><b>README.md</b> &#8594; Markdown documentation for GitHub repository.</li><li><b>Technical Documentation</b> &#8594; Contains the technical documentation (Numerical_Differentiation_Using_the_Complex-Step_Approximation.pdf) for the various algorithms.</li><li><b>tests</b> &#8594; Code for unit tests.</li><li><b>toolbox</b> &#8594; Contains all the functions specific to this toolbox.</li></ul></div><p><b>To install as a toolbox</b>, simply open "Numerical Differentiation Toolbox.mltbx" in the "INSTALL" folder. MATLAB will automatically perform the installation and add all the functions included in the toolbox to the MATLAB search path.</p><p>Alternatively, all the functions in the "toolbox" folder can be used independently.</p><p class="footer"><br><a href="https://www.mathworks.com/products/matlab/">Published with MATLAB&reg; R2021b</a><br></p></div><!--
7171
##### SOURCE BEGIN #####
7272
%% Numerical Differentiation Toolbox Documentation
7373
%
@@ -94,6 +94,11 @@
9494
%% Technical Documentation
9595
% Click <https://tamaskis.github.io/documentation/Numerical_Differentiation.pdf here>.
9696
%% Warnings/Disclaimers
97+
% * Whenever a transpose is used in a function that is being differentiated
98+
% using the complex-step approximation, special care must be taken to use
99+
% the non-conjugate transpose (|.'|) instead of the conjugate transpose
100+
% (|'|) → see Section 1.4 of the <https://tamaskis.github.io/documentation/Numerical_Differentiation.pdf
101+
% technical documentation>.
97102
% * There are some special cases of functions where the complex-step
98103
% approximation will not work directly; for example, trying to
99104
% differentiate functions using MATLAB's |atan2| or |abs| would result in

0 commit comments

Comments
 (0)