\input texinfo @c -*-texinfo-*-
@c Copyright (c) 2006-2012, Thomas Treichl <treichl@users.sourceforge.net>
@c OdePkg - A package for solving ordinary differential equations and more

@c For manually generating the documentation use
@c   LANGUAGE=en makeinfo --html --no-split odepkg.texi

@c %*** Start of HEADER
@setfilename odepkg.info
@settitle OdePkg - A package for solving ordinary differential equations and more
@afourpaper
@set VERSION 0.8.5
@c @afourwide
@c %*** End of the HEADER

@c %*** Start of TITLEPAGE
@titlepage
@title OdePkg @value{VERSION}
@subtitle A package for solving ordinary differential equations and more
@c @subtitle @b{OdePkg and this document currently are under development}
@author by Thomas Treichl
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 2006-2012, Thomas Treichl

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the same conditions as for modified versions.
@end titlepage
@c %*** End of TITLEPAGE

@c %*** Start of BODY
@contents
@ifnottex
@node Top, Beginners Guide, (dir), (dir)
@top Copyright

Copyright @copyright{} 2006-2012, Thomas Treichl 

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the same conditions as for modified versions.
@end ifnottex

@menu
* Beginners Guide::            Manual for users who are completely new to OdePkg
* Users Guide::               Manual for users who are already familiar with OdePkg
* Programmers Guide::          Manual for users who want to make changes to OdePkg
* Function Index::             Reference about all functions from this package
* Index::                      OdePkg Reference
@end menu

@c %*** Start of first chapter: Beginners Guide
@node Beginners Guide, Users Guide, Top, Top
@chapter Beginners Guide
@cindex Beginners guide
The ``Beginners Guide'' is intended for users who are new to OdePkg and who want to solve differential equations with the Octave language and the package OdePkg. In this section it will be explained what OdePkg is about in @ref{About OdePkg} and how OdePkg grew up from the beginning in @ref{OdePkg history and roadmap}. In @ref{Installation and deinstallation} it is explained how OdePkg can be installed in Octave and how it can later be removed from Octave if it is not needed anymore. If you encounter problems while using OdePkg then have a look at @ref{Reporting Bugs} how these bugs can be reported. In the @ref{The "foo" example} a first example is explained.

@menu
* About OdePkg::                An introduction about OdePkg
* OdePkg history and roadmap::  From the first OdePkg release to the future
* Installation and deinstallation::  Setting up OdePkg on your system
* Reporting Bugs::              Writing comments and bugs to the help list
* The "foo" example::         A first example and where to go from here
@end menu

