source: html/ckbs/_printable.htm @ 81

Last change on this file since 81 was 81, checked in by bradbell, 12 years ago

[html/ckbs] fix one yyyymmdd reference that was in code font (now italic)

File size: 255.6 KB
Line 
1<html>
2<head><title>ckbs-0.20100228.0: A Constrained Kalman-Bucy Smoother</title></head>
3<body>
4
5<hr>
6<code>
7<span style='white-space: nowrap'>&nbsp;\newcommand{\T}{{\rm&nbsp;T}}</span></code>
8
9<code>
10<span style='white-space: nowrap'>&nbsp;\newcommand{\R}{{\bf&nbsp;R}}</span></code>
11
12
13
14
15
16<center><b><big><big>ckbs-0.20100228.0: A Constrained Kalman-Bucy Smoother</big></big></b></center>
17<br>
18<b><big><a name="a" id="a">a: MathML</a></big></b>
19<br>
20This documentation is in XHTML + MathML.
21If you have trouble viewing it in your browser see
22Viewing MathML on the web page
23<code><span style='white-space: nowrap'><br>
24&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></code>
25        <a href="http://www.seanet.com/~bradbell/packages.htm" target="_top"><span style='white-space: nowrap'>http://www.seanet.com/~bradbell/packages.htm</span></a>
26
27
28<br>
29<br>
30<b><big><a name="b" id="b">b: System Requirements</a></big></b>
31<br>
32This constrained Kalman-Bucy smoother runs under both the
33<a href="http://www.mathworks.com/" target="_top"><span style='white-space: nowrap'>Matlab&#174;</span></a>
34 (http://www.mathworks.com/)
35and
36<a href="http://www.gnu.org/software/octave/" target="_top"><span style='white-space: nowrap'>Octave</span></a>
37 (http://www.gnu.org/software/octave/)
38While it will work under MS windows,
39these download instructions are for the Unix operating system.
40
41<br>
42<br>
43<b><big><a name="c" id="c">c: Download</a></big></b>
44
45
46<br>
47<br>
48<b><a name="c.a" id="c.a">c.a: Using Subversion</a></b>
49<br>
50If you have subversion, you can download a copy of the most recent
51version of ckbs with the command
52
53<code><font color="blue"><span style='white-space: nowrap'><br>
54&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;web=&quot;https://projects.coin-or.org/svn/CoinBazaar/projects/ckbs&quot;<br>
55&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;svn&nbsp;checkout&nbsp;$web/trunk&nbsp;ckbs-0.20100228.0<br>
56</span></font></code>
57You can download a previous release of ckbs with the command
58
59<code><font color="blue"><span style='white-space: nowrap'><br>
60&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;svn&nbsp;checkout&nbsp;$web/releases/0.</span></font><i><font color="black"><span style='white-space: nowrap'>yyyymmdd</span></font></i><font color="blue"><span style='white-space: nowrap'>.</span></font><i><font color="black"><span style='white-space: nowrap'>r</span></font></i><font color="blue"><span style='white-space: nowrap'>&nbsp;ckbs-0.</span></font><i><font color="black"><span style='white-space: nowrap'>yyyymmdd</span></font></i><font color="blue"><span style='white-space: nowrap'>.</span></font><i><font color="black"><span style='white-space: nowrap'>r</span></font></i><font color="blue"><span style='white-space: nowrap'><br>
61</span></font></code>
62where
63<code><i><font color="black"><span style='white-space: nowrap'>yyyy</span></font></i></code>
64 is the year,
65
66<code><i><font color="black"><span style='white-space: nowrap'>mm</span></font></i></code>
67 is the month,
68
69<code><i><font color="black"><span style='white-space: nowrap'>dd</span></font></i></code>
70 is the day,
71and
72<code><i><font color="black"><span style='white-space: nowrap'>r</span></font></i></code>
73 is the release number for the release you want.
74In either case, this creates the directory
75
76<code><font color="blue"><span style='white-space: nowrap'>ckbs-0.</span></font><i><font color="black"><span style='white-space: nowrap'>yyyymmdd</span></font></i><font color="blue"><span style='white-space: nowrap'>.</span></font><i><font color="black"><span style='white-space: nowrap'>r</span></font></i></code>
77.
78<code><span style='white-space: nowrap'><br>
79<br>
80</span></code>The release number (
81<code><i><font color="black"><span style='white-space: nowrap'>r</span></font></i></code>
82 above)
83starts at zero and is incremented for bug fixes.
84The date (
85<code><i><font color="black"><span style='white-space: nowrap'>yyyymmdd</span></font></i></code>
86 above)
87is incremented with feature changes which are discussed by date
88in the <a href="#7">7: <span style='white-space: nowrap'>whatsnew</span></a>
89 section of this documentation
90
91<br>
92<br>
93<b><a name="c.b" id="c.b">c.b: Release Tarballs</a></b>
94<br>
95If you do not have subversion you can download the tarball
96
97<code><font color="blue"><span style='white-space: nowrap'>ckbs-0.</span></font><i><font color="black"><span style='white-space: nowrap'>yyyymmdd</span></font></i><font color="blue"><span style='white-space: nowrap'>.</span></font><i><font color="black"><span style='white-space: nowrap'>r</span></font></i><font color="blue"><span style='white-space: nowrap'>.tgz</span></font></code>
98 from the release download directory
99<code><font color='blue'><pre style='display:inline'> 
100        http://www.coin-or.org/download/source/CoinBazaar
101</pre></font></code>
102
103You can extract the files from the tarball using the command
104
105<code><font color="blue"><span style='white-space: nowrap'><br>
106&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;tar&nbsp;-xvzf&nbsp;ckbs-0.</span></font><i><font color="black"><span style='white-space: nowrap'>yyyymmdd</span></font></i><font color="blue"><span style='white-space: nowrap'>.</span></font><i><font color="black"><span style='white-space: nowrap'>r</span></font></i><font color="blue"><span style='white-space: nowrap'>.tgz<br>
107</span></font></code>
108This will create the directory
109
110<code><font color="blue"><span style='white-space: nowrap'>ckbs-0.</span></font><i><font color="black"><span style='white-space: nowrap'>yyyymmdd</span></font></i><font color="blue"><span style='white-space: nowrap'>.</span></font><i><font color="black"><span style='white-space: nowrap'>r</span></font></i></code>
111.
112
113<br>
114<br>
115<b><big><a name="d" id="d">d: Test Install</a></big></b>
116<br>
117Using Matlab&#174; or Octave, to change into the directory
118
119<code><font color="blue"><span style='white-space: nowrap'><br>
120&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ckbs-0.</span></font><i><font color="black"><span style='white-space: nowrap'>yyyymmdd</span></font></i><font color="blue"><span style='white-space: nowrap'>.</span></font><i><font color="black"><span style='white-space: nowrap'>r</span></font></i><font color="blue"><span style='white-space: nowrap'>/test<br>
121</span></font></code>
122and run the program <code><font color="blue">all_ok.m</font></code>.
123It will print the test results for all the components of <code><font color="blue">ckbs</font></code>.
124
125<br>
126<br>
127<b><big><a name="e" id="e">e: Documentation</a></big></b>
128<br>
129A copy of the documentation for your version of ckbs can
130be built by executing the command
131<code><font color='blue'><pre style='display:inline'> 
132        ./build_doc.sh
133</pre></font></code>
134
135in the
136<code><font color="blue"><span style='white-space: nowrap'>ckbs-0.</span></font><i><font color="black"><span style='white-space: nowrap'>yyyymmdd</span></font></i><font color="blue"><span style='white-space: nowrap'>.</span></font><i><font color="black"><span style='white-space: nowrap'>r</span></font></i></code>
137 directory.
138You can then view the documentation by loading the file
139
140<code><font color="blue"><span style='white-space: nowrap'><br>
141&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;ckbs-0.</span></font><i><font color="black"><span style='white-space: nowrap'>yyyymmdd</span></font></i><font color="blue"><span style='white-space: nowrap'>.</span></font><i><font color="black"><span style='white-space: nowrap'>r</span></font></i><font color="blue"><span style='white-space: nowrap'>/doc/ckbs.xml<br>
142</span></font></code>
143into your browser.
144
145<br>
146<br>
147<b><big><a name="f" id="f">f: Contents</a></big></b>
148<br>
149<table>
150<tr><td><a href="#1" target="_top">_contents:&nbsp;1</a></td><td>Table&nbsp;of&nbsp;Contents</td></tr><tr><td><a href="#2" target="_top">license:&nbsp;2</a></td><td>Your&nbsp;License&nbsp;to&nbsp;use&nbsp;the&nbsp;ckbs&nbsp;Software</td></tr><tr><td><a href="#3" target="_top">ckbs_nonlinear:&nbsp;3</a></td><td>The&nbsp;Nonlinear&nbsp;Constrained&nbsp;Kalman-Bucy&nbsp;Smoother</td></tr><tr><td><a href="#4" target="_top">ckbs_affine:&nbsp;4</a></td><td>Constrained&nbsp;Affine&nbsp;Kalman&nbsp;Bucy&nbsp;Smoother</td></tr><tr><td><a href="#5" target="_top">utility:&nbsp;5</a></td><td>ckbs&nbsp;Utility&nbsp;Functions</td></tr><tr><td><a href="#6" target="_top">all_ok.m:&nbsp;6</a></td><td>Run&nbsp;All&nbsp;Correctness&nbsp;Tests</td></tr><tr><td><a href="#7" target="_top">whatsnew:&nbsp;7</a></td><td>Changes&nbsp;and&nbsp;Additions&nbsp;to&nbsp;ckbs</td></tr><tr><td><a href="#8" target="_top">_reference:&nbsp;8</a></td><td>Alphabetic&nbsp;Listing&nbsp;of&nbsp;Cross&nbsp;Reference&nbsp;Tags</td></tr><tr><td><a href="#9" target="_top">_index:&nbsp;9</a></td><td>Keyword&nbsp;Index</td></tr><tr><td><a href="#10" target="_top">_external:&nbsp;10</a></td><td>External&nbsp;Internet&nbsp;References</td></tr></table>
151<hr>Input File: ckbs.omh
152
153<hr>
154<center><b><big><big>
1551: Table of Contents</big></big></b></center>
156
157<pre>
158ckbs-0.20100228.0: A Constrained Kalman-Bucy Smoother: <a href="#">: ckbs</a>
159    Table of Contents: <a href="#1">1: _contents</a>
160    Your License to use the ckbs Software: <a href="#2">2: license</a>
161    The Nonlinear Constrained Kalman-Bucy Smoother: <a href="#3">3: ckbs_nonlinear</a>
162        Simple ckbs_nonlinear Example and Test: <a href="#3.1">3.1: nonlinear_ok_simple.m</a>
163            Example Constraint Function: nonlinear_ok_simple_f: <a href="#3.1.1">3.1.1: nonlinear_ok_simple_f.m</a>
164            Example Transition Function: nonlinear_ok_simple_g: <a href="#3.1.2">3.1.2: nonlinear_ok_simple_g.m</a>
165            Example Measurement Function: nonlinear_ok_simple_h: <a href="#3.1.3">3.1.3: nonlinear_ok_simple_h.m</a>
166        ckbs_nonlinear Box Constrained Tracking Example and Test: <a href="#3.2">3.2: nonlinear_ok_box.m</a>
167            Example Constraint Function: nonlinear_ok_box_f: <a href="#3.2.1">3.2.1: nonlinear_ok_box_f.m</a>
168            Example Transition Function: nonlinear_ok_box_g: <a href="#3.2.2">3.2.2: nonlinear_ok_box_g.m</a>
169            Example Measurement Function: nonlinear_ok_box_h: <a href="#3.2.3">3.2.3: nonlinear_ok_box_h.m</a>
170            Example no Constraint Function: nonlinear_ok_box_nof: <a href="#3.2.4">3.2.4: nonlinear_ok_box_nof.m</a>
171        ckbs_nonlinear Sine Wave Constrained Tracking Example and Test: <a href="#3.3">3.3: nonlinear_ok_sin.m</a>
172            Example Constraint Function: nonlinear_ok_sin_f: <a href="#3.3.1">3.3.1: nonlinear_ok_sin_f.m</a>
173    Constrained Affine Kalman Bucy Smoother: <a href="#4">4: ckbs_affine</a>
174        ckbs_affine Box Constrained Smoothing Spline Example and Test: <a href="#4.1">4.1: affine_ok_box.m</a>
175    ckbs Utility Functions: <a href="#5">5: utility</a>
176        Packed Block Diagonal Matrix Times a Vector: <a href="#5.1">5.1: ckbs_blkdiag_mul</a>
177            blkdiag_mul Example and Test: <a href="#5.1.1">5.1.1: blkdiag_mul_ok.m</a>
178        Transpose of Packed Block Diagonal Matrix Times a Vector: <a href="#5.2">5.2: ckbs_blkdiag_mul_t</a>
179            blkdiag_mul_t Example and Test: <a href="#5.2.1">5.2.1: blkdiag_mul_t_ok.m</a>
180        Affine Residual Sum of Squares Objective: <a href="#5.3">5.3: ckbs_sumsq_obj</a>
181            ckbs_sumsq_obj Example and Test: <a href="#5.3.1">5.3.1: sumsq_obj_ok.m</a>
182        Affine Residual Sum of Squares Gradient: <a href="#5.4">5.4: ckbs_sumsq_grad</a>
183            ckbs_sumsq_grad Example and Test: <a href="#5.4.1">5.4.1: sumsq_grad_ok.m</a>
184        Affine Residual Sum of Squares Hessian: <a href="#5.5">5.5: ckbs_sumsq_hes</a>
185            ckbs_sumsq_hes Example and Test: <a href="#5.5.1">5.5.1: sumsq_hes_ok.m</a>
186        Symmetric Block Tridiagonal Algorithm: <a href="#5.6">5.6: ckbs_tridiag_solve</a>
187            ckbs_tridiag_solve Example and Test: <a href="#5.6.1">5.6.1: tridiag_solve_ok.m</a>
188        Affine Constrained Kalman Bucy Smoother Newton Step: <a href="#5.7">5.7: ckbs_newton_step</a>
189            ckbs_newton_step Example and Test: <a href="#5.7.1">5.7.1: newton_step_ok.m</a>
190        Compute Residual in Kuhn-Tucker Conditions: <a href="#5.8">5.8: ckbs_kuhn_tucker</a>
191            ckbs_kuhn_tucker Example and Test: <a href="#5.8.1">5.8.1: kuhn_tucker_ok.m</a>
192    Run All Correctness Tests: <a href="#6">6: all_ok.m</a>
193        Ensure Path is Set for Testing: <a href="#6.1">6.1: test_path.m</a>
194    Changes and Additions to ckbs: <a href="#7">7: whatsnew</a>
195    Alphabetic Listing of Cross Reference Tags: <a href="#8">8: _reference</a>
196    Keyword Index: <a href="#9">9: _index</a>
197    External Internet References: <a href="#10">10: _external</a>
198</pre>
199<hr>
200<center><b><big><big><a name="2" id="2">2: Your License to use the ckbs Software</a>
201</big></big></b></center>
202<code><span style='white-space: nowrap'><br>
203&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;GNU&nbsp;GENERAL&nbsp;PUBLIC&nbsp;LICENSE<br>
204&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Version&nbsp;2,&nbsp;June&nbsp;1991<br>
205<br>
206&nbsp;Copyright&nbsp;(C)&nbsp;1989,&nbsp;1991&nbsp;Free&nbsp;Software&nbsp;Foundation,&nbsp;Inc.,<br>
207&nbsp;51&nbsp;Franklin&nbsp;Street,&nbsp;Fifth&nbsp;Floor,&nbsp;Boston,&nbsp;MA&nbsp;02110-1301&nbsp;USA<br>
208&nbsp;Everyone&nbsp;is&nbsp;permitted&nbsp;to&nbsp;copy&nbsp;and&nbsp;distribute&nbsp;verbatim&nbsp;copies<br>
209&nbsp;of&nbsp;this&nbsp;license&nbsp;document,&nbsp;but&nbsp;changing&nbsp;it&nbsp;is&nbsp;not&nbsp;allowed.<br>
210<br>
211&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Preamble<br>
212<br>
213&nbsp;&nbsp;The&nbsp;licenses&nbsp;for&nbsp;most&nbsp;software&nbsp;are&nbsp;designed&nbsp;to&nbsp;take&nbsp;away&nbsp;your<br>
214freedom&nbsp;to&nbsp;share&nbsp;and&nbsp;change&nbsp;it.&nbsp;&nbsp;By&nbsp;contrast,&nbsp;the&nbsp;GNU&nbsp;General&nbsp;Public<br>
215License&nbsp;is&nbsp;intended&nbsp;to&nbsp;guarantee&nbsp;your&nbsp;freedom&nbsp;to&nbsp;share&nbsp;and&nbsp;change&nbsp;free<br>
216software--to&nbsp;make&nbsp;sure&nbsp;the&nbsp;software&nbsp;is&nbsp;free&nbsp;for&nbsp;all&nbsp;its&nbsp;users.&nbsp;&nbsp;This<br>
217General&nbsp;Public&nbsp;License&nbsp;applies&nbsp;to&nbsp;most&nbsp;of&nbsp;the&nbsp;Free&nbsp;Software<br>
218Foundation's&nbsp;software&nbsp;and&nbsp;to&nbsp;any&nbsp;other&nbsp;program&nbsp;whose&nbsp;authors&nbsp;commit&nbsp;to<br>
219using&nbsp;it.&nbsp;&nbsp;(Some&nbsp;other&nbsp;Free&nbsp;Software&nbsp;Foundation&nbsp;software&nbsp;is&nbsp;covered&nbsp;by<br>
220the&nbsp;GNU&nbsp;Lesser&nbsp;General&nbsp;Public&nbsp;License&nbsp;instead.)&nbsp;&nbsp;You&nbsp;can&nbsp;apply&nbsp;it&nbsp;to<br>
221your&nbsp;programs,&nbsp;too.<br>
222<br>
223&nbsp;&nbsp;When&nbsp;we&nbsp;speak&nbsp;of&nbsp;free&nbsp;software,&nbsp;we&nbsp;are&nbsp;referring&nbsp;to&nbsp;freedom,&nbsp;not<br>
224price.&nbsp;&nbsp;Our&nbsp;General&nbsp;Public&nbsp;Licenses&nbsp;are&nbsp;designed&nbsp;to&nbsp;make&nbsp;sure&nbsp;that&nbsp;you<br>
225have&nbsp;the&nbsp;freedom&nbsp;to&nbsp;distribute&nbsp;copies&nbsp;of&nbsp;free&nbsp;software&nbsp;(and&nbsp;charge&nbsp;for<br>
226this&nbsp;service&nbsp;if&nbsp;you&nbsp;wish),&nbsp;that&nbsp;you&nbsp;receive&nbsp;source&nbsp;code&nbsp;or&nbsp;can&nbsp;get&nbsp;it<br>
227if&nbsp;you&nbsp;want&nbsp;it,&nbsp;that&nbsp;you&nbsp;can&nbsp;change&nbsp;the&nbsp;software&nbsp;or&nbsp;use&nbsp;pieces&nbsp;of&nbsp;it<br>
228in&nbsp;new&nbsp;free&nbsp;programs;&nbsp;and&nbsp;that&nbsp;you&nbsp;know&nbsp;you&nbsp;can&nbsp;do&nbsp;these&nbsp;things.<br>
229<br>
230&nbsp;&nbsp;To&nbsp;protect&nbsp;your&nbsp;rights,&nbsp;we&nbsp;need&nbsp;to&nbsp;make&nbsp;restrictions&nbsp;that&nbsp;forbid<br>
231anyone&nbsp;to&nbsp;deny&nbsp;you&nbsp;these&nbsp;rights&nbsp;or&nbsp;to&nbsp;ask&nbsp;you&nbsp;to&nbsp;surrender&nbsp;the&nbsp;rights.<br>
232These&nbsp;restrictions&nbsp;translate&nbsp;to&nbsp;certain&nbsp;responsibilities&nbsp;for&nbsp;you&nbsp;if&nbsp;you<br>
233distribute&nbsp;copies&nbsp;of&nbsp;the&nbsp;software,&nbsp;or&nbsp;if&nbsp;you&nbsp;modify&nbsp;it.<br>
234<br>
235&nbsp;&nbsp;For&nbsp;example,&nbsp;if&nbsp;you&nbsp;distribute&nbsp;copies&nbsp;of&nbsp;such&nbsp;a&nbsp;program,&nbsp;whether<br>
236gratis&nbsp;or&nbsp;for&nbsp;a&nbsp;fee,&nbsp;you&nbsp;must&nbsp;give&nbsp;the&nbsp;recipients&nbsp;all&nbsp;the&nbsp;rights&nbsp;that<br>
237you&nbsp;have.&nbsp;&nbsp;You&nbsp;must&nbsp;make&nbsp;sure&nbsp;that&nbsp;they,&nbsp;too,&nbsp;receive&nbsp;or&nbsp;can&nbsp;get&nbsp;the<br>
238source&nbsp;code.&nbsp;&nbsp;And&nbsp;you&nbsp;must&nbsp;show&nbsp;them&nbsp;these&nbsp;terms&nbsp;so&nbsp;they&nbsp;know&nbsp;their<br>
239rights.<br>
240<br>
241&nbsp;&nbsp;We&nbsp;protect&nbsp;your&nbsp;rights&nbsp;with&nbsp;two&nbsp;steps:&nbsp;(1)&nbsp;copyright&nbsp;the&nbsp;software,&nbsp;and<br>
242(2)&nbsp;offer&nbsp;you&nbsp;this&nbsp;license&nbsp;which&nbsp;gives&nbsp;you&nbsp;legal&nbsp;permission&nbsp;to&nbsp;copy,<br>
243distribute&nbsp;and/or&nbsp;modify&nbsp;the&nbsp;software.<br>
244<br>
245&nbsp;&nbsp;Also,&nbsp;for&nbsp;each&nbsp;author's&nbsp;protection&nbsp;and&nbsp;ours,&nbsp;we&nbsp;want&nbsp;to&nbsp;make&nbsp;certain<br>
246that&nbsp;everyone&nbsp;understands&nbsp;that&nbsp;there&nbsp;is&nbsp;no&nbsp;warranty&nbsp;for&nbsp;this&nbsp;free<br>
247software.&nbsp;&nbsp;If&nbsp;the&nbsp;software&nbsp;is&nbsp;modified&nbsp;by&nbsp;someone&nbsp;else&nbsp;and&nbsp;passed&nbsp;on,&nbsp;we<br>
248want&nbsp;its&nbsp;recipients&nbsp;to&nbsp;know&nbsp;that&nbsp;what&nbsp;they&nbsp;have&nbsp;is&nbsp;not&nbsp;the&nbsp;original,&nbsp;so<br>
249that&nbsp;any&nbsp;problems&nbsp;introduced&nbsp;by&nbsp;others&nbsp;will&nbsp;not&nbsp;reflect&nbsp;on&nbsp;the&nbsp;original<br>
250authors'&nbsp;reputations.<br>
251<br>
252&nbsp;&nbsp;Finally,&nbsp;any&nbsp;free&nbsp;program&nbsp;is&nbsp;threatened&nbsp;constantly&nbsp;by&nbsp;software<br>
253patents.&nbsp;&nbsp;We&nbsp;wish&nbsp;to&nbsp;avoid&nbsp;the&nbsp;danger&nbsp;that&nbsp;redistributors&nbsp;of&nbsp;a&nbsp;free<br>
254program&nbsp;will&nbsp;individually&nbsp;obtain&nbsp;patent&nbsp;licenses,&nbsp;in&nbsp;effect&nbsp;making&nbsp;the<br>
255program&nbsp;proprietary.&nbsp;&nbsp;To&nbsp;prevent&nbsp;this,&nbsp;we&nbsp;have&nbsp;made&nbsp;it&nbsp;clear&nbsp;that&nbsp;any<br>
256patent&nbsp;must&nbsp;be&nbsp;licensed&nbsp;for&nbsp;everyone's&nbsp;free&nbsp;use&nbsp;or&nbsp;not&nbsp;licensed&nbsp;at&nbsp;all.<br>
257<br>
258&nbsp;&nbsp;The&nbsp;precise&nbsp;terms&nbsp;and&nbsp;conditions&nbsp;for&nbsp;copying,&nbsp;distribution&nbsp;and<br>
259modification&nbsp;follow.<br>
260<br>
261&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;GNU&nbsp;GENERAL&nbsp;PUBLIC&nbsp;LICENSE<br>
262&nbsp;&nbsp;&nbsp;TERMS&nbsp;AND&nbsp;CONDITIONS&nbsp;FOR&nbsp;COPYING,&nbsp;DISTRIBUTION&nbsp;AND&nbsp;MODIFICATION<br>
263<br>
264&nbsp;&nbsp;0.&nbsp;This&nbsp;License&nbsp;applies&nbsp;to&nbsp;any&nbsp;program&nbsp;or&nbsp;other&nbsp;work&nbsp;which&nbsp;contains<br>
265a&nbsp;notice&nbsp;placed&nbsp;by&nbsp;the&nbsp;copyright&nbsp;holder&nbsp;saying&nbsp;it&nbsp;may&nbsp;be&nbsp;distributed<br>
266under&nbsp;the&nbsp;terms&nbsp;of&nbsp;this&nbsp;General&nbsp;Public&nbsp;License.&nbsp;&nbsp;The&nbsp;&quot;Program&quot;,&nbsp;below,<br>
267refers&nbsp;to&nbsp;any&nbsp;such&nbsp;program&nbsp;or&nbsp;work,&nbsp;and&nbsp;a&nbsp;&quot;work&nbsp;based&nbsp;on&nbsp;the&nbsp;Program&quot;<br>
268means&nbsp;either&nbsp;the&nbsp;Program&nbsp;or&nbsp;any&nbsp;derivative&nbsp;work&nbsp;under&nbsp;copyright&nbsp;law:<br>
269that&nbsp;is&nbsp;to&nbsp;say,&nbsp;a&nbsp;work&nbsp;containing&nbsp;the&nbsp;Program&nbsp;or&nbsp;a&nbsp;portion&nbsp;of&nbsp;it,<br>
270either&nbsp;verbatim&nbsp;or&nbsp;with&nbsp;modifications&nbsp;and/or&nbsp;translated&nbsp;into&nbsp;another<br>
271language.&nbsp;&nbsp;(Hereinafter,&nbsp;translation&nbsp;is&nbsp;included&nbsp;without&nbsp;limitation&nbsp;in<br>
272the&nbsp;term&nbsp;&quot;modification&quot;.)&nbsp;&nbsp;Each&nbsp;licensee&nbsp;is&nbsp;addressed&nbsp;as&nbsp;&quot;you&quot;.<br>
273<br>
274Activities&nbsp;other&nbsp;than&nbsp;copying,&nbsp;distribution&nbsp;and&nbsp;modification&nbsp;are&nbsp;not<br>
275covered&nbsp;by&nbsp;this&nbsp;License;&nbsp;they&nbsp;are&nbsp;outside&nbsp;its&nbsp;scope.&nbsp;&nbsp;The&nbsp;act&nbsp;of<br>
276running&nbsp;the&nbsp;Program&nbsp;is&nbsp;not&nbsp;restricted,&nbsp;and&nbsp;the&nbsp;output&nbsp;from&nbsp;the&nbsp;Program<br>
277is&nbsp;covered&nbsp;only&nbsp;if&nbsp;its&nbsp;contents&nbsp;constitute&nbsp;a&nbsp;work&nbsp;based&nbsp;on&nbsp;the<br>
278Program&nbsp;(independent&nbsp;of&nbsp;having&nbsp;been&nbsp;made&nbsp;by&nbsp;running&nbsp;the&nbsp;Program).<br>
279Whether&nbsp;that&nbsp;is&nbsp;true&nbsp;depends&nbsp;on&nbsp;what&nbsp;the&nbsp;Program&nbsp;does.<br>
280<br>
281&nbsp;&nbsp;1.&nbsp;You&nbsp;may&nbsp;copy&nbsp;and&nbsp;distribute&nbsp;verbatim&nbsp;copies&nbsp;of&nbsp;the&nbsp;Program's<br>
282source&nbsp;code&nbsp;as&nbsp;you&nbsp;receive&nbsp;it,&nbsp;in&nbsp;any&nbsp;medium,&nbsp;provided&nbsp;that&nbsp;you<br>
283conspicuously&nbsp;and&nbsp;appropriately&nbsp;publish&nbsp;on&nbsp;each&nbsp;copy&nbsp;an&nbsp;appropriate<br>
284copyright&nbsp;notice&nbsp;and&nbsp;disclaimer&nbsp;of&nbsp;warranty;&nbsp;keep&nbsp;intact&nbsp;all&nbsp;the<br>
285notices&nbsp;that&nbsp;refer&nbsp;to&nbsp;this&nbsp;License&nbsp;and&nbsp;to&nbsp;the&nbsp;absence&nbsp;of&nbsp;any&nbsp;warranty;<br>
286and&nbsp;give&nbsp;any&nbsp;other&nbsp;recipients&nbsp;of&nbsp;the&nbsp;Program&nbsp;a&nbsp;copy&nbsp;of&nbsp;this&nbsp;License<br>
287along&nbsp;with&nbsp;the&nbsp;Program.<br>
288<br>
289You&nbsp;may&nbsp;charge&nbsp;a&nbsp;fee&nbsp;for&nbsp;the&nbsp;physical&nbsp;act&nbsp;of&nbsp;transferring&nbsp;a&nbsp;copy,&nbsp;and<br>
290you&nbsp;may&nbsp;at&nbsp;your&nbsp;option&nbsp;offer&nbsp;warranty&nbsp;protection&nbsp;in&nbsp;exchange&nbsp;for&nbsp;a&nbsp;fee.<br>
291<br>
292&nbsp;&nbsp;2.&nbsp;You&nbsp;may&nbsp;modify&nbsp;your&nbsp;copy&nbsp;or&nbsp;copies&nbsp;of&nbsp;the&nbsp;Program&nbsp;or&nbsp;any&nbsp;portion<br>
293of&nbsp;it,&nbsp;thus&nbsp;forming&nbsp;a&nbsp;work&nbsp;based&nbsp;on&nbsp;the&nbsp;Program,&nbsp;and&nbsp;copy&nbsp;and<br>
294distribute&nbsp;such&nbsp;modifications&nbsp;or&nbsp;work&nbsp;under&nbsp;the&nbsp;terms&nbsp;of&nbsp;Section&nbsp;1<br>
295above,&nbsp;provided&nbsp;that&nbsp;you&nbsp;also&nbsp;meet&nbsp;all&nbsp;of&nbsp;these&nbsp;conditions:<br>
296<br>
297&nbsp;&nbsp;&nbsp;&nbsp;a)&nbsp;You&nbsp;must&nbsp;cause&nbsp;the&nbsp;modified&nbsp;files&nbsp;to&nbsp;carry&nbsp;prominent&nbsp;notices<br>
298&nbsp;&nbsp;&nbsp;&nbsp;stating&nbsp;that&nbsp;you&nbsp;changed&nbsp;the&nbsp;files&nbsp;and&nbsp;the&nbsp;date&nbsp;of&nbsp;any&nbsp;change.<br>
299<br>
300&nbsp;&nbsp;&nbsp;&nbsp;b)&nbsp;You&nbsp;must&nbsp;cause&nbsp;any&nbsp;work&nbsp;that&nbsp;you&nbsp;distribute&nbsp;or&nbsp;publish,&nbsp;that&nbsp;in<br>
301&nbsp;&nbsp;&nbsp;&nbsp;whole&nbsp;or&nbsp;in&nbsp;part&nbsp;contains&nbsp;or&nbsp;is&nbsp;derived&nbsp;from&nbsp;the&nbsp;Program&nbsp;or&nbsp;any<br>
302&nbsp;&nbsp;&nbsp;&nbsp;part&nbsp;thereof,&nbsp;to&nbsp;be&nbsp;licensed&nbsp;as&nbsp;a&nbsp;whole&nbsp;at&nbsp;no&nbsp;charge&nbsp;to&nbsp;all&nbsp;third<br>
303&nbsp;&nbsp;&nbsp;&nbsp;parties&nbsp;under&nbsp;the&nbsp;terms&nbsp;of&nbsp;this&nbsp;License.<br>
304<br>
305&nbsp;&nbsp;&nbsp;&nbsp;c)&nbsp;If&nbsp;the&nbsp;modified&nbsp;program&nbsp;normally&nbsp;reads&nbsp;commands&nbsp;interactively<br>
306&nbsp;&nbsp;&nbsp;&nbsp;when&nbsp;run,&nbsp;you&nbsp;must&nbsp;cause&nbsp;it,&nbsp;when&nbsp;started&nbsp;running&nbsp;for&nbsp;such<br>
307&nbsp;&nbsp;&nbsp;&nbsp;interactive&nbsp;use&nbsp;in&nbsp;the&nbsp;most&nbsp;ordinary&nbsp;way,&nbsp;to&nbsp;print&nbsp;or&nbsp;display&nbsp;an<br>
308&nbsp;&nbsp;&nbsp;&nbsp;announcement&nbsp;including&nbsp;an&nbsp;appropriate&nbsp;copyright&nbsp;notice&nbsp;and&nbsp;a<br>
309&nbsp;&nbsp;&nbsp;&nbsp;notice&nbsp;that&nbsp;there&nbsp;is&nbsp;no&nbsp;warranty&nbsp;(or&nbsp;else,&nbsp;saying&nbsp;that&nbsp;you&nbsp;provide<br>
310&nbsp;&nbsp;&nbsp;&nbsp;a&nbsp;warranty)&nbsp;and&nbsp;that&nbsp;users&nbsp;may&nbsp;redistribute&nbsp;the&nbsp;program&nbsp;under<br>
311&nbsp;&nbsp;&nbsp;&nbsp;these&nbsp;conditions,&nbsp;and&nbsp;telling&nbsp;the&nbsp;user&nbsp;how&nbsp;to&nbsp;view&nbsp;a&nbsp;copy&nbsp;of&nbsp;this<br>
312&nbsp;&nbsp;&nbsp;&nbsp;License.&nbsp;&nbsp;(Exception:&nbsp;if&nbsp;the&nbsp;Program&nbsp;itself&nbsp;is&nbsp;interactive&nbsp;but<br>
313&nbsp;&nbsp;&nbsp;&nbsp;does&nbsp;not&nbsp;normally&nbsp;print&nbsp;such&nbsp;an&nbsp;announcement,&nbsp;your&nbsp;work&nbsp;based&nbsp;on<br>
314&nbsp;&nbsp;&nbsp;&nbsp;the&nbsp;Program&nbsp;is&nbsp;not&nbsp;required&nbsp;to&nbsp;print&nbsp;an&nbsp;announcement.)<br>
315<br>
316These&nbsp;requirements&nbsp;apply&nbsp;to&nbsp;the&nbsp;modified&nbsp;work&nbsp;as&nbsp;a&nbsp;whole.&nbsp;&nbsp;If<br>
317identifiable&nbsp;sections&nbsp;of&nbsp;that&nbsp;work&nbsp;are&nbsp;not&nbsp;derived&nbsp;from&nbsp;the&nbsp;Program,<br>
318and&nbsp;can&nbsp;be&nbsp;reasonably&nbsp;considered&nbsp;independent&nbsp;and&nbsp;separate&nbsp;works&nbsp;in<br>
319themselves,&nbsp;then&nbsp;this&nbsp;License,&nbsp;and&nbsp;its&nbsp;terms,&nbsp;do&nbsp;not&nbsp;apply&nbsp;to&nbsp;those<br>
320sections&nbsp;when&nbsp;you&nbsp;distribute&nbsp;them&nbsp;as&nbsp;separate&nbsp;works.&nbsp;&nbsp;But&nbsp;when&nbsp;you<br>
321distribute&nbsp;the&nbsp;same&nbsp;sections&nbsp;as&nbsp;part&nbsp;of&nbsp;a&nbsp;whole&nbsp;which&nbsp;is&nbsp;a&nbsp;work&nbsp;based<br>
322on&nbsp;the&nbsp;Program,&nbsp;the&nbsp;distribution&nbsp;of&nbsp;the&nbsp;whole&nbsp;must&nbsp;be&nbsp;on&nbsp;the&nbsp;terms&nbsp;of<br>
323this&nbsp;License,&nbsp;whose&nbsp;permissions&nbsp;for&nbsp;other&nbsp;licensees&nbsp;extend&nbsp;to&nbsp;the<br>
324entire&nbsp;whole,&nbsp;and&nbsp;thus&nbsp;to&nbsp;each&nbsp;and&nbsp;every&nbsp;part&nbsp;regardless&nbsp;of&nbsp;who&nbsp;wrote&nbsp;it.<br>
325<br>
326Thus,&nbsp;it&nbsp;is&nbsp;not&nbsp;the&nbsp;intent&nbsp;of&nbsp;this&nbsp;section&nbsp;to&nbsp;claim&nbsp;rights&nbsp;or&nbsp;contest<br>
327your&nbsp;rights&nbsp;to&nbsp;work&nbsp;written&nbsp;entirely&nbsp;by&nbsp;you;&nbsp;rather,&nbsp;the&nbsp;intent&nbsp;is&nbsp;to<br>
328exercise&nbsp;the&nbsp;right&nbsp;to&nbsp;control&nbsp;the&nbsp;distribution&nbsp;of&nbsp;derivative&nbsp;or<br>
329collective&nbsp;works&nbsp;based&nbsp;on&nbsp;the&nbsp;Program.<br>
330<br>
331In&nbsp;addition,&nbsp;mere&nbsp;aggregation&nbsp;of&nbsp;another&nbsp;work&nbsp;not&nbsp;based&nbsp;on&nbsp;the&nbsp;Program<br>
332with&nbsp;the&nbsp;Program&nbsp;(or&nbsp;with&nbsp;a&nbsp;work&nbsp;based&nbsp;on&nbsp;the&nbsp;Program)&nbsp;on&nbsp;a&nbsp;volume&nbsp;of<br>
333a&nbsp;storage&nbsp;or&nbsp;distribution&nbsp;medium&nbsp;does&nbsp;not&nbsp;bring&nbsp;the&nbsp;other&nbsp;work&nbsp;under<br>
334the&nbsp;scope&nbsp;of&nbsp;this&nbsp;License.<br>
335<br>
336&nbsp;&nbsp;3.&nbsp;You&nbsp;may&nbsp;copy&nbsp;and&nbsp;distribute&nbsp;the&nbsp;Program&nbsp;(or&nbsp;a&nbsp;work&nbsp;based&nbsp;on&nbsp;it,<br>
337under&nbsp;Section&nbsp;2)&nbsp;in&nbsp;object&nbsp;code&nbsp;or&nbsp;executable&nbsp;form&nbsp;under&nbsp;the&nbsp;terms&nbsp;of<br>
338Sections&nbsp;1&nbsp;and&nbsp;2&nbsp;above&nbsp;provided&nbsp;that&nbsp;you&nbsp;also&nbsp;do&nbsp;one&nbsp;of&nbsp;the&nbsp;following:<br>
339<br>
340&nbsp;&nbsp;&nbsp;&nbsp;a)&nbsp;Accompany&nbsp;it&nbsp;with&nbsp;the&nbsp;complete&nbsp;corresponding&nbsp;machine-readable<br>
341&nbsp;&nbsp;&nbsp;&nbsp;source&nbsp;code,&nbsp;which&nbsp;must&nbsp;be&nbsp;distributed&nbsp;under&nbsp;the&nbsp;terms&nbsp;of&nbsp;Sections<br>
342&nbsp;&nbsp;&nbsp;&nbsp;1&nbsp;and&nbsp;2&nbsp;above&nbsp;on&nbsp;a&nbsp;medium&nbsp;customarily&nbsp;used&nbsp;for&nbsp;software&nbsp;interchange;&nbsp;or,<br>
343<br>
344&nbsp;&nbsp;&nbsp;&nbsp;b)&nbsp;Accompany&nbsp;it&nbsp;with&nbsp;a&nbsp;written&nbsp;offer,&nbsp;valid&nbsp;for&nbsp;at&nbsp;least&nbsp;three<br>
345&nbsp;&nbsp;&nbsp;&nbsp;years,&nbsp;to&nbsp;give&nbsp;any&nbsp;third&nbsp;party,&nbsp;for&nbsp;a&nbsp;charge&nbsp;no&nbsp;more&nbsp;than&nbsp;your<br>
346&nbsp;&nbsp;&nbsp;&nbsp;cost&nbsp;of&nbsp;physically&nbsp;performing&nbsp;source&nbsp;distribution,&nbsp;a&nbsp;complete<br>
347&nbsp;&nbsp;&nbsp;&nbsp;machine-readable&nbsp;copy&nbsp;of&nbsp;the&nbsp;corresponding&nbsp;source&nbsp;code,&nbsp;to&nbsp;be<br>
348&nbsp;&nbsp;&nbsp;&nbsp;distributed&nbsp;under&nbsp;the&nbsp;terms&nbsp;of&nbsp;Sections&nbsp;1&nbsp;and&nbsp;2&nbsp;above&nbsp;on&nbsp;a&nbsp;medium<br>
349&nbsp;&nbsp;&nbsp;&nbsp;customarily&nbsp;used&nbsp;for&nbsp;software&nbsp;interchange;&nbsp;or,<br>
350<br>
351&nbsp;&nbsp;&nbsp;&nbsp;c)&nbsp;Accompany&nbsp;it&nbsp;with&nbsp;the&nbsp;information&nbsp;you&nbsp;received&nbsp;as&nbsp;to&nbsp;the&nbsp;offer<br>
352&nbsp;&nbsp;&nbsp;&nbsp;to&nbsp;distribute&nbsp;corresponding&nbsp;source&nbsp;code.&nbsp;&nbsp;(This&nbsp;alternative&nbsp;is<br>
353&nbsp;&nbsp;&nbsp;&nbsp;allowed&nbsp;only&nbsp;for&nbsp;noncommercial&nbsp;distribution&nbsp;and&nbsp;only&nbsp;if&nbsp;you<br>
354&nbsp;&nbsp;&nbsp;&nbsp;received&nbsp;the&nbsp;program&nbsp;in&nbsp;object&nbsp;code&nbsp;or&nbsp;executable&nbsp;form&nbsp;with&nbsp;such<br>
355&nbsp;&nbsp;&nbsp;&nbsp;an&nbsp;offer,&nbsp;in&nbsp;accord&nbsp;with&nbsp;Subsection&nbsp;b&nbsp;above.)<br>
356<br>
357The&nbsp;source&nbsp;code&nbsp;for&nbsp;a&nbsp;work&nbsp;means&nbsp;the&nbsp;preferred&nbsp;form&nbsp;of&nbsp;the&nbsp;work&nbsp;for<br>
358making&nbsp;modifications&nbsp;to&nbsp;it.&nbsp;&nbsp;For&nbsp;an&nbsp;executable&nbsp;work,&nbsp;complete&nbsp;source<br>
359code&nbsp;means&nbsp;all&nbsp;the&nbsp;source&nbsp;code&nbsp;for&nbsp;all&nbsp;modules&nbsp;it&nbsp;contains,&nbsp;plus&nbsp;any<br>
360associated&nbsp;interface&nbsp;definition&nbsp;files,&nbsp;plus&nbsp;the&nbsp;scripts&nbsp;used&nbsp;to<br>
361control&nbsp;compilation&nbsp;and&nbsp;installation&nbsp;of&nbsp;the&nbsp;executable.&nbsp;&nbsp;However,&nbsp;as&nbsp;a<br>
362special&nbsp;exception,&nbsp;the&nbsp;source&nbsp;code&nbsp;distributed&nbsp;need&nbsp;not&nbsp;include<br>
363anything&nbsp;that&nbsp;is&nbsp;normally&nbsp;distributed&nbsp;(in&nbsp;either&nbsp;source&nbsp;or&nbsp;binary<br>
364form)&nbsp;with&nbsp;the&nbsp;major&nbsp;components&nbsp;(compiler,&nbsp;kernel,&nbsp;and&nbsp;so&nbsp;on)&nbsp;of&nbsp;the<br>
365operating&nbsp;system&nbsp;on&nbsp;which&nbsp;the&nbsp;executable&nbsp;runs,&nbsp;unless&nbsp;that&nbsp;component<br>
366itself&nbsp;accompanies&nbsp;the&nbsp;executable.<br>
367<br>
368If&nbsp;distribution&nbsp;of&nbsp;executable&nbsp;or&nbsp;object&nbsp;code&nbsp;is&nbsp;made&nbsp;by&nbsp;offering<br>
369access&nbsp;to&nbsp;copy&nbsp;from&nbsp;a&nbsp;designated&nbsp;place,&nbsp;then&nbsp;offering&nbsp;equivalent<br>
370access&nbsp;to&nbsp;copy&nbsp;the&nbsp;source&nbsp;code&nbsp;from&nbsp;the&nbsp;same&nbsp;place&nbsp;counts&nbsp;as<br>
371distribution&nbsp;of&nbsp;the&nbsp;source&nbsp;code,&nbsp;even&nbsp;though&nbsp;third&nbsp;parties&nbsp;are&nbsp;not<br>
372compelled&nbsp;to&nbsp;copy&nbsp;the&nbsp;source&nbsp;along&nbsp;with&nbsp;the&nbsp;object&nbsp;code.<br>
373<br>
374&nbsp;&nbsp;4.&nbsp;You&nbsp;may&nbsp;not&nbsp;copy,&nbsp;modify,&nbsp;sublicense,&nbsp;or&nbsp;distribute&nbsp;the&nbsp;Program<br>
375except&nbsp;as&nbsp;expressly&nbsp;provided&nbsp;under&nbsp;this&nbsp;License.&nbsp;&nbsp;Any&nbsp;attempt<br>
376otherwise&nbsp;to&nbsp;copy,&nbsp;modify,&nbsp;sublicense&nbsp;or&nbsp;distribute&nbsp;the&nbsp;Program&nbsp;is<br>
377void,&nbsp;and&nbsp;will&nbsp;automatically&nbsp;terminate&nbsp;your&nbsp;rights&nbsp;under&nbsp;this&nbsp;License.<br>
378However,&nbsp;parties&nbsp;who&nbsp;have&nbsp;received&nbsp;copies,&nbsp;or&nbsp;rights,&nbsp;from&nbsp;you&nbsp;under<br>
379this&nbsp;License&nbsp;will&nbsp;not&nbsp;have&nbsp;their&nbsp;licenses&nbsp;terminated&nbsp;so&nbsp;long&nbsp;as&nbsp;such<br>
380parties&nbsp;remain&nbsp;in&nbsp;full&nbsp;compliance.<br>
381<br>
382&nbsp;&nbsp;5.&nbsp;You&nbsp;are&nbsp;not&nbsp;required&nbsp;to&nbsp;accept&nbsp;this&nbsp;License,&nbsp;since&nbsp;you&nbsp;have&nbsp;not<br>
383signed&nbsp;it.&nbsp;&nbsp;However,&nbsp;nothing&nbsp;else&nbsp;grants&nbsp;you&nbsp;permission&nbsp;to&nbsp;modify&nbsp;or<br>
384distribute&nbsp;the&nbsp;Program&nbsp;or&nbsp;its&nbsp;derivative&nbsp;works.&nbsp;&nbsp;These&nbsp;actions&nbsp;are<br>
385prohibited&nbsp;by&nbsp;law&nbsp;if&nbsp;you&nbsp;do&nbsp;not&nbsp;accept&nbsp;this&nbsp;License.&nbsp;&nbsp;Therefore,&nbsp;by<br>
386modifying&nbsp;or&nbsp;distributing&nbsp;the&nbsp;Program&nbsp;(or&nbsp;any&nbsp;work&nbsp;based&nbsp;on&nbsp;the<br>
387Program),&nbsp;you&nbsp;indicate&nbsp;your&nbsp;acceptance&nbsp;of&nbsp;this&nbsp;License&nbsp;to&nbsp;do&nbsp;so,&nbsp;and<br>
388all&nbsp;its&nbsp;terms&nbsp;and&nbsp;conditions&nbsp;for&nbsp;copying,&nbsp;distributing&nbsp;or&nbsp;modifying<br>
389the&nbsp;Program&nbsp;or&nbsp;works&nbsp;based&nbsp;on&nbsp;it.<br>
390<br>
391&nbsp;&nbsp;6.&nbsp;Each&nbsp;time&nbsp;you&nbsp;redistribute&nbsp;the&nbsp;Program&nbsp;(or&nbsp;any&nbsp;work&nbsp;based&nbsp;on&nbsp;the<br>
392Program),&nbsp;the&nbsp;recipient&nbsp;automatically&nbsp;receives&nbsp;a&nbsp;license&nbsp;from&nbsp;the<br>
393original&nbsp;licensor&nbsp;to&nbsp;copy,&nbsp;distribute&nbsp;or&nbsp;modify&nbsp;the&nbsp;Program&nbsp;subject&nbsp;to<br>
394these&nbsp;terms&nbsp;and&nbsp;conditions.&nbsp;&nbsp;You&nbsp;may&nbsp;not&nbsp;impose&nbsp;any&nbsp;further<br>
395restrictions&nbsp;on&nbsp;the&nbsp;recipients'&nbsp;exercise&nbsp;of&nbsp;the&nbsp;rights&nbsp;granted&nbsp;herein.<br>
396You&nbsp;are&nbsp;not&nbsp;responsible&nbsp;for&nbsp;enforcing&nbsp;compliance&nbsp;by&nbsp;third&nbsp;parties&nbsp;to<br>
397this&nbsp;License.<br>
398<br>
399&nbsp;&nbsp;7.&nbsp;If,&nbsp;as&nbsp;a&nbsp;consequence&nbsp;of&nbsp;a&nbsp;court&nbsp;judgment&nbsp;or&nbsp;allegation&nbsp;of&nbsp;patent<br>
400infringement&nbsp;or&nbsp;for&nbsp;any&nbsp;other&nbsp;reason&nbsp;(not&nbsp;limited&nbsp;to&nbsp;patent&nbsp;issues),<br>
401conditions&nbsp;are&nbsp;imposed&nbsp;on&nbsp;you&nbsp;(whether&nbsp;by&nbsp;court&nbsp;order,&nbsp;agreement&nbsp;or<br>
402otherwise)&nbsp;that&nbsp;contradict&nbsp;the&nbsp;conditions&nbsp;of&nbsp;this&nbsp;License,&nbsp;they&nbsp;do&nbsp;not<br>
403excuse&nbsp;you&nbsp;from&nbsp;the&nbsp;conditions&nbsp;of&nbsp;this&nbsp;License.&nbsp;&nbsp;If&nbsp;you&nbsp;cannot<br>
404distribute&nbsp;so&nbsp;as&nbsp;to&nbsp;satisfy&nbsp;simultaneously&nbsp;your&nbsp;obligations&nbsp;under&nbsp;this<br>
405License&nbsp;and&nbsp;any&nbsp;other&nbsp;pertinent&nbsp;obligations,&nbsp;then&nbsp;as&nbsp;a&nbsp;consequence&nbsp;you<br>
406may&nbsp;not&nbsp;distribute&nbsp;the&nbsp;Program&nbsp;at&nbsp;all.&nbsp;&nbsp;For&nbsp;example,&nbsp;if&nbsp;a&nbsp;patent<br>
407license&nbsp;would&nbsp;not&nbsp;permit&nbsp;royalty-free&nbsp;redistribution&nbsp;of&nbsp;the&nbsp;Program&nbsp;by<br>
408all&nbsp;those&nbsp;who&nbsp;receive&nbsp;copies&nbsp;directly&nbsp;or&nbsp;indirectly&nbsp;through&nbsp;you,&nbsp;then<br>
409the&nbsp;only&nbsp;way&nbsp;you&nbsp;could&nbsp;satisfy&nbsp;both&nbsp;it&nbsp;and&nbsp;this&nbsp;License&nbsp;would&nbsp;be&nbsp;to<br>
410refrain&nbsp;entirely&nbsp;from&nbsp;distribution&nbsp;of&nbsp;the&nbsp;Program.<br>
411<br>
412If&nbsp;any&nbsp;portion&nbsp;of&nbsp;this&nbsp;section&nbsp;is&nbsp;held&nbsp;invalid&nbsp;or&nbsp;unenforceable&nbsp;under<br>
413any&nbsp;particular&nbsp;circumstance,&nbsp;the&nbsp;balance&nbsp;of&nbsp;the&nbsp;section&nbsp;is&nbsp;intended&nbsp;to<br>
414apply&nbsp;and&nbsp;the&nbsp;section&nbsp;as&nbsp;a&nbsp;whole&nbsp;is&nbsp;intended&nbsp;to&nbsp;apply&nbsp;in&nbsp;other<br>
415circumstances.<br>
416<br>
417It&nbsp;is&nbsp;not&nbsp;the&nbsp;purpose&nbsp;of&nbsp;this&nbsp;section&nbsp;to&nbsp;induce&nbsp;you&nbsp;to&nbsp;infringe&nbsp;any<br>
418patents&nbsp;or&nbsp;other&nbsp;property&nbsp;right&nbsp;claims&nbsp;or&nbsp;to&nbsp;contest&nbsp;validity&nbsp;of&nbsp;any<br>
419such&nbsp;claims;&nbsp;this&nbsp;section&nbsp;has&nbsp;the&nbsp;sole&nbsp;purpose&nbsp;of&nbsp;protecting&nbsp;the<br>
420integrity&nbsp;of&nbsp;the&nbsp;free&nbsp;software&nbsp;distribution&nbsp;system,&nbsp;which&nbsp;is<br>
421implemented&nbsp;by&nbsp;public&nbsp;license&nbsp;practices.&nbsp;&nbsp;Many&nbsp;people&nbsp;have&nbsp;made<br>
422generous&nbsp;contributions&nbsp;to&nbsp;the&nbsp;wide&nbsp;range&nbsp;of&nbsp;software&nbsp;distributed<br>
423through&nbsp;that&nbsp;system&nbsp;in&nbsp;reliance&nbsp;on&nbsp;consistent&nbsp;application&nbsp;of&nbsp;that<br>
424system;&nbsp;it&nbsp;is&nbsp;up&nbsp;to&nbsp;the&nbsp;author/donor&nbsp;to&nbsp;decide&nbsp;if&nbsp;he&nbsp;or&nbsp;she&nbsp;is&nbsp;willing<br>
425to&nbsp;distribute&nbsp;software&nbsp;through&nbsp;any&nbsp;other&nbsp;system&nbsp;and&nbsp;a&nbsp;licensee&nbsp;cannot<br>
426impose&nbsp;that&nbsp;choice.<br>
427<br>
428This&nbsp;section&nbsp;is&nbsp;intended&nbsp;to&nbsp;make&nbsp;thoroughly&nbsp;clear&nbsp;what&nbsp;is&nbsp;believed&nbsp;to<br>
429be&nbsp;a&nbsp;consequence&nbsp;of&nbsp;the&nbsp;rest&nbsp;of&nbsp;this&nbsp;License.<br>
430<br>
431&nbsp;&nbsp;8.&nbsp;If&nbsp;the&nbsp;distribution&nbsp;and/or&nbsp;use&nbsp;of&nbsp;the&nbsp;Program&nbsp;is&nbsp;restricted&nbsp;in<br>
432certain&nbsp;countries&nbsp;either&nbsp;by&nbsp;patents&nbsp;or&nbsp;by&nbsp;copyrighted&nbsp;interfaces,&nbsp;the<br>
433original&nbsp;copyright&nbsp;holder&nbsp;who&nbsp;places&nbsp;the&nbsp;Program&nbsp;under&nbsp;this&nbsp;License<br>
434may&nbsp;add&nbsp;an&nbsp;explicit&nbsp;geographical&nbsp;distribution&nbsp;limitation&nbsp;excluding<br>
435those&nbsp;countries,&nbsp;so&nbsp;that&nbsp;distribution&nbsp;is&nbsp;permitted&nbsp;only&nbsp;in&nbsp;or&nbsp;among<br>
436countries&nbsp;not&nbsp;thus&nbsp;excluded.&nbsp;&nbsp;In&nbsp;such&nbsp;case,&nbsp;this&nbsp;License&nbsp;incorporates<br>
437the&nbsp;limitation&nbsp;as&nbsp;if&nbsp;written&nbsp;in&nbsp;the&nbsp;body&nbsp;of&nbsp;this&nbsp;License.<br>
438<br>
439&nbsp;&nbsp;9.&nbsp;The&nbsp;Free&nbsp;Software&nbsp;Foundation&nbsp;may&nbsp;publish&nbsp;revised&nbsp;and/or&nbsp;new&nbsp;versions<br>
440of&nbsp;the&nbsp;General&nbsp;Public&nbsp;License&nbsp;from&nbsp;time&nbsp;to&nbsp;time.&nbsp;&nbsp;Such&nbsp;new&nbsp;versions&nbsp;will<br>
441be&nbsp;similar&nbsp;in&nbsp;spirit&nbsp;to&nbsp;the&nbsp;present&nbsp;version,&nbsp;but&nbsp;may&nbsp;differ&nbsp;in&nbsp;detail&nbsp;to<br>
442address&nbsp;new&nbsp;problems&nbsp;or&nbsp;concerns.<br>
443<br>
444Each&nbsp;version&nbsp;is&nbsp;given&nbsp;a&nbsp;distinguishing&nbsp;version&nbsp;number.&nbsp;&nbsp;If&nbsp;the&nbsp;Program<br>
445specifies&nbsp;a&nbsp;version&nbsp;number&nbsp;of&nbsp;this&nbsp;License&nbsp;which&nbsp;applies&nbsp;to&nbsp;it&nbsp;and&nbsp;&quot;any<br>
446later&nbsp;version&quot;,&nbsp;you&nbsp;have&nbsp;the&nbsp;option&nbsp;of&nbsp;following&nbsp;the&nbsp;terms&nbsp;and&nbsp;conditions<br>
447either&nbsp;of&nbsp;that&nbsp;version&nbsp;or&nbsp;of&nbsp;any&nbsp;later&nbsp;version&nbsp;published&nbsp;by&nbsp;the&nbsp;Free<br>
448Software&nbsp;Foundation.&nbsp;&nbsp;If&nbsp;the&nbsp;Program&nbsp;does&nbsp;not&nbsp;specify&nbsp;a&nbsp;version&nbsp;number&nbsp;of<br>
449this&nbsp;License,&nbsp;you&nbsp;may&nbsp;choose&nbsp;any&nbsp;version&nbsp;ever&nbsp;published&nbsp;by&nbsp;the&nbsp;Free&nbsp;Software<br>
450Foundation.<br>
451<br>
452&nbsp;&nbsp;10.&nbsp;If&nbsp;you&nbsp;wish&nbsp;to&nbsp;incorporate&nbsp;parts&nbsp;of&nbsp;the&nbsp;Program&nbsp;into&nbsp;other&nbsp;free<br>
453programs&nbsp;whose&nbsp;distribution&nbsp;conditions&nbsp;are&nbsp;different,&nbsp;write&nbsp;to&nbsp;the&nbsp;author<br>
454to&nbsp;ask&nbsp;for&nbsp;permission.&nbsp;&nbsp;For&nbsp;software&nbsp;which&nbsp;is&nbsp;copyrighted&nbsp;by&nbsp;the&nbsp;Free<br>
455Software&nbsp;Foundation,&nbsp;write&nbsp;to&nbsp;the&nbsp;Free&nbsp;Software&nbsp;Foundation;&nbsp;we&nbsp;sometimes<br>
456make&nbsp;exceptions&nbsp;for&nbsp;this.&nbsp;&nbsp;Our&nbsp;decision&nbsp;will&nbsp;be&nbsp;guided&nbsp;by&nbsp;the&nbsp;two&nbsp;goals<br>
457of&nbsp;preserving&nbsp;the&nbsp;free&nbsp;status&nbsp;of&nbsp;all&nbsp;derivatives&nbsp;of&nbsp;our&nbsp;free&nbsp;software&nbsp;and<br>
458of&nbsp;promoting&nbsp;the&nbsp;sharing&nbsp;and&nbsp;reuse&nbsp;of&nbsp;software&nbsp;generally.<br>
459<br>
460&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;NO&nbsp;WARRANTY<br>
461<br>
462&nbsp;&nbsp;11.&nbsp;BECAUSE&nbsp;THE&nbsp;PROGRAM&nbsp;IS&nbsp;LICENSED&nbsp;FREE&nbsp;OF&nbsp;CHARGE,&nbsp;THERE&nbsp;IS&nbsp;NO&nbsp;WARRANTY<br>
463FOR&nbsp;THE&nbsp;PROGRAM,&nbsp;TO&nbsp;THE&nbsp;EXTENT&nbsp;PERMITTED&nbsp;BY&nbsp;APPLICABLE&nbsp;LAW.&nbsp;&nbsp;EXCEPT&nbsp;WHEN<br>
464OTHERWISE&nbsp;STATED&nbsp;IN&nbsp;WRITING&nbsp;THE&nbsp;COPYRIGHT&nbsp;HOLDERS&nbsp;AND/OR&nbsp;OTHER&nbsp;PARTIES<br>
465PROVIDE&nbsp;THE&nbsp;PROGRAM&nbsp;&quot;AS&nbsp;IS&quot;&nbsp;WITHOUT&nbsp;WARRANTY&nbsp;OF&nbsp;ANY&nbsp;KIND,&nbsp;EITHER&nbsp;EXPRESSED<br>
466OR&nbsp;IMPLIED,&nbsp;INCLUDING,&nbsp;BUT&nbsp;NOT&nbsp;LIMITED&nbsp;TO,&nbsp;THE&nbsp;IMPLIED&nbsp;WARRANTIES&nbsp;OF<br>
467MERCHANTABILITY&nbsp;AND&nbsp;FITNESS&nbsp;FOR&nbsp;A&nbsp;PARTICULAR&nbsp;PURPOSE.&nbsp;&nbsp;THE&nbsp;ENTIRE&nbsp;RISK&nbsp;AS<br>
468TO&nbsp;THE&nbsp;QUALITY&nbsp;AND&nbsp;PERFORMANCE&nbsp;OF&nbsp;THE&nbsp;PROGRAM&nbsp;IS&nbsp;WITH&nbsp;YOU.&nbsp;&nbsp;SHOULD&nbsp;THE<br>
469PROGRAM&nbsp;PROVE&nbsp;DEFECTIVE,&nbsp;YOU&nbsp;ASSUME&nbsp;THE&nbsp;COST&nbsp;OF&nbsp;ALL&nbsp;NECESSARY&nbsp;SERVICING,<br>
470REPAIR&nbsp;OR&nbsp;CORRECTION.<br>
471<br>
472&nbsp;&nbsp;12.&nbsp;IN&nbsp;NO&nbsp;EVENT&nbsp;UNLESS&nbsp;REQUIRED&nbsp;BY&nbsp;APPLICABLE&nbsp;LAW&nbsp;OR&nbsp;AGREED&nbsp;TO&nbsp;IN&nbsp;WRITING<br>
473WILL&nbsp;ANY&nbsp;COPYRIGHT&nbsp;HOLDER,&nbsp;OR&nbsp;ANY&nbsp;OTHER&nbsp;PARTY&nbsp;WHO&nbsp;MAY&nbsp;MODIFY&nbsp;AND/OR<br>
474REDISTRIBUTE&nbsp;THE&nbsp;PROGRAM&nbsp;AS&nbsp;PERMITTED&nbsp;ABOVE,&nbsp;BE&nbsp;LIABLE&nbsp;TO&nbsp;YOU&nbsp;FOR&nbsp;DAMAGES,<br>
475INCLUDING&nbsp;ANY&nbsp;GENERAL,&nbsp;SPECIAL,&nbsp;INCIDENTAL&nbsp;OR&nbsp;CONSEQUENTIAL&nbsp;DAMAGES&nbsp;ARISING<br>
476OUT&nbsp;OF&nbsp;THE&nbsp;USE&nbsp;OR&nbsp;INABILITY&nbsp;TO&nbsp;USE&nbsp;THE&nbsp;PROGRAM&nbsp;(INCLUDING&nbsp;BUT&nbsp;NOT&nbsp;LIMITED<br>
477TO&nbsp;LOSS&nbsp;OF&nbsp;DATA&nbsp;OR&nbsp;DATA&nbsp;BEING&nbsp;RENDERED&nbsp;INACCURATE&nbsp;OR&nbsp;LOSSES&nbsp;SUSTAINED&nbsp;BY<br>
478YOU&nbsp;OR&nbsp;THIRD&nbsp;PARTIES&nbsp;OR&nbsp;A&nbsp;FAILURE&nbsp;OF&nbsp;THE&nbsp;PROGRAM&nbsp;TO&nbsp;OPERATE&nbsp;WITH&nbsp;ANY&nbsp;OTHER<br>
479PROGRAMS),&nbsp;EVEN&nbsp;IF&nbsp;SUCH&nbsp;HOLDER&nbsp;OR&nbsp;OTHER&nbsp;PARTY&nbsp;HAS&nbsp;BEEN&nbsp;ADVISED&nbsp;OF&nbsp;THE<br>
480POSSIBILITY&nbsp;OF&nbsp;SUCH&nbsp;DAMAGES.<br>
481<br>
482&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;END&nbsp;OF&nbsp;TERMS&nbsp;AND&nbsp;CONDITIONS<br>
483<br>
484&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;How&nbsp;to&nbsp;Apply&nbsp;These&nbsp;Terms&nbsp;to&nbsp;Your&nbsp;New&nbsp;Programs<br>
485<br>
486&nbsp;&nbsp;If&nbsp;you&nbsp;develop&nbsp;a&nbsp;new&nbsp;program,&nbsp;and&nbsp;you&nbsp;want&nbsp;it&nbsp;to&nbsp;be&nbsp;of&nbsp;the&nbsp;greatest<br>
487possible&nbsp;use&nbsp;to&nbsp;the&nbsp;public,&nbsp;the&nbsp;best&nbsp;way&nbsp;to&nbsp;achieve&nbsp;this&nbsp;is&nbsp;to&nbsp;make&nbsp;it<br>
488free&nbsp;software&nbsp;which&nbsp;everyone&nbsp;can&nbsp;redistribute&nbsp;and&nbsp;change&nbsp;under&nbsp;these&nbsp;terms.<br>
489<br>
490&nbsp;&nbsp;To&nbsp;do&nbsp;so,&nbsp;attach&nbsp;the&nbsp;following&nbsp;notices&nbsp;to&nbsp;the&nbsp;program.&nbsp;&nbsp;It&nbsp;is&nbsp;safest<br>
491to&nbsp;attach&nbsp;them&nbsp;to&nbsp;the&nbsp;start&nbsp;of&nbsp;each&nbsp;source&nbsp;file&nbsp;to&nbsp;most&nbsp;effectively<br>
492convey&nbsp;the&nbsp;exclusion&nbsp;of&nbsp;warranty;&nbsp;and&nbsp;each&nbsp;file&nbsp;should&nbsp;have&nbsp;at&nbsp;least<br>
493the&nbsp;&quot;copyright&quot;&nbsp;line&nbsp;and&nbsp;a&nbsp;pointer&nbsp;to&nbsp;where&nbsp;the&nbsp;full&nbsp;notice&nbsp;is&nbsp;found.<br>
494<br>
495&nbsp;&nbsp;&nbsp;&nbsp;&lt;one&nbsp;line&nbsp;to&nbsp;give&nbsp;the&nbsp;program's&nbsp;name&nbsp;and&nbsp;a&nbsp;brief&nbsp;idea&nbsp;of&nbsp;what&nbsp;it&nbsp;does.&gt;<br>
496&nbsp;&nbsp;&nbsp;&nbsp;Copyright&nbsp;(C)&nbsp;&lt;year&gt;&nbsp;&nbsp;&lt;name&nbsp;of&nbsp;author&gt;<br>
497<br>
498&nbsp;&nbsp;&nbsp;&nbsp;This&nbsp;program&nbsp;is&nbsp;free&nbsp;software;&nbsp;you&nbsp;can&nbsp;redistribute&nbsp;it&nbsp;and/or&nbsp;modify<br>
499&nbsp;&nbsp;&nbsp;&nbsp;it&nbsp;under&nbsp;the&nbsp;terms&nbsp;of&nbsp;the&nbsp;GNU&nbsp;General&nbsp;Public&nbsp;License&nbsp;as&nbsp;published&nbsp;by<br>
500&nbsp;&nbsp;&nbsp;&nbsp;the&nbsp;Free&nbsp;Software&nbsp;Foundation;&nbsp;either&nbsp;version&nbsp;2&nbsp;of&nbsp;the&nbsp;License,&nbsp;or<br>
501&nbsp;&nbsp;&nbsp;&nbsp;(at&nbsp;your&nbsp;option)&nbsp;any&nbsp;later&nbsp;version.<br>
502<br>
503&nbsp;&nbsp;&nbsp;&nbsp;This&nbsp;program&nbsp;is&nbsp;distributed&nbsp;in&nbsp;the&nbsp;hope&nbsp;that&nbsp;it&nbsp;will&nbsp;be&nbsp;useful,<br>
504&nbsp;&nbsp;&nbsp;&nbsp;but&nbsp;WITHOUT&nbsp;ANY&nbsp;WARRANTY;&nbsp;without&nbsp;even&nbsp;the&nbsp;implied&nbsp;warranty&nbsp;of<br>
505&nbsp;&nbsp;&nbsp;&nbsp;MERCHANTABILITY&nbsp;or&nbsp;FITNESS&nbsp;FOR&nbsp;A&nbsp;PARTICULAR&nbsp;PURPOSE.&nbsp;&nbsp;See&nbsp;the<br>
506&nbsp;&nbsp;&nbsp;&nbsp;GNU&nbsp;General&nbsp;Public&nbsp;License&nbsp;for&nbsp;more&nbsp;details.<br>
507<br>
508&nbsp;&nbsp;&nbsp;&nbsp;You&nbsp;should&nbsp;have&nbsp;received&nbsp;a&nbsp;copy&nbsp;of&nbsp;the&nbsp;GNU&nbsp;General&nbsp;Public&nbsp;License&nbsp;along<br>
509&nbsp;&nbsp;&nbsp;&nbsp;with&nbsp;this&nbsp;program;&nbsp;if&nbsp;not,&nbsp;write&nbsp;to&nbsp;the&nbsp;Free&nbsp;Software&nbsp;Foundation,&nbsp;Inc.,<br>
510&nbsp;&nbsp;&nbsp;&nbsp;51&nbsp;Franklin&nbsp;Street,&nbsp;Fifth&nbsp;Floor,&nbsp;Boston,&nbsp;MA&nbsp;02110-1301&nbsp;USA.<br>
511<br>
512Also&nbsp;add&nbsp;information&nbsp;on&nbsp;how&nbsp;to&nbsp;contact&nbsp;you&nbsp;by&nbsp;electronic&nbsp;and&nbsp;paper&nbsp;mail.<br>
513<br>
514If&nbsp;the&nbsp;program&nbsp;is&nbsp;interactive,&nbsp;make&nbsp;it&nbsp;output&nbsp;a&nbsp;short&nbsp;notice&nbsp;like&nbsp;this<br>
515when&nbsp;it&nbsp;starts&nbsp;in&nbsp;an&nbsp;interactive&nbsp;mode:<br>
516<br>
517&nbsp;&nbsp;&nbsp;&nbsp;Gnomovision&nbsp;version&nbsp;69,&nbsp;Copyright&nbsp;(C)&nbsp;year&nbsp;name&nbsp;of&nbsp;author<br>
518&nbsp;&nbsp;&nbsp;&nbsp;Gnomovision&nbsp;comes&nbsp;with&nbsp;ABSOLUTELY&nbsp;NO&nbsp;WARRANTY;&nbsp;for&nbsp;details&nbsp;type&nbsp;`show&nbsp;w'.<br>
519&nbsp;&nbsp;&nbsp;&nbsp;This&nbsp;is&nbsp;free&nbsp;software,&nbsp;and&nbsp;you&nbsp;are&nbsp;welcome&nbsp;to&nbsp;redistribute&nbsp;it<br>
520&nbsp;&nbsp;&nbsp;&nbsp;under&nbsp;certain&nbsp;conditions;&nbsp;type&nbsp;`show&nbsp;c'&nbsp;for&nbsp;details.<br>
521<br>
522The&nbsp;hypothetical&nbsp;commands&nbsp;`show&nbsp;w'&nbsp;and&nbsp;`show&nbsp;c'&nbsp;should&nbsp;show&nbsp;the&nbsp;appropriate<br>
523parts&nbsp;of&nbsp;the&nbsp;General&nbsp;Public&nbsp;License.&nbsp;&nbsp;Of&nbsp;course,&nbsp;the&nbsp;commands&nbsp;you&nbsp;use&nbsp;may<br>
524be&nbsp;called&nbsp;something&nbsp;other&nbsp;than&nbsp;`show&nbsp;w'&nbsp;and&nbsp;`show&nbsp;c';&nbsp;they&nbsp;could&nbsp;even&nbsp;be<br>
525mouse-clicks&nbsp;or&nbsp;menu&nbsp;items--whatever&nbsp;suits&nbsp;your&nbsp;program.<br>
526<br>
527You&nbsp;should&nbsp;also&nbsp;get&nbsp;your&nbsp;employer&nbsp;(if&nbsp;you&nbsp;work&nbsp;as&nbsp;a&nbsp;programmer)&nbsp;or&nbsp;your<br>
528school,&nbsp;if&nbsp;any,&nbsp;to&nbsp;sign&nbsp;a&nbsp;&quot;copyright&nbsp;disclaimer&quot;&nbsp;for&nbsp;the&nbsp;program,&nbsp;if<br>
529necessary.&nbsp;&nbsp;Here&nbsp;is&nbsp;a&nbsp;sample;&nbsp;alter&nbsp;the&nbsp;names:<br>
530<br>
531&nbsp;&nbsp;Yoyodyne,&nbsp;Inc.,&nbsp;hereby&nbsp;disclaims&nbsp;all&nbsp;copyright&nbsp;interest&nbsp;in&nbsp;the&nbsp;program<br>
532&nbsp;&nbsp;`Gnomovision'&nbsp;(which&nbsp;makes&nbsp;passes&nbsp;at&nbsp;compilers)&nbsp;written&nbsp;by&nbsp;James&nbsp;Hacker.<br>
533<br>
534&nbsp;&nbsp;&lt;signature&nbsp;of&nbsp;Ty&nbsp;Coon&gt;,&nbsp;1&nbsp;April&nbsp;1989<br>
535&nbsp;&nbsp;Ty&nbsp;Coon,&nbsp;President&nbsp;of&nbsp;Vice<br>
536<br>
537This&nbsp;General&nbsp;Public&nbsp;License&nbsp;does&nbsp;not&nbsp;permit&nbsp;incorporating&nbsp;your&nbsp;program&nbsp;into<br>
538proprietary&nbsp;programs.&nbsp;&nbsp;If&nbsp;your&nbsp;program&nbsp;is&nbsp;a&nbsp;subroutine&nbsp;library,&nbsp;you&nbsp;may<br>
539consider&nbsp;it&nbsp;more&nbsp;useful&nbsp;to&nbsp;permit&nbsp;linking&nbsp;proprietary&nbsp;applications&nbsp;with&nbsp;the<br>
540library.&nbsp;&nbsp;If&nbsp;this&nbsp;is&nbsp;what&nbsp;you&nbsp;want&nbsp;to&nbsp;do,&nbsp;use&nbsp;the&nbsp;GNU&nbsp;Lesser&nbsp;General<br>
541Public&nbsp;License&nbsp;instead&nbsp;of&nbsp;this&nbsp;License.<br>
542</span></code>
543<hr>Input File: omh/license.omh
544
545<hr>
546<center><b><big><big><a name="3" id="3">3: The Nonlinear Constrained Kalman-Bucy Smoother</a>
547</big></big></b></center>
548<br>
549<b><big><a name="3.a" id="3.a">3.a: Syntax</a></big></b>
550
551<br>
552<code><font color="blue"><span style='white-space: nowrap'>[</span></font></code><i><span style='white-space: nowrap'>x_out</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>u_out</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>info</span></i><code><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;ckbs_nonlinear(</span></font></code><i><span style='white-space: nowrap'>f_fun</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>g_fun</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>h_fun</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;...<br>
553&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></font></code><i><span style='white-space: nowrap'>max_itr</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>epsilon</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>x_in</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>z</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>qinv</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>rinv</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>level</span></i><code><font color="blue"><span style='white-space: nowrap'>)</span></font></code>
554
555<br>
556<br>
557<b><big><a name="3.b" id="3.b">3.b: Purpose</a></big></b>
558<br>
559This routine minimizes the
560Kalman-Bucy smoother residual sum of squares objective
561for a general nonlinear model functions
562(in the case where the model functions are affine, the routine
563<a href="#4">4: <span style='white-space: nowrap'>ckbs_affine</span></a>
564 is more efficient).
565
566<br>
567<br>
568<b><big><a name="3.c" id="3.c">3.c: Notation</a></big></b>
569<br>
570The Kalman-Bucy smoother residual sum of squares is defined by
571<code>
572<span style='white-space: nowrap'>&nbsp;\[<br>
573\begin{array}{rcl}<br>
574S&nbsp;(&nbsp;x_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N&nbsp;)&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;\sum_{k=1}^N&nbsp;S_k&nbsp;(&nbsp;x_k&nbsp;,&nbsp;x_{k-1}&nbsp;)&nbsp;\\<br>
575S_k&nbsp;(&nbsp;x_k&nbsp;,&nbsp;x_{k-1}&nbsp;)&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;<br>
576\frac{1}{2}&nbsp;<br>
577[&nbsp;z_k&nbsp;-&nbsp;h_k&nbsp;(&nbsp;x_k&nbsp;)&nbsp;]^\T&nbsp;*&nbsp;R_k^{-1}&nbsp;*&nbsp;[&nbsp;z_k&nbsp;-&nbsp;h_k&nbsp;(&nbsp;x_k&nbsp;)&nbsp;]<br>
578\\<br>
579&amp;&nbsp;+&nbsp;&amp;<br>
580\frac{1}{2}&nbsp;<br>
581[&nbsp;x_k&nbsp;-&nbsp;g_k&nbsp;(&nbsp;x_{k-1}&nbsp;)&nbsp;]^\T&nbsp;*&nbsp;Q_k^{-1}&nbsp;*&nbsp;[&nbsp;x_k&nbsp;-&nbsp;g_k&nbsp;(&nbsp;x_{k-1}&nbsp;)&nbsp;]<br>
582\\<br>
583\end{array}<br>
584\]&nbsp;</span></code>
585
586where the matrices <code>
587<span style='white-space: nowrap'>&nbsp;R_k</span></code>
588 and <code>
589<span style='white-space: nowrap'>&nbsp;Q_k</span></code>
590 are
591symmetric positive definite and
592<code>
593<span style='white-space: nowrap'>&nbsp;x_0</span></code>
594 is the constant zero.
595Note that <code>
596<span style='white-space: nowrap'>&nbsp;g_1&nbsp;(&nbsp;x_0&nbsp;)</span></code>
597 is the initial state estimate
598and <code>
599<span style='white-space: nowrap'>&nbsp;Q_1</span></code>
600 is the corresponding covariance.
601
602<br>
603<br>
604<b><big><a name="3.d" id="3.d">3.d: Problem</a></big></b>
605<br>
606Our constrained Kalman-Bucy smoother problem is
607<code>
608<span style='white-space: nowrap'>&nbsp;\[<br>
609\begin{array}{rll}<br>
610{\rm&nbsp;minimize}&nbsp;<br>
611&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;S(&nbsp;x_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N&nbsp;)&nbsp;<br>
612&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;{\rm&nbsp;w.r.t.}&nbsp;\;&nbsp;x_1&nbsp;\in&nbsp;\R^n&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N&nbsp;\in&nbsp;\R^n<br>
613\\<br>
614{\rm&nbsp;subject&nbsp;\;&nbsp;to}&nbsp;<br>
615&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;f_k(x_k)&nbsp;\leq&nbsp;0&nbsp;<br>
616&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;{\rm&nbsp;for}&nbsp;\;&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N<br>
617\end{array}<br>
618\]&nbsp;</span></code>
619
620
621<br>
622<br>
623<b><big><a name="3.e" id="3.e">3.e: First Order Conditions</a></big></b>
624<br>
625A state sequence <code>
626<span style='white-space: nowrap'>&nbsp;(&nbsp;x_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N&nbsp;)</span></code>
627 is considered a solution
628if there is a Lagrange multiplier sequence <code>
629<span style='white-space: nowrap'>&nbsp;(&nbsp;u_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;u_N&nbsp;)</span></code>
630 
631such that the following conditions are satisfied for
632<code>
633<span style='white-space: nowrap'>&nbsp;i&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;\ell</span></code>
634 and <code>
635<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
636:
637<code>
638<span style='white-space: nowrap'>&nbsp;\[<br>
639\begin{array}{rcl}<br>
640f_k&nbsp;(&nbsp;x_k&nbsp;)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;\leq&nbsp;&amp;&nbsp;\varepsilon&nbsp;&nbsp;\\<br>
6410&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;\leq&nbsp;&amp;&nbsp;u_k&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
642|&nbsp;u_k^\T&nbsp;*&nbsp;\partial_k&nbsp;f_k&nbsp;(&nbsp;x_k&nbsp;)&nbsp;+&nbsp;\partial_k&nbsp;&nbsp;S(&nbsp;x_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N&nbsp;)&nbsp;|<br>
643&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;\leq&nbsp;&amp;&nbsp;\varepsilon&nbsp;\\&nbsp;&nbsp;<br>
644|&nbsp;f_k&nbsp;(&nbsp;x_k&nbsp;)_i&nbsp;|&nbsp;*&nbsp;(&nbsp;u_k&nbsp;)_i&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;\leq&nbsp;&amp;&nbsp;\varepsilon<br>
645\end{array}<br>
646\]&nbsp;</span></code>
647
648Here the notation
649<code>
650<span style='white-space: nowrap'>&nbsp;\partial_k</span></code>
651 is used for the partial derivative of
652with respect to <code>
653<span style='white-space: nowrap'>&nbsp;x_k</span></code>
654 and the notation
655<code>
656<span style='white-space: nowrap'>&nbsp;(u_k)_i</span></code>
657 denotes the <i>i</i>-th component of <code>
658<span style='white-space: nowrap'>&nbsp;u_k</span></code>
659.
660
661<br>
662<br>
663<b><big><a name="3.f" id="3.f">3.f: f_fun</a></big></b>
664<br>
665The <code><font color="blue">ckbs_nonlinear</font></code> argument <i>f_fun</i> 
666is a function that supports both of the
667following syntaxes
668<code><font color="blue"><span style='white-space: nowrap'><br>
669&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[</span></font></code><i><span style='white-space: nowrap'>fk</span></i><code><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;feval(</span></font></code><i><span style='white-space: nowrap'>f_fun</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>k</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>xk</span></i><code><font color="blue"><span style='white-space: nowrap'>)<br>
670&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[</span></font></code><i><span style='white-space: nowrap'>fk</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>Fk</span></i><code><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;feval(</span></font></code><i><span style='white-space: nowrap'>f_fun</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>k</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>xk</span></i><code><font color="blue"><span style='white-space: nowrap'>)<br>
671</span></font></code>In the case where there are no constraints,
672one can use the following function for <i>f_fun</i>:
673<code><font color='blue'><pre style='display:inline'> 
674        [fk, Fk] = f_fun(k, xk)
675        n  = size(xk, 1);
676        fk = -1;
677        Fk =  zeros(1, n);
678        return
679        end
680</pre></font></code>
681
682
683<br>
684<br>
685<b><a name="3.f.a" id="3.f.a">3.f.a: k</a></b>
686<br>
687The <i>f_fun</i> argument <i>k</i> is an integer with
688<code>
689<span style='white-space: nowrap'>&nbsp;1&nbsp;\leq&nbsp;k&nbsp;\leq&nbsp;N</span></code>
690.
691
692<br>
693<br>
694<b><a name="3.f.b" id="3.f.b">3.f.b: xk</a></b>
695<br>
696The <i>f_fun</i> argument <i>xk</i> is an column vector with
697length <code>
698<span style='white-space: nowrap'>&nbsp;n</span></code>
699. It specifies the state vector at time index <i>k</i>
700<code>
701<span style='white-space: nowrap'>&nbsp;\[<br>
702&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;xk&nbsp;=&nbsp;x_k<br>
703\]&nbsp;</span></code>
704.
705
706<br>
707<br>
708<b><a name="3.f.c" id="3.f.c">3.f.c: fk</a></b>
709<br>
710The <i>f_fun</i> result <i>fk</i> is an column vector with
711length <code>
712<span style='white-space: nowrap'>&nbsp;\ell</span></code>
713 and
714<code>
715<span style='white-space: nowrap'>&nbsp;\[<br>
716&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;fk&nbsp;=&nbsp;f_k&nbsp;(&nbsp;x_k&nbsp;)&nbsp;<br>
717\]&nbsp;</span></code>
718
719
720<br>
721<br>
722<b><a name="3.f.d" id="3.f.d">3.f.d: Fk</a></b>
723<br>
724If the <i>f_fun</i> result <i>Fk</i> is present in the syntax,
725it is the <code>
726<span style='white-space: nowrap'>&nbsp;\ell&nbsp;\times&nbsp;n</span></code>
727 matrix given by
728and
729<code>
730<span style='white-space: nowrap'>&nbsp;\[<br>
731&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Fk&nbsp;=&nbsp;\partial_k&nbsp;f_k&nbsp;(&nbsp;x_k&nbsp;)&nbsp;<br>
732\]&nbsp;</span></code>
733
734
735<br>
736<br>
737<b><big><a name="3.g" id="3.g">3.g: g_fun</a></big></b>
738<br>
739The <code><font color="blue">ckbs_nonlinear</font></code> argument <i>g_fun</i> 
740is a function that supports both of
741the following syntaxes
742<code><font color="blue"><span style='white-space: nowrap'><br>
743&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[</span></font></code><i><span style='white-space: nowrap'>gk</span></i><code><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;feval(</span></font></code><i><span style='white-space: nowrap'>g_fun</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>k</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>xk1</span></i><code><font color="blue"><span style='white-space: nowrap'>)<br>
744&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[</span></font></code><i><span style='white-space: nowrap'>gk</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>Gk</span></i><code><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;feval(</span></font></code><i><span style='white-space: nowrap'>g_fun</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>k</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>xk1</span></i><code><font color="blue"><span style='white-space: nowrap'>)<br>
745</span></font></code><br>
746<b><a name="3.g.a" id="3.g.a">3.g.a: k</a></b>
747<br>
748The <i>g_fun</i> argument <i>k</i> is an integer with
749<code>
750<span style='white-space: nowrap'>&nbsp;1&nbsp;\leq&nbsp;k&nbsp;\leq&nbsp;N</span></code>
751.
752The case <code>
753<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1</span></code>
754 serves to specify the initial state estimate.
755
756<br>
757<br>
758<b><a name="3.g.b" id="3.g.b">3.g.b: xk1</a></b>
759<br>
760The <i>g_fun</i> argument <i>xk1</i> is an column vector with
761length <code>
762<span style='white-space: nowrap'>&nbsp;n</span></code>
763. It specifies the state vector at time index <i>k</i>
764<code>
765<span style='white-space: nowrap'>&nbsp;\[<br>
766&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;xk1&nbsp;=&nbsp;x_{k-1}<br>
767\]&nbsp;</span></code>
768.
769In the case <code>
770<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1</span></code>
771, the value of <i>xk1</i> does not matter.
772
773<br>
774<br>
775<b><a name="3.g.c" id="3.g.c">3.g.c: gk</a></b>
776<br>
777The <i>g_fun</i> result <i>gk</i> is an column vector with
778length <code>
779<span style='white-space: nowrap'>&nbsp;n</span></code>
780 and
781<code>
782<span style='white-space: nowrap'>&nbsp;\[<br>
783&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;gk&nbsp;=&nbsp;g_k&nbsp;(&nbsp;x_{k-1}&nbsp;)&nbsp;<br>
784\]&nbsp;</span></code>
785
786In the case <code>
787<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1</span></code>
788, the value of <i>gk</i> is the initial state
789estimate at time index <i>k</i>.
790
791<br>
792<br>
793<b><a name="3.g.d" id="3.g.d">3.g.d: Gk</a></b>
794<br>
795If the <i>g_fun</i> result <i>Gk</i> is present in the syntax,
796it is the <code>
797<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n</span></code>
798 matrix given by
799and
800<code>
801<span style='white-space: nowrap'>&nbsp;\[<br>
802&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Gk&nbsp;=&nbsp;\partial_{k-1}&nbsp;g_k&nbsp;(&nbsp;x_{k-1}&nbsp;)&nbsp;<br>
803\]&nbsp;</span></code>
804
805In the case <code>
806<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1</span></code>
807, the value of <i>Gk</i> is the zero matrix;
808i.e., <code>
809<span style='white-space: nowrap'>&nbsp;g_k</span></code>
810 does not depend on the value of <code>
811<span style='white-space: nowrap'>&nbsp;x_{k-1}</span></code>
812.
813
814<br>
815<br>
816<b><big><a name="3.h" id="3.h">3.h: h_fun</a></big></b>
817<br>
818The <code><font color="blue">ckbs_nonlinear</font></code> argument <i>h_fun</i> 
819is a function that supports both of the
820following syntaxes
821<code><font color="blue"><span style='white-space: nowrap'><br>
822&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[</span></font></code><i><span style='white-space: nowrap'>hk</span></i><code><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;feval(</span></font></code><i><span style='white-space: nowrap'>h_fun</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>k</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>xk</span></i><code><font color="blue"><span style='white-space: nowrap'>)<br>
823&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[</span></font></code><i><span style='white-space: nowrap'>hk</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>Hk</span></i><code><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;feval(</span></font></code><i><span style='white-space: nowrap'>h_fun</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>k</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>xk</span></i><code><font color="blue"><span style='white-space: nowrap'>)<br>
824</span></font></code><br>
825<b><a name="3.h.a" id="3.h.a">3.h.a: k</a></b>
826<br>
827The <i>h_fun</i> argument <i>k</i> is an integer with
828<code>
829<span style='white-space: nowrap'>&nbsp;1&nbsp;\leq&nbsp;k&nbsp;\leq&nbsp;N</span></code>
830.
831
832<br>
833<br>
834<b><a name="3.h.b" id="3.h.b">3.h.b: xk</a></b>
835<br>
836The <i>h_fun</i> argument <i>xk</i> is an column vector with
837length <code>
838<span style='white-space: nowrap'>&nbsp;n</span></code>
839. It specifies the state vector at time index <i>k</i>
840<code>
841<span style='white-space: nowrap'>&nbsp;\[<br>
842&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;xk&nbsp;=&nbsp;x_k<br>
843\]&nbsp;</span></code>
844.
845
846<br>
847<br>
848<b><a name="3.h.c" id="3.h.c">3.h.c: hk</a></b>
849<br>
850The <i>h_fun</i> result <i>hk</i> is an column vector with
851length <code>
852<span style='white-space: nowrap'>&nbsp;m</span></code>
853 and
854<code>
855<span style='white-space: nowrap'>&nbsp;\[<br>
856&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;hk&nbsp;=&nbsp;h_k&nbsp;(&nbsp;x_k&nbsp;)&nbsp;<br>
857\]&nbsp;</span></code>
858
859
860<br>
861<br>
862<b><a name="3.h.d" id="3.h.d">3.h.d: Hk</a></b>
863<br>
864If the <i>h_fun</i> result <i>Hk</i> is present in the syntax,
865it is the <code>
866<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;n</span></code>
867 matrix given by
868and
869<code>
870<span style='white-space: nowrap'>&nbsp;\[<br>
871&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Hk&nbsp;=&nbsp;\partial_k&nbsp;h_k&nbsp;(&nbsp;x_k&nbsp;)&nbsp;<br>
872\]&nbsp;</span></code>
873
874
875<br>
876<br>
877<b><big><a name="3.i" id="3.i">3.i: max_itr</a></big></b>
878<br>
879The integer scalar <i>max_itr</i> specifies the maximum number of
880iterations of the algorithm to execute. It must be greater than or
881equal to zero. Note that if it is zero, the first row of the
882<a href="#3.r">3.r: <span style='white-space: nowrap'>info</span></a>
883 return value will still be computed.
884This can be useful for deciding what is a good value for the argument
885<a href="#3.j">3.j: <span style='white-space: nowrap'>epsilon</span></a>
886.
887
888<br>
889<br>
890<b><big><a name="3.j" id="3.j">3.j: epsilon</a></big></b>
891<br>
892The <code><font color="blue">ckbs_nonlinear</font></code> argument <i>epsilon</i> is a positive scalar.
893It specifies the convergence
894criteria value; i.e.,
895<code>
896<span style='white-space: nowrap'>&nbsp;\[<br>
897&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\varepsilon&nbsp;=&nbsp;epsilon<br>
898\]&nbsp;</span></code>
899
900In some instances, <code><font color="blue">ckbs_nonlinear</font></code> will return after printing
901a warning without convergence; see <a href="#3.r">3.r: <span style='white-space: nowrap'>info</span></a>
902.
903
904<br>
905<br>
906<b><big><a name="3.k" id="3.k">3.k: x_in</a></big></b>
907<br>
908The <code><font color="blue">ckbs_nonlinear</font></code> argument <i>x_in</i> 
909is a two dimensional array with size <code>
910<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;N</span></code>
911.
912It specifies a sequence of state values; i.e.,
913for <code>
914<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
915
916<code>
917<span style='white-space: nowrap'>&nbsp;\[<br>
918&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x\_in&nbsp;(:,&nbsp;k)&nbsp;=&nbsp;x_k<br>
919\]&nbsp;</span></code>
920
921The closer the initial state sequence is to the solution
922the faster, and more likely, the <code><font color="blue">ckbs_nonlinear</font></code> will converge.
923The initial state sequence need not be feasible; i.e.
924it is not necessary that
925<code>
926<span style='white-space: nowrap'>&nbsp;\[<br>
927&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;f_k&nbsp;(&nbsp;x_k&nbsp;)&nbsp;\leq&nbsp;0<br>
928\]&nbsp;</span></code>
929
930for all <code>
931<span style='white-space: nowrap'>&nbsp;k</span></code>
932.
933
934<br>
935<br>
936<b><big><a name="3.l" id="3.l">3.l: z</a></big></b>
937<br>
938The <code><font color="blue">ckbs_nonlinear</font></code> argument <i>z</i> is a two dimensional array
939with size <code>
940<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;N</span></code>
941.
942It specifies the sequence of measurement vectors; i.e.,
943for <code>
944<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
945
946<code>
947<span style='white-space: nowrap'>&nbsp;\[<br>
948&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;z(:,&nbsp;k)&nbsp;=&nbsp;z_k<br>
949\]</span></code>
950
951
952<br>
953<br>
954<b><big><a name="3.m" id="3.m">3.m: qinv</a></big></b>
955<br>
956The <code><font color="blue">ckbs_nonlinear</font></code> argument <i>qinv</i> 
957is a three dimensional array
958with size <code>
959<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
960.
961It specifies the inverse of the variance of the measurement noise; i.e.,
962for <code>
963<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
964
965<code>
966<span style='white-space: nowrap'>&nbsp;\[<br>
967&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;qinv(:,:,&nbsp;k)&nbsp;=&nbsp;Q_k^{-1}<br>
968\]</span></code>
969
970In the case <code>
971<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1</span></code>
972, the value of <code>
973<span style='white-space: nowrap'>&nbsp;Q_k</span></code>
974 is the variance
975of the initial state estimate (see <a href="#3.g">3.g: <span style='white-space: nowrap'>g_fun</span></a>
976.
977
978<br>
979<br>
980<b><big><a name="3.n" id="3.n">3.n: rinv</a></big></b>
981<br>
982The <code><font color="blue">ckbs_nonlinear</font></code> argument <i>rinv</i> 
983is a three dimensional array,
984with size <code>
985<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;m&nbsp;\times&nbsp;N</span></code>
986.
987it specifies the inverse of the variance of the transition noise; i.e.,
988for <code>
989<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
990
991<code>
992<span style='white-space: nowrap'>&nbsp;\[<br>
993&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;rinv(:,:,&nbsp;k)&nbsp;=&nbsp;R_k^{-1}<br>
994\]</span></code>
995
996It is ok to signify a missing data value by setting the corresponding
997row and column of <i>rinv</i> to zero. This also enables use
998to interpolate the state vector <code>
999<span style='white-space: nowrap'>&nbsp;x_k</span></code>
1000 to points where
1001there are no measurements.
1002
1003<br>
1004<br>
1005<b><big><a name="3.o" id="3.o">3.o: level</a></big></b>
1006<br>
1007The integer scalar <i>level</i> specifies the level of tracing to do.
1008If <code><font color="blue"></font></code><i><span style='white-space: nowrap'>level</span></i><code><font color="blue"><span style='white-space: nowrap'>&nbsp;==&nbsp;0</span></font></code>, no tracing is done.
1009If <code><font color="blue"></font></code><i><span style='white-space: nowrap'>level</span></i><code><font color="blue"><span style='white-space: nowrap'>&nbsp;&gt;=&nbsp;1</span></font></code>, the row index <i>q</i>
1010and the correspond row of <i>info</i> 
1011are printed as soon as soon as they are computed.
1012If <code><font color="blue"></font></code><i><span style='white-space: nowrap'>level</span></i><code><font color="blue"><span style='white-space: nowrap'>&nbsp;&gt;=&nbsp;2</span></font></code>, a check of the derivative calculations
1013is printed before the calculations start. In this case, control will
1014return to the keyboard so that you can print values, continue,
1015or abort the calculation.
1016
1017<br>
1018<br>
1019<b><big><a name="3.p" id="3.p">3.p: x_out</a></big></b>
1020<br>
1021The result <i>x_out</i> 
1022is a two dimensional array with size <code>
1023<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;N</span></code>
1024.
1025<code>
1026<span style='white-space: nowrap'>&nbsp;(&nbsp;x_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N&nbsp;)</span></code>
1027.
1028It contains an approximation for the optimal sequence; i.e.,
1029for <code>
1030<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
1031
1032<code>
1033<span style='white-space: nowrap'>&nbsp;\[<br>
1034&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x\_out(:,&nbsp;k)&nbsp;=&nbsp;x_k<br>
1035\]</span></code>
1036
1037
1038<br>
1039<br>
1040<b><big><a name="3.q" id="3.q">3.q: u_out</a></big></b>
1041<br>
1042The result <i>u_out</i> 
1043is a two dimensional array with size % <code>
1044<span style='white-space: nowrap'>&nbsp;\ell&nbsp;\times&nbsp;N</span></code>
1045.
1046It contains the Lagrange multiplier sequence
1047corresponding to <i>x_out</i>; i.e.,
1048for <code>
1049<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
1050
1051<code>
1052<span style='white-space: nowrap'>&nbsp;\[<br>
1053&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;u\_out(:,&nbsp;k)&nbsp;=&nbsp;u_k<br>
1054\]</span></code>
1055
1056The pair <i>x_out</i>, <i>u_out</i> satisfy the
1057<a href="#3.e">3.e: <span style='white-space: nowrap'>first&nbsp;order&nbsp;conditions</span></a>
1058.
1059
1060<br>
1061<br>
1062<b><big><a name="3.r" id="3.r">3.r: info</a></big></b>
1063<br>
1064The result <i>info</i> is a matrix with each row corresponding
1065to an iteration of the algorithm.
1066Note that <code><font color="blue">ckbs_nonlinear</font></code> has satisfied the convergence condition if
1067and only if
1068<code><font color="blue"><span style='white-space: nowrap'><br>
1069&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;all(&nbsp;</span></font></code><i><span style='white-space: nowrap'>info</span></i><code><font color="blue"><span style='white-space: nowrap'>(end,&nbsp;1:3)&nbsp;&lt;=&nbsp;</span></font></code><i><span style='white-space: nowrap'>epsilon</span></i><code><font color="blue"><span style='white-space: nowrap'>&nbsp;)<br>
1070</span></font></code><code><span style='white-space: nowrap'><br>
1071<br>
1072</span></code>We use <code>
1073<span style='white-space: nowrap'>&nbsp;\{&nbsp;x_k^q&nbsp;\}</span></code>
1074 to denote the state vector sequence at the
1075at the end of iteration <code>
1076<span style='white-space: nowrap'>&nbsp;q-1</span></code>
1077 and
1078<code>
1079<span style='white-space: nowrap'>&nbsp;\{&nbsp;u_k^q&nbsp;\}</span></code>
1080 for the dual vector sequence (<code>
1081<span style='white-space: nowrap'>&nbsp;u_k^q&nbsp;\geq&nbsp;0</span></code>
1082).
1083
1084<br>
1085<br>
1086<b><a name="3.r.a" id="3.r.a">3.r.a: max_f</a></b>
1087<br>
1088The value
1089<code><font color="blue"><span style='white-space: nowrap'><br>
1090&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></font></code><i><span style='white-space: nowrap'>max_f</span></i><code><font color="blue"><span style='white-space: nowrap'>(</span></font></code><i><span style='white-space: nowrap'>q</span></i><code><font color="blue"><span style='white-space: nowrap'>)&nbsp;=&nbsp;</span></font></code><i><span style='white-space: nowrap'>info</span></i><code><font color="blue"><span style='white-space: nowrap'>(</span></font></code><i><span style='white-space: nowrap'>q</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;1)<br>
1091</span></font></code>is a bound on the constraint functions
1092at the end of iteration <i>q-1</i>. To be specific
1093<code>
1094<span style='white-space: nowrap'>&nbsp;\[<br>
1095&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;max\_f(q)&nbsp;=&nbsp;\max_{i,&nbsp;k}&nbsp;[&nbsp;f_k&nbsp;(&nbsp;x_k^q&nbsp;)_i&nbsp;]<br>
1096\]&nbsp;</span></code>
1097
1098where the maximum is with respect to
1099<code>
1100<span style='white-space: nowrap'>&nbsp;i&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;\ell</span></code>
1101 and
1102<code>
1103<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
1104.
1105Convergence requires this value to be less than or equal <i>epsilon</i>.
1106
1107<br>
1108<br>
1109<b><a name="3.r.b" id="3.r.b">3.r.b: max_grad</a></b>
1110<br>
1111The value
1112<code><font color="blue"><span style='white-space: nowrap'><br>
1113&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></font></code><i><span style='white-space: nowrap'>max_grad</span></i><code><font color="blue"><span style='white-space: nowrap'>(</span></font></code><i><span style='white-space: nowrap'>q)</span></i><code><font color="blue"><span style='white-space: nowrap'>&nbsp;=&nbsp;</span></font></code><i><span style='white-space: nowrap'>info</span></i><code><font color="blue"><span style='white-space: nowrap'>(</span></font></code><i><span style='white-space: nowrap'>q</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;2)<br>
1114</span></font></code>is a bound on the partial of the
1115Lagrangian with respect to <code>
1116<span style='white-space: nowrap'>&nbsp;x</span></code>
1117
1118at the end of iteration <i>q-1</i>. To be specific
1119<code>
1120<span style='white-space: nowrap'>&nbsp;\[<br>
1121max\_grad(q)&nbsp;=&nbsp;\max_{j,&nbsp;k}&nbsp;\left[&nbsp;\left|<br>
1122(u_k^q)^\T&nbsp;*&nbsp;\partial_k&nbsp;f_k(x_k^q)&nbsp;+&nbsp;\partial_k&nbsp;&nbsp;S(x_1^q,&nbsp;\ldots&nbsp;,x_N^q)&nbsp;<br>
1123\right|&nbsp;\right]_j<br>
1124\]&nbsp;</span></code>
1125
1126where the maximum is with respect to
1127<code>
1128<span style='white-space: nowrap'>&nbsp;j&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;n</span></code>
1129 and
1130<code>
1131<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
1132.
1133This value should converge to zero.
1134
1135<br>
1136<br>
1137<b><a name="3.r.c" id="3.r.c">3.r.c: max_fu</a></b>
1138<br>
1139The value
1140<code><font color="blue"><span style='white-space: nowrap'><br>
1141&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></font></code><i><span style='white-space: nowrap'>max_fu</span></i><code><font color="blue"><span style='white-space: nowrap'>&nbsp;=&nbsp;</span></font></code><i><span style='white-space: nowrap'>info</span></i><code><font color="blue"><span style='white-space: nowrap'>(</span></font></code><i><span style='white-space: nowrap'>q</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;3)<br>
1142</span></font></code>is a bound on
1143the complementarity conditions
1144at the end of iteration <i>q-1</i>. To be specific
1145<code>
1146<span style='white-space: nowrap'>&nbsp;\[<br>
1147max\_fu(q)&nbsp;=&nbsp;\max_{i,&nbsp;k}&nbsp;[&nbsp;|&nbsp;f_k&nbsp;(&nbsp;x_k&nbsp;)_i&nbsp;|&nbsp;*&nbsp;(&nbsp;u_k&nbsp;)_i&nbsp;]<br>
1148\]&nbsp;</span></code>
1149
1150where the maximum is with respect to
1151<code>
1152<span style='white-space: nowrap'>&nbsp;i&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;\ell</span></code>
1153 and
1154<code>
1155<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
1156.
1157This value should converge to be less than or equal zero.
1158
1159<br>
1160<br>
1161<b><a name="3.r.d" id="3.r.d">3.r.d: obj_cur</a></b>
1162<br>
1163The value
1164<code><font color="blue"><span style='white-space: nowrap'><br>
1165&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></font></code><i><span style='white-space: nowrap'>obj_cur</span></i><code><font color="blue"><span style='white-space: nowrap'>(</span></font></code><i><span style='white-space: nowrap'>q</span></i><code><font color="blue"><span style='white-space: nowrap'>)&nbsp;=&nbsp;</span></font></code><i><span style='white-space: nowrap'>info</span></i><code><font color="blue"><span style='white-space: nowrap'>(</span></font></code><i><span style='white-space: nowrap'>q</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;4)<br>
1166</span></font></code>is the value of the objective function
1167at the end of <code>
1168<span style='white-space: nowrap'>&nbsp;q-1</span></code>
1169; i.e.,
1170<code>
1171<span style='white-space: nowrap'>&nbsp;\[<br>
1172&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;obj\_cur(q)&nbsp;=&nbsp;S(&nbsp;x_1^q&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_k^q&nbsp;)<br>
1173\]&nbsp;</span></code>
1174
1175(Note that <code>
1176<span style='white-space: nowrap'>&nbsp;info(1,&nbsp;4)%</span></code>
1177 is the value of the objective
1178corresponding to <i>x_in</i>.
1179
1180<br>
1181<br>
1182<b><a name="3.r.e" id="3.r.e">3.r.e: lambda</a></b>
1183<br>
1184The value
1185<code><font color="blue"><span style='white-space: nowrap'><br>
1186&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></font></code><i><span style='white-space: nowrap'>lambda</span></i><code><font color="blue"><span style='white-space: nowrap'>(</span></font></code><i><span style='white-space: nowrap'>q</span></i><code><font color="blue"><span style='white-space: nowrap'>)&nbsp;=&nbsp;</span></font></code><i><span style='white-space: nowrap'>info</span></i><code><font color="blue"><span style='white-space: nowrap'>(</span></font></code><i><span style='white-space: nowrap'>q</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;5)<br>
1187</span></font></code>is the line search step size used during
1188iteration <code>
1189<span style='white-space: nowrap'>&nbsp;q-1</span></code>
1190 of <code><font color="blue">ckbs_nonlinear</font></code>.
1191If the problem is nearly affine (if the affine approximate is accurate)
1192this will be one.
1193Much small step sizes indicate highly non-affine problems
1194(with the exception that <code><font color="blue"></font></code><i><span style='white-space: nowrap'>info</span></i><code><font color="blue"><span style='white-space: nowrap'>(1,&nbsp;5)</span></font></code> is always zero).
1195
1196<br>
1197<br>
1198<b><a name="3.r.f" id="3.r.f">3.r.f: lam_aff</a></b>
1199<br>
1200The value
1201<code><font color="blue"><span style='white-space: nowrap'><br>
1202&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;</span></font></code><i><span style='white-space: nowrap'>lam_aff</span></i><code><font color="blue"><span style='white-space: nowrap'>(</span></font></code><i><span style='white-space: nowrap'>q</span></i><code><font color="blue"><span style='white-space: nowrap'>)&nbsp;=&nbsp;</span></font></code><i><span style='white-space: nowrap'>info</span></i><code><font color="blue"><span style='white-space: nowrap'>(</span></font></code><i><span style='white-space: nowrap'>q</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;6)<br>
1203</span></font></code>is the minimum line search step size
1204while solving the affine sub-problem that corresponds to
1205iteration <code>
1206<span style='white-space: nowrap'>&nbsp;q-1</span></code>
1207 of <code><font color="blue">ckbs_nonlinear</font></code>.
1208If the sub-problem solution is working well,
1209this will be one.
1210Much small step sizes indicate the sub-problem solution is not working well.
1211
1212
1213
1214<br>
1215<br>
1216<b><a name="3.r.g" id="3.r.g">3.r.g: Penalty Parameter</a></b>
1217<br>
1218The exact penalty function
1219<code>
1220<span style='white-space: nowrap'>&nbsp;\[<br>
1221&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;S(&nbsp;x_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_k&nbsp;)&nbsp;<br>
1222&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;+&nbsp;\alpha&nbsp;\sum_{k=1}^N&nbsp;\sum_{i=1}^\ell&nbsp;\max&nbsp;[&nbsp;f_k&nbsp;(&nbsp;x_k&nbsp;)_i&nbsp;,&nbsp;0&nbsp;]<br>
1223\]&nbsp;</span></code>
1224
1225is used to determine the line search step size.
1226The value <code><font color="blue"></font></code><i><span style='white-space: nowrap'>info</span></i><code><font color="blue"><span style='white-space: nowrap'>(</span></font></code><i><span style='white-space: nowrap'>a</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;7)</span></font></code> is the penalty parameter
1227<code>
1228<span style='white-space: nowrap'>&nbsp;\alpha</span></code>
1229 during iteration <code>
1230<span style='white-space: nowrap'>&nbsp;q-1</span></code>
1231 of <code><font color="blue">ckbs_nonlinear</font></code>.
1232
1233<br>
1234<br>
1235<b><big><a name="3.s" id="3.s">3.s: Example</a></big></b>
1236
1237
1238<br>
1239<br>
1240<b><a name="3.s.a" id="3.s.a">3.s.a: Simple</a></b>
1241<br>
1242The file <a href="#3.1">3.1: <span style='white-space: nowrap'>nonlinear_ok_simple.m</span></a>
1243 contains a simple example
1244and test of <code><font color="blue">ckbs_nonlinear</font></code>.
1245It returns true if <code><font color="blue">ckbs_nonlinear</font></code> passes the tests
1246and false otherwise.
1247
1248<br>
1249<br>
1250<b><a name="3.s.b" id="3.s.b">3.s.b: Box Constraints</a></b>
1251<br>
1252The file <a href="#3.2">3.2: <span style='white-space: nowrap'>nonlinear_ok_box.m</span></a>
1253 contains an example
1254and test of <code><font color="blue">ckbs_nonlinear</font></code> with box constraints
1255and a nonlinear measurement function.
1256It returns true if <code><font color="blue">ckbs_nonlinear</font></code> passes the tests
1257and false otherwise.
1258
1259<br>
1260<br>
1261<b><a name="3.s.c" id="3.s.c">3.s.c: Nonlinear Constraints</a></b>
1262<br>
1263The file <a href="#3.3">3.3: <span style='white-space: nowrap'>nonlinear_ok_sin.m</span></a>
1264 contains an example
1265and test of <code><font color="blue">ckbs_nonlinear</font></code> with a sine wave constraint
1266and a nonlinear measurement function.
1267It returns true if <code><font color="blue">ckbs_nonlinear</font></code> passes the tests
1268and false otherwise.
1269
1270
1271
1272<hr>Input File: src/ckbs_nonlinear.m
1273
1274<hr>
1275 
1276
1277
1278<center><b><big><big><a name="3.1" id="3.1">3.1: Simple ckbs_nonlinear Example and Test</a>
1279</big></big></b></center>
1280<br>
1281<b><big><a name="3.1.a" id="3.1.a">3.1.a: Call Back Functions</a></big></b>
1282
1283<table><tr><td align='left'  valign='top'>
1284
1285<a href="#3.1.1">3.1.1: nonlinear_ok_simple_f.m</a></td><td>
1286Example Constraint Function: nonlinear_ok_simple_f</td></tr>
1287<tr><td>
1288
1289<a href="#3.1.2">3.1.2: nonlinear_ok_simple_g.m</a></td><td>
1290Example Transition Function: nonlinear_ok_simple_g</td></tr>
1291<tr><td>
1292
1293<a href="#3.1.3">3.1.3: nonlinear_ok_simple_h.m</a></td><td>
1294Example Measurement Function: nonlinear_ok_simple_h</td></tr>
1295<tr><td>
1296
1297</td></tr>
1298</table>
1299<br>
1300<b><big><a name="3.1.b" id="3.1.b">3.1.b: Source Code</a></big></b>
1301
1302 <code><font color='blue'><pre style='display:inline'> 
1303function [ok] = nonlinear_ok_simple()
1304% --------------------------------------------------------------------
1305max_itr = 20;      % maximum number of iterations
1306epsilon = 1e-5;    % convergence criteria
1307N       = 3;       % number of time points
1308ell     = 2;       % number of constraints
1309m       = 1;       % number of measurements per time point
1310n       = 3;       % number of state vector components per time point
1311sigma   = 1;       % variance of measurement noise
1312level   = 0;       % level of tracing in ckbs_nonlinear
1313%
1314% simulated true trajectory
1315x_true  = ones(n, 1) * (1 : N);
1316%
1317% simulate measurement noise
1318e_true  = zeros(m, N);
1319%
1320% initial x vector
1321x_in = zeros(n, N);
1322%
1323% --------------------------------------------------------------------
1324if m &gt; n
1325        error('nonlinear_ok_simple: m &gt; n');
1326end
1327if ell &gt; n
1328        error('nonlinear_ok_simple: ell &gt; n');
1329end
1330%
1331global nonlinear_ok_simple_m
1332global nonlinear_ok_simple_ell
1333global nonlinear_ok_simple_N
1334%
1335nonlinear_ok_simple_m   = m;
1336nonlinear_ok_simple_ell = ell;
1337nonlinear_ok_simple_N   = N;
1338%
1339% measurement variances
1340rinv    = zeros(m, m, N);
1341qinv    = zeros(n, n, N);
1342qinvk   = eye(n) / (sigma * sigma);
1343rinvk   = eye(m) / (sigma * sigma);
1344z       = zeros(m, N);
1345for k = 1 : N
1346        xk           = x_true(:, k);
1347        ek           = e_true(:, k);
1348        hk           = nonlinear_ok_simple_h(k, xk);
1349        z(:, k)      = hk + ek;
1350        qinv(:,:, k) = qinvk;
1351        rinv(:,:, k) = rinvk;
1352end
1353%
1354% pass the maximum state value to f
1355global nonlinear_ok_simple_f_max
1356nonlinear_ok_simple_f_max = (N - .5) * ones(m, 1);
1357%
1358% ----------------------------------------------------------------------
1359f_fun = 'nonlinear_ok_simple_f';
1360g_fun = 'nonlinear_ok_simple_g';
1361h_fun = 'nonlinear_ok_simple_h';
1362[x_out, u_out, info] = ckbs_nonlinear( ...
1363        f_fun,    ...
1364        g_fun,    ...
1365        h_fun,    ...
1366        max_itr,  ...
1367        epsilon,  ...
1368        x_in,     ...
1369        z,        ...
1370        qinv,     ...
1371        rinv,     ...
1372        level     ...
1373);
1374% ----------------------------------------------------------------------
1375ok     = size(info, 1) &lt;= max_itr;
1376f_out  = zeros(ell, N);
1377g_out  = zeros(n,   N);
1378h_out  = zeros(m,   N);
1379df_out = zeros(ell, n, N);
1380dg_out = zeros(n, n,   N);
1381dh_out = zeros(m, n,   N);
1382xk1    = zeros(n, 1);
1383for k = 1 : N
1384        xk       = x_out(:, k);
1385        uk       = u_out(:, k);
1386        [fk, Fk] = feval(f_fun, k, xk);
1387        [gk, Gk] = feval(g_fun, k, xk1);
1388        [hk, Hk] = feval(h_fun, k, xk);
1389        %
1390        ok       = ok &amp; all( fk &lt;= epsilon);
1391        ok       = ok &amp; all( abs(fk) .* uk &lt;= epsilon );
1392        %
1393        f_out(:, k) = fk - Fk * xk;
1394        g_out(:, k) = gk - Gk * xk1;
1395        h_out(:, k) = hk - Hk * xk;
1396        df_out(:,:, k) = Fk;
1397        dg_out(:,:, k) = Gk;
1398        dh_out(:,:, k) = Hk;
1399        xk1 = xk;
1400end
1401ok   = ok &amp; all( all( u_out &gt;= 0 ) );
1402grad  = ckbs_sumsq_grad(x_out, z, g_out, h_out, dg_out, dh_out, qinv, rinv);
1403for k = 1 : N
1404        uk  = u_out(:, k);
1405        Fk  = df_out(:,:, k);
1406        dk  = grad(:, k);
1407        %
1408        ok  = ok &amp; all( abs(Fk' * uk + dk) &lt;= epsilon );
1409end
1410return
1411end
1412</pre></font></code>
1413 
1414
1415<hr>Input File: test/nonlinear_ok_simple.m
1416
1417<hr>
1418 
1419
1420
1421
1422<center><b><big><big><a name="3.1.1" id="3.1.1">3.1.1: Example Constraint Function: nonlinear_ok_simple_f</a>
1423</big></big></b></center>
1424<br>
1425<b><big><a name="3.1.1.a" id="3.1.1.a">3.1.1.a: Source Code</a></big></b>
1426
1427 <code><font color='blue'><pre style='display:inline'> 
1428function [fk, Fk] = nonlinear_ok_simple_f(k, xk)
1429        global nonlinear_ok_simple_N
1430        global nonlinear_ok_simple_ell
1431        %
1432        N   = nonlinear_ok_simple_N;
1433        ell = nonlinear_ok_simple_ell;
1434        n   = size(xk, 1);
1435        % xk(1:ell)^2 &lt;= N - .5
1436        fk = xk(1:ell).^2 - (N - .5);
1437        Fk = zeros(ell, n);
1438        for i = 1 : ell
1439                Fk(i, i) = 2 * xk(i);
1440        end
1441        return
1442end
1443</pre></font></code>
1444 
1445
1446<hr>Input File: test/nonlinear_ok_simple_f.m
1447
1448<hr>
1449 
1450
1451
1452
1453<center><b><big><big><a name="3.1.2" id="3.1.2">3.1.2: Example Transition Function: nonlinear_ok_simple_g</a>
1454</big></big></b></center>
1455<br>
1456<b><big><a name="3.1.2.a" id="3.1.2.a">3.1.2.a: Source Code</a></big></b>
1457
1458 <code><font color='blue'><pre style='display:inline'> 
1459function [gk, Gk] = nonlinear_ok_simple_g(k, xk1)
1460        n  = size(xk1, 1);
1461        if k == 1
1462                Gk = zeros(n, n);
1463                gk = Gk * xk1 + 1;
1464        else
1465                Gk = eye(n);
1466                gk = Gk * xk1 + 1;
1467        end
1468        return
1469end
1470</pre></font></code>
1471 
1472
1473<hr>Input File: test/nonlinear_ok_simple_g.m
1474
1475<hr>
1476 
1477
1478
1479
1480<center><b><big><big><a name="3.1.3" id="3.1.3">3.1.3: Example Measurement Function: nonlinear_ok_simple_h</a>
1481</big></big></b></center>
1482<br>
1483<b><big><a name="3.1.3.a" id="3.1.3.a">3.1.3.a: Source Code</a></big></b>
1484
1485 <code><font color='blue'><pre style='display:inline'> 
1486function [hk, Hk] = nonlinear_ok_simple_h(k, xk)
1487        global nonlinear_ok_simple_m
1488        %
1489        n        = size(xk, 1);
1490        m        = nonlinear_ok_simple_m;
1491        hk       = xk(1:m);
1492        Hk       = [ eye(m) , zeros(m, n-m) ];
1493        return
1494end
1495</pre></font></code>
1496 
1497
1498<hr>Input File: test/nonlinear_ok_simple_h.m
1499
1500<hr>
1501 
1502
1503
1504<center><b><big><big><a name="3.2" id="3.2">3.2: ckbs_nonlinear Box Constrained Tracking Example and Test</a>
1505</big></big></b></center>
1506<br>
1507<b><big><a name="3.2.a" id="3.2.a">3.2.a: Syntax</a></big></b>
1508
1509<br>
1510<code><font color="blue"><span style='white-space: nowrap'>[</span></font></code><i><span style='white-space: nowrap'>ok</span></i><code><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;nonlinear_ok_box(</span></font></code><i><span style='white-space: nowrap'>draw_plot</span></i><code><font color="blue"><span style='white-space: nowrap'>)</span></font></code>
1511
1512<br>
1513<br>
1514<b><big><a name="3.2.b" id="3.2.b">3.2.b: draw_plot</a></big></b>
1515<br>
1516If this argument is true, a plot is drawn showing the results
1517and the <code><font color="blue">nonlinear_ok_box.out</font></code> file is written for use with
1518the program <code><font color="blue">nonlinear_ok_box.r</font></code>.
1519
1520<br>
1521<br>
1522<b><big><a name="3.2.c" id="3.2.c">3.2.c: ok</a></big></b>
1523<br>
1524If the return value <i>ok</i> is true, the test passed,
1525otherwise the test failed.
1526
1527<br>
1528<br>
1529<b><big><a name="3.2.d" id="3.2.d">3.2.d: State Vector</a></big></b>
1530
1531<table><tr><td align='left'  valign='top'>
1532
1533<code>
1534<span style='white-space: nowrap'>&nbsp;x1&nbsp;(t)</span></code>
1535  </td><td align='left'  valign='top'>
1536 first component of velocity  </td></tr><tr><td align='left'  valign='top'>
1537
1538<code>
1539<span style='white-space: nowrap'>&nbsp;x2&nbsp;(t)</span></code>
1540  </td><td align='left'  valign='top'>
1541 first component of position  </td></tr><tr><td align='left'  valign='top'>
1542
1543<code>
1544<span style='white-space: nowrap'>&nbsp;x3&nbsp;(t)</span></code>
1545  </td><td align='left'  valign='top'>
1546 second component of velocity  </td></tr><tr><td align='left'  valign='top'>
1547
1548<code>
1549<span style='white-space: nowrap'>&nbsp;x4&nbsp;(t)</span></code>
1550  </td><td align='left'  valign='top'>
1551 second component of position 
1552</td></tr>
1553</table>
1554<br>
1555<b><big><a name="3.2.e" id="3.2.e">3.2.e: Measurement Vector</a></big></b>
1556
1557<table><tr><td align='left'  valign='top'>
1558
1559<code>
1560<span style='white-space: nowrap'>&nbsp;z1&nbsp;(t)</span></code>
1561  </td><td align='left'  valign='top'>
1562 range to the station s1  plus noise </td></tr><tr><td align='left'  valign='top'>
1563
1564<code>
1565<span style='white-space: nowrap'>&nbsp;z2&nbsp;(t)</span></code>
1566  </td><td align='left'  valign='top'>
1567 range to the station s2  plus noise
1568</td></tr>
1569</table>
1570<br>
1571<b><big><a name="3.2.f" id="3.2.f">3.2.f: Constraint</a></big></b>
1572
1573<br>
1574<code>
1575<span style='white-space: nowrap'>&nbsp;2&nbsp;+&nbsp;x4\_min&nbsp;\geq&nbsp;x_4&nbsp;(t)&nbsp;\geq&nbsp;x4\_min&nbsp;</span></code>
1576.
1577
1578
1579<br>
1580<br>
1581<b><big><a name="3.2.g" id="3.2.g">3.2.g: Call Back Functions</a></big></b>
1582
1583<table><tr><td align='left'  valign='top'>
1584
1585<a href="#3.2.1">3.2.1: nonlinear_ok_box_f.m</a></td><td>
1586Example Constraint Function: nonlinear_ok_box_f</td></tr>
1587<tr><td>
1588
1589<a href="#3.2.2">3.2.2: nonlinear_ok_box_g.m</a></td><td>
1590Example Transition Function: nonlinear_ok_box_g</td></tr>
1591<tr><td>
1592
1593<a href="#3.2.3">3.2.3: nonlinear_ok_box_h.m</a></td><td>
1594Example Measurement Function: nonlinear_ok_box_h</td></tr>
1595<tr><td>
1596
1597<a href="#3.2.4">3.2.4: nonlinear_ok_box_nof.m</a></td><td>
1598Example no Constraint Function: nonlinear_ok_box_nof</td></tr>
1599<tr><td>
1600
1601</td></tr>
1602</table>
1603<br>
1604<b><big><a name="3.2.h" id="3.2.h">3.2.h: Source Code</a></big></b>
1605
1606 <code><font color='blue'><pre style='display:inline'> 
1607function [ok] = nonlinear_ok_box(draw_plot)
1608if nargin &lt; 1
1609        draw_plot = false;
1610end
1611% --------------------------------------------------------
1612% You can change these parameters
1613N       = 50;            % number of measurement time points
1614dt      = 2 * pi / N;    % time between measurement points
1615sigma   = .25;           % standard deviation of measurement noise
1616gamma   = 1;             % multiplier for transition variance
1617max_itr = 50;            % maximum number of iterations
1618epsilon = 1e-4;          % convergence criteria
1619x4_min  = .25;           % minimum value for x4_true
1620h_min   = 0;             % minimum horizontal value in plots
1621h_max   = 7;             % maximum horizontal value in plots
1622v_min   = 0;             % minimum vertical value in plots
1623v_max   = 2.5;           % maximum vertical value in plots
1624s1      = [ 0 , 0 ];     % station one
1625s2      = [ 2*pi , 0 ];  % station two
1626%
1627% level of tracing during the optimization
1628if draw_plot
1629        level   = 1;
1630else
1631        level   = 0;
1632end
1633% ---------------------------------------------------------
1634%
1635% global variables used by nonlinear_ok_box_h
1636global nonlinear_ok_box_s1
1637global nonlinear_ok_box_s2
1638nonlinear_ok_box_s1 = s1;
1639nonlinear_ok_box_s2 = s2;
1640%
1641ok = true;
1642%
1643%  Define the problem
1644rand('seed', 1234);
1645%
1646% number of constraints per time point
1647ell   = 2;
1648%
1649% number of measurements per time point
1650m     = 2;
1651%
1652% number of state vector components per time point
1653n     = 4;
1654%
1655% simulate the true trajectory and measurement noise
1656t        =  (1 : N) * dt;
1657x2_true  = t;
1658x4_max   = x4_min + 2;
1659x4_true  = x4_min + 1 - sin(t);
1660x1_true  = ones(1, N);
1661x3_true  = - cos(t);
1662x_true   = [ x1_true ; x2_true ; x3_true ; x4_true ];
1663v1_true  = sigma * randn(1, N);
1664v2_true  = sigma * randn(1, N);
1665%
1666% corresponding measurement values
1667rinv    = zeros(m, m, N);
1668z       = zeros(m, N);
1669rinvk   = eye(m) / (sigma * sigma);
1670for k = 1 : N
1671        x_k          = x_true(:, k);
1672        h_k          = nonlinear_ok_box_h(k, x_k);
1673        z(:, k)      = h_k + [ v1_true(k) ; v2_true(k) ];
1674        rinv(:,:, k) = rinvk;
1675end
1676%
1677% covariance for the transition noise
1678qk       = diag( [ dt, dt^3 / 3 , dt, dt^3 / 3 ] );
1679qk(1, 2) = dt^2 / 2;
1680qk(2, 1) = dt^2 / 2;
1681qk(3, 4) = dt^2 / 2;
1682qk(4, 3) = dt^2 / 2;
1683qk       = qk * gamma;
1684qinvk    = inv(qk);
1685qinv     = zeros(n, n, N);
1686for k = 2 : N
1687        qinv(:,:, k) = qinvk;
1688end
1689%
1690% covariance for the initial estimate
1691qinv(:,:,1) = eye(n) * 100 * gamma;
1692%
1693% initial x vector
1694x_in = zeros(n, N);
1695for k = 1 : N
1696        x_in(:, k) = [ 0 ; 1 ; 0 ; 1 ];
1697end
1698%
1699% global variables used by nonlinear_ok_box_f
1700global nonlinear_ok_box_x4_min
1701global nonlinear_ok_box_x4_max
1702nonlinear_ok_box_x4_min = x4_min;
1703nonlinear_ok_box_x4_max = x4_max;
1704%
1705% global variables used by nonlinear_ok_box_g
1706global nonlinear_ok_box_x1
1707global nonlinear_ok_box_dt
1708nonlinear_ok_box_x1 = x_true(:, 1);
1709nonlinear_ok_box_dt = dt;
1710%
1711% ----------------------------------------------------------------------
1712f_fun = 'nonlinear_ok_box_f';
1713g_fun = 'nonlinear_ok_box_g';
1714h_fun = 'nonlinear_ok_box_h';
1715[x_out, u_out, info] = ckbs_nonlinear( ...
1716        f_fun,    ...
1717        g_fun,    ...
1718        h_fun,    ...
1719        max_itr,  ...
1720        epsilon,  ...
1721        x_in,     ...
1722        z,        ...
1723        qinv,     ...
1724        rinv,     ...
1725        level     ...
1726);
1727% ----------------------------------------------------------------------
1728ok         = ok &amp; (size(info,1) &lt;= max_itr);
1729f_out      = zeros(ell, N);
1730g_out      = zeros(n, N);
1731h_out      = zeros(m, N);
1732df_out     = zeros(ell, n, N);
1733dg_out     = zeros(n, n, N);
1734dh_out     = zeros(m, n, N);
1735xk1        = zeros(n, 1);
1736for k = 1 : N
1737        xk    = x_out(:, k);
1738        uk    = u_out(:, k);
1739        [fk, Fk]   = nonlinear_ok_box_f(k, xk);
1740        [gk, Gk]   = nonlinear_ok_box_g(k, xk1);
1741        [hk, Hk]   = nonlinear_ok_box_h(k, xk);
1742        %
1743        ok   = ok &amp; all( fk &lt;= epsilon );
1744        ok   = ok &amp; all( abs(fk) .* uk &lt;= epsilon );
1745        %
1746        df_out(:,:, k) = Fk;
1747        dg_out(:,:, k) = Gk;
1748        dh_out(:,:, k) = Hk;
1749        f_out(:, k)    = fk - Fk * xk;
1750        g_out(:, k)    = gk - Gk * xk1;
1751        h_out(:, k)    = hk - Hk * xk;
1752        xk1 = xk;
1753end
1754ok   = ok &amp; all( all( u_out &gt;= 0 ) );
1755%
1756d_out = ckbs_sumsq_grad(x_out, z, g_out, h_out, dg_out, dh_out, qinv, rinv);
1757for k = 1 : N
1758        uk = u_out(:, k);
1759        Fk = df_out(:,:, k);
1760        dk = d_out(:, k);
1761        %
1762        ok = ok &amp; (max ( abs( Fk' * uk + dk ) ) &lt;= epsilon);
1763end
1764if ~ ok
1765        keyboard
1766end
1767if draw_plot
1768        figure(1);
1769        clf
1770        hold on
1771        plot(x_true(2,:)', x_true(4,:)', 'b-' );
1772        plot(x_out(2,:)', x_out(4,:)', 'g-' );
1773        plot(x_true(2,:)', x4_min * ones(N,1), 'r-');
1774        plot(x_true(2,:)', x4_max * ones(N,1), 'r-');
1775        axis([h_min, h_max, v_min, v_max]);
1776        title('Constrained: blue=truth, green=estimate, red=constraint');
1777        hold off
1778        %
1779        % constrained estimate
1780        x_con = x_out;
1781end
1782% ----------------------------------------------------------------------
1783% Unconstrained case
1784f_fun = 'nonlinear_ok_box_nof';
1785[x_out, u_out, info] = ckbs_nonlinear( ...
1786        f_fun,    ...
1787        g_fun,    ...
1788        h_fun,    ...
1789        max_itr,  ...
1790        epsilon,  ...
1791        x_in,     ...
1792        z,        ...
1793        qinv,     ...
1794        rinv,     ...
1795        level     ...
1796);
1797% ----------------------------------------------------------------------
1798ok   = ok &amp; (size(info,1) &lt;= max_itr);
1799xk1  = zeros(n, 1);
1800for k = 1 : N
1801        xk    = x_out(:, k);
1802        [gk, Gk]   = nonlinear_ok_box_g(k, xk1);
1803        [hk, Hk]   = nonlinear_ok_box_h(k, xk);
1804        %
1805        dg_out(:,:, k) = Gk;
1806        dh_out(:,:, k) = Hk;
1807        g_out(:, k)    = gk - Gk * xk1;
1808        h_out(:, k)    = hk - Hk * xk;
1809        xk1 = xk;
1810end
1811d_out  = ckbs_sumsq_grad(x_out, z, g_out, h_out, dg_out, dh_out, qinv, rinv);
1812ok     = ok &amp; (max( max( abs(d_out) ) ) &lt;= epsilon);
1813if draw_plot
1814        figure(2);
1815        clf
1816        hold on
1817        plot(x_true(2,:)', x_true(4,:)', 'b-' );
1818        plot(x_out(2,:)', x_out(4,:)', 'g-' );
1819        plot(x_true(2,:)', x4_min * ones(1,N), 'r-');
1820        plot(x_true(2,:)', x4_max * ones(1,N), 'r-');
1821        axis([h_min, h_max, v_min, v_max]);
1822        title('Unconstrained: blue=truth, green=estimate, red=constraint');
1823        hold off
1824        %
1825        % unconstrained estimate
1826        x_free = x_out;
1827        %
1828        % write out constrained and unconstrained results
1829        [fid, msg] = fopen('nonlinear_ok_box.out', 'wt');
1830        if size(msg, 2) &gt; 0
1831                disp(['nonlinear_ok: ', msg]);
1832        end
1833        %                      123456789012345678901234'
1834        heading =             ' x2_true  x2_con x2_free'  ;
1835        heading = [ heading , ' x4_true  x4_con x4_free' ];
1836        heading = [ heading , '      z1      z2\n'       ];
1837        fprintf(fid, heading);
1838        for k = 1 : N
1839                fprintf(fid,'%8.3f%8.3f%8.3f%8.3f%8.3f%8.3f%8.3f%8.3f\n', ...
1840                        x_true(2,k), x_con(2,k), x_free(2,k), ...
1841                        x_true(4,k), x_con(4,k), x_free(4,k), ...
1842                        z(1,k), z(2,k) ...
1843                );
1844        end
1845        fclose(fid);
1846end
1847return
1848end
1849</pre></font></code>
1850 
1851
1852<hr>Input File: test/nonlinear_ok_box.m
1853
1854<hr>
1855 
1856
1857
1858
1859<center><b><big><big><a name="3.2.1" id="3.2.1">3.2.1: Example Constraint Function: nonlinear_ok_box_f</a>
1860</big></big></b></center>
1861<br>
1862<b><big><a name="3.2.1.a" id="3.2.1.a">3.2.1.a: Source Code</a></big></b>
1863
1864 <code><font color='blue'><pre style='display:inline'> 
1865function [fk, Fk] = nonlinear_ok_box_f(k, xk)
1866        global nonlinear_ok_box_x4_min
1867        global nonlinear_ok_box_x4_max
1868        %
1869        % constrained so that x4_min &lt;= x4(t) &lt;= x4_max
1870        x4_min = nonlinear_ok_box_x4_min;
1871        x4_max = nonlinear_ok_box_x4_max;
1872        ell    = 2;
1873        n      = size(xk, 1);
1874        %
1875        fk = [ ...
1876                xk(4) - x4_max;
1877                x4_min - xk(4) ...
1878        ];
1879        Fk = zeros(ell, n);
1880        Fk(1, 4) = 1;
1881        Fk(2, 4) = -1;
1882        return
1883end
1884</pre></font></code>
1885 
1886
1887<hr>Input File: test/nonlinear_ok_box_f.m
1888
1889<hr>
1890 
1891
1892
1893
1894<center><b><big><big><a name="3.2.2" id="3.2.2">3.2.2: Example Transition Function: nonlinear_ok_box_g</a>
1895</big></big></b></center>
1896<br>
1897<b><big><a name="3.2.2.a" id="3.2.2.a">3.2.2.a: Source Code</a></big></b>
1898
1899 <code><font color='blue'><pre style='display:inline'> 
1900function [gk, Gk] = nonlinear_ok_box_g(k, xk1)
1901        global nonlinear_ok_box_x1
1902        global nonlinear_ok_box_dt
1903        if k == 1
1904                Gk = zeros(4, 4);
1905                gk = nonlinear_ok_box_x1;
1906                return;
1907        end
1908        dt = nonlinear_ok_box_dt;
1909        Gk = [ ...
1910                1  0  0  0
1911                dt 1  0  0
1912                0  0  1  0
1913                0  0  dt 1 ...
1914        ];
1915        gk = Gk * xk1;
1916        return
1917end
1918</pre></font></code>
1919 
1920
1921<hr>Input File: test/nonlinear_ok_box_g.m
1922
1923<hr>
1924 
1925
1926
1927
1928<center><b><big><big><a name="3.2.3" id="3.2.3">3.2.3: Example Measurement Function: nonlinear_ok_box_h</a>
1929</big></big></b></center>
1930<br>
1931<b><big><a name="3.2.3.a" id="3.2.3.a">3.2.3.a: Source Code</a></big></b>
1932
1933 <code><font color='blue'><pre style='display:inline'> 
1934function [hk, Hk] = nonlinear_ok_box_h(k, xk)
1935        global nonlinear_ok_box_s1
1936        global nonlinear_ok_box_s2
1937        s1  = nonlinear_ok_box_s1;
1938        s2  = nonlinear_ok_box_s2;
1939        r1  = sqrt( (xk(2) - s1(1))^2 + (xk(4) - s1(2))^2 );
1940        r2  = sqrt( (xk(2) - s2(1))^2 + (xk(4) - s2(2))^2 );
1941        hk = [ r1 ; r2 ];
1942        dr1 = [ 0, xk(2) - s1(1), 0, xk(4) - s1(2) ] / r1;
1943        dr2 = [ 0, xk(2) - s2(1), 0, xk(4) - s2(2) ] / r2;
1944        Hk = [ dr1 ; dr2 ];
1945        return
1946end
1947</pre></font></code>
1948 
1949
1950<hr>Input File: test/nonlinear_ok_box_h.m
1951
1952<hr>
1953 
1954
1955
1956
1957<center><b><big><big><a name="3.2.4" id="3.2.4">3.2.4: Example no Constraint Function: nonlinear_ok_box_nof</a>
1958</big></big></b></center>
1959<br>
1960<b><big><a name="3.2.4.a" id="3.2.4.a">3.2.4.a: Source Code</a></big></b>
1961
1962 <code><font color='blue'><pre style='display:inline'> 
1963function [fk, Fk] = nonlinear_ok_box_nof(k, xk)
1964        % no constraint case
1965        n  = size(xk, 1);
1966        fk = -1;
1967        Fk = zeros(1, n);
1968        return
1969end
1970</pre></font></code>
1971 
1972
1973<hr>Input File: test/nonlinear_ok_box_nof.m
1974
1975<hr>
1976 
1977
1978
1979<center><b><big><big><a name="3.3" id="3.3">3.3: ckbs_nonlinear Sine Wave Constrained Tracking Example and Test</a>
1980</big></big></b></center>
1981<br>
1982<b><big><a name="3.3.a" id="3.3.a">3.3.a: Syntax</a></big></b>
1983
1984<br>
1985<code><font color="blue"><span style='white-space: nowrap'>[</span></font></code><i><span style='white-space: nowrap'>ok</span></i><code><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;nonlinear_ok_sin(</span></font></code><i><span style='white-space: nowrap'>draw_plot</span></i><code><font color="blue"><span style='white-space: nowrap'>)</span></font></code>
1986
1987<br>
1988<br>
1989<b><big><a name="3.3.b" id="3.3.b">3.3.b: draw_plot</a></big></b>
1990<br>
1991If this argument is true, a plot is drawn showing the results
1992and the <code><font color="blue">nonlinear_ok_sin.out</font></code> file is written for use with the
1993program <code><font color="blue">test/nonlinear_ok_sin.r</font></code>.
1994
1995<br>
1996<br>
1997<b><big><a name="3.3.c" id="3.3.c">3.3.c: ok</a></big></b>
1998<br>
1999If the return value <i>ok</i> is true, the test passed,
2000otherwise the test failed.
2001
2002<br>
2003<br>
2004<b><big><a name="3.3.d" id="3.3.d">3.3.d: State Vector</a></big></b>
2005
2006<table><tr><td align='left'  valign='top'>
2007
2008<code>
2009<span style='white-space: nowrap'>&nbsp;x1&nbsp;(t)</span></code>
2010  </td><td align='left'  valign='top'>
2011 first component of velocity   </td></tr><tr><td align='left'  valign='top'>
2012
2013<code>
2014<span style='white-space: nowrap'>&nbsp;x2&nbsp;(t)</span></code>
2015  </td><td align='left'  valign='top'>
2016 first component of position  </td></tr><tr><td align='left'  valign='top'>
2017
2018<code>
2019<span style='white-space: nowrap'>&nbsp;x3&nbsp;(t)</span></code>
2020  </td><td align='left'  valign='top'>
2021 second component of velocity   </td></tr><tr><td align='left'  valign='top'>
2022
2023<code>
2024<span style='white-space: nowrap'>&nbsp;x4&nbsp;(t)</span></code>
2025  </td><td align='left'  valign='top'>
2026 second component of position 
2027</td></tr>
2028</table>
2029<br>
2030<b><big><a name="3.3.e" id="3.3.e">3.3.e: Measurement Vector</a></big></b>
2031
2032<table><tr><td align='left'  valign='top'>
2033
2034<code>
2035<span style='white-space: nowrap'>&nbsp;z1&nbsp;(t)</span></code>
2036  </td><td align='left'  valign='top'>
2037 range to station s1 plus noise </td></tr><tr><td align='left'  valign='top'>
2038
2039<code>
2040<span style='white-space: nowrap'>&nbsp;z2&nbsp;(t)</span></code>
2041  </td><td align='left'  valign='top'>
2042 range to station s2  plus noise
2043</td></tr>
2044</table>
2045<br>
2046<b><big><a name="3.3.f" id="3.3.f">3.3.f: Constraint</a></big></b>
2047
2048<br>
2049<code>
2050<span style='white-space: nowrap'>&nbsp;&nbsp;x4(t)&nbsp;\geq&nbsp;1&nbsp;-&nbsp;sin(&nbsp;x2(t)&nbsp;)</span></code>
2051 
2052
2053
2054<br>
2055<br>
2056<b><big><a name="3.3.g" id="3.3.g">3.3.g: Call Back Functions</a></big></b>
2057
2058<table><tr><td align='left'  valign='top'>
2059
2060<a href="#3.3.1">3.3.1: nonlinear_ok_sin_f.m</a></td><td>
2061Example Constraint Function: nonlinear_ok_sin_f</td></tr>
2062<tr><td>
2063
2064<a href="#3.2.2">3.2.2: nonlinear_ok_box_g.m</a></td><td>
2065Example Transition Function: nonlinear_ok_box_g</td></tr>
2066<tr><td>
2067
2068<a href="#3.2.3">3.2.3: nonlinear_ok_box_h.m</a></td><td>
2069Example Measurement Function: nonlinear_ok_box_h</td></tr>
2070<tr><td>
2071
2072<a href="#3.2.4">3.2.4: nonlinear_ok_box_nof.m</a></td><td>
2073Example no Constraint Function: nonlinear_ok_box_nof</td></tr>
2074<tr><td>
2075
2076</td></tr>
2077</table>
2078<br>
2079<b><big><a name="3.3.h" id="3.3.h">3.3.h: Source Code</a></big></b>
2080
2081 <code><font color='blue'><pre style='display:inline'> 
2082function [ok] = nonlinear_ok_sin(draw_plot)
2083if nargin &lt; 1
2084        draw_plot = false;
2085end
2086% --------------------------------------------------------
2087% You can change these parameters
2088N       = 50;            % number of measurement time points
2089dt      = 2 * pi / N;    % time between measurement points
2090sigma   = .25;           % standard deviation of measurement noise
2091gamma   = 1.;            % multiplier for transition variance
2092max_itr = 50;            % maximum number of iterations
2093epsilon = 1e-4;          % convergence criteria
2094x4_min  = .25;           % minimum value for x4 constraint
2095h_min   = 0;             % minimum horizontal value in plots
2096h_max   = 7;             % maximum horizontal value in plots
2097v_min   = 0;             % minimum vertical value in plots
2098v_max   = 2.5;           % maximum vertical value in plots
2099x4_dist = .05;           % distance true path is from the constraint
2100s1      = [ 0 , 0 ];     % station one
2101s2      = [ 2*pi , 0 ];  % station two
2102%
2103% level of tracing during the optimization
2104if draw_plot
2105        level   = 1;
2106else
2107        level   = 0;
2108end
2109% ---------------------------------------------------------
2110% global variables used by nonlinear_ok_box_h
2111global nonlinear_ok_box_s1
2112global nonlinear_ok_box_s2
2113nonlinear_ok_box_s1 = s1;
2114nonlinear_ok_box_s2 = s2;
2115%
2116% global variable used by nonlinear_ok_sin_f
2117global nonlinear_ok_sin_x4_min
2118nonlinear_ok_sin_x4_min = x4_min;
2119%
2120ok = true;
2121%
2122%  Define the problem
2123rand('seed', 234);
2124%
2125% number of constraints per time point
2126ell   = 1;
2127%
2128% number of measurements per time point
2129m     = 2;
2130%
2131% number of state vector components per time point
2132n     = 4;
2133%
2134% simulate the true trajectory and measurement noise
2135t        =  (1 : N) * dt;
2136x1_true  = ones(1, N);
2137x2_true  = t;
2138x3_true  = - cos(t);
2139x4_true  = x4_dist + 1 - sin(t) + x4_min;
2140x_true   = [ x1_true ; x2_true ; x3_true ; x4_true ];
2141v1_true  = sigma * randn(1, N);
2142v2_true  = sigma * randn(1, N);
2143%
2144% corresponding measurement values
2145rinv    = zeros(m, m, N);
2146z       = zeros(m, N);
2147rinvk   = eye(m) / (sigma * sigma);
2148for k = 1 : N
2149        x_k          = x_true(:, k);
2150        h_k          = nonlinear_ok_box_h(k, x_k);
2151        z(:, k)      = h_k + [ v1_true(k) ; v2_true(k) ];
2152        rinv(:,:, k) = rinvk;
2153end
2154%
2155% covariance for the transition noise
2156qk       = diag( [ dt, dt^3 / 3 , dt, dt^3 / 3 ] );
2157qk(1, 2) = dt^2 / 2;
2158qk(2, 1) = dt^2 / 2;
2159qk(3, 4) = dt^2 / 2;
2160qk(4, 3) = dt^2 / 2;
2161qk       = qk * gamma;
2162qinvk    = inv(qk);
2163qinv     = zeros(n, n, N);
2164for k = 2 : N
2165        qinv(:,:, k) = qinvk;
2166end
2167%
2168% covariance for the initial estimate
2169qinv(:,:,1) = eye(n) * 100 * gamma;
2170%
2171% initial x vector
2172x_in       = zeros(n, N);
2173x_in(4, :) = 1;
2174%
2175% nonlinear_ok_sin use same g function as nonlinear_box_ok
2176% global variables used by nonlinear_ok_box_g
2177global nonlinear_ok_box_x1
2178global nonlinear_ok_box_dt
2179nonlinear_ok_box_x1 = x_true(:, 1);
2180nonlinear_ok_box_dt = dt;
2181%
2182% ----------------------------------------------------------------------
2183f_fun = 'nonlinear_ok_sin_f';  % special nonlinear_ok_sin constraints
2184g_fun = 'nonlinear_ok_box_g';  % same transition function as nonlinear_ok_box
2185h_fun = 'nonlinear_ok_box_h';  % same measurement function as nonlinear_ok_box
2186[x_out, u_out, info] = ckbs_nonlinear( ...
2187        f_fun,    ...
2188        g_fun,    ...
2189        h_fun,    ...
2190        max_itr,  ...
2191        epsilon,  ...
2192        x_in,     ...
2193        z,        ...
2194        qinv,     ...
2195        rinv,     ...
2196        level     ...
2197);
2198% ----------------------------------------------------------------------
2199ok         = ok &amp; (size(info,1) &lt;= max_itr);
2200f_out      = zeros(ell, N);
2201g_out      = zeros(n, N);
2202h_out      = zeros(m, N);
2203df_out     = zeros(ell, n, N);
2204dg_out     = zeros(n, n, N);
2205dh_out     = zeros(m, n, N);
2206xk1        = zeros(n, 1);
2207for k = 1 : N
2208        xk    = x_out(:, k);
2209        uk    = u_out(:, k);
2210        [fk, Fk]   = nonlinear_ok_sin_f(k, xk);
2211        [gk, Gk]   = nonlinear_ok_box_g(k, xk1);
2212        [hk, Hk]   = nonlinear_ok_box_h(k, xk);
2213        %
2214        ok   = ok &amp; all( fk &lt;= epsilon );
2215        ok   = ok &amp; all( abs(fk) .* uk &lt;= epsilon );
2216        %
2217        df_out(:,:, k) = Fk;
2218        dg_out(:,:, k) = Gk;
2219        dh_out(:,:, k) = Hk;
2220        f_out(:, k)    = fk - Fk * xk;
2221        g_out(:, k)    = gk - Gk * xk1;
2222        h_out(:, k)    = hk - Hk * xk;
2223        xk1 = xk;
2224end
2225ok   = ok &amp; all( all( u_out &gt;= 0 ) );
2226%
2227d_out = ckbs_sumsq_grad(x_out, z, g_out, h_out, dg_out, dh_out, qinv, rinv);
2228for k = 1 : N
2229        uk = u_out(:, k);
2230        Fk = df_out(:,:, k);
2231        dk = d_out(:, k);
2232        %
2233        ok = ok &amp; (max ( abs( Fk' * uk + dk ) ) &lt;= epsilon);
2234end
2235if ~ ok
2236        keyboard
2237end
2238if draw_plot
2239        figure(1);
2240        clf
2241        hold on
2242        plot(x_true(2,:)', x_true(4,:)', 'b-' );
2243        plot(x_out(2,:)', x_out(4,:)', 'g-' );
2244        plot(x_true(2,:)', 1 - sin(x_true(2,:))' + x4_min, 'r-');
2245        axis([h_min, h_max, v_min, v_max]);
2246        title('Constrained: blue=truth, green=estimate, red=constraint');
2247        hold off
2248        %
2249        % constrained estimate
2250        x_con = x_out;
2251end
2252% ----------------------------------------------------------------------
2253% Unconstrained case
2254f_fun = 'nonlinear_ok_box_nof';  % same function as used by nonlinear_ok_box
2255[x_out, u_out, info] = ckbs_nonlinear( ...
2256        f_fun,    ...
2257        g_fun,    ...
2258        h_fun,    ...
2259        max_itr,  ...
2260        epsilon,  ...
2261        x_in,     ...
2262        z,        ...
2263        qinv,     ...
2264        rinv,     ...
2265        level     ...
2266);
2267% ----------------------------------------------------------------------
2268ok   = ok &amp; (size(info,1) &lt;= max_itr);
2269xk1  = zeros(n, 1);
2270for k = 1 : N
2271        xk    = x_out(:, k);
2272        [gk, Gk]   = nonlinear_ok_box_g(k, xk1);
2273        [hk, Hk]   = nonlinear_ok_box_h(k, xk);
2274        %
2275        dg_out(:,:, k) = Gk;
2276        dh_out(:,:, k) = Hk;
2277        g_out(:, k)    = gk - Gk * xk1;
2278        h_out(:, k)    = hk - Hk * xk;
2279        xk1 = xk;
2280end
2281d_out  = ckbs_sumsq_grad(x_out, z, g_out, h_out, dg_out, dh_out, qinv, rinv);
2282ok     = ok &amp; (max( max( abs(d_out) ) ) &lt;= epsilon);
2283if draw_plot
2284        figure(2);
2285        clf
2286        hold on
2287        plot(x_true(2,:)', x_true(4,:)', 'b-' );
2288        plot(x_out(2,:)', x_out(4,:)', 'g-' );
2289        plot(x_true(2,:)', 1 - sin(x_true(2,:))' + x4_min, 'r-');
2290        axis([h_min, h_max, v_min, v_max]);
2291        title('Unconstrained: blue=truth, green=estimate, red=constraint');
2292        hold off
2293        %
2294        % unconstrained estimate
2295        x_free = x_out;
2296        %
2297        % write out constrained and unconstrained results
2298        [fid, msg] = fopen('nonlinear_ok_sin.out', 'wt');
2299        if size(msg, 2) &gt; 0
2300                disp(['nonlinear_ok: ', msg]);
2301        end
2302        %                      123456789012345678901234'
2303        heading =             ' x2_true  x2_con x2_free'  ;
2304        heading = [ heading , ' x4_true  x4_con x4_free' ];
2305        heading = [ heading , '      z1      z2\n'       ];
2306        fprintf(fid, heading);
2307        for k = 1 : N
2308                fprintf(fid,'%8.3f%8.3f%8.3f%8.3f%8.3f%8.3f%8.3f%8.3f\n', ...
2309                        x_true(2,k), x_con(2,k), x_free(2,k), ...
2310                        x_true(4,k), x_con(4,k), x_free(4,k), ...
2311                        z(1,k), z(2,k) ...
2312                );
2313        end
2314        fclose(fid);
2315end
2316return
2317end
2318</pre></font></code>
2319 
2320
2321<hr>Input File: test/nonlinear_ok_sin.m
2322
2323<hr>
2324 
2325
2326
2327
2328<center><b><big><big><a name="3.3.1" id="3.3.1">3.3.1: Example Constraint Function: nonlinear_ok_sin_f</a>
2329</big></big></b></center>
2330<br>
2331<b><big><a name="3.3.1.a" id="3.3.1.a">3.3.1.a: Source Code</a></big></b>
2332
2333 <code><font color='blue'><pre style='display:inline'> 
2334function [fk, Fk] = nonlinear_ok_sin_f(k, xk)
2335        global nonlinear_ok_sin_x4_min
2336        x4_min = nonlinear_ok_sin_x4_min;
2337        %
2338        % constrained so that x(4) &gt;= 1 - sin( x(1) ) + x4_min
2339        ell      = 1;
2340        n        = size(xk, 1);
2341        %
2342        fk       = 1 - sin( xk(2) ) + x4_min - xk(4);
2343        Fk       = zeros(ell, n);
2344        Fk(1, 2) = - cos( xk(2) );
2345        Fk(1, 4) = -1;
2346        return
2347end
2348</pre></font></code>
2349 
2350
2351<hr>Input File: test/nonlinear_ok_sin_f.m
2352
2353<hr>
2354 
2355
2356
2357
2358
2359
2360
2361
2362
2363<center><b><big><big><a name="4" id="4">4: Constrained Affine Kalman Bucy Smoother</a>
2364</big></big></b></center>
2365<br>
2366<b><big><a name="4.a" id="4.a">4.a: Syntax</a></big></b>
2367
2368<br>
2369<code><font color="blue"><span style='white-space: nowrap'>[</span></font></code><i><span style='white-space: nowrap'>xOut</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>uOut</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>info</span></i><code><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;ckbs_affine(</span></font></code><i><span style='white-space: nowrap'>max_itr</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>epsilon</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>z</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>b</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>g</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>h</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>db</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>dg</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>dh</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>qinv</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>rinv</span></i><code><font color="blue"><span style='white-space: nowrap'>)</span></font></code>
2370
2371<br>
2372<br>
2373<b><big><a name="4.b" id="4.b">4.b: Purpose</a></big></b>
2374<br>
2375This routine minimizes the
2376affine Kalman-Bucy smoother residual sum of squares objective
2377subject to an affine inequality constraint.
2378
2379<br>
2380<br>
2381<b><big><a name="4.c" id="4.c">4.c: Notation</a></big></b>
2382<br>
2383The affine Kalman-Bucy smoother residual sum of squares is defined by
2384<code>
2385<span style='white-space: nowrap'>&nbsp;\[<br>
2386\begin{array}{rcl}<br>
2387S&nbsp;(&nbsp;x_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N&nbsp;)&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;\sum_{k=1}^N&nbsp;S_k&nbsp;(&nbsp;x_k&nbsp;,&nbsp;x_{k-1}&nbsp;)&nbsp;\\<br>
2388S_k&nbsp;(&nbsp;x_k&nbsp;,&nbsp;x_{k-1}&nbsp;)&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;<br>
2389\frac{1}{2}&nbsp;<br>
2390(&nbsp;z_k&nbsp;-&nbsp;h_k&nbsp;-&nbsp;H_k&nbsp;*&nbsp;x_k&nbsp;)^\T&nbsp;*&nbsp;R_k^{-1}&nbsp;*&nbsp;(&nbsp;z_k&nbsp;-&nbsp;h_k&nbsp;-&nbsp;H_k&nbsp;*&nbsp;x_k&nbsp;)<br>
2391\\<br>
2392&amp;&nbsp;+&nbsp;&amp;<br>
2393\frac{1}{2}&nbsp;<br>
2394(&nbsp;x_k&nbsp;-&nbsp;g_k&nbsp;-&nbsp;G_k&nbsp;*&nbsp;x_{k-1}&nbsp;)^\T&nbsp;*&nbsp;Q_k^{-1}&nbsp;*&nbsp;(&nbsp;x_k&nbsp;-&nbsp;g_k&nbsp;-&nbsp;G_k&nbsp;*&nbsp;x_{k-1}&nbsp;)<br>
2395\\<br>
2396\end{array}<br>
2397\]&nbsp;</span></code>
2398
2399where the matrices <code>
2400<span style='white-space: nowrap'>&nbsp;R_k</span></code>
2401 and <code>
2402<span style='white-space: nowrap'>&nbsp;Q_k</span></code>
2403 are
2404symmetric positive definite and
2405<code>
2406<span style='white-space: nowrap'>&nbsp;x_0</span></code>
2407 is the constant zero.
2408Note that <code>
2409<span style='white-space: nowrap'>&nbsp;g_1</span></code>
2410 is the initial state estimate
2411and <code>
2412<span style='white-space: nowrap'>&nbsp;Q_1</span></code>
2413 is the corresponding covariance.
2414
2415<br>
2416<br>
2417<b><big><a name="4.d" id="4.d">4.d: Problem</a></big></b>
2418<br>
2419The affine constrained Kalman-Bucy smoother problem is
2420<code>
2421<span style='white-space: nowrap'>&nbsp;\[<br>
2422\begin{array}{rll}<br>
2423{\rm&nbsp;minimize}&nbsp;<br>
2424&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;S(&nbsp;x_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N&nbsp;)&nbsp;<br>
2425&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;{\rm&nbsp;w.r.t.}&nbsp;\;&nbsp;x_1&nbsp;\in&nbsp;\R^n&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N&nbsp;\in&nbsp;\R^n<br>
2426\\<br>
2427{\rm&nbsp;subject&nbsp;\;&nbsp;to}&nbsp;<br>
2428&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;b_k&nbsp;+&nbsp;B_k&nbsp;*&nbsp;x_k&nbsp;&nbsp;\leq&nbsp;0&nbsp;<br>
2429&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;{\rm&nbsp;for}&nbsp;\;&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N<br>
2430\end{array}<br>
2431\]&nbsp;</span></code>
2432
2433
2434<br>
2435<br>
2436<b><big><a name="4.e" id="4.e">4.e: First Order Conditions</a></big></b>
2437<br>
2438A state sequence <code>
2439<span style='white-space: nowrap'>&nbsp;(&nbsp;x_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N&nbsp;)</span></code>
2440 is considered a solution
2441if there is a Lagrange multiplier sequence <code>
2442<span style='white-space: nowrap'>&nbsp;(&nbsp;u_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;u_N&nbsp;)</span></code>
2443 
2444such that the following conditions are satisfied.
2445<code>
2446<span style='white-space: nowrap'>&nbsp;\[<br>
2447\begin{array}{rcl}<br>
2448&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;b_k&nbsp;+&nbsp;B_k&nbsp;*&nbsp;x_k&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;\leq&nbsp;&amp;&nbsp;\varepsilon&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
2449&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;\leq&nbsp;&amp;&nbsp;u_k&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
2450&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;(&nbsp;B_k^T&nbsp;*&nbsp;u_k&nbsp;+&nbsp;d_k&nbsp;)_j&nbsp;|&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;\leq&nbsp;&amp;&nbsp;\varepsilon&nbsp;\\&nbsp;&nbsp;<br>
2451&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;|&nbsp;(u_k)_i&nbsp;*&nbsp;(&nbsp;b_k&nbsp;+&nbsp;B_k&nbsp;*&nbsp;x_k)_i&nbsp;|&nbsp;&amp;&nbsp;\leq&nbsp;&amp;&nbsp;\varepsilon<br>
2452\end{array}<br>
2453\]&nbsp;</span></code>
2454
2455for <code>
2456<span style='white-space: nowrap'>&nbsp;j&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;n</span></code>
2457,
2458<code>
2459<span style='white-space: nowrap'>&nbsp;i&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;\ell</span></code>
2460, and
2461<code>
2462<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
2463.
2464Here
2465<code>
2466<span style='white-space: nowrap'>&nbsp;d_k</span></code>
2467 is the partial derivative of <code>
2468<span style='white-space: nowrap'>&nbsp;S&nbsp;(&nbsp;x_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N&nbsp;)</span></code>
2469
2470with respect to <code>
2471<span style='white-space: nowrap'>&nbsp;x_k</span></code>
2472
2473and <code>
2474<span style='white-space: nowrap'>&nbsp;(u_k)_i</span></code>
2475 denotes the <i>i</i>-th component of <code>
2476<span style='white-space: nowrap'>&nbsp;u_k</span></code>
2477.
2478
2479<br>
2480<br>
2481<b><big><a name="4.f" id="4.f">4.f: max_itr</a></big></b>
2482<br>
2483The integer scalar <i>max_itr</i> specifies the maximum number of
2484iterations of the algorithm to execute. It must be greater than or
2485equal to zero. Note that if it is zero, the first row of the
2486<a href="#4.s">4.s: <span style='white-space: nowrap'>info</span></a>
2487 return value will still be computed.
2488This can be useful for deciding what is a good value for the argument
2489<a href="#4.g">4.g: <span style='white-space: nowrap'>epsilon</span></a>
2490.
2491
2492<br>
2493<br>
2494<b><big><a name="4.g" id="4.g">4.g: epsilon</a></big></b>
2495<br>
2496The positive scalar <i>epsilon</i> specifies the convergence
2497criteria value; i.e.,
2498<code>
2499<span style='white-space: nowrap'>&nbsp;\[<br>
2500&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\varepsilon&nbsp;=&nbsp;epsilon<br>
2501\]&nbsp;</span></code>
2502
2503
2504<br>
2505<br>
2506<b><big><a name="4.h" id="4.h">4.h: z</a></big></b>
2507<br>
2508The argument <i>z</i> is a two dimensional array,
2509for <code>
2510<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
2511
2512<code>
2513<span style='white-space: nowrap'>&nbsp;\[<br>
2514&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;z_k&nbsp;=&nbsp;z(:,&nbsp;k)<br>
2515\]</span></code>
2516
2517and <i>z</i> has size <code>
2518<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;N</span></code>
2519.
2520
2521<br>
2522<br>
2523<b><big><a name="4.i" id="4.i">4.i: b</a></big></b>
2524<br>
2525The argument <i>b</i> is a two dimensional array,
2526for <code>
2527<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
2528
2529<code>
2530<span style='white-space: nowrap'>&nbsp;\[<br>
2531&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;b_k&nbsp;=&nbsp;b(:,&nbsp;k)<br>
2532\]</span></code>
2533
2534and <i>b</i> has size <code>
2535<span style='white-space: nowrap'>&nbsp;\ell&nbsp;\times&nbsp;N</span></code>
2536.
2537If <code>
2538<span style='white-space: nowrap'>&nbsp;\ell&nbsp;=&nbsp;0</span></code>
2539, the problem is not constrained; i.e.,
2540it is the affine Kalman-Bucy smoother problem.
2541
2542<br>
2543<br>
2544<b><big><a name="4.j" id="4.j">4.j: g</a></big></b>
2545<br>
2546The argument <i>g</i> is a two dimensional array,
2547for <code>
2548<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
2549
2550<code>
2551<span style='white-space: nowrap'>&nbsp;\[<br>
2552&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;g_k&nbsp;=&nbsp;g(:,&nbsp;k)<br>
2553\]</span></code>
2554
2555and <i>g</i> has size <code>
2556<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;N</span></code>
2557.
2558The value <code>
2559<span style='white-space: nowrap'>&nbsp;g_1</span></code>
2560 serves as the initial state estimate.
2561
2562<br>
2563<br>
2564<b><big><a name="4.k" id="4.k">4.k: h</a></big></b>
2565<br>
2566The argument <i>h</i> is a two dimensional array,
2567for <code>
2568<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
2569
2570<code>
2571<span style='white-space: nowrap'>&nbsp;\[<br>
2572&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;h_k&nbsp;=&nbsp;h(:,&nbsp;k)<br>
2573\]</span></code>
2574
2575and <i>h</i> has size <code>
2576<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;N</span></code>
2577.
2578
2579<br>
2580<br>
2581<b><big><a name="4.l" id="4.l">4.l: db</a></big></b>
2582<br>
2583The argument <i>db</i> is a three dimensional array,
2584for <code>
2585<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
2586
2587<code>
2588<span style='white-space: nowrap'>&nbsp;\[<br>
2589&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;B_k&nbsp;=&nbsp;db(:,:,k)<br>
2590\]</span></code>
2591
2592and <i>db</i> has size <code>
2593<span style='white-space: nowrap'>&nbsp;\ell&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
2594.
2595
2596
2597<br>
2598<br>
2599<b><big><a name="4.m" id="4.m">4.m: dg</a></big></b>
2600<br>
2601The argument <i>dg</i> is a three dimensional array,
2602for <code>
2603<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
2604
2605<code>
2606<span style='white-space: nowrap'>&nbsp;\[<br>
2607&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;G_k&nbsp;=&nbsp;dg(:,:,k)<br>
2608\]</span></code>
2609
2610and <i>dg</i> has size <code>
2611<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
2612.
2613The initial state estimate <code>
2614<span style='white-space: nowrap'>&nbsp;g_1</span></code>
2615 does not depend on the value of
2616<code>
2617<span style='white-space: nowrap'>&nbsp;x_0</span></code>
2618, hence <code>
2619<span style='white-space: nowrap'>&nbsp;G_1</span></code>
2620 should be zero.
2621
2622<br>
2623<br>
2624<b><big><a name="4.n" id="4.n">4.n: dh</a></big></b>
2625<br>
2626The argument <i>dh</i> is a three dimensional array,
2627for <code>
2628<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
2629
2630<code>
2631<span style='white-space: nowrap'>&nbsp;\[<br>
2632&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;H_k&nbsp;=&nbsp;dh(:,:,k)<br>
2633\]</span></code>
2634
2635and <i>dh</i> has size <code>
2636<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
2637.
2638
2639<br>
2640<br>
2641<b><big><a name="4.o" id="4.o">4.o: qinv</a></big></b>
2642<br>
2643The argument <i>qinv</i> is a three dimensional array,
2644for <code>
2645<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
2646
2647<code>
2648<span style='white-space: nowrap'>&nbsp;\[<br>
2649&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Q_k^{-1}&nbsp;=&nbsp;qinv(:,:,&nbsp;k)<br>
2650\]</span></code>
2651
2652and <i>qinv</i> has size <code>
2653<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
2654.
2655The value of <code>
2656<span style='white-space: nowrap'>&nbsp;Q_k</span></code>
2657 is the variance of the initial state
2658estimate <code>
2659<span style='white-space: nowrap'>&nbsp;g_1</span></code>
2660.
2661
2662<br>
2663<br>
2664<b><big><a name="4.p" id="4.p">4.p: rinv</a></big></b>
2665<br>
2666The argument <i>rinv</i> is a three dimensional array,
2667for <code>
2668<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
2669
2670<code>
2671<span style='white-space: nowrap'>&nbsp;\[<br>
2672&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;R_k^{-1}&nbsp;=&nbsp;rinv(:,:,&nbsp;k)<br>
2673\]</span></code>
2674
2675and <i>rinv</i> has size <code>
2676<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;m&nbsp;\times&nbsp;N</span></code>
2677.
2678It is ok to signify a missing data value by setting the corresponding
2679row and column of <i>rinv</i> to zero. This also enables use
2680to interpolate the state vector <code>
2681<span style='white-space: nowrap'>&nbsp;x_k</span></code>
2682 to points where
2683there are no measurements.
2684
2685<br>
2686<br>
2687<b><big><a name="4.q" id="4.q">4.q: xOut</a></big></b>
2688<br>
2689The result <i>xOut</i> contains the optimal sequence
2690<code>
2691<span style='white-space: nowrap'>&nbsp;(&nbsp;x_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N&nbsp;)</span></code>
2692.
2693For <code>
2694<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
2695
2696<code>
2697<span style='white-space: nowrap'>&nbsp;\[<br>
2698&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x_k&nbsp;=&nbsp;xOut(:,&nbsp;k)<br>
2699\]</span></code>
2700
2701and <i>xOut</i> is a two dimensional array with size <code>
2702<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;N</span></code>
2703.
2704
2705<br>
2706<br>
2707<b><big><a name="4.r" id="4.r">4.r: uOut</a></big></b>
2708<br>
2709The result <i>uOut</i> contains the Lagrange multiplier sequence
2710corresponding to <i>xOut</i>.
2711For <code>
2712<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
2713
2714<code>
2715<span style='white-space: nowrap'>&nbsp;\[<br>
2716&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;u_k&nbsp;=&nbsp;uOut(:,&nbsp;k)<br>
2717\]</span></code>
2718
2719and <i>uOut</i> is a two dimensional array with size
2720<code>
2721<span style='white-space: nowrap'>&nbsp;\ell&nbsp;\times&nbsp;N</span></code>
2722.
2723The pair <i>xOut</i>, <i>uOut</i> satisfy the
2724<a href="#4.e">4.e: <span style='white-space: nowrap'>first&nbsp;order&nbsp;conditions</span></a>
2725.
2726
2727<br>
2728<br>
2729<b><big><a name="4.s" id="4.s">4.s: info</a></big></b>
2730<br>
2731The result <i>info</i> is a matrix with each row corresponding
2732to an iteration of the algorithm.
2733Note that <code><font color="blue">ckbs_affine</font></code> has satisfied the convergence condition if
2734and only if
2735<code><font color="blue"><span style='white-space: nowrap'><br>
2736&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;all(&nbsp;</span></font></code><i><span style='white-space: nowrap'>info</span></i><code><font color="blue"><span style='white-space: nowrap'>(end,&nbsp;1:3)&nbsp;&lt;=&nbsp;</span></font></code><i><span style='white-space: nowrap'>epsilon</span></i><code><font color="blue"><span style='white-space: nowrap'>&nbsp;)<br>
2737</span></font></code><code><span style='white-space: nowrap'><br>
2738<br>
2739</span></code>We use <code>
2740<span style='white-space: nowrap'>&nbsp;x_k^q</span></code>
2741 (<code>
2742<span style='white-space: nowrap'>&nbsp;u_k^q</span></code>
2743)
2744to denote the state vector (dual vector)
2745for time point <code>
2746<span style='white-space: nowrap'>&nbsp;k</span></code>
2747 and at the end of iteration <code>
2748<span style='white-space: nowrap'>&nbsp;q-1</span></code>
2749
2750We use <code>
2751<span style='white-space: nowrap'>&nbsp;d_k^q</span></code>
2752 for the partial derivative of
2753<code>
2754<span style='white-space: nowrap'>&nbsp;S&nbsp;(&nbsp;x_1^q&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N^q&nbsp;)</span></code>
2755 with respect to <code>
2756<span style='white-space: nowrap'>&nbsp;x_k</span></code>
2757.
2758
2759<br>
2760<br>
2761<b><a name="4.s.a" id="4.s.a">4.s.a: Constraint Bound</a></b>
2762<br>
2763The value <code><font color="blue"></font></code><i><span style='white-space: nowrap'>info</span></i><code><font color="blue"><span style='white-space: nowrap'>(</span></font></code><i><span style='white-space: nowrap'>q</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;1)</span></font></code> is
2764a bound on the constraint functions
2765at the end of iteration <code>
2766<span style='white-space: nowrap'>&nbsp;q-1</span></code>
2767. To be specific
2768<code>
2769<span style='white-space: nowrap'>&nbsp;\[<br>
2770info(q,&nbsp;1)&nbsp;=&nbsp;\max_{i,k}&nbsp;(&nbsp;b_k&nbsp;+&nbsp;B_k&nbsp;*&nbsp;x_k&nbsp;)_i<br>
2771\]&nbsp;</span></code>
2772
2773
2774<br>
2775<br>
2776<b><a name="4.s.b" id="4.s.b">4.s.b: First Order Conditions</a></b>
2777<br>
2778The value <code><font color="blue"></font></code><i><span style='white-space: nowrap'>info</span></i><code><font color="blue"><span style='white-space: nowrap'>(</span></font></code><i><span style='white-space: nowrap'>q</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;2)</span></font></code> is
2779a bound on the partial derivative of the Lagrangian with respect to
2780the state vector sequence
2781at the end of iteration <code>
2782<span style='white-space: nowrap'>&nbsp;q-1</span></code>
2783:
2784<code>
2785<span style='white-space: nowrap'>&nbsp;\[<br>
2786info(q,&nbsp;2)&nbsp;=&nbsp;\max&nbsp;\left[&nbsp;|&nbsp;(&nbsp;B_k^T&nbsp;*&nbsp;u_k&nbsp;+&nbsp;d_k&nbsp;)_j&nbsp;|&nbsp;\right]<br>
2787\]&nbsp;</span></code>
2788
2789where the maximum is with respect to <code>
2790<span style='white-space: nowrap'>&nbsp;j&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;n</span></code>
2791
2792and <code>
2793<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
2794.
2795
2796<br>
2797<br>
2798<b><a name="4.s.c" id="4.s.c">4.s.c: Complementarity Conditions</a></b>
2799<br>
2800The value <code><font color="blue"></font></code><i><span style='white-space: nowrap'>info</span></i><code><font color="blue"><span style='white-space: nowrap'>(</span></font></code><i><span style='white-space: nowrap'>q</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;3)</span></font></code> is
2801a bound on the complementarity conditions
2802at the end of iteration <code>
2803<span style='white-space: nowrap'>&nbsp;q-1</span></code>
2804:
2805<code>
2806<span style='white-space: nowrap'>&nbsp;\[<br>
2807info(q,&nbsp;3)&nbsp;=&nbsp;\max&nbsp;\left[&nbsp;|&nbsp;(u_k)_i&nbsp;*&nbsp;(&nbsp;b_k&nbsp;+&nbsp;B_k&nbsp;*&nbsp;x_k)_i&nbsp;|&nbsp;\right]<br>
2808\]&nbsp;</span></code>
2809
2810where the maximum is with respect to
2811<code>
2812<span style='white-space: nowrap'>&nbsp;i&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;\ell</span></code>
2813 and
2814<code>
2815<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
2816.
2817
2818
2819<br>
2820<br>
2821<b><a name="4.s.d" id="4.s.d">4.s.d: Step Size</a></b>
2822<br>
2823The value <code><font color="blue"></font></code><i><span style='white-space: nowrap'>info</span></i><code><font color="blue"><span style='white-space: nowrap'>(</span></font></code><i><span style='white-space: nowrap'>q</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;4)</span></font></code> is the line search step size used during
2824iteration <code>
2825<span style='white-space: nowrap'>&nbsp;q-1</span></code>
2826.
2827Small step sizes indicate problems with the interior point method
2828used to solve the affine problem
2829(with the exception that <code><font color="blue"></font></code><i><span style='white-space: nowrap'>info</span></i><code><font color="blue"><span style='white-space: nowrap'>(1,&nbsp;4)</span></font></code> is always zero).
2830
2831
2832
2833
2834<br>
2835<br>
2836<b><big><a name="4.t" id="4.t">4.t: Example</a></big></b>
2837<br>
2838The file <a href="#4.1">4.1: <span style='white-space: nowrap'>affine_ok_box.m</span></a>
2839 contains an example and test of
2840<code><font color="blue">ckbs_affine</font></code>.
2841It returns true if <code><font color="blue">ckbs_affine</font></code> passes the test
2842and false otherwise.
2843
2844
2845<hr>Input File: src/ckbs_affine.m
2846
2847<hr>
2848 
2849
2850
2851<center><b><big><big><a name="4.1" id="4.1">4.1: ckbs_affine Box Constrained Smoothing Spline Example and Test</a>
2852</big></big></b></center>
2853<br>
2854<b><big><a name="4.1.a" id="4.1.a">4.1.a: Syntax</a></big></b>
2855
2856<br>
2857<code><font color="blue"><span style='white-space: nowrap'>[</span></font></code><i><span style='white-space: nowrap'>ok</span></i><code><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;affine_ok_box(</span></font></code><i><span style='white-space: nowrap'>draw_plot</span></i><code><font color="blue"><span style='white-space: nowrap'>)</span></font></code>
2858
2859<br>
2860<br>
2861<b><big><a name="4.1.b" id="4.1.b">4.1.b: draw_plot</a></big></b>
2862<br>
2863If this argument is true, a plot is drawn showing the results
2864and the <code><font color="blue">nonlinear_ok_box.out</font></code> file is written for use with
2865the program <code><font color="blue">nonlinear_ok_box.r</font></code>.
2866
2867<br>
2868<br>
2869<b><big><a name="4.1.c" id="4.1.c">4.1.c: ok</a></big></b>
2870<br>
2871If the return value <i>ok</i> is true, the test passed,
2872otherwise the test failed.
2873
2874<br>
2875<br>
2876<b><big><a name="4.1.d" id="4.1.d">4.1.d: State Vector</a></big></b>
2877
2878<table><tr><td align='left'  valign='top'>
2879
2880<code>
2881<span style='white-space: nowrap'>&nbsp;x1&nbsp;(t)</span></code>
2882 </td><td align='left'  valign='top'>
2883 derivative of function we are estimating </td></tr><tr><td align='left'  valign='top'>
2884
2885<code>
2886<span style='white-space: nowrap'>&nbsp;x2&nbsp;(t)</span></code>
2887 </td><td align='left'  valign='top'>
2888 value of function we are estimating
2889</td></tr>
2890</table>
2891<br>
2892<b><big><a name="4.1.e" id="4.1.e">4.1.e: Measurement</a></big></b>
2893
2894<br>
2895<code>
2896<span style='white-space: nowrap'>&nbsp;z1&nbsp;(t)</span></code>
2897 value of <code>
2898<span style='white-space: nowrap'>&nbsp;x2&nbsp;(t)</span></code>
2899 plus noise
2900
2901<br>
2902<br>
2903<b><big><a name="4.1.f" id="4.1.f">4.1.f: Constraint</a></big></b>
2904
2905<br>
2906<code>
2907<span style='white-space: nowrap'>&nbsp;\[<br>
2908&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\begin{array}{c}<br>
2909&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-1&nbsp;\leq&nbsp;x1&nbsp;(t)&nbsp;\leq&nbsp;+1<br>
2910&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
2911&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;-1&nbsp;\leq&nbsp;x2&nbsp;(t)&nbsp;\leq&nbsp;+1<br>
2912&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\end{array}<br>
2913\]</span></code>
2914.
2915
2916<br>
2917<br>
2918<b><big><a name="4.1.g" id="4.1.g">4.1.g: Source Code</a></big></b>
2919
2920
2921 <code><font color='blue'><pre style='display:inline'> 
2922function [ok] = affine_ok_box(draw_plot)
2923% --------------------------------------------------------
2924% You can change these parameters
2925N     = 50;        % number of measurement time points
2926dt    = 2*pi / N;  % time between measurement points
2927gamma =  1;        % transition covariance multiplier
2928sigma =  .5;       % standard deviation of measurement noise
2929max_itr = 30;      % maximum number of iterations
2930epsilon = 1e-5;    % convergence criteria
2931h_min   = 0;       % minimum horizontal value in plots
2932h_max   = 7;       % maximum horizontal value in plots
2933v_min   = -2.0;    % minimum vertical value in plots
2934v_max   = +2.0;    % maximum vertical value in plots
2935% ---------------------------------------------------------
2936ok = true;
2937if nargin &lt; 1
2938        draw_plot = false;
2939end
2940%  Define the problem
2941rand('seed', 1234);
2942%
2943% number of constraints per time point
2944ell   = 4;
2945%
2946% number of measurements per time point
2947m     = 1;
2948%
2949% number of state vector components per time point
2950n     = 2;
2951%
2952% simulate the true trajectory and measurement noise
2953t       =  (1 : N) * dt;
2954x1_true = - cos(t);
2955x2_true = - sin(t);
2956x_true  = [ x1_true ; x2_true ];
2957v_true  = sigma * rand(1, N);
2958%
2959% measurement values and model
2960v_true  = sigma * randn(1, N);
2961z       = x2_true + v_true;
2962rk      = sigma * sigma;
2963rinvk   = 1 / rk;
2964rinv    = zeros(m, m, N);
2965h       = zeros(m, N);
2966dh      = zeros(m, n, N);
2967for k = 1 : N
2968        rinv(:, :, k) = rinvk;
2969        h(:, k)       = 0;
2970        dh(:,:, k)    = [ 0 , 1 ];
2971end
2972%
2973% transition model
2974g       = zeros(n, N);
2975dg      = zeros(n, n, N);
2976qinv    = zeros(n, n, N);
2977qk      = gamma * [ dt , dt^2/2 ; dt^2/2 , dt^3/3 ];
2978qinvk   = inv(qk);
2979for k = 2 : N
2980        g(:, k)       = 0;
2981        dg(:,:, k)    = [ 1 , 0 ; dt , 1 ];
2982        qinv(:,:, k)  = qinvk;
2983end
2984%
2985% initial state estimate
2986g(:, 1)      = x_true(:, 1);
2987qinv(:,:, 1) = 100 * eye(2);
2988%
2989% constraints
2990b       = zeros(ell, N);
2991db      = zeros(ell, n, N);
2992for k = 1 : N
2993        %
2994        % b(:, k) + db(:,:, k) * x(:, k) &lt;= 0
2995        b(:, k)    = [ -1 ; -1 ; -1 ; -1 ];
2996        db(:,:, k) = [ -1 , 0 ; 1 , 0 ; 0 , -1 ; 0 , 1 ];
2997end
2998%
2999% -------------------------------------------------------------------------
3000[xOut, uOut, info] = ...
3001        ckbs_affine(max_itr, epsilon, z, b, g, h, db, dg, dh, qinv, rinv);
3002% --------------------------------------------------------------------------
3003ok   = ok &amp; all( info(end, 1:3) &lt;= epsilon);
3004d    = ckbs_sumsq_grad(xOut, z, g, h, dg, dh, qinv, rinv);
3005for k = 1 : N
3006        xk = xOut(:, k);
3007        uk = uOut(:, k);
3008        bk = b(:, k);
3009        Bk = db(:,:, k);
3010        dk = d(:, k);
3011        sk = - bk - Bk * xk;
3012        %
3013        ok = ok &amp; (min(uk) &gt;= 0.);
3014        ok = ok &amp; (max (bk + Bk * xk) &lt;= epsilon);
3015        ok = ok &amp; (max ( abs( Bk' * uk + dk ) ) &lt;= epsilon);
3016        ok = ok &amp; (max ( uk .* sk ) &lt;= epsilon );
3017end
3018if draw_plot
3019        figure(1);
3020        clf
3021        hold on
3022        plot(t', x_true(2,:)', 'r-' );
3023        plot(t', z(1,:)', 'ko' );
3024        plot(t', xOut(2,:)', 'b-' );
3025        plot(t', - ones(N,1), 'b-');
3026        plot(t', ones(N,1), 'b-');
3027        axis([h_min, h_max, v_min, v_max]);
3028        title('Constrained');
3029        hold off
3030        %
3031        % constrained estimate
3032        x_con = xOut;
3033end
3034%
3035% Unconstrained Case
3036b           = zeros(0, N);
3037db          = zeros(0, n, N);
3038% -------------------------------------------------------------------------
3039[xOut, uOut, info] = ...
3040        ckbs_affine(max_itr, epsilon, z, b, g, h, db, dg, dh, qinv, rinv);
3041% --------------------------------------------------------------------------
3042ok   = ok &amp; all( info(end, 1:3) &lt;= epsilon);
3043d    = ckbs_sumsq_grad(xOut, z, g, h, dg, dh, qinv, rinv);
3044for k = 1 : N
3045        xk = xOut(:, k);
3046        dk = d(:, k);
3047        %
3048        ok = ok &amp; (min(dk) &lt;= epsilon);
3049end
3050if draw_plot
3051        figure(2);
3052        clf
3053        hold on
3054        plot(t', x_true(2,:)', 'r-' );
3055        plot(t', z(1,:)', 'ko' );
3056        plot(t', xOut(2,:)', 'b-' );
3057        plot(t', - ones(N,1), 'b-');
3058        plot(t', ones(N,1), 'b-');
3059        axis([h_min, h_max, v_min, v_max]);
3060        title('Unconstrained');
3061        hold off
3062        %
3063        % unconstrained estimate
3064        x_free = xOut;
3065        %
3066        % write out constrained and unconstrained results
3067        [fid, msg] = fopen('affine_ok_box.out', 'wt');
3068        if size(msg, 2) &gt; 0
3069                disp(['affine_ok: ', msg]);
3070        end
3071        %                      123456789012345678901234'
3072        heading =             '       t';
3073        heading = [ heading , ' x2_true  x2_con x2_free' ];
3074        heading = [ heading , '      z1\n'               ];
3075        fprintf(fid, heading);
3076        for k = 1 : N
3077                fprintf(fid,'%8.3f%8.3f%8.3f%8.3f%8.3f\n', ...
3078                        t(k), ...
3079                        x_true(2,k), x_con(2,k), x_free(2,k), ...
3080                        z(1,k) ...
3081                );
3082        end
3083        fclose(fid);
3084end
3085return
3086end
3087</pre></font></code>
3088 
3089
3090<hr>Input File: test/affine_ok_box.m
3091
3092<hr>
3093
3094
3095
3096<center><b><big><big><a name="5" id="5">5: ckbs Utility Functions</a>
3097</big></big></b></center>
3098<br>
3099<b><big><a name="5.a" id="5.a">5.a: Contents</a></big></b>
3100<br>
3101<table>
3102<tr><td><a href="#5.1" target="_top">ckbs_blkdiag_mul:&nbsp;5.1</a></td><td>Packed&nbsp;Block&nbsp;Diagonal&nbsp;Matrix&nbsp;Times&nbsp;a&nbsp;Vector</td></tr><tr><td><a href="#5.2" target="_top">ckbs_blkdiag_mul_t:&nbsp;5.2</a></td><td>Transpose&nbsp;of&nbsp;Packed&nbsp;Block&nbsp;Diagonal&nbsp;Matrix&nbsp;Times&nbsp;a&nbsp;Vector</td></tr><tr><td><a href="#5.3" target="_top">ckbs_sumsq_obj:&nbsp;5.3</a></td><td>Affine&nbsp;Residual&nbsp;Sum&nbsp;of&nbsp;Squares&nbsp;Objective</td></tr><tr><td><a href="#5.4" target="_top">ckbs_sumsq_grad:&nbsp;5.4</a></td><td>Affine&nbsp;Residual&nbsp;Sum&nbsp;of&nbsp;Squares&nbsp;Gradient</td></tr><tr><td><a href="#5.5" target="_top">ckbs_sumsq_hes:&nbsp;5.5</a></td><td>Affine&nbsp;Residual&nbsp;Sum&nbsp;of&nbsp;Squares&nbsp;Hessian</td></tr><tr><td><a href="#5.6" target="_top">ckbs_tridiag_solve:&nbsp;5.6</a></td><td>Symmetric&nbsp;Block&nbsp;Tridiagonal&nbsp;Algorithm</td></tr><tr><td><a href="#5.7" target="_top">ckbs_newton_step:&nbsp;5.7</a></td><td>Affine&nbsp;Constrained&nbsp;Kalman&nbsp;Bucy&nbsp;Smoother&nbsp;Newton&nbsp;Step</td></tr><tr><td><a href="#5.8" target="_top">ckbs_kuhn_tucker:&nbsp;5.8</a></td><td>Compute&nbsp;Residual&nbsp;in&nbsp;Kuhn-Tucker&nbsp;Conditions</td></tr></table>
3103<hr>Input File: omh/utility.omh
3104
3105<hr>
3106<center><b><big><big><a name="5.1" id="5.1">5.1: Packed Block Diagonal Matrix Times a Vector</a>
3107</big></big></b></center>
3108<br>
3109<b><big><a name="5.1.a" id="5.1.a">5.1.a: Syntax</a></big></b>
3110
3111<br>
3112<code><font color="blue"><span style='white-space: nowrap'>[</span></font></code><i><span style='white-space: nowrap'>w</span></i><code><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;ckbs_blkdiag_mul(</span></font></code><i><span style='white-space: nowrap'>Bdia</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>v</span></i><code><font color="blue"><span style='white-space: nowrap'>)</span></font></code>
3113
3114<br>
3115<br>
3116<b><big><a name="5.1.b" id="5.1.b">5.1.b: Purpose</a></big></b>
3117<br>
3118This routine enables one to used the packed form of a block diagonal matrix
3119and returns the matrix times a vector; i.e.,
3120<code>
3121<span style='white-space: nowrap'>&nbsp;\[<br>
3122&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;w&nbsp;=&nbsp;B&nbsp;*&nbsp;v<br>
3123\]&nbsp;</span></code>
3124
3125
3126<br>
3127<br>
3128<b><big><a name="5.1.c" id="5.1.c">5.1.c: Bdia</a></big></b>
3129<br>
3130The argument <i>Bdia</i> is an <code>
3131<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
3132 array.
3133For <code>
3134<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3135 we define <code>
3136<span style='white-space: nowrap'>&nbsp;B_k&nbsp;\in&nbsp;\R^{m&nbsp;\times&nbsp;n}</span></code>
3137 by
3138<code>
3139<span style='white-space: nowrap'>&nbsp;\[<br>
3140&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;B_k&nbsp;=&nbsp;Bdia(:,&nbsp;:,&nbsp;k)<br>
3141\]&nbsp;</span></code>
3142
3143
3144<br>
3145<br>
3146<b><big><a name="5.1.d" id="5.1.d">5.1.d: B</a></big></b>
3147<br>
3148The matrix <code>
3149<span style='white-space: nowrap'>&nbsp;B</span></code>
3150 is defined by
3151<code>
3152<span style='white-space: nowrap'>&nbsp;\[<br>
3153B&nbsp;<br>
3154=<br>
3155\left(&nbsp;\begin{array}{cccc}<br>
3156&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;B_1&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
3157&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&amp;&nbsp;B_2&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
3158&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;\ddots&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
3159&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;B_N&nbsp;<br>
3160\end{array}&nbsp;\right)<br>
3161\]&nbsp;</span></code>
3162
3163
3164<br>
3165<br>
3166<b><big><a name="5.1.e" id="5.1.e">5.1.e: v</a></big></b>
3167<br>
3168The argument <i>v</i> is a column vector of length <code>
3169<span style='white-space: nowrap'>&nbsp;n&nbsp;*&nbsp;N</span></code>
3170.
3171
3172<br>
3173<br>
3174<b><big><a name="5.1.f" id="5.1.f">5.1.f: w</a></big></b>
3175<br>
3176The result <i>w</i> is a column vector of length <code>
3177<span style='white-space: nowrap'>&nbsp;m&nbsp;*&nbsp;N</span></code>
3178.
3179
3180
3181
3182
3183<br>
3184<br>
3185<b><big><a name="5.1.g" id="5.1.g">5.1.g: Example</a></big></b>
3186<br>
3187The file <a href="#5.1.1">5.1.1: <span style='white-space: nowrap'>blkdiag_mul_ok.m</span></a>
3188 contains an example and test of
3189<code><font color="blue">ckbs_blkdiag_mul</font></code>.
3190It returns true if <code><font color="blue">ckbs_blkdiag_mul</font></code> passes the test
3191and false otherwise.
3192
3193
3194<hr>Input File: src/ckbs_blkdiag_mul.m
3195
3196<hr>
3197 
3198
3199
3200<center><b><big><big><a name="5.1.1" id="5.1.1">5.1.1: blkdiag_mul Example and Test</a>
3201</big></big></b></center>
3202<br>
3203<b><big><a name="5.1.1.a" id="5.1.1.a">5.1.1.a: Source Code</a></big></b>
3204
3205 <code><font color='blue'><pre style='display:inline'> 
3206function [ok] = blkdiag_mul_ok()
3207ok = true;
3208% -------------------------------------------------------------
3209% You can change these parameters
3210m    = 2;
3211n    = 3;
3212N    = 2;
3213% -------------------------------------------------------------
3214% Define the problem
3215rand('seed', 123);
3216v     = rand(n * N, 1);
3217Bdiag = zeros(m, n, N);
3218B     = zeros(m * N , n * N);
3219blk_m = 1 : m;
3220blk_n = 1 : n;
3221for k = 1 : N
3222        Bdiag(:, :, k)  = rand(m, n);
3223        B(blk_m, blk_n) = Bdiag(:, :, k);
3224        blk_m           = blk_m + m;
3225        blk_n           = blk_n + n;
3226end
3227% -------------------------------------
3228w     = ckbs_blkdiag_mul(Bdiag, v);
3229% -------------------------------------
3230check = B * v;
3231ok    = ok &amp; ( max(abs(w - check)) &lt; 1e-10 );
3232return
3233end
3234</pre></font></code>
3235 
3236
3237<hr>Input File: test/blkdiag_mul_ok.m
3238
3239<hr>
3240 
3241
3242
3243<center><b><big><big><a name="5.2" id="5.2">5.2: Transpose of Packed Block Diagonal Matrix Times a Vector</a>
3244</big></big></b></center>
3245<br>
3246<b><big><a name="5.2.a" id="5.2.a">5.2.a: Syntax</a></big></b>
3247
3248<br>
3249<code><font color="blue"><span style='white-space: nowrap'>[</span></font></code><i><span style='white-space: nowrap'>w</span></i><code><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;ckbs_blkdiag_mul_t(</span></font></code><i><span style='white-space: nowrap'>Bdia</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>v</span></i><code><font color="blue"><span style='white-space: nowrap'>)</span></font></code>
3250
3251<br>
3252<br>
3253<b><big><a name="5.2.b" id="5.2.b">5.2.b: Purpose</a></big></b>
3254<br>
3255This routine enables one to used the packed form of a block diagonal matrix
3256and returns the transpose of the matrix times a vector; i.e.,
3257<code>
3258<span style='white-space: nowrap'>&nbsp;\[<br>
3259&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;w&nbsp;=&nbsp;B^\T&nbsp;*&nbsp;v<br>
3260\]&nbsp;</span></code>
3261
3262
3263<br>
3264<br>
3265<b><big><a name="5.2.c" id="5.2.c">5.2.c: Bdia</a></big></b>
3266<br>
3267The argument <i>Bdia</i> is an <code>
3268<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
3269 array.
3270For <code>
3271<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3272 we define <code>
3273<span style='white-space: nowrap'>&nbsp;B_k&nbsp;\in&nbsp;\R^{m&nbsp;\times&nbsp;n}</span></code>
3274 by
3275<code>
3276<span style='white-space: nowrap'>&nbsp;\[<br>
3277&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;B_k&nbsp;=&nbsp;Bdia(:,&nbsp;:,&nbsp;k)<br>
3278\]&nbsp;</span></code>
3279
3280
3281<br>
3282<br>
3283<b><big><a name="5.2.d" id="5.2.d">5.2.d: B</a></big></b>
3284<br>
3285The matrix <code>
3286<span style='white-space: nowrap'>&nbsp;B</span></code>
3287 is defined by
3288<code>
3289<span style='white-space: nowrap'>&nbsp;\[<br>
3290B&nbsp;<br>
3291=<br>
3292\left(&nbsp;\begin{array}{cccc}<br>
3293&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;B_1&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
3294&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&amp;&nbsp;B_2&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
3295&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;0&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;\ddots&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
3296&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;B_N&nbsp;<br>
3297\end{array}&nbsp;\right)<br>
3298\]&nbsp;</span></code>
3299
3300
3301<br>
3302<br>
3303<b><big><a name="5.2.e" id="5.2.e">5.2.e: v</a></big></b>
3304<br>
3305The argument <i>v</i> is a column vector of length <code>
3306<span style='white-space: nowrap'>&nbsp;m&nbsp;*&nbsp;N</span></code>
3307.
3308
3309<br>
3310<br>
3311<b><big><a name="5.2.f" id="5.2.f">5.2.f: w</a></big></b>
3312<br>
3313The result <i>w</i> is a column vector of length <code>
3314<span style='white-space: nowrap'>&nbsp;n&nbsp;*&nbsp;N</span></code>
3315.
3316
3317
3318
3319<br>
3320<br>
3321<b><big><a name="5.2.g" id="5.2.g">5.2.g: Example</a></big></b>
3322<br>
3323The file <a href="#5.2.1">5.2.1: <span style='white-space: nowrap'>blkdiag_mul_t_ok.m</span></a>
3324 contains an example and test of
3325<code><font color="blue">ckbs_blkdiag_mul_t</font></code>.
3326It returns true if <code><font color="blue">ckbs_blkdiag_mul_t</font></code> passes the test
3327and false otherwise.
3328
3329
3330<hr>Input File: src/ckbs_blkdiag_mul_t.m
3331
3332<hr>
3333 
3334
3335
3336<center><b><big><big><a name="5.2.1" id="5.2.1">5.2.1: blkdiag_mul_t Example and Test</a>
3337</big></big></b></center>
3338<br>
3339<b><big><a name="5.2.1.a" id="5.2.1.a">5.2.1.a: Source Code</a></big></b>
3340
3341 <code><font color='blue'><pre style='display:inline'> 
3342function [ok] = blkdiag_mul_t_ok()
3343ok = true;
3344% -------------------------------------------------------------
3345% You can change these parameters
3346m    = 2;
3347n    = 3;
3348N    = 2;
3349% -------------------------------------------------------------
3350% Define the problem
3351rand('seed', 123);
3352v     = rand(m * N, 1);
3353Bdiag = zeros(m, n, N);
3354B     = zeros(m * N , n * N);
3355blk_m = 1 : m;
3356blk_n = 1 : n;
3357for k = 1 : N
3358        Bdiag(:, :, k)  = rand(m, n);
3359        B(blk_m, blk_n) = Bdiag(:, :, k);
3360        blk_m           = blk_m + m;
3361        blk_n           = blk_n + n;
3362end
3363% -------------------------------------
3364w     = ckbs_blkdiag_mul_t(Bdiag, v);
3365% -------------------------------------
3366check = B' * v;
3367ok    = ok &amp; ( max(abs(w - check)) &lt; 1e-10 );
3368return
3369end
3370</pre></font></code>
3371 
3372
3373<hr>Input File: test/blkdiag_mul_t_ok.m
3374
3375<hr>
3376 
3377
3378
3379<center><b><big><big><a name="5.3" id="5.3">5.3: Affine Residual Sum of Squares Objective</a>
3380</big></big></b></center>
3381<br>
3382<b><big><a name="5.3.a" id="5.3.a">5.3.a: Syntax</a></big></b>
3383
3384<br>
3385<code><font color="blue"><span style='white-space: nowrap'>[</span></font></code><i><span style='white-space: nowrap'>obj</span></i><code><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;ckbs_sumsq_obj(</span></font></code><i><span style='white-space: nowrap'>x</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>z</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>g</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>h</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>dg</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>dh</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>qinv</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>rinv</span></i><code><font color="blue"><span style='white-space: nowrap'>)</span></font></code>
3386
3387<br>
3388<br>
3389<b><big><a name="5.3.b" id="5.3.b">5.3.b: Purpose</a></big></b>
3390<br>
3391This routine computes the value of the
3392affine Kalman-Bucy smoother residual sum of squares objective function.
3393
3394<br>
3395<br>
3396<b><big><a name="5.3.c" id="5.3.c">5.3.c: Notation</a></big></b>
3397<br>
3398The affine Kalman-Bucy smoother residual sum of squares is defined by
3399<code>
3400<span style='white-space: nowrap'>&nbsp;\[<br>
3401\begin{array}{rcl}<br>
3402S&nbsp;(&nbsp;x_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N&nbsp;)&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;\sum_{k=1}^N&nbsp;S_k&nbsp;(&nbsp;x_k&nbsp;,&nbsp;x_{k-1}&nbsp;)&nbsp;\\<br>
3403S_k&nbsp;(&nbsp;x_k&nbsp;,&nbsp;x_{k-1}&nbsp;)&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;<br>
3404\frac{1}{2}&nbsp;<br>
3405(&nbsp;z_k&nbsp;-&nbsp;h_k&nbsp;-&nbsp;H_k&nbsp;*&nbsp;x_k&nbsp;)^\T&nbsp;*&nbsp;R_k^{-1}&nbsp;*&nbsp;(&nbsp;z_k&nbsp;-&nbsp;h_k&nbsp;-&nbsp;H_k&nbsp;*&nbsp;x_k&nbsp;)<br>
3406\\<br>
3407&amp;&nbsp;+&nbsp;&amp;<br>
3408\frac{1}{2}&nbsp;<br>
3409(&nbsp;x_k&nbsp;-&nbsp;g_k&nbsp;-&nbsp;G_k&nbsp;*&nbsp;x_{k-1}&nbsp;)^\T&nbsp;*&nbsp;Q_k^{-1}&nbsp;*&nbsp;(&nbsp;x_k&nbsp;-&nbsp;g_k&nbsp;-&nbsp;G_k&nbsp;*&nbsp;x_{k-1}&nbsp;)<br>
3410\\<br>
3411\end{array}<br>
3412\]&nbsp;</span></code>
3413
3414where the matrices <code>
3415<span style='white-space: nowrap'>&nbsp;R_k</span></code>
3416 and <code>
3417<span style='white-space: nowrap'>&nbsp;Q_k</span></code>
3418 are
3419symmetric positive definite and
3420<code>
3421<span style='white-space: nowrap'>&nbsp;x_0</span></code>
3422 is the constant zero.
3423
3424<br>
3425<br>
3426<b><big><a name="5.3.d" id="5.3.d">5.3.d: x</a></big></b>
3427<br>
3428The argument <i>x</i> is a two dimensional array,
3429for <code>
3430<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3431
3432<code>
3433<span style='white-space: nowrap'>&nbsp;\[<br>
3434&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x_k&nbsp;=&nbsp;x(:,&nbsp;k)<br>
3435\]</span></code>
3436
3437and <i>x</i> has size <code>
3438<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;N</span></code>
3439.
3440
3441<br>
3442<br>
3443<b><big><a name="5.3.e" id="5.3.e">5.3.e: z</a></big></b>
3444<br>
3445The argument <i>z</i> is a two dimensional array,
3446for <code>
3447<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3448
3449<code>
3450<span style='white-space: nowrap'>&nbsp;\[<br>
3451&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;z_k&nbsp;=&nbsp;z(:,&nbsp;k)<br>
3452\]</span></code>
3453
3454and <i>z</i> has size <code>
3455<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;N</span></code>
3456.
3457
3458<br>
3459<br>
3460<b><big><a name="5.3.f" id="5.3.f">5.3.f: g</a></big></b>
3461<br>
3462The argument <i>g</i> is a two dimensional array,
3463for <code>
3464<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3465
3466<code>
3467<span style='white-space: nowrap'>&nbsp;\[<br>
3468&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;g_k&nbsp;=&nbsp;g(:,&nbsp;k)<br>
3469\]</span></code>
3470
3471and <i>g</i> has size <code>
3472<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;N</span></code>
3473.
3474
3475<br>
3476<br>
3477<b><big><a name="5.3.g" id="5.3.g">5.3.g: h</a></big></b>
3478<br>
3479The argument <i>h</i> is a two dimensional array,
3480for <code>
3481<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3482
3483<code>
3484<span style='white-space: nowrap'>&nbsp;\[<br>
3485&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;h_k&nbsp;=&nbsp;h(:,&nbsp;k)<br>
3486\]</span></code>
3487
3488and <i>h</i> has size <code>
3489<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;N</span></code>
3490.
3491
3492<br>
3493<br>
3494<b><big><a name="5.3.h" id="5.3.h">5.3.h: dg</a></big></b>
3495<br>
3496The argument <i>dg</i> is a three dimensional array,
3497for <code>
3498<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3499
3500<code>
3501<span style='white-space: nowrap'>&nbsp;\[<br>
3502&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;G_k&nbsp;=&nbsp;dg(:,:,k)<br>
3503\]</span></code>
3504
3505and <i>dg</i> has size <code>
3506<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
3507.
3508
3509<br>
3510<br>
3511<b><big><a name="5.3.i" id="5.3.i">5.3.i: dh</a></big></b>
3512<br>
3513The argument <i>dh</i> is a three dimensional array,
3514for <code>
3515<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3516
3517<code>
3518<span style='white-space: nowrap'>&nbsp;\[<br>
3519&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;H_k&nbsp;=&nbsp;dh(:,:,k)<br>
3520\]</span></code>
3521
3522and <i>dh</i> has size <code>
3523<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
3524.
3525
3526<br>
3527<br>
3528<b><big><a name="5.3.j" id="5.3.j">5.3.j: qinv</a></big></b>
3529<br>
3530The argument <i>qinv</i> is a three dimensional array,
3531for <code>
3532<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3533
3534<code>
3535<span style='white-space: nowrap'>&nbsp;\[<br>
3536&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Q_k^{-1}&nbsp;=&nbsp;qinv(:,:,&nbsp;k)<br>
3537\]</span></code>
3538
3539and <i>qinv</i> has size <code>
3540<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
3541.
3542
3543<br>
3544<br>
3545<b><big><a name="5.3.k" id="5.3.k">5.3.k: rinv</a></big></b>
3546<br>
3547The argument <i>rinv</i> is a three dimensional array,
3548for <code>
3549<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3550
3551<code>
3552<span style='white-space: nowrap'>&nbsp;\[<br>
3553&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;R_k^{-1}&nbsp;=&nbsp;rinv(:,:,&nbsp;k)<br>
3554\]</span></code>
3555
3556and <i>rinv</i> has size <code>
3557<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;m&nbsp;\times&nbsp;N</span></code>
3558.
3559
3560<br>
3561<br>
3562<b><big><a name="5.3.l" id="5.3.l">5.3.l: obj</a></big></b>
3563<br>
3564The result <i>obj</i> is a scalar given by
3565<code>
3566<span style='white-space: nowrap'>&nbsp;\[<br>
3567&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;obj&nbsp;=&nbsp;S&nbsp;(&nbsp;x_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N&nbsp;)<br>
3568\]&nbsp;</span></code>
3569
3570
3571
3572
3573<br>
3574<br>
3575<b><big><a name="5.3.m" id="5.3.m">5.3.m: Example</a></big></b>
3576<br>
3577The file <a href="#5.3.1">5.3.1: <span style='white-space: nowrap'>sumsq_obj_ok.m</span></a>
3578 contains an example and test of
3579<code><font color="blue">ckbs_sumsq_obj</font></code>.
3580It returns true if <code><font color="blue">ckbs_sumsq_obj</font></code> passes the test
3581and false otherwise.
3582
3583
3584<hr>Input File: src/ckbs_sumsq_obj.m
3585
3586<hr>
3587 
3588
3589
3590<center><b><big><big><a name="5.3.1" id="5.3.1">5.3.1: ckbs_sumsq_obj Example and Test</a>
3591</big></big></b></center>
3592<br>
3593<b><big><a name="5.3.1.a" id="5.3.1.a">5.3.1.a: Source Code</a></big></b>
3594
3595 <code><font color='blue'><pre style='display:inline'> 
3596function [ok] = sumsq_obj_ok()
3597ok = true;
3598% --------------------------------------------------------
3599% You can change these parameters
3600m    = 1;   % number of measurements per time point
3601n    = 2;   % number of state vector components per time point
3602N    = 3;   % number of time points
3603% ---------------------------------------------------------
3604%  Define the problem
3605rand('seed', 123);
3606x    = rand(n, N);
3607z    = rand(m, N);
3608h    = rand(m, N);
3609g    = rand(n, N);
3610dh   = zeros(m, n, N);
3611dg   = zeros(n, n, N);
3612qinv = zeros(n, n, N);
3613rinv = zeros(m, m, N);
3614for k = 1 : N
3615        dh(:, :, k)   = rand(m, n);
3616        dg(:, :, k)   = rand(n, n);
3617        tmp           = rand(m, m);
3618        rinv(:, :, k) = (tmp + tmp') / 2 + 2 * eye(m);
3619        tmp           = rand(n, n);
3620        qinv(:, :, k) = (tmp + tmp') / 2 + 2 * eye(n);
3621end
3622% ---------------------------------------------------------
3623% Compute the Objective using ckbs_sumsq_obj
3624obj  = ckbs_sumsq_obj(x, z, g, h, dg, dh, qinv, rinv);
3625% ---------------------------------------------------------
3626sumsq = 0;
3627xk    = zeros(n, 1);
3628for k = 1 : N
3629        xkm   = xk;
3630        xk    = x(:, k);
3631        xres  = xk      - g(:, k) - dg(:,:, k) * xkm;
3632        zres  = z(:, k) - h(:, k) - dh(:,:, k) * xk;
3633        sumsq = sumsq + xres' * qinv(:,:, k) * xres;
3634        sumsq = sumsq + zres' * rinv(:,:, k) * zres;
3635end
3636ok = ok &amp; ( abs(obj - sumsq/2) &lt; 1e-10 );
3637return
3638end
3639</pre></font></code>
3640 
3641
3642<hr>Input File: test/sumsq_obj_ok.m
3643
3644<hr>
3645 
3646
3647
3648<center><b><big><big><a name="5.4" id="5.4">5.4: Affine Residual Sum of Squares Gradient</a>
3649</big></big></b></center>
3650<br>
3651<b><big><a name="5.4.a" id="5.4.a">5.4.a: Syntax</a></big></b>
3652
3653<br>
3654<code><font color="blue"><span style='white-space: nowrap'>[</span></font></code><i><span style='white-space: nowrap'>grad</span></i><code><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;ckbs_sumsq_grad(</span></font></code><i><span style='white-space: nowrap'>x</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>z</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>g</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>h</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>dg</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>dh</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>qinv</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>rinv</span></i><code><font color="blue"><span style='white-space: nowrap'>)</span></font></code>
3655
3656<br>
3657<br>
3658<b><big><a name="5.4.b" id="5.4.b">5.4.b: Purpose</a></big></b>
3659<br>
3660This computes the gradient of the
3661of the affine Kalman-Bucy smoother residual sum of squares.
3662
3663<br>
3664<br>
3665<b><big><a name="5.4.c" id="5.4.c">5.4.c: Notation</a></big></b>
3666<br>
3667The affine Kalman-Bucy smoother residual sum of squares is defined by
3668<code>
3669<span style='white-space: nowrap'>&nbsp;\[<br>
3670\begin{array}{rcl}<br>
3671S&nbsp;(&nbsp;x_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N&nbsp;)&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;\sum_{k=1}^N&nbsp;S_k&nbsp;(&nbsp;x_k&nbsp;,&nbsp;x_{k-1}&nbsp;)&nbsp;\\<br>
3672S_k&nbsp;(&nbsp;x_k&nbsp;,&nbsp;x_{k-1}&nbsp;)&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;<br>
3673\frac{1}{2}&nbsp;<br>
3674(&nbsp;z_k&nbsp;-&nbsp;h_k&nbsp;-&nbsp;H_k&nbsp;*&nbsp;x_k&nbsp;)^\T&nbsp;*&nbsp;R_k^{-1}&nbsp;*&nbsp;(&nbsp;z_k&nbsp;-&nbsp;h_k&nbsp;-&nbsp;H_k&nbsp;*&nbsp;x_k&nbsp;)<br>
3675\\<br>
3676&amp;&nbsp;+&nbsp;&amp;<br>
3677\frac{1}{2}&nbsp;<br>
3678(&nbsp;x_k&nbsp;-&nbsp;g_k&nbsp;-&nbsp;G_k&nbsp;*&nbsp;x_{k-1}&nbsp;)^\T&nbsp;*&nbsp;Q_k^{-1}&nbsp;*&nbsp;(&nbsp;x_k&nbsp;-&nbsp;g_k&nbsp;-&nbsp;G_k&nbsp;*&nbsp;x_{k-1}&nbsp;)<br>
3679\end{array}<br>
3680\]&nbsp;</span></code>
3681
3682where the matrices <code>
3683<span style='white-space: nowrap'>&nbsp;R_k</span></code>
3684 and <code>
3685<span style='white-space: nowrap'>&nbsp;Q_k</span></code>
3686 are
3687symmetric positive definite and
3688<code>
3689<span style='white-space: nowrap'>&nbsp;x_0</span></code>
3690 is the constant zero.
3691
3692<br>
3693<br>
3694<b><big><a name="5.4.d" id="5.4.d">5.4.d: Gradient</a></big></b>
3695<br>
3696We define <code>
3697<span style='white-space: nowrap'>&nbsp;Q_{N+1}</span></code>
3698 to be the <code>
3699<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n</span></code>
3700 identity
3701matrix and <code>
3702<span style='white-space: nowrap'>&nbsp;G_{N+1}</span></code>
3703 to be zero,
3704<code>
3705<span style='white-space: nowrap'>&nbsp;\[<br>
3706\begin{array}{rcl}<br>
3707\nabla_k&nbsp;S_k^{(1)}&nbsp;(&nbsp;x_k&nbsp;,&nbsp;x_{k-1}&nbsp;)&nbsp;<br>
3708&amp;&nbsp;=&nbsp;&amp;&nbsp;&nbsp;H_k^\T&nbsp;*&nbsp;R_k^{-1}&nbsp;*&nbsp;(&nbsp;h_k&nbsp;+&nbsp;H_k&nbsp;*&nbsp;x_k&nbsp;-&nbsp;z_k&nbsp;)&nbsp;<br>
3709&nbsp;&nbsp;+&nbsp;&nbsp;&nbsp;&nbsp;Q_k^{-1}&nbsp;*&nbsp;(&nbsp;x_k&nbsp;-&nbsp;g_k&nbsp;-&nbsp;G_k&nbsp;*&nbsp;x_{k-1}&nbsp;)<br>
3710\\<br>
3711\nabla_k&nbsp;S_{k+1}^{(1)}&nbsp;(&nbsp;x_{k+1}&nbsp;,&nbsp;x_k&nbsp;)&nbsp;<br>
3712&amp;&nbsp;=&nbsp;&amp;&nbsp;G_{k+1}^\T&nbsp;*&nbsp;Q_{k+1}^{-1}&nbsp;*&nbsp;(&nbsp;g_{k+1}&nbsp;+&nbsp;G_{k+1}&nbsp;*&nbsp;x_k&nbsp;&nbsp;-&nbsp;x_{k+1}&nbsp;)<br>
3713\end{array}<br>
3714\]&nbsp;</span></code>
3715
3716It follows that the gradient of the
3717affine Kalman-Bucy smoother residual sum of squares is
3718<code>
3719<span style='white-space: nowrap'>&nbsp;\[<br>
3720\begin{array}{rcl}<br>
3721\nabla&nbsp;S&nbsp;(&nbsp;x_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N&nbsp;)&nbsp;<br>
3722&amp;&nbsp;=&nbsp;&amp;<br>
3723\left(&nbsp;\begin{array}{c}<br>
3724&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;d_1&nbsp;\\&nbsp;\vdots&nbsp;\\&nbsp;d_N<br>
3725\end{array}&nbsp;\right)<br>
3726\\<br>
3727d_k&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;\nabla_k&nbsp;S_k^{(1)}&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;(&nbsp;x_k&nbsp;,&nbsp;x_{k-1}&nbsp;)&nbsp;<br>
3728&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;+&nbsp;&nbsp;&nbsp;\nabla_k&nbsp;S_{k+1}^{(1)}&nbsp;(&nbsp;x_{k+1}&nbsp;,&nbsp;x_k&nbsp;)<br>
3729\end{array}<br>
3730\]&nbsp;</span></code>
3731
3732where <code>
3733<span style='white-space: nowrap'>&nbsp;S_{N+1}&nbsp;(&nbsp;x_{N+1}&nbsp;,&nbsp;x_N&nbsp;)</span></code>
3734 is defined as
3735identically zero.
3736
3737<br>
3738<br>
3739<b><big><a name="5.4.e" id="5.4.e">5.4.e: x</a></big></b>
3740<br>
3741The argument <i>x</i> is a two dimensional array,
3742for <code>
3743<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3744
3745<code>
3746<span style='white-space: nowrap'>&nbsp;\[<br>
3747&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;x_k&nbsp;=&nbsp;x(:,&nbsp;k)<br>
3748\]</span></code>
3749
3750and <i>x</i> has size <code>
3751<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;N</span></code>
3752.
3753
3754<br>
3755<br>
3756<b><big><a name="5.4.f" id="5.4.f">5.4.f: z</a></big></b>
3757<br>
3758The argument <i>z</i> is a two dimensional array,
3759for <code>
3760<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3761
3762<code>
3763<span style='white-space: nowrap'>&nbsp;\[<br>
3764&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;z_k&nbsp;=&nbsp;z(:,&nbsp;k)<br>
3765\]</span></code>
3766
3767and <i>z</i> has size <code>
3768<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;N</span></code>
3769.
3770
3771<br>
3772<br>
3773<b><big><a name="5.4.g" id="5.4.g">5.4.g: g</a></big></b>
3774<br>
3775The argument <i>g</i> is a two dimensional array,
3776for <code>
3777<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3778
3779<code>
3780<span style='white-space: nowrap'>&nbsp;\[<br>
3781&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;g_k&nbsp;=&nbsp;g(:,&nbsp;k)<br>
3782\]</span></code>
3783
3784and <i>g</i> has size <code>
3785<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;N</span></code>
3786.
3787
3788<br>
3789<br>
3790<b><big><a name="5.4.h" id="5.4.h">5.4.h: h</a></big></b>
3791<br>
3792The argument <i>h</i> is a two dimensional array,
3793for <code>
3794<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3795
3796<code>
3797<span style='white-space: nowrap'>&nbsp;\[<br>
3798&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;h_k&nbsp;=&nbsp;h(:,&nbsp;k)<br>
3799\]</span></code>
3800
3801and <i>h</i> has size <code>
3802<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;N</span></code>
3803.
3804
3805<br>
3806<br>
3807<b><big><a name="5.4.i" id="5.4.i">5.4.i: dg</a></big></b>
3808<br>
3809The argument <i>dg</i> is a three dimensional array,
3810for <code>
3811<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3812
3813<code>
3814<span style='white-space: nowrap'>&nbsp;\[<br>
3815&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;G_k&nbsp;=&nbsp;dg(:,:,k)<br>
3816\]</span></code>
3817
3818and <i>dg</i> has size <code>
3819<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
3820.
3821
3822<br>
3823<br>
3824<b><big><a name="5.4.j" id="5.4.j">5.4.j: dh</a></big></b>
3825<br>
3826The argument <i>dh</i> is a three dimensional array,
3827for <code>
3828<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3829
3830<code>
3831<span style='white-space: nowrap'>&nbsp;\[<br>
3832&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;H_k&nbsp;=&nbsp;dh(:,:,k)<br>
3833\]</span></code>
3834
3835and <i>dh</i> has size <code>
3836<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
3837.
3838
3839<br>
3840<br>
3841<b><big><a name="5.4.k" id="5.4.k">5.4.k: qinv</a></big></b>
3842<br>
3843The argument <i>qinv</i> is a three dimensional array,
3844for <code>
3845<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3846
3847<code>
3848<span style='white-space: nowrap'>&nbsp;\[<br>
3849&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Q_k^{-1}&nbsp;=&nbsp;qinv(:,:,k)<br>
3850\]</span></code>
3851
3852and <i>qinv</i> has size <code>
3853<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
3854.
3855
3856<br>
3857<br>
3858<b><big><a name="5.4.l" id="5.4.l">5.4.l: rinv</a></big></b>
3859<br>
3860The argument <i>rinv</i> is a three dimensional array,
3861for <code>
3862<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3863
3864<code>
3865<span style='white-space: nowrap'>&nbsp;\[<br>
3866&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;R_k^{-1}&nbsp;=&nbsp;rinv(:,:,k)<br>
3867\]</span></code>
3868
3869and <i>rinv</i> has size <code>
3870<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;m&nbsp;\times&nbsp;N</span></code>
3871.
3872
3873<br>
3874<br>
3875<b><big><a name="5.4.m" id="5.4.m">5.4.m: grad</a></big></b>
3876<br>
3877The result <i>grad</i> is a two dimensional array,
3878for <code>
3879<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
3880
3881<code>
3882<span style='white-space: nowrap'>&nbsp;\[<br>
3883&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;d_k&nbsp;=&nbsp;grad(:,&nbsp;k)<br>
3884\]</span></code>
3885
3886and <i>grad</i> has size <code>
3887<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;N</span></code>
3888.
3889
3890
3891
3892<br>
3893<br>
3894<b><big><a name="5.4.n" id="5.4.n">5.4.n: Example</a></big></b>
3895<br>
3896The file <a href="#5.4.1">5.4.1: <span style='white-space: nowrap'>sumsq_grad_ok.m</span></a>
3897 contains an example and test of
3898<code><font color="blue">ckbs_sumsq_grad</font></code>.
3899It returns true if <code><font color="blue">ckbs_sumsq_grad</font></code> passes the test
3900and false otherwise.
3901
3902
3903<hr>Input File: src/ckbs_sumsq_grad.m
3904
3905<hr>
3906 
3907
3908
3909<center><b><big><big><a name="5.4.1" id="5.4.1">5.4.1: ckbs_sumsq_grad Example and Test</a>
3910</big></big></b></center>
3911<br>
3912<b><big><a name="5.4.1.a" id="5.4.1.a">5.4.1.a: Source Code</a></big></b>
3913
3914 <code><font color='blue'><pre style='display:inline'> 
3915function [ok] = sumsq_grad_ok()
3916ok = true;
3917% --------------------------------------------------------
3918% You can change these parameters
3919m    = 1;   % number of measurements per time point
3920n    = 2;   % number of state vector components per time point
3921N    = 3;   % number of time points
3922% ---------------------------------------------------------
3923%  Define the problem
3924rand('seed', 123);
3925x    = rand(n, N);
3926z    = rand(m, N);
3927h    = rand(m, N);
3928g    = rand(n, N);
3929dg   = zeros(n, n, N);
3930dh   = zeros(m, n, N);
3931qinv = zeros(n, n, N);
3932rinv = zeros(m, m, N);
3933for k = 1 : N
3934        dh(:, :, k)   = rand(m, n);
3935        dg(:, :, k)   = rand(n, n);
3936        tmp           = rand(m, m);
3937        rinv(:, :, k) = (tmp + tmp') / 2 + 2 * eye(m);
3938        tmp           = rand(n, n);
3939        qinv(:, :, k) = (tmp + tmp') / 2 + 2 * eye(n);
3940end
3941% ---------------------------------------------------------
3942% Compute the gradient using ckbs_sumsq_grad
3943grad = ckbs_sumsq_grad(x, z, g, h, dg, dh, qinv, rinv);
3944% ---------------------------------------------------------
3945% Use finite differences to check gradient
3946step   = 1;
3947for k  = 1 : N
3948for i  = 1 : n
3949        % Check second partial w.r.t x(i,k)
3950        xm        = x;
3951        xm(i, k)  = xm(i, k) - step;
3952        Sm        = ckbs_sumsq_obj(xm, z, g, h, dg, dh, qinv, rinv);
3953        %
3954        xp        = x;
3955        xp(i, k)  = xp(i, k) + step;
3956        Sp        = ckbs_sumsq_obj(xp, z, g, h, dg, dh, qinv, rinv);
3957        %
3958        check  = (Sp - Sm) / ( 2 * step);
3959        diff   = grad(i, k) - check;
3960        ok     = ok &amp; ( abs(diff) &lt; 1e-10 );
3961end
3962end
3963return
3964end
3965</pre></font></code>
3966 
3967
3968<hr>Input File: test/sumsq_grad_ok.m
3969
3970<hr>
3971 
3972
3973
3974<center><b><big><big><a name="5.5" id="5.5">5.5: Affine Residual Sum of Squares Hessian</a>
3975</big></big></b></center>
3976<br>
3977<b><big><a name="5.5.a" id="5.5.a">5.5.a: Syntax</a></big></b>
3978
3979<br>
3980<code><font color="blue"><span style='white-space: nowrap'>[</span></font></code><i><span style='white-space: nowrap'>D</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>A</span></i><code><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;ckbs_sumsq_hes(</span></font></code><i><span style='white-space: nowrap'>dg</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>dh</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>qinv</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>rinv</span></i><code><font color="blue"><span style='white-space: nowrap'>)</span></font></code>
3981
3982<br>
3983<br>
3984<b><big><a name="5.5.b" id="5.5.b">5.5.b: Purpose</a></big></b>
3985<br>
3986This routine returns the diagonal and off diagonal blocks corresponding to
3987the Hessian of the affine Kalman-Bucy smoother residual sum of squares.
3988
3989<br>
3990<br>
3991<b><big><a name="5.5.c" id="5.5.c">5.5.c: Notation</a></big></b>
3992<br>
3993The affine Kalman-Bucy smoother residual sum of squares is defined by
3994<code>
3995<span style='white-space: nowrap'>&nbsp;\[<br>
3996\begin{array}{rcl}<br>
3997S&nbsp;(&nbsp;x_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N&nbsp;)&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;\sum_{k=1}^N&nbsp;S_k&nbsp;(&nbsp;x_k&nbsp;,&nbsp;x_{k-1}&nbsp;)&nbsp;\\<br>
3998S_k&nbsp;(&nbsp;x_k&nbsp;,&nbsp;x_{k-1}&nbsp;)&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;<br>
3999\frac{1}{2}&nbsp;<br>
4000(&nbsp;z_k&nbsp;-&nbsp;h_k&nbsp;-&nbsp;H_k&nbsp;*&nbsp;x_k&nbsp;)^\T&nbsp;*&nbsp;R_k^{-1}&nbsp;*&nbsp;(&nbsp;z_k&nbsp;-&nbsp;h_k&nbsp;-&nbsp;H_k&nbsp;*&nbsp;x_k&nbsp;)<br>
4001\\<br>
4002&amp;&nbsp;+&nbsp;&amp;<br>
4003\frac{1}{2}&nbsp;<br>
4004(&nbsp;x_k&nbsp;-&nbsp;g_k&nbsp;-&nbsp;G_k&nbsp;*&nbsp;x_{k-1}&nbsp;)^\T&nbsp;*&nbsp;Q_k^{-1}&nbsp;*&nbsp;(&nbsp;x_k&nbsp;-&nbsp;g_k&nbsp;-&nbsp;G_k&nbsp;*&nbsp;x_{k-1}&nbsp;)<br>
4005\end{array}<br>
4006\]&nbsp;</span></code>
4007
4008where the matrices <code>
4009<span style='white-space: nowrap'>&nbsp;R_k</span></code>
4010 and <code>
4011<span style='white-space: nowrap'>&nbsp;Q_k</span></code>
4012 are
4013symmetric positive definite and
4014<code>
4015<span style='white-space: nowrap'>&nbsp;x_0</span></code>
4016 is the constant zero.
4017
4018<br>
4019<br>
4020<b><big><a name="5.5.d" id="5.5.d">5.5.d: Hessian</a></big></b>
4021<br>
4022If we define <code>
4023<span style='white-space: nowrap'>&nbsp;Q_{N+1}</span></code>
4024 to be the <code>
4025<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n</span></code>
4026 identity
4027matrix and <code>
4028<span style='white-space: nowrap'>&nbsp;G_{N+1}</span></code>
4029 to be zero,
4030the Hessian of the
4031affine Kalman-Bucy smoother residual sum of squares is
4032<code>
4033<span style='white-space: nowrap'>&nbsp;\[<br>
4034\begin{array}{rcl}<br>
4035S^{(2)}&nbsp;(&nbsp;x_1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;x_N&nbsp;)&nbsp;&amp;&nbsp;=&nbsp;&amp;<br>
4036\left(&nbsp;\begin{array}{cccc}<br>
4037D_1&nbsp;&amp;&nbsp;A_2^\T&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
4038A_2&nbsp;&amp;&nbsp;D_2&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;A_3^\T&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
40390&nbsp;&nbsp;&nbsp;&amp;&nbsp;\ddots&nbsp;&amp;&nbsp;\ddots&nbsp;&amp;&nbsp;\ddots&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
4040&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;A_N&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;D_N&nbsp;<br>
4041\end{array}&nbsp;\right)<br>
4042\\<br>
4043D_k&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;H_k^\T&nbsp;*&nbsp;R_k^{-1}&nbsp;*&nbsp;H_k&nbsp;+&nbsp;Q_k^{-1}&nbsp;<br>
4044&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;+&nbsp;G_{k+1}^\T&nbsp;*&nbsp;Q_{k+1}^{-1}&nbsp;*&nbsp;G_{k+1}&nbsp;<br>
4045\\<br>
4046A_k&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;-&nbsp;Q_k^{-1}&nbsp;*&nbsp;G_k<br>
4047\end{array}<br>
4048\]&nbsp;</span></code>
4049
4050
4051<br>
4052<br>
4053<b><big><a name="5.5.e" id="5.5.e">5.5.e: dg</a></big></b>
4054<br>
4055The argument <i>dg</i> is a three dimensional array,
4056for <code>
4057<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
4058
4059<code>
4060<span style='white-space: nowrap'>&nbsp;\[<br>
4061&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;G_k&nbsp;=&nbsp;dg(:,:,k)<br>
4062\]</span></code>
4063
4064and <i>dg</i> has size <code>
4065<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
4066.
4067
4068<br>
4069<br>
4070<b><big><a name="5.5.f" id="5.5.f">5.5.f: dh</a></big></b>
4071<br>
4072The argument <i>dh</i> is a three dimensional array,
4073for <code>
4074<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
4075
4076<code>
4077<span style='white-space: nowrap'>&nbsp;\[<br>
4078&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;H_k&nbsp;=&nbsp;dh(:,:,k)<br>
4079\]</span></code>
4080
4081and <i>dh</i> has size <code>
4082<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
4083.
4084
4085<br>
4086<br>
4087<b><big><a name="5.5.g" id="5.5.g">5.5.g: qinv</a></big></b>
4088<br>
4089The argument <i>qinv</i> is a three dimensional array,
4090for <code>
4091<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
4092
4093<code>
4094<span style='white-space: nowrap'>&nbsp;\[<br>
4095&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Q_k^{-1}&nbsp;=&nbsp;qinv(:,:,k)<br>
4096\]</span></code>
4097
4098and <i>qinv</i> has size <code>
4099<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
4100.
4101
4102<br>
4103<br>
4104<b><big><a name="5.5.h" id="5.5.h">5.5.h: rinv</a></big></b>
4105<br>
4106The argument <i>rinv</i> is a three dimensional array,
4107for <code>
4108<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
4109
4110<code>
4111<span style='white-space: nowrap'>&nbsp;\[<br>
4112&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;R_k^{-1}&nbsp;=&nbsp;rinv(:,:,k)<br>
4113\]</span></code>
4114
4115and <i>rinv</i> has size <code>
4116<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;m&nbsp;\times&nbsp;N</span></code>
4117.
4118
4119<br>
4120<br>
4121<b><big><a name="5.5.i" id="5.5.i">5.5.i: D</a></big></b>
4122<br>
4123The result <i>D</i> is a three dimensional array,
4124for <code>
4125<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
4126
4127<code>
4128<span style='white-space: nowrap'>&nbsp;\[<br>
4129&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;D_k&nbsp;=&nbsp;D(:,:,k)<br>
4130\]</span></code>
4131
4132and <i>D</i> has size <code>
4133<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
4134.
4135
4136<br>
4137<br>
4138<b><big><a name="5.5.j" id="5.5.j">5.5.j: A</a></big></b>
4139<br>
4140The result <i>A</i> is a three dimensional array,
4141for <code>
4142<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;2&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
4143
4144<code>
4145<span style='white-space: nowrap'>&nbsp;\[<br>
4146&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;A_k&nbsp;=&nbsp;A(:,:,k)<br>
4147\]</span></code>
4148
4149and <i>A</i> has size <code>
4150<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
4151.
4152
4153
4154
4155
4156<br>
4157<br>
4158<b><big><a name="5.5.k" id="5.5.k">5.5.k: Example</a></big></b>
4159<br>
4160The file <a href="#5.5.1">5.5.1: <span style='white-space: nowrap'>sumsq_hes_ok.m</span></a>
4161 contains an example and test of
4162<code><font color="blue">ckbs_sumsq_hes</font></code>.
4163It returns true if <code><font color="blue">ckbs_sumsq_hes</font></code> passes the test
4164and false otherwise.
4165
4166
4167<hr>Input File: src/ckbs_sumsq_hes.m
4168
4169<hr>
4170 
4171
4172
4173<center><b><big><big><a name="5.5.1" id="5.5.1">5.5.1: ckbs_sumsq_hes Example and Test</a>
4174</big></big></b></center>
4175<br>
4176<b><big><a name="5.5.1.a" id="5.5.1.a">5.5.1.a: Source Code</a></big></b>
4177
4178 <code><font color='blue'><pre style='display:inline'> 
4179function [ok] = sumsq_hes_ok()
4180ok = true;
4181% --------------------------------------------------------
4182% You can change these parameters
4183m    = 1;   % number of measurements per time point
4184n    = 2;   % number of state vector components per time point
4185N    = 3;   % number of time points
4186% ---------------------------------------------------------
4187%  Define the problem
4188rand('seed', 123);
4189dg   = zeros(n, n, N);
4190dh   = zeros(m, n, N);
4191qinv = zeros(n, n, N);
4192rinv = zeros(m, m, N);
4193for k = 1 : N
4194        dh(:, :, k)   = rand(m, n);
4195        dg(:, :, k)   = rand(n, n);
4196        tmp           = rand(m, m);
4197        rinv(:, :, k) = (tmp + tmp') / 2 + 2 * eye(m);
4198        tmp           = rand(n, n);
4199        qinv(:, :, k) = (tmp + tmp') / 2 + 2 * eye(n);
4200end
4201% ---------------------------------------------------------
4202% Compute the Hessian using ckbs_sumsq_hes
4203[D, A] = ckbs_sumsq_hes(dg, dh, qinv, rinv);
4204% ---------------------------------------------------------
4205H    = zeros(n * N , n * N );
4206for k = 1 : N
4207        index           = (k - 1) * n + (1 : n);
4208        H(index, index) = D(:, :, k);
4209        if k &gt; 1
4210                H(index - n, index) = A(:, :, k)';
4211                H(index, index - n) = A(:, :, k);
4212        end
4213end
4214%
4215% Use finite differences to check Hessian
4216x    = rand(n, N);
4217z    = rand(m, N);
4218h    = rand(m, N);
4219g    = rand(n, N);
4220%
4221step   = 1;
4222for k = 1 : N
4223        for i = 1 : n
4224                % Check second partial w.r.t x(i, k)
4225                xm       = x;
4226                xm(i, k) = xm(i, k) - step;
4227                gradm = ckbs_sumsq_grad(xm, z, g, h, dg, dh, qinv, rinv);
4228                %
4229                xp       = x;
4230                xp(i, k) = xp(i, k) + step;
4231                gradp = ckbs_sumsq_grad(xp, z, g, h, dg, dh, qinv, rinv);
4232                %
4233                check  = (gradp - gradm) / ( 2 * step );
4234                for k1 = 1 : N
4235                        for i1 = 1 : n
4236                                value = H(i + (k-1)*n, i1 + (k1-1)*n);
4237                                diff  = check(i1, k1) - value;
4238                                ok     = ok &amp; ( abs(diff) &lt; 1e-10 );
4239                        end
4240                end
4241        end
4242end
4243return
4244end
4245</pre></font></code>
4246 
4247
4248<hr>Input File: test/sumsq_hes_ok.m
4249
4250<hr>
4251 
4252
4253
4254<center><b><big><big><a name="5.6" id="5.6">5.6: Symmetric Block Tridiagonal Algorithm</a>
4255</big></big></b></center>
4256<br>
4257<b><big><a name="5.6.a" id="5.6.a">5.6.a: Syntax</a></big></b>
4258
4259<br>
4260
4261<code><font color="blue"><span style='white-space: nowrap'>[</span></font><i><font color="black"><span style='white-space: nowrap'>e</span></font></i><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font><i><font color="black"><span style='white-space: nowrap'>lambda</span></font></i><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;ckbs_tridiag_solve(</span></font><i><font color="black"><span style='white-space: nowrap'>b</span></font></i><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font><i><font color="black"><span style='white-space: nowrap'>c</span></font></i><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font><i><font color="black"><span style='white-space: nowrap'>r</span></font></i><font color="blue"><span style='white-space: nowrap'>)</span></font></code>
4262
4263
4264<br>
4265<br>
4266<b><big><a name="5.6.b" id="5.6.b">5.6.b: Purpose</a></big></b>
4267<br>
4268This routine solves the following linear system of equations for
4269<code>
4270<span style='white-space: nowrap'>&nbsp;e</span></code>
4271:
4272<code>
4273<span style='white-space: nowrap'>&nbsp;\[<br>
4274&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;A&nbsp;*&nbsp;e&nbsp;=&nbsp;r<br>
4275\]&nbsp;</span></code>
4276
4277where the symmetric block tridiagonal matrix <code>
4278<span style='white-space: nowrap'>&nbsp;A</span></code>
4279 is defined by
4280<code>
4281<span style='white-space: nowrap'>&nbsp;\[<br>
4282A&nbsp;=<br>
4283\left(&nbsp;\begin{array}{ccccc}<br>
4284b_1&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;c_2^\T&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;\cdots&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
4285c_2&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;b_2&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;c_3^\T&nbsp;&nbsp;&amp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;\vdots&nbsp;\\<br>
4286\vdots&nbsp;&amp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;\ddots&nbsp;&nbsp;&amp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
42870&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;\cdots&nbsp;&amp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;b_N&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;c_N<br>
4288\end{array}&nbsp;\right)<br>
4289\]&nbsp;</span></code>
4290
4291
4292<br>
4293<br>
4294<b><big><a name="5.6.c" id="5.6.c">5.6.c: b</a></big></b>
4295<br>
4296The argument
4297<code><i><font color="black"><span style='white-space: nowrap'>b</span></font></i></code>
4298 is a three dimensional array,
4299for <code>
4300<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
4301
4302<code>
4303<span style='white-space: nowrap'>&nbsp;\[<br>
4304&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;b_k&nbsp;=&nbsp;b(:,:,k)<br>
4305\]</span></code>
4306
4307and
4308<code><i><font color="black"><span style='white-space: nowrap'>b</span></font></i></code>
4309 has size <code>
4310<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
4311.
4312
4313<br>
4314<br>
4315<b><big><a name="5.6.d" id="5.6.d">5.6.d: c</a></big></b>
4316<br>
4317The argument
4318<code><i><font color="black"><span style='white-space: nowrap'>c</span></font></i></code>
4319 is a three dimensional array,
4320for <code>
4321<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;2&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
4322
4323<code>
4324<span style='white-space: nowrap'>&nbsp;\[<br>
4325&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;c_k&nbsp;=&nbsp;c(:,:,k)<br>
4326\]</span></code>
4327
4328and
4329<code><i><font color="black"><span style='white-space: nowrap'>c</span></font></i></code>
4330 has size <code>
4331<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
4332.
4333
4334<br>
4335<br>
4336<b><big><a name="5.6.e" id="5.6.e">5.6.e: r</a></big></b>
4337<br>
4338The argument
4339<code><i><font color="black"><span style='white-space: nowrap'>r</span></font></i></code>
4340 is an <code>
4341<span style='white-space: nowrap'>&nbsp;(n&nbsp;*&nbsp;N)&nbsp;\times&nbsp;m</span></code>
4342 matrix.
4343
4344<br>
4345<br>
4346<b><big><a name="5.6.f" id="5.6.f">5.6.f: e</a></big></b>
4347<br>
4348The result
4349<code><i><font color="black"><span style='white-space: nowrap'>e</span></font></i></code>
4350 is an <code>
4351<span style='white-space: nowrap'>&nbsp;(n&nbsp;*&nbsp;N)&nbsp;\times&nbsp;m</span></code>
4352 matrix.
4353
4354<br>
4355<br>
4356<b><big><a name="5.6.g" id="5.6.g">5.6.g: lambda</a></big></b>
4357<br>
4358The result
4359<code><i><font color="black"><span style='white-space: nowrap'>lambda</span></font></i></code>
4360 is a scalar equal to the
4361logarithm of the determinant of <code>
4362<span style='white-space: nowrap'>&nbsp;A</span></code>
4363.
4364
4365<br>
4366<br>
4367<b><big><a name="5.6.h" id="5.6.h">5.6.h: Reference</a></big></b>
4368
4369<i><br>
4370The marginal likelihood for parameters in a discrete
4371Gauss Markov process</i>,
4372Bradley M. Bell,
4373IEEE Transactions on Signal Processing,
4374Vol. 48,
4375No. 3,
4376March 2000.
4377
4378<br>
4379<br>
4380<b><big><a name="5.6.i" id="5.6.i">5.6.i: Lemma</a></big></b>
4381<br>
4382The following result is proven as Lemma 6 of the reference above:
4383Suppose that for <code>
4384<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
4385
4386<code>
4387<span style='white-space: nowrap'>&nbsp;\[<br>
4388\begin{array}{rcl}<br>
4389&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;b_k&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;u_k&nbsp;+&nbsp;q_{k-1}^{-1}&nbsp;+&nbsp;a_k&nbsp;*&nbsp;q_k^{-1}&nbsp;*&nbsp;a_k^\T&nbsp;&nbsp;\\<br>
4390&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;c_k&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;q_{k-1}^{-1}&nbsp;*&nbsp;a_k^\T<br>
4391\end{array}<br>
4392\]&nbsp;</span></code>
4393
4394where <code>
4395<span style='white-space: nowrap'>&nbsp;u_k</span></code>
4396 is symmetric positive semi-definite and
4397<code>
4398<span style='white-space: nowrap'>&nbsp;q_k</span></code>
4399 is symmetric positive definite.
4400It follows that the algorithm used by <code><font color="blue">ckbs_tridiag_solve</font></code>
4401is well conditioned and will not try to invert singular matrices.
4402
4403
4404
4405<br>
4406<br>
4407<b><big><a name="5.6.j" id="5.6.j">5.6.j: Example</a></big></b>
4408<br>
4409The file <a href="#5.6.1">5.6.1: <span style='white-space: nowrap'>tridiag_solve_ok.m</span></a>
4410 contains an example and test of
4411<code><font color="blue">ckbs_tridiag_solve</font></code>.
4412It returns true if <code><font color="blue">ckbs_tridiag_solve</font></code> passes the test
4413and false otherwise.
4414
4415
4416<hr>Input File: src/ckbs_tridiag_solve.m
4417
4418<hr>
4419 
4420
4421
4422<center><b><big><big><a name="5.6.1" id="5.6.1">5.6.1: ckbs_tridiag_solve Example and Test</a>
4423</big></big></b></center>
4424<br>
4425<b><big><a name="5.6.1.a" id="5.6.1.a">5.6.1.a: Source Code</a></big></b>
4426
4427 <code><font color='blue'><pre style='display:inline'> 
4428function [ok] = tridiag_solve_ok()
4429ok = true;
4430m  = 2;
4431n  = 3;
4432N  = 4;
4433% case where uk = 0, qk = I, and ak is random
4434rand('seed', 123);
4435a = rand(n, n, N);
4436r = rand(n * N, m);
4437c = zeros(n, n, N);
4438for k = 1 : N
4439        ak         = a(:, :, k);
4440        b(:, :, k) = 2 * eye(n) + ak * ak';
4441        c(:, :, k) = ak';
4442end 
4443% ----------------------------------------
4444[e, lambda] = ckbs_tridiag_solve(b, c, r);
4445% ----------------------------------------
4446%
4447% check equation corresponding to first row
4448blk_n = 1 : n;
4449lhs   = b(:, :, 1) * e(blk_n, :) + c(:, :, 2)' * e(blk_n + n, :);
4450ok    = ok &amp; ( max( max( abs( lhs - r(blk_n, :) ) ) ) &lt; 1e-10 );
4451%
4452% check equation corresponding to last row
4453blk_n = (N-1) * n + (1 : n);
4454lhs   = c(:, :, N) * e(blk_n - n, :) + b(:, :, N) * e(blk_n, :);
4455ok    = ok &amp; ( max( max( abs( lhs - r(blk_n, :) ) ) ) &lt; 1e-10 );
4456%
4457% check other rows
4458blk_n = 1 : n;
4459for k = 2 : N-1
4460        blk_n = blk_n + n;
4461        lhs   = c(:, :, k)    * e(blk_n - n, :)  ...
4462              + b(:, :, k)    * e(blk_n, :)    ...
4463              + c(:, :, k+1)' * e(blk_n + n, :);
4464        ok    = ok &amp; ( max( max( abs( lhs - r(blk_n, :) ) ) ) &lt; 1e-10 );
4465end
4466return
4467end
4468</pre></font></code>
4469 
4470
4471<hr>Input File: test/tridiag_solve_ok.m
4472
4473<hr>
4474 
4475
4476
4477<center><b><big><big><a name="5.7" id="5.7">5.7: Affine Constrained Kalman Bucy Smoother Newton Step</a>
4478</big></big></b></center>
4479<br>
4480<b><big><a name="5.7.a" id="5.7.a">5.7.a: Syntax</a></big></b>
4481
4482<br>
4483<code><font color="blue"><span style='white-space: nowrap'>[</span></font></code><i><span style='white-space: nowrap'>ds</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>dy</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>du</span></i><code><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;ckbs_newton_step(</span></font></code><i><span style='white-space: nowrap'>mu</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>s</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>y</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>u</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>b</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>d</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>Bdia</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>Hdia</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>Hlow</span></i><code><font color="blue"><span style='white-space: nowrap'>)</span></font></code>
4484
4485<br>
4486<br>
4487<b><big><a name="5.7.b" id="5.7.b">5.7.b: Purpose</a></big></b>
4488<br>
4489This routine computes one step of Newton's method for solving
4490the non-linear Kuhn-Tucker conditions for
4491the <code>
4492<span style='white-space: nowrap'>&nbsp;\mu</span></code>
4493-relaxed affine constrained Kalman-Bucy smoother problem.
4494
4495
4496<br>
4497<br>
4498<b><big><a name="5.7.c" id="5.7.c">5.7.c: Problem</a></big></b>
4499<br>
4500Given
4501<code>
4502<span style='white-space: nowrap'>&nbsp;\mu&nbsp;\in&nbsp;\R_+</span></code>
4503,
4504<code>
4505<span style='white-space: nowrap'>&nbsp;H&nbsp;\in&nbsp;\R^{p&nbsp;\times&nbsp;p}</span></code>
4506,
4507<code>
4508<span style='white-space: nowrap'>&nbsp;d&nbsp;\in&nbsp;\R^p</span></code>
4509,
4510<code>
4511<span style='white-space: nowrap'>&nbsp;b&nbsp;\in&nbsp;\R^r</span></code>
4512, and
4513<code>
4514<span style='white-space: nowrap'>&nbsp;B&nbsp;\in&nbsp;\R^{r&nbsp;\times&nbsp;p}</span></code>
4515,
4516the <code>
4517<span style='white-space: nowrap'>&nbsp;\mu</span></code>
4518-relaxed affine constrained Kalman-Bucy smoother problem is:
4519<code>
4520<span style='white-space: nowrap'>&nbsp;\[<br>
4521\begin{array}{rl}<br>
4522{\rm&nbsp;minimize}&nbsp;&amp;&nbsp;\frac{1}{2}&nbsp;y^\T&nbsp;H&nbsp;y&nbsp;+&nbsp;d^\T&nbsp;y<br>
4523-&nbsp;\mu&nbsp;\sum_{i=1}^r&nbsp;\log(s_i)<br>
4524\;&nbsp;{\rm&nbsp;w.r.t}&nbsp;\;&nbsp;y&nbsp;\in&nbsp;\R^p&nbsp;\;&nbsp;,&nbsp;\;&nbsp;s&nbsp;\in&nbsp;\R_+^r<br>
4525\\<br>
4526{\rm&nbsp;subject&nbsp;\;&nbsp;to}&nbsp;&amp;&nbsp;s&nbsp;+&nbsp;b&nbsp;+&nbsp;B&nbsp;y&nbsp;&nbsp;=&nbsp;0&nbsp;<br>
4527\end{array}<br>
4528\]&nbsp;</span></code>
4529
4530In addition, <code>
4531<span style='white-space: nowrap'>&nbsp;H</span></code>
4532 is symmetric block tri-diagonal with each block of
4533size <code>
4534<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n</span></code>
4535 and
4536<code>
4537<span style='white-space: nowrap'>&nbsp;B</span></code>
4538 is block diagonal with each block of size <code>
4539<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;n</span></code>
4540
4541(there is an integer <code>
4542<span style='white-space: nowrap'>&nbsp;N</span></code>
4543 such that
4544<code>
4545<span style='white-space: nowrap'>&nbsp;p&nbsp;=&nbsp;n&nbsp;*&nbsp;N</span></code>
4546 and <code>
4547<span style='white-space: nowrap'>&nbsp;r&nbsp;=&nbsp;m&nbsp;*&nbsp;N</span></code>
4548).
4549
4550
4551<br>
4552<br>
4553<b><a name="5.7.c.a" id="5.7.c.a">5.7.c.a: Lagrangian</a></b>
4554<br>
4555We use <code>
4556<span style='white-space: nowrap'>&nbsp;u&nbsp;\in&nbsp;\R^r</span></code>
4557
4558to denote the Lagrange multipliers corresponding to the constraint equation.
4559The corresponding Lagrangian is
4560<code>
4561<span style='white-space: nowrap'>&nbsp;\[<br>
4562L(y,&nbsp;s,&nbsp;u)&nbsp;&nbsp;=<br>
4563\frac{1}{2}&nbsp;y^\T&nbsp;H&nbsp;y&nbsp;+&nbsp;d^\T&nbsp;y<br>
4564-&nbsp;\mu&nbsp;\sum_{i=1}^r&nbsp;\log(s_i)<br>
4565+&nbsp;u^\T&nbsp;(s&nbsp;+&nbsp;b&nbsp;+&nbsp;B&nbsp;y)<br>
4566\]&nbsp;</span></code>
4567
4568The partial gradients of the Lagrangian are given by
4569<code>
4570<span style='white-space: nowrap'>&nbsp;\[<br>
4571\begin{array}{rcl}<br>
4572\nabla_y&nbsp;L(y,&nbsp;s,&nbsp;u&nbsp;)&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;H&nbsp;y&nbsp;+&nbsp;B^\T&nbsp;u&nbsp;+&nbsp;d&nbsp;&nbsp;\\<br>
4573\nabla_s&nbsp;L(y,&nbsp;s,&nbsp;u&nbsp;)&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;u&nbsp;-&nbsp;\mu&nbsp;/&nbsp;s&nbsp;\\<br>
4574\nabla_u&nbsp;L(y,&nbsp;s,&nbsp;u&nbsp;)&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;s&nbsp;+&nbsp;b&nbsp;+&nbsp;B&nbsp;y&nbsp;\\<br>
4575\end{array}<br>
4576\]&nbsp;</span></code>
4577
4578where <code>
4579<span style='white-space: nowrap'>&nbsp;\mu&nbsp;/&nbsp;s&nbsp;</span></code>
4580 is the component by component division of
4581<code>
4582<span style='white-space: nowrap'>&nbsp;\mu&nbsp;</span></code>
4583 by the components of the <code>
4584<span style='white-space: nowrap'>&nbsp;s</span></code>
4585.
4586Note, from the second equation, that we only need consider
4587<code>
4588<span style='white-space: nowrap'>&nbsp;u&nbsp;\geq&nbsp;0</span></code>
4589 because <code>
4590<span style='white-space: nowrap'>&nbsp;s&nbsp;\geq&nbsp;0</span></code>
4591.
4592
4593<br>
4594<br>
4595<b><a name="5.7.c.b" id="5.7.c.b">5.7.c.b: Kuhn-Tucker Conditions</a></b>
4596<br>
4597We use <code>
4598<span style='white-space: nowrap'>&nbsp;D(s)</span></code>
4599 
4600to denote the diagonal matrix with <code>
4601<span style='white-space: nowrap'>&nbsp;s</span></code>
4602
4603along its diagonal and <code>
4604<span style='white-space: nowrap'>&nbsp;1_r</span></code>
4605 
4606to denote the vector, of length <code>
4607<span style='white-space: nowrap'>&nbsp;r</span></code>
4608 with all its components
4609equal to one.
4610We define
4611<code>
4612<span style='white-space: nowrap'>&nbsp;F&nbsp;:&nbsp;\R^{r&nbsp;+&nbsp;p&nbsp;+&nbsp;r}&nbsp;\rightarrow&nbsp;\R^{r&nbsp;+&nbsp;p&nbsp;+&nbsp;r}</span></code>
4613
4614by
4615<code>
4616<span style='white-space: nowrap'>&nbsp;\[<br>
4617F(s,&nbsp;y,&nbsp;u)<br>
4618=<br>
4619\left(<br>
4620\begin{array}{c}<br>
4621s&nbsp;+&nbsp;b&nbsp;+&nbsp;B&nbsp;y&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
4622H&nbsp;y&nbsp;+&nbsp;B^\T&nbsp;u&nbsp;+&nbsp;d&nbsp;&nbsp;&nbsp;\\<br>
4623D(s)&nbsp;D(u)&nbsp;1_r&nbsp;-&nbsp;\mu&nbsp;1_r<br>
4624\end{array}<br>
4625\right)<br>
4626\]&nbsp;</span></code>
4627
4628The Kuhn-Tucker conditions for a solution of the
4629<code>
4630<span style='white-space: nowrap'>&nbsp;\mu</span></code>
4631-relaxed constrained affine Kalman-Bucy smoother problem is
4632<code>
4633<span style='white-space: nowrap'>&nbsp;F(s,&nbsp;y,&nbsp;u)&nbsp;=&nbsp;0&nbsp;</span></code>
4634.
4635
4636<br>
4637<br>
4638<b><a name="5.7.c.c" id="5.7.c.c">5.7.c.c: Newton Step</a></b>
4639<br>
4640Given a value for <code>
4641<span style='white-space: nowrap'>&nbsp;(s,&nbsp;y,&nbsp;u)</span></code>
4642, the Newton step
4643<code>
4644<span style='white-space: nowrap'>&nbsp;(&nbsp;\Delta&nbsp;s^\T&nbsp;,&nbsp;\Delta&nbsp;y^\T&nbsp;,&nbsp;\Delta&nbsp;u^\T&nbsp;)^\T</span></code>
4645 solves the problem:
4646<code>
4647<span style='white-space: nowrap'>&nbsp;\[<br>
4648F^{(1)}&nbsp;(s,&nbsp;y,&nbsp;u)&nbsp;<br>
4649\left(&nbsp;\begin{array}{c}&nbsp;\Delta&nbsp;s&nbsp;\\&nbsp;\Delta&nbsp;y&nbsp;\\&nbsp;\Delta&nbsp;u&nbsp;\end{array}&nbsp;\right)<br>
4650=<br>
4651-&nbsp;F(s,&nbsp;y,&nbsp;u)<br>
4652\]&nbsp;</span></code>
4653
4654
4655<br>
4656<br>
4657<b><big><a name="5.7.d" id="5.7.d">5.7.d: mu</a></big></b>
4658<br>
4659The argument <i>mu</i> is a positive scalar specifying the
4660relaxation parameter <code>
4661<span style='white-space: nowrap'>&nbsp;\mu</span></code>
4662.
4663
4664<br>
4665<br>
4666<b><big><a name="5.7.e" id="5.7.e">5.7.e: s</a></big></b>
4667<br>
4668The argument <i>s</i> is a column vector of length <code>
4669<span style='white-space: nowrap'>&nbsp;r</span></code>
4670.
4671All the elements of <i>s</i> are greater than zero.
4672
4673<br>
4674<br>
4675<b><big><a name="5.7.f" id="5.7.f">5.7.f: y</a></big></b>
4676<br>
4677The argument <i>y</i> is a column vector of length <code>
4678<span style='white-space: nowrap'>&nbsp;p</span></code>
4679
4680
4681<br>
4682<br>
4683<b><big><a name="5.7.g" id="5.7.g">5.7.g: u</a></big></b>
4684<br>
4685The argument <i>u</i> is a column vector of length <code>
4686<span style='white-space: nowrap'>&nbsp;r</span></code>
4687.
4688All the elements of <i>s</i> are greater than zero.
4689
4690<br>
4691<br>
4692<b><big><a name="5.7.h" id="5.7.h">5.7.h: b</a></big></b>
4693<br>
4694The argument <i>b</i> is a column vector of length <code>
4695<span style='white-space: nowrap'>&nbsp;r</span></code>
4696.
4697
4698<br>
4699<br>
4700<b><big><a name="5.7.i" id="5.7.i">5.7.i: d</a></big></b>
4701<br>
4702The argument <i>d</i> is a column vector of length <code>
4703<span style='white-space: nowrap'>&nbsp;p</span></code>
4704
4705
4706<br>
4707<br>
4708<b><big><a name="5.7.j" id="5.7.j">5.7.j: Bdia</a></big></b>
4709<br>
4710The argument <i>Bdia</i> is an <code>
4711<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
4712 array.
4713For <code>
4714<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
4715 we define <code>
4716<span style='white-space: nowrap'>&nbsp;B_k&nbsp;\in&nbsp;\R^{m&nbsp;\times&nbsp;n}</span></code>
4717 by
4718<code>
4719<span style='white-space: nowrap'>&nbsp;\[<br>
4720&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;B_k&nbsp;=&nbsp;Bdia(:,&nbsp;:,&nbsp;k)<br>
4721\]&nbsp;</span></code>
4722
4723
4724<br>
4725<br>
4726<b><big><a name="5.7.k" id="5.7.k">5.7.k: B</a></big></b>
4727<br>
4728The matrix <code>
4729<span style='white-space: nowrap'>&nbsp;B</span></code>
4730 is defined by
4731<code>
4732<span style='white-space: nowrap'>&nbsp;\[<br>
4733B&nbsp;<br>
4734=<br>
4735\left(&nbsp;\begin{array}{cccc}<br>
4736B_1&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
47370&nbsp;&nbsp;&nbsp;&amp;&nbsp;B_2&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
47380&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;\ddots&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
4739&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;B_N&nbsp;<br>
4740\end{array}&nbsp;\right)<br>
4741\]&nbsp;</span></code>
4742
4743
4744<br>
4745<br>
4746<b><big><a name="5.7.l" id="5.7.l">5.7.l: Hdia</a></big></b>
4747<br>
4748The argument <i>Hdia</i> is an <code>
4749<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
4750 array.
4751For <code>
4752<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
4753 we define <code>
4754<span style='white-space: nowrap'>&nbsp;H_k&nbsp;\in&nbsp;\R^{n&nbsp;\times&nbsp;n}</span></code>
4755 by
4756<code>
4757<span style='white-space: nowrap'>&nbsp;\[<br>
4758&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;H_k&nbsp;=&nbsp;Hdia(:,&nbsp;:,&nbsp;k)<br>
4759\]&nbsp;</span></code>
4760
4761
4762
4763<br>
4764<br>
4765<b><big><a name="5.7.m" id="5.7.m">5.7.m: Hlow</a></big></b>
4766<br>
4767The argument <i>Hlow</i> is an <code>
4768<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
4769 array.
4770For <code>
4771<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
4772 we define <code>
4773<span style='white-space: nowrap'>&nbsp;L_k&nbsp;\in&nbsp;\R^{n&nbsp;\times&nbsp;n}</span></code>
4774 by
4775<code>
4776<span style='white-space: nowrap'>&nbsp;\[<br>
4777&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;L_k&nbsp;=&nbsp;Hlow(:,&nbsp;:,&nbsp;k)<br>
4778\]&nbsp;</span></code>
4779
4780
4781<br>
4782<br>
4783<b><big><a name="5.7.n" id="5.7.n">5.7.n: H</a></big></b>
4784<br>
4785The matrix <code>
4786<span style='white-space: nowrap'>&nbsp;H</span></code>
4787 is defined by
4788<code>
4789<span style='white-space: nowrap'>&nbsp;\[<br>
4790H&nbsp;<br>
4791=<br>
4792\left(&nbsp;\begin{array}{cccc}<br>
4793H_1&nbsp;&amp;&nbsp;L_2^\T&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
4794L_2&nbsp;&amp;&nbsp;H_2&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;L_3^\T&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
47950&nbsp;&nbsp;&nbsp;&amp;&nbsp;\ddots&nbsp;&amp;&nbsp;\ddots&nbsp;&amp;&nbsp;\ddots&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
4796&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;L_N&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;H_N&nbsp;<br>
4797\end{array}&nbsp;\right)<br>
4798\]&nbsp;</span></code>
4799
4800
4801<br>
4802<br>
4803<b><big><a name="5.7.o" id="5.7.o">5.7.o: ds</a></big></b>
4804<br>
4805The result <i>ds</i> is a column vector of length <code>
4806<span style='white-space: nowrap'>&nbsp;r</span></code>
4807 
4808equal to the <code>
4809<span style='white-space: nowrap'>&nbsp;\Delta&nbsp;s</span></code>
4810 components of the Newton step.
4811
4812<br>
4813<br>
4814<b><big><a name="5.7.p" id="5.7.p">5.7.p: dy</a></big></b>
4815<br>
4816The result <i>dy</i> is a column vector of length <code>
4817<span style='white-space: nowrap'>&nbsp;p</span></code>
4818 
4819equal to the <code>
4820<span style='white-space: nowrap'>&nbsp;\Delta&nbsp;y</span></code>
4821 components of the Newton step.
4822
4823<br>
4824<br>
4825<b><big><a name="5.7.q" id="5.7.q">5.7.q: du</a></big></b>
4826<br>
4827The result <i>du</i> is a column vector of length <code>
4828<span style='white-space: nowrap'>&nbsp;r</span></code>
4829 
4830equal to the <code>
4831<span style='white-space: nowrap'>&nbsp;\Delta&nbsp;u</span></code>
4832 components of the Newton step.
4833
4834
4835
4836<br>
4837<br>
4838<b><big><a name="5.7.r" id="5.7.r">5.7.r: Example</a></big></b>
4839<br>
4840The file <a href="#5.7.1">5.7.1: <span style='white-space: nowrap'>newton_step_ok.m</span></a>
4841 contains an example and test of
4842<code><font color="blue">ckbs_newton_step</font></code>.
4843It returns true if <code><font color="blue">ckbs_newton_step</font></code> passes the test
4844and false otherwise.
4845
4846<br>
4847<br>
4848<b><big><a name="5.7.s" id="5.7.s">5.7.s: Method</a></big></b>
4849<br>
4850The derivative of <code>
4851<span style='white-space: nowrap'>&nbsp;F</span></code>
4852 is given by
4853<code>
4854<span style='white-space: nowrap'>&nbsp;\[<br>
4855F^{(1)}&nbsp;(s,&nbsp;y,&nbsp;u)&nbsp;=<br>
4856\left(<br>
4857\begin{array}{ccccc}<br>
4858D(&nbsp;1_r&nbsp;)&nbsp;&amp;&nbsp;B&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
48590&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;H&nbsp;&nbsp;&nbsp;&amp;&nbsp;B^\T&nbsp;&nbsp;\\<br>
4860D(&nbsp;u&nbsp;)&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&amp;&nbsp;D(s)<br>
4861\end{array}<br>
4862\right)<br>
4863\]&nbsp;</span></code>
4864
4865It follows that
4866<code>
4867<span style='white-space: nowrap'>&nbsp;\[<br>
4868\left(&nbsp;\begin{array}{ccc}<br>
4869D(&nbsp;1_r&nbsp;)&nbsp;&amp;&nbsp;B&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
48700&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;H&nbsp;&nbsp;&nbsp;&amp;&nbsp;B^\T&nbsp;&nbsp;\\<br>
4871D(&nbsp;u&nbsp;)&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&amp;&nbsp;D(s)<br>
4872\end{array}&nbsp;\right)<br>
4873\left(&nbsp;\begin{array}{c}&nbsp;\Delta&nbsp;s&nbsp;\\&nbsp;\Delta&nbsp;y&nbsp;\\&nbsp;\Delta&nbsp;u&nbsp;\end{array}&nbsp;\right)<br>
4874=<br>
4875-<br>
4876\left(&nbsp;\begin{array}{c}<br>
4877s&nbsp;+&nbsp;b&nbsp;+&nbsp;B&nbsp;y&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
4878H&nbsp;y&nbsp;+&nbsp;B^\T&nbsp;u&nbsp;+&nbsp;d&nbsp;&nbsp;&nbsp;\\<br>
4879D(s)&nbsp;D(u)&nbsp;1_r&nbsp;-&nbsp;\mu&nbsp;1_r<br>
4880\end{array}&nbsp;\right)<br>
4881\]&nbsp;</span></code>
4882
4883Replacing the bottom row by the bottom row minus
4884<code>
4885<span style='white-space: nowrap'>&nbsp;D(u)</span></code>
4886 times the top row,
4887we obtain the reduced set of equations
4888<code>
4889<span style='white-space: nowrap'>&nbsp;\[<br>
4890\left(&nbsp;\begin{array}{cc}<br>
4891&nbsp;H&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;B^\T&nbsp;&nbsp;\\<br>
4892-D(u)&nbsp;B&nbsp;&amp;&nbsp;D(s)&nbsp;<br>
4893\end{array}&nbsp;\right)&nbsp;<br>
4894\left(&nbsp;\begin{array}{c}&nbsp;\Delta&nbsp;y&nbsp;\\&nbsp;\Delta&nbsp;u&nbsp;\end{array}&nbsp;\right)<br>
4895=<br>
4896\left(&nbsp;\begin{array}{c}<br>
4897-&nbsp;H&nbsp;y&nbsp;-&nbsp;B^\T&nbsp;u&nbsp;-&nbsp;d&nbsp;&nbsp;&nbsp;\\<br>
4898\mu&nbsp;1_r&nbsp;+&nbsp;D(u)&nbsp;(&nbsp;b&nbsp;+&nbsp;B&nbsp;y&nbsp;)<br>
4899\end{array}&nbsp;\right)<br>
4900\]&nbsp;</span></code>
4901
4902Replacing the top row by <code>
4903<span style='white-space: nowrap'>&nbsp;H^{-1}</span></code>
4904 times the top row we obtain
4905<code>
4906<span style='white-space: nowrap'>&nbsp;\[<br>
4907\left(&nbsp;\begin{array}{cc}<br>
4908&nbsp;D(&nbsp;1_p&nbsp;)&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;H^{-1}&nbsp;B^\T&nbsp;&nbsp;\\<br>
4909-D(u)&nbsp;B&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;D(s)&nbsp;<br>
4910\end{array}&nbsp;\right)&nbsp;<br>
4911\left(&nbsp;\begin{array}{c}&nbsp;\Delta&nbsp;y&nbsp;\\&nbsp;\Delta&nbsp;u&nbsp;\end{array}&nbsp;\right)<br>
4912=<br>
4913\left(&nbsp;\begin{array}{c}<br>
4914-&nbsp;y&nbsp;-&nbsp;H^{-1}(&nbsp;B^\T&nbsp;u&nbsp;+&nbsp;d&nbsp;)&nbsp;&nbsp;&nbsp;\\<br>
4915\mu&nbsp;1_r&nbsp;+&nbsp;D(u)&nbsp;(&nbsp;b&nbsp;+&nbsp;B&nbsp;y&nbsp;)<br>
4916\end{array}&nbsp;\right)<br>
4917\]&nbsp;</span></code>
4918
4919Replacing the bottom row by
4920the <code>
4921<span style='white-space: nowrap'>&nbsp;D(u)^{-1}</span></code>
4922 times the bottom row
4923plus <code>
4924<span style='white-space: nowrap'>&nbsp;B</span></code>
4925 times the top row,
4926we obtain the reduced equation
4927<code>
4928<span style='white-space: nowrap'>&nbsp;\[<br>
4929\begin{array}{rcl}<br>
4930[&nbsp;B&nbsp;H^{-1}&nbsp;B^\T&nbsp;+&nbsp;D(s&nbsp;/&nbsp;u)&nbsp;]&nbsp;\Delta&nbsp;u&nbsp;<br>
4931&amp;&nbsp;=&nbsp;&amp;<br>
4932\mu&nbsp;(&nbsp;1_r&nbsp;/&nbsp;u&nbsp;)&nbsp;+&nbsp;b&nbsp;-&nbsp;B&nbsp;H^{-1}(&nbsp;B^\T&nbsp;u&nbsp;+&nbsp;d&nbsp;)&nbsp;<br>
4933\end{array}<br>
4934\]&nbsp;</span></code>
4935
4936Thus we obtain the following solution for the Newton step:
4937<code>
4938<span style='white-space: nowrap'>&nbsp;\[<br>
4939\begin{array}{rcl}<br>
4940\Delta&nbsp;u&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;<br>
4941&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[&nbsp;B&nbsp;H^{-1}&nbsp;B^\T&nbsp;+&nbsp;D(s&nbsp;/&nbsp;u)&nbsp;]^{-1}&nbsp;<br>
4942&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;[&nbsp;\mu&nbsp;(&nbsp;1_r&nbsp;/&nbsp;u&nbsp;)&nbsp;+&nbsp;b&nbsp;-&nbsp;B&nbsp;H^{-1}(&nbsp;B^\T&nbsp;u&nbsp;+&nbsp;d&nbsp;)&nbsp;]<br>
4943\\<br>
4944\Delta&nbsp;y&nbsp;&amp;&nbsp;=&nbsp;&amp;<br>
4945-&nbsp;y&nbsp;-&nbsp;H^{-1}&nbsp;[&nbsp;d&nbsp;+&nbsp;B^\T&nbsp;(&nbsp;u&nbsp;+&nbsp;\Delta&nbsp;u&nbsp;)&nbsp;]&nbsp;&nbsp;&nbsp;\\<br>
4946\\<br>
4947\Delta&nbsp;s&nbsp;&amp;&nbsp;=&nbsp;&amp;<br>
4948-&nbsp;s&nbsp;-&nbsp;b&nbsp;-&nbsp;B&nbsp;(&nbsp;y&nbsp;+&nbsp;\Delta&nbsp;y&nbsp;)<br>
4949\end{array}<br>
4950\]&nbsp;</span></code>
4951
4952It follows from the matrix inversion lemma that
4953<code>
4954<span style='white-space: nowrap'>&nbsp;\[<br>
4955[&nbsp;B&nbsp;H^{-1}&nbsp;B^\T&nbsp;+&nbsp;D(s&nbsp;/&nbsp;u)&nbsp;]^{-1}&nbsp;<br>
4956=&nbsp;<br>
4957D(s/u)^{-1}&nbsp;-&nbsp;D(s/u)^{-1}&nbsp;B&nbsp;[&nbsp;H&nbsp;+&nbsp;B^\T&nbsp;D(s/u)^{-1}&nbsp;B&nbsp;]^{-1}&nbsp;B^\T&nbsp;D(s/u)^{-1}<br>
4958\]&nbsp;</span></code>
4959
4960
4961
4962<hr>Input File: src/ckbs_newton_step.m
4963
4964<hr>
4965 
4966
4967
4968<center><b><big><big><a name="5.7.1" id="5.7.1">5.7.1: ckbs_newton_step Example and Test</a>
4969</big></big></b></center>
4970<br>
4971<b><big><a name="5.7.1.a" id="5.7.1.a">5.7.1.a: Source Code</a></big></b>
4972
4973 <code><font color='blue'><pre style='display:inline'> 
4974function [ok] = newton_step_ok()
4975ok = true;
4976% --------------------------------------------------------
4977% You can change these parameters
4978m    = 2;   % number of measurements per time point
4979n    = 3;   % number of state vector components per time point
4980N    = 4;   % number of time points
4981% ---------------------------------------------------------
4982%  Define the problem
4983rand('seed', 123);
4984mu    = .5;
4985r     = m * N;
4986p     = n * N;
4987s     = rand(r, 1) + 1;
4988y     = rand(p, 1);
4989u     = rand(r, 1) + 1;
4990b     = rand(r, 1);
4991d     = rand(p, 1);
4992H     = zeros(p, p);
4993B     = zeros(r, r);
4994Hdia  = zeros(n, n, N);
4995Hlow  = zeros(n, n, N);
4996Bdia  = zeros(m, n, N);
4997blk_m = m * N + (1 : m);
4998blk_n = n * N + (1 : n);
4999for k = N : -1 : 1
5000        blk_n = blk_n - n;
5001        blk_m = blk_m - m;
5002        %
5003        Bdia(:,:, k)    = rand(m, n);
5004        tmp             = rand(n, n);
5005        Hlow(:,:, k)    = tmp;
5006        Hdia(:,:, k)   = (tmp * tmp') + 4 * eye(n);
5007        %
5008        B(blk_m, blk_n) = Bdia(:,:, k);
5009        H(blk_n, blk_n) = Hdia(:,:, k);
5010        if k &gt; 1
5011                H(blk_n, blk_n - n) = Hlow(:,:, k);
5012        end
5013        if k &lt; N
5014                H(blk_n, blk_n + n) = Hlow(:,:, k + 1)';
5015        end
5016end
5017% -------------------------------------------------------------------
5018[ds, dy, du] = ckbs_newton_step(mu, s, y, u, b, d, Bdia, Hdia, Hlow);
5019% -------------------------------------------------------------------
5020F      = [ ...
5021        s + b + B * y
5022        H * y + B' * u + d
5023        s .* u - mu ...
5024];
5025dF     = [ ...
5026        eye(r)      , B           , zeros(r, r)
5027        zeros(p, r) , H           , B'
5028        diag(u)     , zeros(r, p) , diag(s) ...
5029];
5030delta        = [ ds ; dy ; du ];
5031ok           = ok &amp; ( max( abs( F + dF * delta ) ) &lt;= 1e-10 );
5032return
5033end
5034</pre></font></code>
5035 
5036
5037<hr>Input File: test/newton_step_ok.m
5038
5039<hr>
5040 
5041
5042
5043<center><b><big><big><a name="5.8" id="5.8">5.8: Compute Residual in Kuhn-Tucker Conditions</a>
5044</big></big></b></center>
5045<br>
5046<b><big><a name="5.8.a" id="5.8.a">5.8.a: Syntax</a></big></b>
5047
5048<br>
5049<code><font color="blue"><span style='white-space: nowrap'>[</span></font></code><i><span style='white-space: nowrap'>F</span></i><code><font color="blue"><span style='white-space: nowrap'>]&nbsp;=&nbsp;ckbs_kuhn_tucker(</span></font></code><i><span style='white-space: nowrap'>mu</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>s</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>y</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>u</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>b</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>d</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>Bdia</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>Hdia</span></i><code><font color="blue"><span style='white-space: nowrap'>,&nbsp;</span></font></code><i><span style='white-space: nowrap'>Hlow</span></i><code><font color="blue"><span style='white-space: nowrap'>)</span></font></code>
5050
5051<br>
5052<br>
5053<b><big><a name="5.8.b" id="5.8.b">5.8.b: Purpose</a></big></b>
5054<br>
5055This routine computes the residual in the Kuhn-Tucker conditions for
5056the <code>
5057<span style='white-space: nowrap'>&nbsp;\mu</span></code>
5058-relaxed affine constrained Kalman-Bucy smoother problem.
5059
5060<br>
5061<br>
5062<b><big><a name="5.8.c" id="5.8.c">5.8.c: Problem</a></big></b>
5063<br>
5064Given
5065<code>
5066<span style='white-space: nowrap'>&nbsp;\mu&nbsp;\in&nbsp;\R_+</span></code>
5067,
5068<code>
5069<span style='white-space: nowrap'>&nbsp;H&nbsp;\in&nbsp;\R^{p&nbsp;\times&nbsp;p}</span></code>
5070,
5071<code>
5072<span style='white-space: nowrap'>&nbsp;d&nbsp;\in&nbsp;\R^p</span></code>
5073,
5074<code>
5075<span style='white-space: nowrap'>&nbsp;b&nbsp;\in&nbsp;\R^r</span></code>
5076, and
5077<code>
5078<span style='white-space: nowrap'>&nbsp;B&nbsp;\in&nbsp;\R^{r&nbsp;\times&nbsp;p}</span></code>
5079,
5080the <code>
5081<span style='white-space: nowrap'>&nbsp;\mu</span></code>
5082-relaxed affine constrained Kalman-Bucy smoother problem is:
5083<code>
5084<span style='white-space: nowrap'>&nbsp;\[<br>
5085\begin{array}{rl}<br>
5086{\rm&nbsp;minimize}&nbsp;&amp;&nbsp;\frac{1}{2}&nbsp;y^\T&nbsp;H&nbsp;y&nbsp;+&nbsp;d^\T&nbsp;y<br>
5087-&nbsp;\mu&nbsp;\sum_{i=1}^r&nbsp;\log(s_i)<br>
5088\;&nbsp;{\rm&nbsp;w.r.t}&nbsp;\;&nbsp;y&nbsp;\in&nbsp;\R^p&nbsp;\;&nbsp;,&nbsp;\;&nbsp;s&nbsp;\in&nbsp;\R_+^r<br>
5089\\<br>
5090{\rm&nbsp;subject&nbsp;\;&nbsp;to}&nbsp;&amp;&nbsp;s&nbsp;+&nbsp;b&nbsp;+&nbsp;B&nbsp;y&nbsp;&nbsp;=&nbsp;0&nbsp;<br>
5091\end{array}<br>
5092\]&nbsp;</span></code>
5093
5094In addition, <code>
5095<span style='white-space: nowrap'>&nbsp;H</span></code>
5096 is symmetric block tri-diagonal with each block of
5097size <code>
5098<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n</span></code>
5099 and
5100<code>
5101<span style='white-space: nowrap'>&nbsp;B</span></code>
5102 is block diagonal with each block of size <code>
5103<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;n</span></code>
5104
5105(there is an integer <code>
5106<span style='white-space: nowrap'>&nbsp;N</span></code>
5107 such that
5108<code>
5109<span style='white-space: nowrap'>&nbsp;p&nbsp;=&nbsp;n&nbsp;*&nbsp;N</span></code>
5110 and <code>
5111<span style='white-space: nowrap'>&nbsp;r&nbsp;=&nbsp;m&nbsp;*&nbsp;N</span></code>
5112).
5113
5114
5115<br>
5116<br>
5117<b><big><a name="5.8.d" id="5.8.d">5.8.d: Lagrangian</a></big></b>
5118<br>
5119We use <code>
5120<span style='white-space: nowrap'>&nbsp;u&nbsp;\in&nbsp;\R^r</span></code>
5121
5122to denote the Lagrange multipliers corresponding to the constraint equation.
5123The corresponding Lagrangian is
5124<code>
5125<span style='white-space: nowrap'>&nbsp;\[<br>
5126L(y,&nbsp;s,&nbsp;u)&nbsp;&nbsp;=<br>
5127\frac{1}{2}&nbsp;y^\T&nbsp;H&nbsp;y&nbsp;+&nbsp;d^\T&nbsp;y<br>
5128-&nbsp;\mu&nbsp;\sum_{i=1}^r&nbsp;\log(s_i)<br>
5129+&nbsp;u^\T&nbsp;(s&nbsp;+&nbsp;b&nbsp;+&nbsp;B&nbsp;y)<br>
5130\]&nbsp;</span></code>
5131
5132The partial gradients of the Lagrangian are given by
5133<code>
5134<span style='white-space: nowrap'>&nbsp;\[<br>
5135\begin{array}{rcl}<br>
5136\nabla_y&nbsp;L(y,&nbsp;s,&nbsp;u&nbsp;)&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;H&nbsp;y&nbsp;+&nbsp;B^\T&nbsp;u&nbsp;+&nbsp;d&nbsp;&nbsp;\\<br>
5137\nabla_s&nbsp;L(y,&nbsp;s,&nbsp;u&nbsp;)&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;u&nbsp;-&nbsp;\mu&nbsp;/&nbsp;s&nbsp;\\<br>
5138\nabla_u&nbsp;L(y,&nbsp;s,&nbsp;u&nbsp;)&nbsp;&amp;&nbsp;=&nbsp;&amp;&nbsp;s&nbsp;+&nbsp;b&nbsp;+&nbsp;B&nbsp;y&nbsp;\\<br>
5139\end{array}<br>
5140\]&nbsp;</span></code>
5141
5142where <code>
5143<span style='white-space: nowrap'>&nbsp;\mu&nbsp;/&nbsp;s&nbsp;</span></code>
5144 is the component by component division of
5145<code>
5146<span style='white-space: nowrap'>&nbsp;\mu&nbsp;</span></code>
5147 by the components of the <code>
5148<span style='white-space: nowrap'>&nbsp;s</span></code>
5149.
5150Note, from the second equation, that we only need consider
5151<code>
5152<span style='white-space: nowrap'>&nbsp;u&nbsp;\geq&nbsp;0</span></code>
5153 because <code>
5154<span style='white-space: nowrap'>&nbsp;s&nbsp;\geq&nbsp;0</span></code>
5155.
5156
5157<br>
5158<br>
5159<b><big><a name="5.8.e" id="5.8.e">5.8.e: Kuhn-Tucker Residual</a></big></b>
5160<br>
5161We use <code>
5162<span style='white-space: nowrap'>&nbsp;D(s)</span></code>
5163 
5164to denote the diagonal matrix with <code>
5165<span style='white-space: nowrap'>&nbsp;s</span></code>
5166
5167along its diagonal and <code>
5168<span style='white-space: nowrap'>&nbsp;1_r</span></code>
5169 
5170to denote the vector, of length <code>
5171<span style='white-space: nowrap'>&nbsp;r</span></code>
5172 with all its components
5173equal to one.
5174The Kuhn-Tucker Residual function
5175<code>
5176<span style='white-space: nowrap'>&nbsp;F&nbsp;:&nbsp;\R^{r&nbsp;+&nbsp;p&nbsp;+&nbsp;r}&nbsp;\rightarrow&nbsp;\R^{r&nbsp;+&nbsp;p&nbsp;+&nbsp;r}</span></code>
5177
5178is defined by
5179<code>
5180<span style='white-space: nowrap'>&nbsp;\[<br>
5181F(s,&nbsp;y,&nbsp;u)<br>
5182=<br>
5183\left(<br>
5184\begin{array}{c}<br>
5185s&nbsp;+&nbsp;b&nbsp;+&nbsp;B&nbsp;y&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
5186H&nbsp;y&nbsp;+&nbsp;B^\T&nbsp;u&nbsp;+&nbsp;d&nbsp;&nbsp;&nbsp;\\<br>
5187D(s)&nbsp;D(u)&nbsp;1_r&nbsp;-&nbsp;\mu&nbsp;1_r<br>
5188\end{array}<br>
5189\right)<br>
5190\]&nbsp;</span></code>
5191
5192The Kuhn-Tucker conditions for a solution of the
5193<code>
5194<span style='white-space: nowrap'>&nbsp;\mu</span></code>
5195-relaxed constrained affine Kalman-Bucy smoother problem is
5196<code>
5197<span style='white-space: nowrap'>&nbsp;F(s,&nbsp;y,&nbsp;u)&nbsp;=&nbsp;0&nbsp;</span></code>
5198.
5199
5200<br>
5201<br>
5202<b><big><a name="5.8.f" id="5.8.f">5.8.f: mu</a></big></b>
5203<br>
5204The argument <i>mu</i> is a positive scalar specifying the
5205relaxation parameter <code>
5206<span style='white-space: nowrap'>&nbsp;\mu</span></code>
5207.
5208
5209<br>
5210<br>
5211<b><big><a name="5.8.g" id="5.8.g">5.8.g: s</a></big></b>
5212<br>
5213The argument <i>s</i> is a column vector of length <code>
5214<span style='white-space: nowrap'>&nbsp;r</span></code>
5215.
5216All the elements of <i>s</i> are greater than zero.
5217
5218<br>
5219<br>
5220<b><big><a name="5.8.h" id="5.8.h">5.8.h: y</a></big></b>
5221<br>
5222The argument <i>y</i> is a column vector of length <code>
5223<span style='white-space: nowrap'>&nbsp;p</span></code>
5224
5225
5226<br>
5227<br>
5228<b><big><a name="5.8.i" id="5.8.i">5.8.i: u</a></big></b>
5229<br>
5230The argument <i>u</i> is a column vector of length <code>
5231<span style='white-space: nowrap'>&nbsp;r</span></code>
5232.
5233All the elements of <i>s</i> are greater than zero.
5234
5235<br>
5236<br>
5237<b><big><a name="5.8.j" id="5.8.j">5.8.j: b</a></big></b>
5238<br>
5239The argument <i>b</i> is a column vector of length <code>
5240<span style='white-space: nowrap'>&nbsp;r</span></code>
5241.
5242
5243<br>
5244<br>
5245<b><big><a name="5.8.k" id="5.8.k">5.8.k: d</a></big></b>
5246<br>
5247The argument <i>d</i> is a column vector of length <code>
5248<span style='white-space: nowrap'>&nbsp;p</span></code>
5249
5250
5251<br>
5252<br>
5253<b><big><a name="5.8.l" id="5.8.l">5.8.l: Bdia</a></big></b>
5254<br>
5255The argument <i>Bdia</i> is an <code>
5256<span style='white-space: nowrap'>&nbsp;m&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
5257 array.
5258For <code>
5259<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
5260 we define <code>
5261<span style='white-space: nowrap'>&nbsp;B_k&nbsp;\in&nbsp;\R^{m&nbsp;\times&nbsp;n}</span></code>
5262 by
5263<code>
5264<span style='white-space: nowrap'>&nbsp;\[<br>
5265&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;B_k&nbsp;=&nbsp;Bdia(:,&nbsp;:,&nbsp;k)<br>
5266\]&nbsp;</span></code>
5267
5268
5269<br>
5270<br>
5271<b><big><a name="5.8.m" id="5.8.m">5.8.m: B</a></big></b>
5272<br>
5273The matrix <code>
5274<span style='white-space: nowrap'>&nbsp;B</span></code>
5275 is defined by
5276<code>
5277<span style='white-space: nowrap'>&nbsp;\[<br>
5278B&nbsp;<br>
5279=<br>
5280\left(&nbsp;\begin{array}{cccc}<br>
5281B_1&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
52820&nbsp;&nbsp;&nbsp;&amp;&nbsp;B_2&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
52830&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;\ddots&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
5284&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;B_N&nbsp;<br>
5285\end{array}&nbsp;\right)<br>
5286\]&nbsp;</span></code>
5287
5288
5289<br>
5290<br>
5291<b><big><a name="5.8.n" id="5.8.n">5.8.n: Hdia</a></big></b>
5292<br>
5293The argument <i>Hdia</i> is an <code>
5294<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
5295 array.
5296For <code>
5297<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
5298 we define <code>
5299<span style='white-space: nowrap'>&nbsp;H_k&nbsp;\in&nbsp;\R^{n&nbsp;\times&nbsp;n}</span></code>
5300 by
5301<code>
5302<span style='white-space: nowrap'>&nbsp;\[<br>
5303&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;H_k&nbsp;=&nbsp;Hdia(:,&nbsp;:,&nbsp;k)<br>
5304\]&nbsp;</span></code>
5305
5306
5307
5308<br>
5309<br>
5310<b><big><a name="5.8.o" id="5.8.o">5.8.o: Hlow</a></big></b>
5311<br>
5312The argument <i>Hlow</i> is an <code>
5313<span style='white-space: nowrap'>&nbsp;n&nbsp;\times&nbsp;n&nbsp;\times&nbsp;N</span></code>
5314 array.
5315For <code>
5316<span style='white-space: nowrap'>&nbsp;k&nbsp;=&nbsp;1&nbsp;,&nbsp;\ldots&nbsp;,&nbsp;N</span></code>
5317 we define <code>
5318<span style='white-space: nowrap'>&nbsp;L_k&nbsp;\in&nbsp;\R^{n&nbsp;\times&nbsp;n}</span></code>
5319 by
5320<code>
5321<span style='white-space: nowrap'>&nbsp;\[<br>
5322&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;L_k&nbsp;=&nbsp;Hlow(:,&nbsp;:,&nbsp;k)<br>
5323\]&nbsp;</span></code>
5324
5325
5326<br>
5327<br>
5328<b><big><a name="5.8.p" id="5.8.p">5.8.p: H</a></big></b>
5329<br>
5330The matrix <code>
5331<span style='white-space: nowrap'>&nbsp;H</span></code>
5332 is defined by
5333<code>
5334<span style='white-space: nowrap'>&nbsp;\[<br>
5335H&nbsp;<br>
5336=<br>
5337\left(&nbsp;\begin{array}{cccc}<br>
5338H_1&nbsp;&amp;&nbsp;L_2^\T&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
5339L_2&nbsp;&amp;&nbsp;H_2&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;L_3^\T&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
53400&nbsp;&nbsp;&nbsp;&amp;&nbsp;\ddots&nbsp;&amp;&nbsp;\ddots&nbsp;&amp;&nbsp;\ddots&nbsp;&nbsp;&nbsp;&nbsp;\\<br>
5341&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;0&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;L_N&nbsp;&nbsp;&nbsp;&nbsp;&amp;&nbsp;H_N&nbsp;<br>
5342\end{array}&nbsp;\right)<br>
5343\]&nbsp;</span></code>
5344
5345
5346<br>
5347<br>
5348<b><big><a name="5.8.q" id="5.8.q">5.8.q: F</a></big></b>
5349<br>
5350The result <i>F</i> is a column vector of length <code>
5351<span style='white-space: nowrap'>&nbsp;r&nbsp;+&nbsp;p&nbsp;+&nbsp;r</span></code>
5352
5353containing the value of the
5354<a href="#5.8.e">5.8.e: <span style='white-space: nowrap'>Kuhn-Tucker&nbsp;residual</span></a>
5355; i.e.,
5356<code>
5357<span style='white-space: nowrap'>&nbsp;F(s,&nbsp;y,&nbsp;u)</span></code>
5358.
5359
5360
5361
5362<br>
5363<br>
5364<b><big><a name="5.8.r" id="5.8.r">5.8.r: Example</a></big></b>
5365<br>
5366The file <a href="#5.8.1">5.8.1: <span style='white-space: nowrap'>kuhn_tucker_ok.m</span></a>
5367 contains an example and test of
5368<code><font color="blue">ckbs_kuhn_tucker</font></code>.
5369It returns true if <code><font color="blue">ckbs_kuhn_tucker</font></code> passes the test
5370and false otherwise.
5371
5372
5373<hr>Input File: src/ckbs_kuhn_tucker.m
5374
5375<hr>
5376 
5377
5378
5379<center><b><big><big><a name="5.8.1" id="5.8.1">5.8.1: ckbs_kuhn_tucker Example and Test</a>
5380</big></big></b></center>
5381<br>
5382<b><big><a name="5.8.1.a" id="5.8.1.a">5.8.1.a: Source Code</a></big></b>
5383
5384 <code><font color='blue'><pre style='display:inline'> 
5385function [ok] = kuhn_tucker_ok()
5386ok = true;
5387% -------------------------------------------------------------
5388% You can change these parameters
5389m    = 5;
5390n    = 4;
5391N    = 3;
5392% -------------------------------------------------------------
5393rand('seed', 123);
5394p     = n * N;
5395r     = m * N;
5396mu    = 1.5;
5397s     = rand(r, 1);
5398y     = rand(p, 1);
5399u     = rand(r, 1);
5400b     = rand(r, 1);
5401d     = rand(p, 1);
5402Bdia  = rand(m, n, N);
5403Hdia  = rand(n, n, N);
5404Hlow  = rand(n, n, N);
5405B     = zeros(r, p);
5406H     = zeros(p, p);
5407blk_n = 1 : n;
5408blk_m = 1 : m;
5409for k = 1 : N
5410        B(blk_m, blk_n) = Bdia(:,:, k);
5411        H(blk_n, blk_n) = Hdia(:,:, k);
5412        blk_n           = blk_n + n;
5413        blk_m           = blk_m + m;
5414end
5415blk_n = 1 : n;
5416for k = 2 : N;
5417        blk_minus           = blk_n;
5418        blk_n               = blk_n + n;
5419        H(blk_n, blk_minus) = Hlow(:,:, k);
5420        H(blk_minus, blk_n) = Hlow(:,:, k)';
5421end
5422% -------------------------------------
5423F = ckbs_kuhn_tucker(mu, s, y, u, b, d, Bdia, Hdia, Hlow);
5424% -------------------------------------
5425check = [ ...
5426        s + b + B * y; ...
5427        H * y + B' * u + d; ...
5428        s .* u - mu ...
5429];
5430ok    = ok &amp; ( max(abs(F - check)) &lt; 1e-10 );
5431return
5432end
5433</pre></font></code>
5434 
5435
5436<hr>Input File: test/kuhn_tucker_ok.m
5437
5438<hr>
5439 
5440
5441
5442<center><b><big><big><a name="6" id="6">6: Run All Correctness Tests</a>
5443</big></big></b></center>
5444<br>
5445<b><big><a name="6.a" id="6.a">6.a: Syntax</a></big></b>
5446
5447<br>
5448<code><font color="blue"><span style='white-space: nowrap'>all_ok<br>
5449all_ok(</span></font></code><i><span style='white-space: nowrap'>quick</span></i><code><font color="blue"><span style='white-space: nowrap'>)</span></font></code>
5450
5451<br>
5452<br>
5453<b><big><a name="6.b" id="6.b"