\input texinfo @c -*-texinfo-*-
@c Copyright (c) 2006-2012, Thomas Treichl <treichl@users.sourceforge.net>
@c Copyright (c) 2013, Roberto Porcu' <roberto.porcu@polimi.it>
@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 1.0.0
@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 are currently 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 other improvements were made
so that differential algebraic equations (DAEs) in explicit form and in implicit
form (IDEs) and delay differential equations (DDEs) could 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 OdePkg Version 0.8.x
@tab Final releases before version 1.0.0.
@item @b{(current)} Version 1.0.0
@tab The routines for the options setting (odeset/odeget) and the main solvers
(ode23/ode45) were moved to core (Octave 4.2.0 and later). Most of the options
were implemented, rendering the package mostly compatible to proprietary solver
products.
@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
ode78 (@@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
ode78 (@@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] = ode78 (@@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 = ode78 (@@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
ode78 (@@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);
ode78 (@@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');
ode78 (@@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
* Non-Standard Options::         Non-Standard internal options that can be set for specific solvers
* 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
explicitly 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
* ODE Constrained Equations::   Ordinary differential equations with constraints
* 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, ODE Constrained 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} is always 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 ODE Constrained Equations, DAE Equations, ODE Equations, Differential Equations
@subsection ODE Constrained Eequations
@cindex ode constrained equations
ODE equations with constraints in general are of the form
@ifhtml
@example
@math{y'(t) = f(t,y)}
@math{g(y) = 0}
@end example
@end ifhtml
@ifnothtml
@math{y'(t) = f(t,y)}
@math{g(y) = 0}
@end ifnothtml
where @math{y'(t)} may be a scalar or vector of derivatives. The variable
@math{t} is always 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.
@example
function [dy] = ODEequation (t, y, varargin)
function [g] = Constraint (y)
@end example

@node DAE Equations, IDE Equations, ODE Constrained 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} is always 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} is always 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} is always 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 Euler and Runge--Kutta
solvers in section @ref{Euler Solvers}, @ref{Runge-Kutta Solvers} and is
continued with the Mex--file Hairer--Wanner solvers in section
@ref{Hairer-Wanner 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
* Euler Solvers::                 ODE solvers written as @file{*.m} files
* Runge-Kutta Solvers::           ODE solvers written as @file{*.m} files
* Stiff Runge-Kutta Solvers::     Stiff 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
* Geometric Integration Solvers:: ODE solvers written as @file{*.m} files
* Boundary Value Problem Solver:: BVP solver written as @file{*.m} file
* ODE Solver Performances::       Cross math-engine performance tests
@end menu

@node Euler Solvers, Runge-Kutta Solvers, Solver Families, Solver Families
@subsection Euler Solvers
@cindex Euler
Two Euler solvers are available as @file{m}--files: @command{odefwe} and
@command{obwe}.

@multitable @columnfractions .075 .925
@item @command{odefwe}
@tab Integrates a system of non-stiff Ordinary Differential Equations (non-stiff
ODEs) with the well known explicit Forward-Euler method. This is a first--order
accurate integrator therefore the local error normally expected is
@math{O(h^2)}. This solver requires three function evaluations per integration
step.@*

@item @command{odebwe}
@tab Integrates a system of Ordinary Differential Equations with the well known
implicit Backward-Euler. This is a first--order accurate integrator therefore
the local error normally expected is @math{O(h^2)}. This method is A-stable and
is indicated for both stiff and non--stiff problems.
@end multitable

@node Runge-Kutta Solvers, Hairer-Wanner Solvers, Euler Solvers, 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{ode12}, @command{ode23}, @command{ode45},
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. Since OdePkg 1.0.0 @command{ode23} and
@command{ode45} were moved to Octave core (4.2.0 or more recent). For more
information about them see Octave documentation.

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{ode12}
@tab Integrates a system of non--stiff ordinary differential equations
(non--stiff ODEs and DAEs) combining first order Euler method and second order
Heun method. This is a first--order accurate integrator therefore the local
error normally expected is @math{O(h^2)}. This solver requires two function
evaluations per integration step.@*

@item @command{ode23}
@tab Integrates a system of non--stiff ordinary differential equations
(non--stiff ODEs and DAEs) using second order Bogacki-Shampine method.
This solver uses local extrapolation (i.e. it uses the higher order estimate)
and is then a third--order accurate integrator therefore the local error
normally expected is @math{O(h^4)}. 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 second order Dormand-Prince method.
This solver uses local extrapolation (i.e. it uses the higher order estimate)
and is then a fifth--order accurate integrator therefore the local error
normally expected is @math{O(h^6)}. This solver requires six 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)}. This solver requires thirteen function
evaluations per integration step.
@end multitable

@node Stiff Runge-Kutta Solvers, Hairer-Wanner Solvers, Runge-Kutta Solvers, Solver Families
@subsection Stiff Runge--Kutta Solvers
@cindex Stiff Runge--Kutta
OdePkg provides solver @command{ode23s}, which is a modified Runge--Kutta solver
suited for the solution of stiff--problems.

@multitable @columnfractions .075 .925
@item @command{ode23s}
@tab Integrates a set of stiff ordinary differential (stiff ODEs) equations with
a modified Rosenbrock method. It is especially indicated for low tolerances,
when a one-step method has advantages over methods with memory, and when
Jacobians have eigenvalues near the imaginary axis. This is a second--order
accurate integrator therefore the local error normally expected is
@math{O(h^3)}. This solver requires five function evaluations per integration
step. For the definition of this method see "The MATLAB ode suite", L.F.
Shampine, mass.W. Reichelt, pp.6-7.
@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
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, Geometric Integration Solvers, 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 three 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},
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 three 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

Furthermore, 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 Geometric Integration Solvers, ODE Solver Performances, Modified Runge-Kutta Solvers, Solver Families
@subsection Geometric Integration Solvers
@cindex geometric integrators
The Geometric Integration solvers are written in the Octave language and that
are saved as @file{m}--files. There have been implemented five different solvers
with a very similiar structure, ie. @command{odeRATTLE}, @command{odeSE},
@command{odeSPVI}, @command{odeSV} and @command{odeVV}.

This is a class of symplectic integrators that can be used to solve Hamilton's
equations of motion, that is a system of ODEs of the form
@ifhtml
@example
@math{q' =  dH/dp (t,[q;p])}
@math{p' = -dH/dq (t,[q;p])}
@end example
@end ifhtml
@ifnothtml
@math{q' =  dH/dp (t,[q;p])}
@math{p' = -dH/dq (t,[q;p])},
@end ifnothtml
where q is the variable containing generalized coordinates and p is the variable
for generalized momenta; H(t,[q;p]) is the Hamiltonian of the system.

The @command{odeVV} solver is different because it can be used only to solve
Newton's equations, that is a system of ODEs of the form
@ifhtml
@example
@math{q' = v (t,q)}
@math{v' = a (t,q)}
@end example
@end ifhtml
@ifnothtml
@math{q' = v (t,q)}
@math{v' = a (t,q)},
@end ifnothtml
where v is the variable for generalized velocities and a(t,q) represents the
accelerations of the system.

The @command{odeRATTLE} solver is needed only for constrained systems, where
Hamilton's equations of motion must be paired with the equations
@ifhtml
@example
@math{g(q) = 0}
@end example
@end ifhtml
@ifnothtml
@math{g(q) = 0}.
@end ifnothtml

@multitable @columnfractions .075 .925
@item @command{odeRATTLE}
@tab Integrates a constrained system of Hamilton's equations of motion using
the RATTLE algorithm, which is an extension of the Stormer-Verlet algorithm.
This is a second order method.@*

@item @command{odeSE}
@tab Integrates a system of Hamilton's equations of motion using the
Symplectic-Euler algorithm. This is a first order method.@*

@item  @command{odeSPVI}
@tab Integrates a system of Hamilton's equations of motion using the spectral
variational integrators. The order of this method depends on the dimension of
the polynomial basis used to discretize the solutions. Usually for polynomials
of max order N, the order will be 2*N.@*

@item @command{odeSV}
@tab Integrates a system of Hamilton's equations of motion using the
Stormer-Verlet algorithm. This is a second order method.@*

@item @command{odeVV}
@tab Integrates a system of Newton's equations of motion using the
Velocity-Verlet algorithm. This is a second order method.
@end multitable

@node Boundary Value Problem Solver, ODE Solver Performances, Geometric Integration Solvers, Solver Families
@subsection Boundary Value Problem Solver
@cindex Boundary Value Problem
OdePkg provides solver @command{bvp4c} to solve Boundary Value Problems (BVPs).

@multitable @columnfractions .075 .925
@item @command{bvp4c}
@tab Solves the first order system of non-linear differential equations subject
to user--defined boundary value conditions using a finite difference method that
implements the three-stage Lobatto IIIa formula. This is a collocation formula
and the collocation polynomial provides a @math{C@sup{1}}-continuous solution that
is fourth-order accurate. Mesh selection and error control are based on the
residual of the continuous solution.
@end multitable

@node ODE Solver Performances,  , Boundary Value Problem Solver, 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      -       -      -      -      -       -
 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
-----------------------------------------------------------------------------------------
  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, Non-Standard Options, Solver Families, Users Guide
@section ODE/DAE/IDE/DDE Options
@cindex 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 a 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 standard options that can be set with the @command{odeset}
command are:

@table @samp
@item RelTol - Relative error tolerance
@cindex RelTol option
Default value 1e-3

The relative error tolerance for the error estimation of the solver. 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} 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 — Absolute error tolerance
@cindex AbsTol option
Default value 1e-6

The absolute error tolerance for the error estimation of the solver. 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 - Control error relative to norm
@cindex NormControl option
Default value "off"

Type of error tolerance calculation of the solver. It is a string that can be
set to either @command{"on"} or @command{"off"}. 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 - Maximum step size
@cindex MaxStep option
Default value (tf - ti) / 10

Maximum step size for the solver. It can only be a positive scalar. 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 - Suggested initial step size
@cindex InitialStep option

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 as of now.@*

@item OutputFcn - Output function
@cindex OutputFcn option
Set an output function for displaying the results of the solver. The solver
calls the OutputFcn after each successfull step. 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, flag, varargin)
  switch flag
    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
If a solver is callad with no output argument, @command{odeplot} is used by
default. 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 - Solution refinement factor
@cindex Refine option
Default value 1 (or 4 for ode45)

Option @option{Refine} is currently implemented only if an OutpuFcn is set.

Set the refinement factor. It must be a scalar @math{>= 1}. If set to 1, then
the solver returns solutions only at the end of each step,. If set to
@math{n>1}, then the solver subdivides each step into @math{n} smaller intervals
and returns solutions at each point.The extra values are computed by
interpolation. Each solver uses specific interpolation formulas of the same
order of the solver to keep the highest possible accuracy a without significant
increase in the number of function evaluations. 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- Component selection for output function
@cindex OutputSel option

Component selection for the output function. It is a vector containing the
indeces of the component to be passed to the output function. 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 - Solver statistics
@cindex Stats option
Default value "off"

Return statistics about the solving process once finished. It is a string that
can be set to either @command{"on"} or @command{"off"}. If set @command{"on"}
then the solver displays
@itemize @bullet
@item The number of successful steps

@item The number of failed attempts

@item The number of function evaluations
@end itemize
Implicit solvers display also additional information
@itemize @bullet
@item The number of times that the partial derivatives matrix was created

@item The number of LU decompositions

@item The number of solutions of linear systems
@end itemize
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 - Jacobian matrix
@cindex Jacobian option
Set 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 - Jacobian sparsity pattern
@cindex JPattern option
Specify the Jacobian sparsity pattern. It is a sparse matrix containing ones
where the Jacobian matrix could be non-zero. The solver will use the pattern to
speed up the numerical evaluation of the Jacobian matrix.
@b{Note:} If you specify a Jacobian matrix using @option{Jacobian}, then the
solver ignores any setting for JPattern.

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

@item Mass - Mass matrix
@cindex Mass option
Set up an external Mass function or Mass matrix. It depends on the solver that
is used if @option{Mass} is supported or not. It must either be a function
handle 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 - State dependence of mass matrix
@cindex MStateDependence option
Default value "weak"

Set the dependence of the 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"}.
@itemize @bullet
@item
If the problem is of the form @math{M(t)y(t)' = f(t,y)} set
@option{MStateDependence} to "none". Thus the solver will call the Mass matrix
function with one argument only.

@item
If the mass matrix depends on @math{y}, set MStateDependence to either
"weak" (default) or "strong". In both cases the solver calls the mass matrix
function with two inputs @math{(t,y)}, but the "weak" option results in implicit
solvers using approximations when solving algebraic equations.
@end itemize
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 - Mass matrix sparsity pattern
@cindex MvPattern option
The option @option{MvPattern} is not handled by any of the solvers as of now.@*
 
@item MassSingular
@cindex MassSingular option
Default value "maybe"

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

@item NonNegative - Non negative solution components
@cindex NonNegative option
Set solution variables to zero even if their real solution would be a negative
value. It must be a vector containing the indeces in the solution vector for
which the option @option{NonNegative} should be used.

@b{Note:} NonNegative is not available for ode23s.

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 - Event function
@cindex Events option
Set up an Event function, ie. the Event function can be used to find zero
crossings in one of the results. It is a function handle @samp{[veve, vterm,
vdir] = feve (vt, vy, varargin)}. 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 - Maximum order of BDF formula
@cindex MaxOrder option
Default value 5

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 - Toggle BDF formula
@cindex BDF option
Default value "off"

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.@*
@end table

@node Non-Standard Options, , ODE/DAE/IDE/DDE Options, Users Guide
@section Non-Standard Options
@cindex Non-Standard Options

@command{odeset} allows for the setting of non-standard options that might be
used by some of the solvers. The sintax for the definition of these options is
unchanged but a warning message will be displayed. The non-standard options that
can be set with odeset are:

@table @samp
@item NewtonTol - Newton method tolerance
@cindex NewtonTol option
Defautl value 1e-7

Set the tolerance on the residual of the function that is passed to an inexct
newton solve like @command{fsolve} or or @command{inexact_newton}. This option
is supported by the solvers:
@itemize@bullet
@item @command{odebwe}
@item @command{odeRATTLE}
@item @command{odeSE}
@item @command{odeSPVI}
@item @command{odeSV}
@item @command{odeVV}
@end itemize

Run the following example to illustrate the effect if this option is used

@example
function res = fosc (t, y)
  m = length(y)/2;
  res = [y(m+1:end); -y(1:m)];
endfunction

A = odeset ("NewtonTol",1.e-3)
B = odeset ("NewtonTol",1.e-8)
[t1,y1] = odeSV (@@fosc, [1 10], [1 0], A);
[t2,y2] = odeSV (@@fosc, [1 10], [1 0], B);
plot (t1, y1, "bo-", t2, y2, "rx:");
@end example

@item MaxNewtonIterations - Maximum number of Newton iterations
@cindex MaxNewtonIterations option
Default value 100

Set the maximum number of iterations for the method that is used by an inexact
solver like @command{fsolve} or @command{inexact_newton}. This option
is supported by the solvers:
@itemize@bullet
@item @command{odebwe}
@item @command{odeRATTLE}
@item @command{odeSE}
@item @command{odeSPVI}
@item @command{odeSV}
@item @command{odeVV}
@end itemize

Run the following example to illustrate the effect if this option is used

@example
function res = fosc (t, y)
  m = length(y)/2;
  res = [y(m+1:end); -y(1:m)];
endfunction

A = odeset ("MaxNewtonIterations",15)
B = odeset ("MaxNewtonIterations",50)
[t1,y1] = odeSV (@@fosc, [1 10], [1 0], A);
[t2,y2] = odeSV (@@fosc, [1 10], [1 0], B);
plot (t1, y1, "bo-", t2, y2, "rx:");
@end example

@item Algorithm
@cindex Algorithm
Default value "gmres"

Set the iterative method used by the @command{inexact_newton} function for the
solution of nonlinear systems. It can be ["gmres"], "pcg" or "bicgstab". This
option is supported by the solvers:
@itemize@bullet
@item @command{odebwe}
@item @command{odeRATTLE}
@item @command{odeSE}
@item @command{odeSPVI}
@item @command{odeSV}
@item @command{odeVV}
@end itemize

Run the following example to illustrate the effect if this option is used

@example
function res = fosc (t, y)
  m = length(y)/2;
  res = [y(m+1:end); -y(1:m)];
endfunction

A = odeset ("InexactSolver",'inexact_newton',"Algorithm",'gmres')
B = odeset ("InexactSolver",'inexact_newton',"Algorithm",'pcg')
[t1,y1] = odeSV (@@fosc, [1 10], [1 0], A);
[t2,y2] = odeSV (@@fosc, [1 10], [1 0], B);
plot (t1, y1, "bo-", t2, y2, "rx:");
@end example

@item Choice - Forcing term
@cindex Choice
Default value 1

Set which forcing term will be used by @command{inexact_newton} function for the
solution of nonlinear systems. It can be either 1 or 2. This
option is supported by the solvers:
@itemize@bullet
@item @command{odebwe}
@item @command{odeRATTLE}
@item @command{odeSE}
@item @command{odeSPVI}
@item @command{odeSV}
@item @command{odeVV}
@end itemize

Run the following example to illustrate the effect if this option is used

@example
function res = fosc (t, y)
  m = length(y)/2;
  res = [y(m+1:end); -y(1:m)];
endfunction

A = odeset ("InexactSolver",'inexact_newton',"Choice",1)
B = odeset ("InexactSolver",'inexact_newton',"Choice",2)
[t1,y1] = odeSV (@@fosc, [1 10], [1 0], A);
[t2,y2] = odeSV (@@fosc, [1 10], [1 0], B);
plot (t1, y1, "bo-", t2, y2, "rx:");
@end example

@item Eta
@cindex Eta
Default value 0.5

Set the @var{"Eta"} parameter used by @command{inexact_newton} function for the
solution of nonlinear systems. It must be a scalar in [0, 1). This
option is supported by the solvers:
@itemize@bullet
@item @command{odebwe}
@item @command{odeRATTLE}
@item @command{odeSE}
@item @command{odeSPVI}
@item @command{odeSV}
@item @command{odeVV}
@end itemize

Run the following example to illustrate the effect if this option is used

@example
function res = fosc (t, y)
  m = length(y)/2;
  res = [y(m+1:end); -y(1:m)];
endfunction

A = odeset ("InexactSolver",'inexact_newton',"Eta",0.005)
B = odeset ("InexactSolver",'inexact_newton',"Eta",0.995)
[t1,y1] = odeSV (@@fosc, [1 10], [1 0], A);
[t2,y2] = odeSV (@@fosc, [1 10], [1 0], B);
plot (t1, y1, "bo-", t2, y2, "rx:");
@end example

@item PolynomialDegree - Legendre polynomials degree
@cindex PolynomialDegree
Default value 1

Set the maximum degree for the Legendre polynomials of the functional space
where the solution is discretized. This option is only supported by the
@command{odeSPVI} solver. Run the following example to illustrate the effect if
this option is used

@example
function res = fosc (t, y)
  m = length(y)/2;
  res = [y(m+1:end); -y(1:m)];
endfunction

A = odeset ("PolynomialDegree",1)
B = odeset ("PolynomialDegree",3)
[t1,y1] = odeSPVI (@@fosc, [1 10], [1 0], A);
[t2,y2] = odeSPVI (@@fosc, [1 10], [1 0], B);
plot (t1, y1, "bo-", t2, y2, "rx:");
@end example

@item Restart - GMRES restarting parameter
@cindex Restart
Default value 20

Set the @var{"Restart"} parameter used by @command{inexact_newton} function only
when it is using the @command{gmres} algorithm. This
option is supported by the solvers:
@itemize@bullet
@item @command{odebwe}
@item @command{odeRATTLE}
@item @command{odeSE}
@item @command{odeSPVI}
@item @command{odeSV}
@item @command{odeVV}
@end itemize

Run the following example to illustrate the effect if this option is used

@example
function res = fosc (t, y)
  m = length(y)/2;
  res = [y(m+1:end); -y(1:m)];
endfunction

A = odeset ("InexactSolver",'inexact_newton',"Algorithm",'gmres',"Restart",40)
B = odeset ("InexactSolver",'inexact_newton',"Algorithm",'gmres',"Restart",15)
[t1,y1] = odeSV (@@fosc, [1 10], [1 0], A);
[t2,y2] = odeSV (@@fosc, [1 10], [1 0], B);
plot (t1, y1, "bo-", t2, y2, "rx:");
@end example

@item Explicit - Solve explicit system
@cindex Explicit
Default value "no"

Set whether the system to be solved is explicit or not. This can help to speedup
the computation. This
option is supported by the solvers:
@itemize@bullet
@item @command{odeSE}
@item @command{odeSV}
@item @command{odeVV}
@end itemize

Run the following example to illustrate the effect if this option is used

@example
function res = fosc (t, y)
  m = length(y)/2;
  res = [y(m+1:end); -y(1:m)];
endfunction

A = odeset ("Explicit",'yes')
B = odeset ("Explicit",'no')
[t1,y1] = odeSV (@@fosc, [1 10], [1 0], A);
[t2,y2] = odeSV (@@fosc, [1 10], [1 0], B);
plot (t1, y1, "bo-", t2, y2, "rx:");
@end example

@item UseJacobian
@cindex UseJacobian
Default value "no"

Set whether the @command{fsolve} or @command{inexact_newton} solver must use the
Jacobian of the function to be solved or not. This can help to speedup the
computation. This option is supported by the solvers:
@itemize@bullet
@item @command{odebwe}
@item @command{odeRATTLE}
@item @command{odeSE}
@item @command{odeSPVI}
@item @command{odeSV}
@item @command{odeVV}
@end itemize

Run the following example to illustrate the effect if this option is used

@example
function res = fosc (t, y)
  m = length(y)/2;
  res = [y(m+1:end); -y(1:m)];
endfunction

A = odeset ("UseJacobian",'no')
B = odeset ("UseJacobian",'yes')
[t1,y1] = odeSV (@@fosc, [1 10], [1 0], A);
[t2,y2] = odeSV (@@fosc, [1 10], [1 0], B);
plot (t1, y1, "bo-", t2, y2, "rx:");
@end example

@item InexactSolver - Inexact Newton solver
@cindex InexactSolver
Default value "fsolve"

Set the Newton solver to use for the computation of the solution of the
nonlinear system. It can be set to either "folve", "inexact_newton" or
"newton_raphson" (only for @command{odebwe}). This option is supported by the
solvers:
@itemize@bullet
@item @command{odebwe}
@item @command{odeRATTLE}
@item @command{odeSE}
@item @command{odeSPVI}
@item @command{odeSV}
@item @command{odeVV}
@end itemize

Run the following example to illustrate the effect if this option is used

@example
function res = fosc (t, y)
  m = length(y)/2;
  res = [y(m+1:end); -y(1:m)];
endfunction

A = odeset ("InexactSolver",'fsolve')
B = odeset ("InexactSolver",'inexact_newton')
[t1,y1] = odeSV (@@fosc, [1 10], [1 0], A);
[t2,y2] = odeSV (@@fosc, [1 10], [1 0], B);
plot (t1, y1, "bo-", t2, y2, "rx:");
@end example
@end table

@node M-File Function Reference, Oct-File Function Reference, Non-Standard 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, , Oct-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
* Ongoing Development::         What is currently going on with OdePkg
* Missing Features::            The TODO-list for missing features
@end menu

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 

@node Ongoing Development, Missing Features, Programmers Guide, Programmers Guide
@section Ongoing Development
@cindex ongoing development

OdePkg is constantly under development. Here is a list of features that we are
currently working on:
@itemize
@item Add @command{ode15s} and @command{ode15i} solver for DAEs to Octave core.
Function @command{decic} should also be added to core together with the solvers.
These functions will exploit the external C++ library IDA.

@item Add @command{ode23tb} solver to Octave core. This will be a @file{*.m}
file.

@item Move @command{ode23s} solver for stiff ODEs from the package to Octave
core.
@end itemize

@node Missing Features,  , Ongoing Development, Programmers Guide
@section Missing Features
@cindex missing features

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.

@item OdePkg currently is missing the command @command{deval} 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 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: 