@node About OdePkg, OdePkg history and roadmap, Beginners Guide, Beginners Guide
@section About OdePkg
@cindex About OdePkg
OdePkg is part of the @b{Octave Repository} (resp. the Octave--Forge project) that was initiated by Matthew W. Roberts and Paul Kienzle in the year 2000 and that is hosted at @url{http://octave.sourceforge.net}. Since then a lot of contributors joined this project and added a lot more packages and functions to further extend the capabilities of GNU Octave.
@c The email from Matthew W. Roberts about Octave--forge can be found here:
@c http://velveeta.che.wisc.edu/octave/lists/archive/octave-sources.2000/msg00110.html

OdePkg includes commands for setting up various options, output functions etc. before solving a set of differential equations with the solver functions that are included. The package formerly was initiated in autumn 2006 to solve ordinary differential equations (ODEs) only but there are already improvements so that differential algebraic equations (DAEs) in explicit form and in implicit form (IDEs) and delay differential equations (DDEs) can also be solved. The goal of OdePkg is to have a package for solving differential equations that is mostly compatible to proprietary solver products.

@node OdePkg history and roadmap, Installation and deinstallation, About OdePkg, Beginners Guide
@section OdePkg history and roadmap
@cindex history
@cindex roadmap

@multitable @columnfractions .25 .75
@item OdePkg Version 0.0.1
@tab The initial release was a modification of the old ``ode'' package that is hosted at Octave--Forge and that was written by Marc Compere somewhen between 2000 and 2001. The four variable step--size Runge--Kutta algorithms in three solver files and the three fixed step--size solvers have been merged. It was possible to set some options for these solvers. The four output--functions (@command{odeprint}, @command{odeplot}, @command{odephas2} and @command{odephas3}) have been added along with other examples that initially have not been there.
@item OdePkg Version 0.1.x
@tab The major milestone along versions 0.1.x was that four stable solvers have been implemented (ie. @command{ode23}, @command{ode45}, @command{ode54} and @command{ode78}) supporting all options that can be set for these kind of solvers and also all necessary functions for setting their options (eg. @command{odeset}, @command{odepkg_structure_check, odepkg_event_handle}). Since version 0.1.3 there is also source code available that interfaces the Fortran solver @file{dopri5.f} (that is written by Ernst Hairer and Gerhard Wanner, cf. @file{odepkg_mexsolver_dopri5.c} and the helper files @file{odepkgext.c} and @file{odepkgmex.c}).
@item OdePkg Version 0.2.x
@tab The main work along version 0.2.x was to make the interface functions for the non--stiff and stiff solvers from Ernst Hairer and Gerhard Wanner enough stable so that they could be compiled and installed by default. Wrapper functions have been added to the package containing a help text and test functions (eg. @command{ode2r}, @command{ode5r}, @command{oders}). Six testsuite functions have been added to check the performance of the different solvers (eg. @command{odepkg_testsuite_chemakzo}, @command{odepkg_testsuite_oregonator}).
@item OdePkg Version 0.3.x
@tab Fixed some minor bugs along version 0.3.x. Thanks to Jeff Cash, who released his Fortran @command{mebdfX} solvers under the GNU GPL V2 after some discussion. The first IDE solver @command{odebdi} appeared that is an interface function for Cash's @command{mebdfi} Fortran core solver. With version 0.3.5 of OdePkg a first new interface function was created based on Octave's C++ @code{DEFUN_DLD} interface to achieve the highest performance available. Added more examples and testsuite functions (eg. @command{odepkg_equations_ilorenz}, @command{odepkg_testsuite_implrober}). Porting all at this time present Mex--file solvers to Octave's C++ @code{DEFUN_DLD} interface. Ongoing work with this manual. 
@item OdePkg Version 0.4.x
@tab Added a new solver function @command{odekdi} for the direct method (not the Krylov method) of the @file{daskr.f} solver from the authors Peter N. Brown, Alan C. Hindmarsh, Linda R. Petzold and Clement W. Ulrich that is available under a modified BSD license (without advertising clause). Ongoing work with this manual.
@item OdePkg Version 0.5.x
@tab Added new solver functions @command{ode23d}, @command{ode45d}, @command{ode54d} and @command{ode78d} for solving non--stiff delay differential equations (non-stiff DDEs). These solvers are based on the Runge--Kutta solvers @command{ode23}..@command{ode78}. Tests and demos have been included for this type of solvers. Added new functions @command{odeexamples}, @command{odepkg_examples_ode}, @command{odepkg_examples_dae}, @command{odepkg_examples_ide} and @command{odepkg_examples_ide}. Ongoing work with this manual.
@item OdePkg Version 0.6.x
@tab A lot of compatibility tests, improvements, bugfixes, etc.
@item @b{(current)} Version 0.8.x
@tab Final releases before version 1.0.0.
@item @b{(future)} Version 1.0.0
@tab Completed OdePkg release 1.0.0 with M--solvers and DLD--solvers.
@end multitable

@node Installation and deinstallation, Reporting Bugs, OdePkg history and roadmap, Beginners Guide
@section Installation and deinstallation
@cindex installation
@cindex deinstallation

OdePkg can be installed easily using the @command{pkg} command in Octave. To install OdePkg download the latest release of OdePkg from the Octave--Forge download site, then get into that directory where the downloaded release of OdePkg has been saved, start Octave and type
@example
pkg install odepkg-x.x.x.tar.gz
@end example
where @file{x.x.x} in the name of the @file{*.tar.gz} file is the current release number of OdePkg that is available. If you want to deinstall resp. remove OdePkg then simply type
@example
pkg uninstall odepkg
@end example
and make sure that OdePkg has been removed completely and does not appear in the list of installed packages anymore with the following command
@example
pkg list
@end example

@node Reporting Bugs, The "foo" example, Installation and deinstallation, Beginners Guide
@section Reporting Bugs
@cindex bugs
If you encounter problems during the installation process of OdePkg with the @command{pkg} command or if you have an OdePkg that seems to be broken or if you encounter problems while using OdePkg or if you find bugs in the source codes then please report all of that via email at the Octave--Forge mailing--list using the email address 
@ifnothtml
@email{octave-dev@@lists.sourceforge.net}.
@end ifnothtml 
@ifhtml
@email{octave-dev @{at] lists.sourceforge.net} (replace @{at] with @@).
@end ifhtml 
Not only bugs are welcome but also any kind of comments are welcome (eg. if you think that OdePkg is absolutely useful or even unnecessary).

@node The "foo" example,  , Reporting Bugs, Beginners Guide
@section The "foo" example
@cindex foo example
Have a look at the first ordinary differential equation with the name ``@command{foo}''. The @command{foo} equation of second order may be of the form 
@ifhtml
@example
@math{y''(t) + C1 y'(t) + C2 y(t) = C3}
@end example
@end ifhtml
@ifnothtml
@math{y''(t) + C_1 y'(t) + C_2 y(t) = C_3}.
@end ifnothtml
With the substitutions
@ifhtml
@example
@math{y1(t) = y(t)}
@math{y2(t) = y'(t)}
@end example
@end ifhtml
@ifnothtml
@math{y_1(t) = y(t)} and @math{y_2(t) = y'(t)}
@end ifnothtml
this differential equation of second order can be split into two differential equations of first order, ie.
@ifhtml
@example
@math{y1'(t) = y2(t)}
@math{y2'(t) = - C1 y2(t) - C2 y1(t) + C3}
@end example
@end ifhtml
@ifnothtml
@math{y'_1(t) = y_2(t)} and @math{y'_2(t) = - C_1 y_2(t) - C_2 y_1(t) + C_3}.
@end ifnothtml
Next the numerical values for the constants need to be defined, ie.
@ifhtml
@example
@math{C1 = 2.0}
@math{C2 = 5.0}
@math{C3 = 10.0}
@end example
@end ifhtml
@ifnothtml
@math{C_1 = 2.0}, @math{C_2 = 5.0}, @math{C_3 = 10.0}.
@end ifnothtml
This set of ordinary differential equations can then be written as an Octave M--file function like
@example
function vdy = foo (vt, vy, varargin)
  vdy(1,1) = vy(2);
  vdy(2,1) = - 2.0 * vy(2) - 5.0 * vy(1) + 10.0;
endfunction
@end example
It can be seen that this ODEs do not depend on time, nevertheless the first input argument of this function needs to be defined as the time argument @var{vt} followed by a solution array argument @command{vy} as the second input argument and a variable size input argument @command{varargin} that can be used to set up user defined constants or control variables.

As it is known that @command{foo} is a set of @i{ordinary} differential equations we can choose one of the four Runge--Kutta solvers (cf. @ref{Solver families}). It is also known that the time period of interest may be between
@ifhtml
@example
@math{t0 = 0.0}
@math{te = 5.0}
@end example
@end ifhtml
@ifnothtml
@math{t_0 = 0.0} and @math{t_e = 5.0}
@end ifnothtml
as well as that the initial values of the ODEs are
@ifhtml
@example
@math{y1(t=0) = 0.0}
@math{y2(t=0) = 0.0}
@end example
@end ifhtml
@ifnothtml
@math{y_1(t=0) = 0.0} and @math{y_2(t=0) = 0.0}.
@end ifnothtml
Solving this set of ODEs can be done by typing the following commands in Octave
@example
ode45 (@@foo, [0 5], [0 0]);
@end example
A figure window opens and it can be seen how this ODEs are solved over time. For some of the solvers that come with OdePkg it is possible to define exact time stamps for which an solution is required. Then the example can be called eg.@example
ode45 (@@foo, [0:0.1:5], [0 0]);
@end example
If it is not wanted that a figure window is opened while solving then output arguments have to be used to catch the results of the solving process and to not pass the results to the figure window, eg.
@example
[t, y] = ode45 (@@foo, [0 5], [0 0]);
@end example
Results can also be obtained in form of an Octave structure if one output argument is used like in the following example. Then the results are stored in the fields @command{S.x} and @command{S.y}.
@example
S = ode45 (@@foo, [0 5], [0 0]);
@end example
As noticed before, a function for the ordinary differential equations must not be rewritten all the time if some of the parameters are going to change. That's what the input argument @command{varargin} can be used for. So rewrite the function @command{foo} into @command{newfoo} the following way
@example
function vdy = newfoo (vt, vy, varargin)
  vdy(1,1) = vy(2);
  vdy(2,1) = -varargin@{1@}*vy(2)-varargin@{2@}*vy(1)+varargin@{3@};
endfunction
@end example
There is nothing said anymore about the constant values but if using the following caller routine in the Octave window then the same results can be obtained with the new function @command{newfoo} as before with the function @command{foo} (ie. the parameters are directly feed through from the caller routine @command{ode45} to the function @command{newfoo})
@example
ode45 (@@newfoo, [0 5], [0 0], 2.0, 5.0, 10.0);
@end example
OdePkg can do much more while solving differential equations, eg. setting up other output functions instead of the function @command{odeplot} or setting up other tolerances for the solving process etc. As a last example in this beginning chapter it is shown how this can be done, ie. with the command @command{odeset}
@example
A = odeset ('OutputFcn', @@odeprint);
ode45 (@@newfoo, [0 5], [0 0], A, 2.0, 5.0, 10.0);
@end example
or
@example
A = odeset ('OutputFcn', @@odeprint, 'AbsTol', 1e-5, \
            'RelTol', 1e-5, 'NormControl', 'on');
ode45 (@@newfoo, [0 5], [0 0], A, 2.0, 5.0, 10.0);
@end example
The options structure @command{A} that can be set up with with the command @command{odeset} must always be the fourth input argument when using the ODE solvers and the DAE solvers but if you are using an IDE solver then @command{A} must be the fifth input argument (cf. @ref{Solver families}). The various options that can be set with the command @command{odeset} are described in @ref{ODE/DAE/IDE/DDE options}.

Further examples have also been implemented. These example files and functions are of the form @command{odepkg_examples_*}. Different testsuite examples have been added that are stored in files with filenames @command{odepkg_testsuite_*}. Before reading the next chapter note that nearly every function that comes with OdePkg has its own help text and its own examples. Look for yourself how the different functions, options and combinations can be used. If you want to have a look at the help description of a special function then type
@example
help fcnname
@end example
in the Octave window where @command{fcnname} is the name of the function for the help text to be viewed. Type
@example
demo fcnname
@end example
in the Octave window where @command{fcnname} is the name of the function for the demo to run. Finally write 
@example
doc odepkg
@end example
for opening this manual in the texinfo reader of the Octave window.
@c %*** End of first chapter: Beginners Guide

@c %*** Start of second chapter: Users Guide
@node Users Guide, Programmers Guide, Beginners Guide, Top
@chapter Users Guide
@cindex Users guide
The ``Users Guide'' is intended for trained users who already know in principal how to solve differential equations with the Octave language and OdePkg. In this chapter it will be explained which equations can be solved with OdePkg in @ref{Differential Equations}. It will be explained which solvers can be used for the different kind of equations in @ref{Solver families} and which options can be set for the optimization of the solving process in @ref{ODE/DAE/IDE/DDE options}. The help text of all M--file functions and all Oct--file functions have been extracted and are displayed in the sections @ref{M-File Function Reference} and @ref{Oct-File Function Reference}.

@menu
* Differential Equations::      The different kind of problems that can be solved with OdePkg
* Solver families::             The different kind of solvers within OdePkg
* ODE/DAE/IDE/DDE options::     The options that can be set for a solving process
* M-File Function Reference::   The description about all @file{*.m}-file functions
* Oct-File Function Reference::  The description about all DLD-functions from @file{*.oct}-files
@end menu

@node Differential Equations, Solver families, Users Guide, Users Guide
@section Differential Equations
@cindex differential equations
In this section the different kind of differential equations that can be solved with OdePkg are explained. The formulation of ordinary differential equations is described in section @ref{ODE equations} followed by the description of explicetly formulated differential algebraic equations in section @ref{DAE equations}, implicetely formulated differential algebraic equations in section @ref{IDE equations} and delay differential algebraic equations in section @ref{DDE equations}.

@menu
* ODE equations::               Ordinary differential equations
* DAE equations::               Differential algebraic equations in explicit form
* IDE equations::               Differential algebraic equations in implicit form
* DDE equations::               Delay differential equations
@end menu

@node ODE equations, DAE equations, Differential Equations, Differential Equations
@subsection ODE equations
@cindex ode equations
ODE equations in general are of the form
@ifhtml
@example
@math{y'(t) = f(t,y)}
@end example
@end ifhtml
@ifnothtml
@math{y'(t) = f(t,y)}
@end ifnothtml
where @math{y'(t)} may be a scalar or vector of derivatives. The variable @math{t} always is a scalar describing one point of time and the variable @math{y(t)} is a scalar or vector of solutions from the last time step of the set of ordinary differential equations. If the equation is non--stiff then the @ref{Runge-Kutta solvers} can be used to solve such kind of differential equations but if the equation is stiff then it is recommended to use the @ref{Hairer-Wanner solvers}. An ODE equation definition in Octave must look like
@example
function [dy] = ODEequation (t, y, varargin)
@end example

@node DAE equations, IDE equations, ODE equations, Differential Equations
@subsection DAE equations
@cindex dae equations
DAE equations in general are of the form
@ifhtml
@example
@math{M(t,y) y'(t) = f(t,y)}
@end example
@end ifhtml
@ifnothtml
@math{M(t,y) \cdot y'(t) = f(t,y)}
@end ifnothtml
where @math{y'(t)} may be a scalar or vector of derivatives. The variable @math{t} always is a scalar describing one point of time and the variable @math{y(t)} is a scalar or vector of solutions from the set of differential algebraic equations. The variable @math{M(t,y)} is the squared @i{singular} mass matrix that may depend on @math{y} and @math{t}. If @math{M(t,y)} is not @i{singular} then the set of equations from above can normally also be written as an ODE equation. If it does not depend on time then it can be defined as a constant matrix or a function. If it does depend on time then it must be defined as a function. Use the command @command{odeset} to pass the mass matrix information to the solver function (cf. @ref{ODE/DAE/IDE/DDE options}). If the equation is non--stiff then the @ref{Runge-Kutta solvers} can be used to solve such kind of differential equations but if the equation is stiff then it is recommended to use the @ref{Hairer-Wanner solvers}. A DAE equation definition in Octave must look like
@example
function [dy] = DAEequation (t, y, varargin)
@end example
and the mass matrix definition can either be a constant mass matrix or a valid function handle to a mass matrix calculation function that can be set with the command @command{odeset} (cf. option @code{Mass} of section @ref{ODE/DAE/IDE/DDE options}).

@node IDE equations, DDE equations, DAE equations, Differential Equations
@subsection IDE equations
@cindex ide equations
IDE equations in general are of the form
@ifhtml
@example
@math{y'(t) + f(t,y) = 0}
@end example
@end ifhtml
@ifnothtml
@math{y'(t) + f(t,y) = 0}
@end ifnothtml
where @math{y'(t)} may be a scalar or vector of derivatives. The variable @math{t} always is a scalar describing one point of time and the variable @math{y(t)} is a scalar or vector of solutions from the set of implicit differential equations. Only IDE solvers from section @ref{Cash modified BDF solvers} or section @ref{DDaskr direct method solver} can be used to solve such kind of differential equations. A DAE equation definition in Octave must look like
@example
function [residual] = IDEequation (t, y, dy, varargin)
@end example

@node DDE equations,  , IDE equations, Differential Equations
@subsection DDE equations
@cindex dde equations
DDE equations in general are of the form
@ifhtml
@example
@math{y'(t) = f(t,y(t),y(t-tau_1),...,y(t-tau_n))}
@end example
@end ifhtml
@ifnothtml
@math{y'(t) = f(t,y(t),y(t-\tau_1),...,y(t-\tau_n))}
@end ifnothtml
where @math{y'(t)} may be a scalar or vector of derivatives. The variable @math{t} always is a scalar describing one point of time and the variables
@ifhtml
@math{y(t-tau_i)}
@end ifhtml
@ifnothtml
@math{y(t-\tau_i)}
@end ifnothtml
are scalars or vectors from the past. Only DDE solvers from section @ref{Modified Runge-Kutta solvers} can be used to solve such kind of differential equations. A DDE equation definition in Octave must look like
@example
function [dy] = DDEequation (t, y, z, varargin)
@end example
@b{NOTE:} Only DDEs with constant delays 
@ifhtml
@math{y(t-tau_i)}
@end ifhtml
@ifnothtml
@math{y(t-\tau_i)}
@end ifnothtml
can be solved with OdePkg.

@node Solver families, ODE/DAE/IDE/DDE options, Differential Equations, Users Guide
@section Solver families
@cindex solver families
In this section the different kind of solvers are introduced that have been implemented in OdePkg. This section starts with the basic Runge--Kutta solvers in section @ref{Runge-Kutta solvers} and is continued with the Mex--file Hairer--Wanner solvers in section @ref{Hairer-Wanner solvers}. @c Other solvers are described in section @ref{Other solvers}.
Performance tests have also been added to the OdePkg. Some of these performance results have been added to section @ref{ODE solver performances}.

@menu
* Runge-Kutta solvers::         ODE solvers written as @file{*.m} files
* Hairer-Wanner solvers::       DAE solvers interfaced by @file{*.cc} files
* Cash modified BDF solvers::  A DAE and an IDE solver interfaced by @file{*.cc} files
* DDaskr direct method solver::  An IDE solver interfaced by a @file{*.cc} file
* Modified Runge-Kutta solvers::  DDE solvers written as @file{*.m} files
* ODE solver performances::     Cross math-engine performance tests
@end menu

@node Runge-Kutta solvers, Hairer-Wanner solvers, Solver families, Solver families
@subsection Runge--Kutta solvers
@cindex Runge--Kutta
The Runge--Kutta solvers are written in the Octave language and that are saved as @file{m}--files. There have been implemented four different solvers with a very similiar structure, ie. @command{ode23}, @command{ode45}, @command{ode54} and @command{ode78}@footnote{The descriptions for these Runge--Kutta solvers have been taken from the help texts of the initial Runge--Kutta solvers that were written by Marc Compere, he also pointed out that ''a relevant discussion on step size choice can be found on page 90ff in U.M. Ascher, L.R. Petzold, Computer Methods for  Ordinary Differential Equations and Differential--Agebraic Equations, Society for Industrial and Applied Mathematics (SIAM), Philadelphia, 1998''.}. The Runge--Kutta solvers have been added to the OdePkg to solve non--stiff ODEs and DAEs, stiff equations of that form cannot be solved with these solvers.

The order of all of the following Runge--Kutta methods is the order of the local truncation error, which is the principle error term in the portion of the Taylor series expansion that gets dropped, or intentionally truncated. This is different from the local error which is the difference between the estimated solution and the actual, or true solution. The local error is used in stepsize selection and may be approximated by the difference between two estimates of different order,
@ifhtml
@example
@math{l(h) = x(O(h+1)) - x(O(h))}
@end example
@end ifhtml
@ifnothtml
@math{l(h) = x(O(h+1)) - x(O(h))}.
@end ifnothtml
With this definition, the local error will be as large as the error in the lower order method. The local truncation error is within the group of terms that gets multipled by @math{h} when solving for a solution from the general Runge--Kutta method. Therefore, the order--p solution created by the Runge--Kunge method will be roughly accurate to
@ifhtml
@example
@math{O(h^{(p+1)})}
@end example
@end ifhtml
@ifnothtml
@math{O(h^{(p+1)})}
@end ifnothtml
since the local truncation error shows up in the solution as
@ifhtml
@example
@math{e = h d}
@end example
@end ifhtml
@ifnothtml
@math{e = h\cdot d}
@end ifnothtml
which is @math{h}--times an @math{O(h^p)}--term, or rather @math{O(h^{(p+1)})}.

@multitable @columnfractions .075 .925
@item @command{ode23}
@tab Integrates a system of non--stiff ordinary differential equations (non--stiff ODEs and DAEs) using second and third order Runge--Kutta formulas. This particular third order method reduces to Simpson's @math{1/3} rule and uses the third order estimation for the output solutions. Third order accurate Runge--Kutta methods have local and global errors of @math{O(h^4)} and @math{O(h^3)} respectively and yield exact results when the solution is a cubic (the variable @math{h} is the step size from one integration step to another integration step). This solver requires three function evaluations per integration step.@*

@item  @command{ode45}
@tab Integrates a system of non--stiff ordinary differential equations (non--stiff ODEs and DAEs) using fourth and fifth order embedded formulas from Fehlberg. This is a fourth--order accurate integrator therefore the local error normally expected is @math{O(h^5)}. However, because this particular implementation uses the fifth--order estimate for @math{x_{out}} (ie. local extrapolation) moving forward with the fifth--order estimate should yield local error of @math{O(h^6)}. This solver requires six function evaluations per integration step.@*

@item @command{ode54}
@tab Integrates a system of non--stiff ordinary differential equations (non--stiff ODEs and DAEs) using fifth and fourth order Runge--Kutta formulas. The Fehlberg @math{4(5)} of the @command{ode45} pair is established and works well, however, the Dormand--Prince @math{5(4)} pair minimizes the local truncation error in the fifth--order estimate which is what is used to step forward (local extrapolation). Generally it produces more accurate results and costs roughly the same computationally. This solver requires seven function evaluations per integration step.@*

@item @command{ode78}
@tab Integrates a system of non--stiff ordinary differential equations (non--stiff ODEs and DAEs) using seventh and eighth order Runge--Kutta formulas. This is a seventh--order accurate integrator therefore the local error normally expected is @math{O(h^8)}. However, because this particular implementation uses the eighth--order estimate for @math{x_{out}} moving forward with the eighth--order estimate will yield errors on the order of @math{O(h^9)}. This solver requires thirteen function evaluations per integration step.
@end multitable

@node Hairer-Wanner solvers, Cash modified BDF solvers, Runge-Kutta solvers, Solver families
@subsection Hairer--Wanner solvers
@cindex Hairer--Wanner
The Hairer--Wanner solvers have been written by Ernst Hairer and Gerhard Wanner. They are written in the Fortran language (hosted at @url{http://www.unige.ch/~hairer}) and that have been added to the OdePkg as a compressed file with the name @file{hairer.tgz}. Papers and other details about these solvers can be found at the adress given before. The licence of these solvers is a modified BSD license (without advertising clause and therefore are GPL compatible) and can be found as @file{licence.txt} file in the @file{hairer.tgz} package. The Hairer--Wanner solvers have been added to the OdePkg to solve non--stiff and stiff ODEs and DAEs that cannot be solved with any of the Runge--Kutta solvers.

Interface functions for these solvers have been created and have been added to the OdePkg. Their names are @file{odepkg_octsolver_XXX.cc} where @file{XXX} is the name of the Fortran file that is interfaced. The file @file{dldsolver.oct} is created automatically when installing OdePkg with the command @command{pkg}, but developers can also build each solver manually with the instructions given as a preamble of every @file{odepkg_octsolver_XXX.cc} file.

To provide a short name and to circumvent from the syntax of the original solver function wrapper functions have been added, eg. the command @command{ode2r} calls the solver @command{radau} from the Fortran file @file{radau.f}. The other wrapper functions for the Hairer--Wanner solvers are @command{ode5r} for the @command{radau5} solver, @command{oders} for the @command{rodas} solver and @command{odesx} for the @command{seulex} solver. The help text of all these solver functions can be diaplyed by calling @command{help wrapper} where wrapper is one of @command{ode2r}, @command{ode5r}, @command{oders} or @command{odesx}.

@node Cash modified BDF solvers, DDaskr direct method solver, Hairer-Wanner solvers, Solver families
@subsection Cash modified BDF solvers
@cindex BDF solver
@cindex Cash modified BDF
The backward differentiation algorithm solvers have been written by Jeff Cash in the Fortran language and that are hosted at @url{http://pitagora.dm.uniba.it/~testset}. They have been added to the OdePkg as a compressed file with the name @file{cash.tgz}. The license of these solvers is a General Public License V2 that can be found as a preamble of each Fortran solver source file. Papers and other details about these solvers can be found at the host adress given before and also at Jeff Cash's homepage at @url{http://www.ma.ic.ac.uk/~jcash}. Jeff Cash's modified BDF solvers have been added to the OdePkg to solve non--stiff and stiff ODEs and DAEs and also IDEs that cannot be solved with any of the Runge--Kutta solvers. 

Interface functions for these solvers have been created and have been added to the OdePkg. Their names are @file{odepkg_octsolver_XXX.cc} where @file{XXX} is the name of the Fortran file that is interfaced. The file @file{dldsolver.oct} is created automatically when installing OdePkg with the command @command{pkg}, but developers can also build each solver manually with the instructions given as a preamble of every @file{odepkg_octsolver_XXX.cc} file.

To provide a short name and to circumvent from the syntax of the original solver function wrapper functions have been added. The command @command{odebda} calls the solver @command{mebdfdae} from the Fortran file @file{mebdf.f} and the @command{odebdi} calls the solver @command{mebdfi} from the Fortran file @file{mebdfi.f}.

@node DDaskr direct method solver, Modified Runge-Kutta solvers, Cash modified BDF solvers, Solver families
@subsection DDaskr direct method solver
@cindex ddaskr solver
The direct method from the Krylov solver file @file{ddaskr.f} has been written by Peter N. Brown, Alan C. Hindmarsh, Linda R. Petzold and Clement W. Ulrich in the Fortran language and that is hosted at @url{http://www.netlib.org}. @b{The Krylov method has not been implemented within OdePkg, only the direct method has been implemented.} The solver and further files for the interface have been added to the OdePkg as a compressed package with the name @file{ddaskr.tgz}. The license of these solvers is a modfied BSD license (without advertising clause) that can be found inside of the compressed package. Other details about this solver can be found as a preamble in the source file @file{ddaskr.f}. The direct method solver of the file @file{ddaskr.f} has been added to the OdePkg to solve non--stiff and stiff IDEs.

An interface function for this solver has been created and has been added to the OdePkg. The source file name is @file{odepkg_octsolver_ddaskr.cc}. The binary function can be found in the file @file{dldsolver.oct} that is created automatically when installing OdePkg with the command @command{pkg}, but developers can also build the solver wrapper manually with the instructions given as a preamble of the @file{odepkg_octsolver_ddaskr.cc} file.

To provide a short name and to circumvent from the syntax of the original solver function a wrapper function has been added. The command @command{odekdi} calls the direct method of the solver @command{ddaskr} from the Fortran file @file{ddaskr.f}.

@node Modified Runge-Kutta solvers, ODE solver performances, DDaskr direct method solver, Solver families
@subsection Modified Runge--Kutta solvers
@cindex Runge--Kutta modified
The modified Runge--Kutta solvers are written in the Octave language and that are saved as m--files. There have been implemented four different solvers that do have a very similiar structure to that solvers found in section @ref{Runge-Kutta solvers}. Their names are @command{ode23d}, @command{ode45d}, @command{ode54d} and @command{ode78d}. The modified Runge--Kutta solvers have been added to the OdePkg to solve non--stiff DDEs with constant delays only, stiff equations of that form cannot be solved with these solvers. For further information about the error estimation of these solvers cf. section @ref{Runge-Kutta solvers}.

@b{Note:} The four DDE solvers of OdePkg are not syntax compatible to propietary solvers. The reason is that the input arguments of the propietary DDE--solvers are completely mixed up in comparison to ODE, DAE and IDE propietary solvers. The DDE solvers of OdePkg have been implemented in form of a syntax compatible way to the other family solvers, eg. propietary solver calls look like

@example
ode23  (@@fode, vt, vy)          %# for solving an ODE
ode15i (@@fide, vt, vy, vdy)     %# for solving an IDE
dde23  (@@fdde, vlag, vhist, vt) %# for solving a  DDE
@end example
whereas in OdePkg the same examples would look like
@example
ode23  (@@fode, vt, vy)              %# for solving an ODE
odebdi (@@fide, vt, vy, vdy)         %# for solving an IDE
ode23d (@@fdde, vt, vy, vlag, vhist) %# for solving a  DDE
@end example

Further, the commands @command{ddeset} and @command{ddeget} have not been implemented in OdePkg. Use the functions @command{odeset} and @command{odeget} for setting and returning DDE options instead.

@node ODE solver performances,  , Modified Runge-Kutta solvers, Solver families
@subsection ODE solver performances
@cindex performance

The following tables give an overview about the performance of the OdePkg ODE/DAE solvers in comparison to propietary solvers when running the HIRES function from the OdePkg testsuite (non--stiff ODE test).

@smallexample
>> odepkg ('odepkg_performance_mathires');
-----------------------------------------------------------------------------------------
 Solver  RelTol  AbsTol   Init   Mescd    Scd  Steps  Accept  FEval  JEval  LUdec    Time
-----------------------------------------------------------------------------------------
 ode113  1e-007  1e-007  1e-009   7.57   5.37  24317   21442  45760                11.697
  ode23  1e-007  1e-007  1e-009   7.23   5.03  13876   13862  41629                 2.634
  ode45  1e-007  1e-007  1e-009   7.91   5.70  11017   10412  66103                 2.994
 ode15s  1e-007  1e-007  1e-009   7.15   4.95    290     273    534      8     59   0.070
 ode23s  1e-007  1e-007  1e-009   6.24   4.03    702     702   2107    702    702   0.161
 ode23t  1e-007  1e-007  1e-009   6.00   3.79    892     886   1103      5     72   0.180
ode23tb  1e-007  1e-007  1e-009   5.85   3.65    735     731   2011      5     66   0.230
-----------------------------------------------------------------------------------------
@end smallexample

@smallexample
octave:1> odepkg ('odepkg_performance_octavehires');
-----------------------------------------------------------------------------------------
 Solver  RelTol  AbsTol   Init   Mescd    Scd  Steps  Accept  FEval  JEval  LUdec    Time
-----------------------------------------------------------------------------------------
  ode23   1e-07   1e-07   1e-09   7.86   5.44  17112   13369  51333               138.071
  ode45   1e-07   1e-07   1e-09   8.05   5.63   9397    9393  56376                92.065
  ode54   1e-07   1e-07   1e-09   8.25   5.83   9300    7758  65093                84.319
  ode78   1e-07   1e-07   1e-09   8.54   6.12   7290    6615  94757                97.746
  ode2r   1e-07   1e-07   1e-09   7.69   5.27     50      50    849     50     59   0.624
  ode5r   1e-07   1e-07   1e-09   7.55   5.13     71      71    671     71     81   0.447
  oders   1e-07   1e-07   1e-09   7.08   4.66    138     138    828    138    138   0.661
  odesx   1e-07   1e-07   1e-09   6.56   4.13     30      26   1808     26    205   1.057
 odebda   1e-07   1e-07   1e-09   6.53   4.11    401     400    582     42     42   0.378
-----------------------------------------------------------------------------------------
@end smallexample

The following tables give an overview about the performance of the OdePkg ODE/DAE solvers in comparison to propietary solvers when running the chemical AKZO--NOBEL function from the OdePkg testsuite (non--stiff ODE test).

@smallexample
>> odepkg ('odepkg_performance_matchemakzo');
-----------------------------------------------------------------------------------------
 Solver  RelTol  AbsTol   Init   Mescd    Scd  Steps  Accept  FEval  JEval  LUdec    Time
-----------------------------------------------------------------------------------------
 ode113  1e-007  1e-007  1e-007    NaN    Inf      -       -      -      -      -       - 
  ode23  1e-007  1e-007  1e-007    NaN    Inf     15      15     47                 0.431
  ode45  1e-007  1e-007  1e-007    NaN    Inf     15      15     92                 0.170
 ode15s  1e-007  1e-007  1e-007   7.04   6.20    161     154             4     35   0.521
 ode23s  1e-007  1e-007  1e-007   7.61   6.77   1676    1676   5029   1676   1677   2.704
 ode23t  1e-007  1e-007  1e-007   5.95   5.11    406     404             3     39   0.611
ode23tb  1e-007  1e-007  1e-007    NaN    Inf    607           3036      1    608   6.730
-----------------------------------------------------------------------------------------
@end smallexample

@smallexample
octave:1> odepkg ('odepkg_performance_octavechemakzo');
-----------------------------------------------------------------------------------------
 Solver  RelTol  AbsTol   Init   Mescd    Scd  Steps  Accept  FEval  JEval  LUdec    Time
-----------------------------------------------------------------------------------------
  ode23   1e-07   1e-07   1e-07   2.95   2.06    424     385   1269                 1.270
  ode45   1e-07   1e-07   1e-07   2.95   2.06    256     218   1530                 1.281
  ode54   1e-07   1e-07   1e-07   2.95   2.06    197     195   1372                 1.094
  ode78   1e-07   1e-07   1e-07   2.95   2.06    184     156   2379                 1.933
  ode2r   1e-07   1e-07   1e-07   8.50   7.57     39      39    372     39     43   0.280
  ode5r   1e-07   1e-07   1e-07   8.50   7.57     39      39    372     39     43   0.238
  oders   1e-07   1e-07   1e-07   7.92   7.04     67      66    401     66     67   0.336
  odesx   1e-07   1e-07   1e-07   7.19   6.26     19      19    457     19     82   0.248
 odebda   1e-07   1e-07   1e-07   7.47   6.54    203     203    307     25     25   0.182
-----------------------------------------------------------------------------------------
@end smallexample

Other testsuite functions have been added to the OdePkg that can be taken for further performance tests and syntax checks on your own hardware. These functions all have a name @file{odepkg_testsuite_XXX.m} with @file{XXX} being the name of the testsuite equation that has been implemented.

@node ODE/DAE/IDE/DDE options, M-File Function Reference, Solver families, Users Guide
@section ODE/DAE/IDE/DDE options
@cindex ode options
@cindex dae options
@cindex ide options
@cindex dde options
The default values of an OdePkg options structure can be displayed with the command @command{odeset}. If @command{odeset} is called without any input argument and one output argument then a OdePkg options structure with default values is created, eg.
@example
A = odeset ();
disp (A);
@end example
There also is an command @command{odeget} which extracts one or more options from an OdePkg options structure. Other values than default values can also be set with the command @command{odeset}. The function description of the commands @command{odeset} and @command{odeget} can be found in the @ref{M-File Function Reference}. The values that can be set with the @command{odeset} command are

@table @samp
@item RelTol
@cindex RelTol option
The option @option{RelTol} is used to set the relative error tolerance for the error estimation of the solver that is used while solving. It can either be a positive scalar or a vector with every element of the vector being a positive scalar (this depends on the solver that is used if both variants are supported). The definite error estimation equation also depends on the solver that is used but generalized (eg. for the solvers @command{ode23}, @command{ode45}, @command{ode54} and @command{ode78}) it may be a form like
@ifhtml
@example
@math{e(t) = max (RelTol^T y(t), AbsTol)}
@end example
@end ifhtml
@ifnothtml
@math{e(t) = max (r_{tol}^T y(t), a_{tol})}.
@end ifnothtml
Run the following example to illustrate the effect if this option is used
@example
function yd = fvanderpol (vt, vy, varargin)
  mu = 1; ## Set mu > 10 for higher stiffness
  yd = [vy(2); mu * (1 - vy(1)^2) * vy(2) - vy(1)];
endfunction

A = odeset ("RelTol", 1, "OutputFcn", @@odeplot);
ode78 (@@fvanderpol, [0 20], [2 0], A);
B = odeset (A, "RelTol", 1e-10);
ode78 (@@fvanderpol, [0 20], [2 0], B);
@end example

@item AbsTol
@cindex AbsTol option
The option @option{AbsTol} is used to set the absolute error tolerance for the error estimation of the solver that is used while solving. It can either be a positive scalar or a vector with every element of the vector being a positive scalar (it depends on the solver that is used if both variants are supported). The definite error estimation equation also depends on the solver that is used but generalized (eg. for the solvers @command{ode23}, @command{ode45}, @command{ode54} and @command{ode78}) it may be a form like
@ifhtml
@example
@math{e(t) = max (RelTol^T y(t), AbsTol)}
@end example
@end ifhtml
@ifnothtml
@math{e(t) = max (r_{tol}^T y(t), a_{tol})}.
@end ifnothtml
Run the following example to illustrate the effect if this option is used
@example
## An anonymous implementation of the Van der Pol equation
fvdb = @@(vt,vy) [vy(2); (1 - vy(1)^2) * vy(2) - vy(1)];

A = odeset ("AbsTol", 1e-3, "OutputFcn", @@odeplot);
ode54 (fvdb, [0 10], [2 0], A);
B = odeset (A, "AbsTol", 1e-10);
ode54 (fvdb, [0 10], [2 0], B);
@end example

@item NormControl
@cindex NormControl option
The option @option{NormControl} is used to set the type of error tolerance calculation of the solver that is used while solving. It can either be the string @command{"on"} or @command{"off"}. At the time the solver starts solving a warning message may be displayed if the solver will ignore the @command{"on"} setting of this option because of an unhandled resp. missing implementation. If set @command{"on"} then the definite error estimation equation also depends on the solver that is used but generalized (eg. for the solvers @command{ode23}, @command{ode45}, @command{ode54} and @command{ode78}) it may be a form like
@ifhtml
@example
@math{e(t) = max (RelTol^T max (norm (y(t), Inf)), AbsTol)}
@end example
@end ifhtml
@ifnothtml
@math{e(t) = max (r_{tol}^T max (norm (y(t), \infty{})), a_{tol})}.
@end ifnothtml
Run the following example to illustrate the effect if this option is used
@example
function yd = fvanderpol (vt, vy, varargin)
  mu = 1; ## Set mu > 10 for higher stiffness
  yd = [vy(2); mu * (1 - vy(1)^2) * vy(2) - vy(1)];
endfunction

A = odeset ("NormControl", "on", "OutputFcn", @@odeplot);
ode78 (@@fvanderpol, [0 20], [2 0], A);
B = odeset (A, "NormControl", "off");
ode78 (@@fvanderpol, [0 20], [2 0], B);
@end example

@item MaxStep
@cindex MaxStep option
The option @option{MaxStep} is used to set the maximum step size for the solver that is used while solving. It can only be a positive scalar. By default this value is set internally by every solver and also may differ when using different solvers. Run the following example to illustrate the effect if this option is used
@example
function yd = fvanderpol (vt, vy, varargin)
  mu = 1; ## Set mu > 10 for higher stiffness
  yd = [vy(2); mu * (1 - vy(1)^2) * vy(2) - vy(1)];
endfunction

A = odeset ("MaxStep", 10, "OutputFcn", @@odeprint);
ode78 (@@fvanderpol, [0 20], [2 0], A);
B = odeset (A, "MaxStep", 1e-1);
ode78 (@@fvanderpol, [0 20], [2 0], B);
@end example

@item InitialStep
@cindex InitialStep option
The option @option{InitialStep} is used to set the initial first step size for the solver. It can only be a positive scalar. By default this value is set internally by every solver and also may be different when using different solvers. Run the following example to illustrate the effect if this option is used
@example
function yd = fvanderpol (vt, vy, varargin)
  mu = 1; ## Set mu > 10 for higher stiffness
  yd = [vy(2); mu * (1 - vy(1)^2) * vy(2) - vy(1)];
endfunction

A = odeset ("InitialStep", 1, "OutputFcn", @@odeprint);
ode78 (@@fvanderpol, [0 1], [2 0], A);
B = odeset (A, "InitialStep", 1e-5);
ode78 (@@fvanderpol, [0 1], [2 0], B);
@end example

@item InitialSlope
@cindex InitialSlope option
The option @option{InitialSlope} is not handled by any of the solvers by now.@*

@item OutputFcn
@cindex OutputFcn option
The option @option{OutputFcn} can be used to set up an output function for displaying the results of the solver while solving. It must be a function handle to a valid function. There are four predefined output functions available with OdePkg. @command{odeprint} prints the actual time values and results in the Octave window while solving, @command{odeplot} plots the results over time in a new figure window while solving, @command{odephas2} plots the first result over the second result as a two--dimensional plot while solving and @command{odephas3} plots the first result over the second result over the third result as a three--dimensional plot while solving. Run the following example to illustrate the effect if this option is used
@example
function yd = fvanderpol (vt, vy, varargin)
  mu = 1; ## Set mu > 10 for higher stiffness
  yd = [vy(2); mu * (1 - vy(1)^2) * vy(2) - vy(1)];
endfunction

A = odeset ("OutputFcn", @@odeprint);
ode78 (@@fvanderpol, [0 2], [2 0], A);
@end example
User defined output functions can also be used. A typical framework for a self--made output function may then be of the form
@example
function [vret] = odeoutput (vt, vy, vdeci, varargin)
  switch vdeci
    case "init"
      ## Do everything needed to intialize output function
    case "calc"
      ## Do everything needed to create output
    case "done"
      ## Do everything needed to clean up output function
  endswitch
endfunction
@end example
The output function @command{odeplot} is also set automatically if the solver calculation routine is called without any output argument. Run the following example to illustrate the effect if this option is not used and no output argument is given
@example
## An anonymous implementation of the Van der Pol equation
fvdb = @@(vt,vy) [vy(2); (1 - vy(1)^2) * vy(2) - vy(1)];

ode78 (fvdb, [0 20], [2 0]);
@end example

@item Refine
@cindex Refine option
The option @option{Refine} is used to set the interpolation factor that is used to increase the quality for the output values if an output function is also set with the option @option{OutputFcn}. It can only be a integer value @math{0<=}@option{Refine}@math{<=5}. Run the following example to illustrate the effect if this option is used
@example
function yd = fvanderpol (vt, vy, varargin)
  mu = 1; ## Set mu > 10 for higher stiffness
  yd = [vy(2); mu * (1 - vy(1)^2) * vy(2) - vy(1)];
endfunction

A = odeset ("Refine", 0, "OutputFcn", @@odeplot);
ode78 (@@fvanderpol, [0 20], [2 0], A);
B = odeset (A, "Refine", 3);
ode78 (@@fvanderpol, [0 20], [2 0], B);
@end example

@item OutputSel
@cindex OutputSel option
The option @option{OutputSel} is used to set the components for which output has to be performed if an output function is also set with the option @option{OutputFcn}. It can only be a vector of integer values. Run the following example to illustrate the effect if this option is used
@example
function yd = fvanderpol (vt, vy, varargin)
  mu = 1; ## Set mu > 10 for higher stiffness
  yd = [vy(2); mu * (1 - vy(1)^2) * vy(2) - vy(1)];
endfunction

A = odeset ("OutputSel", [1, 2], "OutputFcn", @@odeplot);
ode78 (@@fvanderpol, [0 20], [2 0], A);
B = odeset (A, "OutputSel", [2]);
ode78 (@@fvanderpol, [0 20], [2 0], B);
@end example

@item Stats
@cindex Stats option
The option @option{Stats} is used to print cost statistics about the solving process after solving has been finished. It can either be the string @command{"on"} or @command{"off"}. Run the following example to illustrate the effect if this option is used
@example
function yd = fvanderpol (vt, vy, varargin)
  mu = 1; ## Set mu > 10 for higher stiffness
  yd = [vy(2); mu * (1 - vy(1)^2) * vy(2) - vy(1)];
endfunction

A = odeset ("Stats", "off");
[a, b] = ode78 (@@fvanderpol, [0 2], [2 0], A);
B = odeset ("Stats", "on");
[c, d] = ode78 (@@fvanderpol, [0 2], [2 0], B);
@end example
The cost statistics can also be obtained if the solver calculation routine is called with one output argument. The cost statistics then are in the field @option{stats} of the output arguemnt structure. Run the following example to illustrate the effect if this option is used
@example
S = ode78 (@@fvanderpol, [0 2], [2 0], B);
disp (S);
@end example

@item Jacobian
@cindex Jacobian option
The option @option{Jacobian} can be used to set up an external Jacobian function or Jacobian matrix for DAE solvers to achieve faster and better results (ODE Runge--Kutta solvers do not need to handle a Jacobian function handle or Jacobian matrix). It must either be a function handle to a valid function or a full constant matrix of size squared the dimension of the set of differential equations. User defined Jacobian functions must have the form @samp{function [vjac] = fjac (vt, vy, varargin)}. Run the following example to illustrate the effect if this option is used
@example
function vdy = fpol (vt, vy, varargin)
  vdy = [vy(2); (1 - vy(1)^2) * vy(2) - vy(1)];
endfunction

function vr = fjac (vt, vy, varargin)
  vr = [0, 1; ...
        -1-2*vy(1)*vy(2), 1-vy(1)^2];
endfunction

A = odeset ("Stats", "on");
B = ode5r (@@fpol, [0 20], [2 0], A);
C = odeset (A, "Jacobian", @@fjac);
D = ode5r (@@fpol, [0 20], [2 0], C);
@end example
@b{Note:} The function definition for Jacobian calculations of IDE equations must have the form @samp{function [vjac, vdjc] = fjac (vt, vy, vyd, varargin)}. Run the following example to illustrate the effect if this option is used
@example
function [vres] = fvanderpol (vt, vy, vyd, varargin)
  vres = [vy(2) - vyd(1); 
          (1 - vy(1)^2) * vy(2) - vy(1) - vyd(2)];
endfunction

function [vjac, vdjc] = fjacobian (vt, vy, vyd, varargin)
  vjac = [0, 1; -1 - 2 * vy(1) * vy(2), 1 - vy(1)^2];
  vdjc = [-1, 0; 0, -1];
endfunction

vopt = odeset ("Jacobian", @@fjacobian, "Stats", "on");
vsol = odebdi (@@fvanderpol, [0, 20], [2; 0], [0; -2], vopt, 10);
@end example

@item JPattern
@cindex JPattern option
The option @option{JPattern} is not handled by any of the solvers by now.@*

@item Vectorized
@cindex Vectorized option
The option @option{Vectorized} is not handled by any of the solvers by now.@*

@item Mass
@cindex Mass option
The option @option{Mass} can be used to set up an external Mass function or Mass matrix for solving DAE equations. It depends on the solver that is used if @option{Mass} is supported or not. It must either be a function handle to a valid function or a full constant matrix of size squared the dimension of the set of differential equations. User defined Jacobian functions must have the form @samp{function vmas = fmas (vt, vy, varargin)}. Run the following example to illustrate the effect if this option is used
@example
function vdy = frob (t, y, varargin)
  vdy(1,1) = -0.04*y(1)+1e4*y(2)*y(3);
  vdy(2,1) =  0.04*y(1)-1e4*y(2)*y(3)-3e7*y(2)^2;
  vdy(3,1) =  y(1)+y(2)+y(3)-1;
endfunction

function vmas = fmas (vt, vy, varargin)
  vmas =  [1, 0, 0; 0, 1, 0; 0, 0, 0];
endfunction

A = odeset ("Mass", @@fmas);
B = ode5r (@@frob, [0 1e8], [1 0 0], A);
@end example
@b{Note:} The function definition for Mass calculations of DDE equations must have the form @samp{function vmas = fmas (vt, vy, vz, varargin)}.@*

@item MStateDependence
@cindex MStateDependence option
The option @option{MStateDependence} can be used to set up the type of the external Mass function for solving DAE equations if a Mass function handle is set with the option @option{Mass}. It depends on the solver that is used if @option{MStateDependence} is supported or not. It must be a string of the form @command{"none"}, @command{"weak"} or @command{"strong"}. Run the following example to illustrate the effect if this option is used
@example
function vdy = frob (vt, vy, varargin)
  vdy(1,1) = -0.04*vy(1)+1e4*vy(2)*vy(3);
  vdy(2,1) =  0.04*vy(1)-1e4*vy(2)*vy(3)-3e7*vy(2)^2;
  vdy(3,1) =  vy(1)+vy(2)+vy(3)-1;
endfunction

function vmas = fmas (vt, varargin)
  vmas =  [1, 0, 0; 0, 1, 0; 0, 0, 0];
endfunction

A = odeset ("Mass", @@fmas, "MStateDependence", "none");
B = ode5r (@@frob, [0 1e8], [1 0 0], A);
@end example
User defined Mass functions must have the form as described before (ie. @samp{function vmas = fmas (vt, varargin)} if the option @option{MStateDependence} was set to @command{"none"}, otherwise the user defined Mass function must have the form @samp{function vmas = fmas (vt, vy, varargin)} if the option @option{MStateDependence} was set to either @command{"weak"} or @command{"strong"}.@*

@item MvPattern
@cindex MvPattern option
The option @option{MvPattern} is not handled by any of the solvers by now.@*
 
@item MassSingular
@cindex MassSingular option
The option @option{MassSingular} is not handled by any of the solvers by now.@*

@item NonNegative
@cindex NonNegative option
The option @option{NonNegative} can be used to set solution variables to zero even if their real solution would be a negative value. It must be a vector describing the positions in the solution vector for which the option @option{NonNegative} should be used. Run the following example to illustrate the effect if this option is used
@example
vfun = @@(vt,vy) -abs(vy);
vopt = odeset ("NonNegative", [1]);

[vt1, vy1] = ode78 (vfun, [0 100], [1]);
[vt2, vy2] = ode78 (vfun, [0 100], [1], vopt);

subplot (2,1,1); plot (vt1, vy1);
subplot (2,1,2); plot (vt2, vy2);
@end example

@item Events
@cindex Events option
The option @option{Events} can be used to set up an Event function, ie. the Event function can be used to find zero crossings in one of the results. It must either be a function handle to a valid function. Run the following example to illustrate the effect if this option is used
@example
function vdy = fbal (vt, vy, varargin)
  vdy(1,1) =  vy(2); 
  vdy(2,1) = -9.81; ## m/sē
endfunction

function [veve, vterm, vdir] = feve (vt, vy, varargin)
  veve  = vy(1); ## Which event component should be tread
  vterm =     1; ## Terminate if an event is found
  vdir  =    -1; ## In which direction, -1 for falling
endfunction

A = odeset ("Events", @@feve);
B = ode78 (@@fbal, [0 1.5], [1 3], A);
plot (B.x, B.y(:,1));
@end example
@b{Note:} The function definition for Events calculations of DDE equations must have the form @samp{function [veve, vterm, vdir] = feve (vt, vy, vz, varargin)} and the function definition for Events calculations of IDE equations must have the form @samp{function [veve, vterm, vdir] = feve (vt, vy, vyd, varargin)}.@*

@item MaxOrder
@cindex MaxOrder option
The option @option{MaxOrder} can be used to set the maximum order of the backward differentiation algorithm of the @command{odebdi} and @command{odebda} solvers. It must be a scalar integer value between @math{1} and @math{7}. Run the following example to illustrate the effect if this option is used
@example
function res = fwei (t, y, yp, varargin)
  res = t*y^2*yp^3 - y^3*yp^2 + t*yp*(t^2 + 1) - t^2*y;
endfunction

function [dy, dyp] = fjac (t, y, yp, varargin)
  dy  = 2*t*y*yp^3 - 3*y^2*yp^2 - t^2;
  dyp = 3*t*y^2*yp^2 - 2*y^3*yp + t*(t^2 + 1);
endfunction

A = odeset ("AbsTol", 1e-6, "RelTol", 1e-6, "Jacobian", @@fjac, ...
            "Stats", "on", "MaxOrder", 1, "BDF", "on")
B = odeset (A, "MaxOrder", 5)
C = odebdi (@@fwei, [1 10], 1.2257, 0.8165, A);
D = odebdi (@@fwei, [1 10], 1.2257, 0.8165, B);
plot (C.x, C.y, "bo-", D.x, D.y, "rx:");
@end example

@item BDF
@cindex BDF option
The option @option{BDF} is only supported by the @command{odebdi} and @command{odebda} solvers. Using these solvers the option @option{BDF} will automatically be set @command{"on"} (even if it was set @command{"off"} before) because the @command{odebdi} and @command{odebda} solvers all use the backward differentiation algorithm to solve the different kind of equations.

@item NewtonTol
@cindex NewtonTol option
TODO

@item MaxNewtonIterations
@cindex MaxNewtonIterations option
TODO
@end table

@node M-File Function Reference, Oct-File Function Reference, ODE/DAE/IDE/DDE options, Users Guide
@section M--File Function Reference
@cindex m--file reference
The help texts of this section are autogenerated and refer to commands that all can be found in the files @file{*.m}. All commands that are listed below are loaded automatically everytime you launch Octave.@*@*
@include mfunref.texi

@node Oct-File Function Reference,  , M-File Function Reference, Users Guide
@section Oct--File Function Reference
@cindex oct--file reference
The help texts of this section are autogenerated and refer to commands that all can be found in the file @file{dldsolver.oct}. The file @file{dldsolver.oct} is generated automatically if you install OdePkg with the command @command{pkg}. All commands that are listed below are loaded automatically everytime you launch Octave.@*@*
@include dldfunref.texi

@c %*** End of second chapter: Users Guide

@c %*** Start of third chapter: Programmers Guide
@node Programmers Guide, Function Index, Users Guide, Top
@chapter Programmers Guide
@cindex Programmers guide

@menu
* Missing features::            The TODO-list for missing features
@end menu

@node Missing features,  , Programmers Guide, Programmers Guide
@section Missing features
@cindex missing features
If somebody want to help improving OdePkg then please contact the Octave--Forge developer team sending your modifications via the mailing--list
@ifnothtml
@email{octave-dev@@lists.sourceforge.net}.
@end ifnothtml 
@ifhtml
@email{octave-dev <at] lists.sourceforge.net} (replace <at] with @@).
@end ifhtml 
Here is a TODO--list about missing features:
@c The OdePack solvers from http://www.netlib.org/odepack have not been added to OdePkg, because the question is not answered if they are really needed from somebody. Other solvers from http://www.netlib.org/ode have not been added because of the same reason.
@itemize
@item Partial Derivative equations (PDEs) and Boundary Value Equations (BVPs) cannot be solved with the solvers of the OdePkg. The wish for solving PDEs and BVPs definitely is there (maybe you'd like to create another package and call that package PdePkg, which is just an idea).

@item Some options that can be set with propietary solver products are not available within OdePkg. Have a look at section @ref{ODE/DAE/IDE/DDE options} about which options can be set and which options are not supported and help improving the command @command{odeset}, @command{odepkg_structure_check} and the solvers that have to deal with these options.

@item OdePkg currently is missing the command @command{decic} which computes an initial constraint for IDEs before solving. The command @command{deval} also is missing that interpolates the results that can be obtained from the solvers after solving and then plots the results in a new figure. However, instead of using @command{deval} any of the commands @command{interpX}.
@cindex decic
@cindex deval

@item If you want to include your own solver within OdePkg then either code in @file{*.m} or @file{*.cc}. Solvers in @file{*.m} are preferred. Choose a GPL compatible license for your solver and send your solver file to the mailing list.

@item Before interfacing other solvers make sure that the core solver file is available under a GPL--compatible license (if you'd like to redistribute your wrapper with OdePkg). There can be found a lot of solver files at @url{http://www.netlib.org} but most of them are not GPL--compatible. Here is a list about authors and their solvers that do have a GPL compatible license so that their codes can be redistributed with OdePkg:

@itemize
@item Cecilia Magherini and Luigi Brugnano from the University of Bari created the BIMD solver that is available at @url{http://pitagora.dm.uniba.it/~testset/solvers/bimd.php}. This solver can be used to solve stiff DAE equations. The Fortran77 file has been released under the GNU GPL V2.

@item Francesca Mazzia and Felice Iavernaro from the University of Bari created the GAMD solver that is available at @url{http://pitagora.dm.uniba.it/~testset/solvers/gamd.php}. This solver can be used to solve stiff DAE equations. The Fortran90 file has been released under the GNU GPL V2 but for OdePkg a Fortran77 implementation would be preferred.

@item Ernst Hairer and Gerhard Wanner have been written more solvers that are released under a modified BSD license than have been interfaced by OdePkg. Notable solvers that can be found at @url{http://www.unige.ch/~hairer/software.html} are explicit Runge-Kutta methods @command{dopri5} and @command{dop853} and extrapolation methods @command{odex} and @command{odex2} for solving ODEs, @command{retard} and @command{radar5} for solving DDEs.

@item Jeff Cash has released some more Fortran77 solvers for different kinds of differential equation problems than are interfaced by OdePkg, check his website at @url{http://www.ma.ic.ac.uk/~jcash}.
@end itemize

@end itemize
@c %*** End of third chapter: Programmers Guide

@node Function Index, Index, Programmers Guide, Top
@unnumbered Function Index
@printindex fn

@node Index,  , Function Index, Top
@unnumbered Index
@printindex cp

@bye

@c Local Variables: 
@c mode: texinfo
@c TeX-master: "odepkg"
@c End: 
