Menu
▾
▴
[Octave-cvsupdate] octave-forge/main/odepkg/doc .cvsignore, 1.1, 1.2 odepkg.texi, 1.11, 1.12
|
From: Thomas T. <tr...@us...> - 2007-05-18 19:53:07
|
Update of /cvsroot/octave/octave-forge/main/odepkg/doc In directory sc8-pr-cvs3.sourceforge.net:/tmp/cvs-serv22156/doc Modified Files: .cvsignore odepkg.texi Log Message: Manual update. Index: .cvsignore =================================================================== RCS file: /cvsroot/octave/octave-forge/main/odepkg/doc/.cvsignore,v retrieving revision 1.1 retrieving revision 1.2 diff -u -d -r1.1 -r1.2 --- .cvsignore 26 Feb 2007 20:07:25 -0000 1.1 +++ .cvsignore 18 May 2007 19:53:04 -0000 1.2 @@ -1,3 +1,6 @@ +gdoc.sh +makedoc.sh +odepkg.dvi *.html *.info *.pdf Index: odepkg.texi =================================================================== RCS file: /cvsroot/octave/octave-forge/main/odepkg/doc/odepkg.texi,v retrieving revision 1.11 retrieving revision 1.12 diff -u -d -r1.11 -r1.12 --- odepkg.texi 14 Mar 2007 21:42:47 -0000 1.11 +++ odepkg.texi 18 May 2007 19:53:04 -0000 1.12 @@ -52,60 +52,60 @@ * Beginner's Guide:: Manual for users that are completely new to OdePkg * User's Guide:: Manual for users that are already familiar with OdePkg * Coder's Guide:: Manual for users that want to make changes to OdePkg -* Appendix:: +* Appendix:: The GNU Free Documentation License of this document @end menu @c %*** Start of first chapter: Beginner's Guide @node Beginner's Guide, User's Guide, Top, Top @chapter Beginner's Guide -The ``Beginner's Guide'' is intended for new users who want to solve differential equations with the higher level language Octave and the toolbox OdePkg. In this chapter 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 road map}. In @ref{Installation and deinstallation} it is explained how OdePkg can be installed and in @ref{First tests and demos} the first examples are explained. +The ``Beginner's Guide'' is intended for new users who want to solve differential equations with the higher level language Octave and the toolbox OdePkg. In this chapter 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 and in @ref{First tests and demos} the first examples are explained. @menu * About OdePkg:: An introduction about OdePkg -* OdePkg history and road map:: From the initial release until now +* OdePkg history and roadmap:: From the initial release until now * Installation and deinstallation:: Setting up OdePkg on your system * Reporting Bugs:: Writing comments and bugs * First tests and demos:: The --foo-- example and others @end menu -@node About OdePkg, OdePkg history and road map, Beginner's Guide, Beginner's Guide +@node About OdePkg, OdePkg history and roadmap, Beginner's Guide, Beginner's Guide @section About OdePkg OdePkg is part of the @b{GNU Octave Repository} (resp. the Octave--Forge project) that was initiated by Paul Kienzle in the year 2000 and that is hosted at @url{http://octave.sourceforge.net}. The package includes commands for setting up various options, output functions etc. before solving a set of differential equations with the solver functions that are also included. OdePkg formerly was initiated to solve explicitly formulated ordinary differential equations (ODEs) only, but there are already improvements so that differential algebraic equations (DAEs) in explicit form can also be solved. At this time OdePkg is under development with the main target, to make a package that is mostly compatible to commercial solver products. -@node OdePkg history and road map, Installation and deinstallation, About OdePkg, Beginner's Guide -@section OdePkg history and road map +@node OdePkg history and roadmap, Installation and deinstallation, About OdePkg, Beginner's Guide +@section OdePkg history and roadmap @cindex history -@cindex road map +@cindex roadmap @multitable @columnfractions .25 .75 @item OdePkg Version 0.0.1 @tab The initial release was already a modification of the old ``ode package'' that was hosted at Octave--Forge and that was written by Marc Compere some when 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}, etc.). Since version 0.1.3 there is also 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 @b{(current)} 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 stable enough so that they could be installed by default. Wrapper functions have been added to the package with help texts and tests (namely <TODO>). -@item @b{(future)} Version 0.3.x -@tab All interface functions for the solvers of Hairer and Wanner are stable so that they can be installed by default (via a @file{Makefile} or the @file{PKA_ADD} file). Finished adding all wrapper functions and help descriptions for theses solvers, added tests and demos for these solvers. Ongoing work with this manual. +@item OdePkg Version 0.2.x +@tab The main work along version 0.2.x was making 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 with help texts and tests (eg. @command{ode2r}, @command{ode5r}, @command{oders} etc.). Six testsuite functions have been added for performance tests of the different solvers (@command{odepkg_testsuite_chemakzo}, @command{odepkg_testsuite_oregonator}, @command{odepkg_testsuite_transistor}, etc.). +@item @b{(current)} Version 0.3.x +@tab Ongoing work with this manual. Fetching and adding DDE--solvers from Netlib or Ernst Hairer or Jeff Cash. @item @b{(future)} Version 0.4.x -@tab (Maybe) Some of the Hindmarsh, Brown and Petzold solvers are added, but/and/or I think I prefer the solvers of Jeff Cash instead. Don't know if DDE solver and BVP solvers should be added to this package. By now I don't have the need for this. +@tab Ongoing work with this manual. Fetching and adding IDE--solvers from Netlib or Ernst Hairer or Jeff Cash. @item @b{(future)} Version 0.5.x -@tab (Maybe) A lot of compatibility tests will be done again. +@tab (Maybe) A lot of compatibility tests. @item @b{(future)} Version 0.6.x @tab (Maybe) Final release before version 1.0.0. @item @b{(future)} Version 1.0.0 @tab Completed odepkg release 1.0.0 with m--solvers and mex--solvers. @end multitable -@node Installation and deinstallation, Reporting Bugs, OdePkg history and road map, Beginner's Guide +@node Installation and deinstallation, Reporting Bugs, OdePkg history and roadmap, Beginner's Guide @section Installation and deinstallation @cindex installation @cindex deinstallation -OdePkg can be installed easily using the @command{pkg} command of Octave. Therefore get into the directory where the current release of OdePkg can be found, start @command{octave} and type +OdePkg can be installed easily using the @command{pkg} command of Octave. For this get into the directory where the current release of OdePkg can be found, start @command{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 that is available. If you want to deinstall resp. remove OdePkg then simply type +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-x.x.x.tar.gz @end example @@ -209,7 +209,7 @@ @node Solver families, ODE/DAE options, User's Guide, User's Guide @section Solver families @cindex Solver -In this section the different kinds of solvers are explained. It is started with the standard M--file Runge--Kutta solvers in section @ref{M--file Runge--Kutta solvers} and then it is continued with the Mex--file Hairer--Wanner solvers in section @ref{Mex--file Hairer--Wanner solvers}. 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}. +In this section the different kinds of solvers are explained. It starts with the standard M--file Runge--Kutta solvers in section @ref{M--file Runge--Kutta solvers} and then it is continued with the Mex--file Hairer--Wanner solvers in section @ref{Mex--file Hairer--Wanner solvers}. 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 * M--file Runge--Kutta solvers:: The ODE solvers written in the Octave language @@ -220,83 +220,54 @@ @node M--file Runge--Kutta solvers, Mex--file Hairer--Wanner solvers, Solver families, Solver families @subsection M--file Runge--Kutta solvers -The M--file Runge--Kutta solvers are written in the Octave interpreter language. There have been implemented four different solvers within OdePkg, ie. @command{ode23}, @command{ode45}, @command{ode54} and @command{ode78} that are explained in the following. -@table @code -@item ode23 -Integrates a system of ordinary differential equations using 2nd and 3rd order Runge--Kutta formulas. This particular 3rd--order method reduces to Simpson's 1/3 rule and uses the 3rd order estimation for the output solutions. 3rd--order accurate Runge--Kutta methods have local and global errors of @math{O(h^4)} and @math{O(h^3)} (where @math{h} is the step size from one to another integration step), respectively and yield exact results when the solution is a cubic. - -The order of the Runge--Kutta method 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, ie. @math{l(h) = x(O(h+1)) - x(O(h))}. 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 the step size @math{h} when solving for a solution from the general Runge--Kutta method. Therefore, the order--p solution created by the Runge--Kutta method will be roughly accurate to @math{O(h^{(p+1)})} since the local truncation error shows up in the solution as h*d, which is h times an O(h^(p)) term, or rather O(h^(p+1)). - -@c Summary: For an order-p accurate RK method, -@c - the local truncation error is O(h^p) -@c - the local error used for stepsize adjustment and that -@c is actually realized in a solution is O(h^(p+1)) - -This requires 3 function evaluations per integration step. +The M--file Runge--Kutta solvers are written in the Octave interpreter language and are stored @file{*.m} files. There have been implemented four different solvers of similiar structure and types, 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 m--file 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''.}. -@c Relevant discussion on step size choice can be found on pp.90,91 in -@c U.M. Ascher, L.R. Petzold, Computer Methods for Ordinary Differential Equations -@c and Differential-Agebraic Equations, Society for Industrial and Applied Mathematics -@c (SIAM), Philadelphia, 1998 +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, @math{l(h) = x(O(h+1)) - x(O(h))}. 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 @math{O(h^{(p+1)})} since the local truncation error shows up in the solution as @math{e = h d}, which is @math{h} times an @math{O(h^p)} term, or rather @math{O(h^{(p+1)})}. -@c The error estimate formula and slopes are from -@c Numerical Methods for Engineers, 2nd Ed., Chapra & Canale, McGraw-Hill, 1985 +@table @code +@item ode23 +Integrates a system of ordinary differential equations 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 ode45 -Integrates a system of ordinary differential equations using 4th and 5th order embedded formulas from Dormand--Prince or Fehlberg. -@c The Fehlberg 4(5) pair is established and works well, however, the Dormand-Prince 4(5) pair minimizes the local truncation error in the 5th-order estimate which is what is used to step forward (local extrapolation.) Generally it produces more accurate results and costs roughly the same computationally. The Dormand-Prince pair is the default. -@c This is a 4th-order accurate integrator therefore the local error normally expected is O(h^5). However, because this particular implementation uses the 5th-order estimate for x_out (i.e. local extrapolation) moving forward with the 5th-order estimate should yield local error of O(h^6). -@c The order of the RK method is the order of the local *truncation* error, d, 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, l(h) = x_(O(h+1)) - x_(O(h)). 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 h when solving for a solution from the general RK method. Therefore, the order-p solution created by the RK method will be roughly accurate to O(h^(p+1)) since the local truncation error shows up in the solution as h*d, which is h times an O(h^(p)) term, or rather O(h^(p+1)). -@c Summary: For an order-p accurate RK method, -@c - the local truncation error is O(h^p) -@c - the local error used for stepsize adjustment and that -@c is actually realized in a solution is O(h^(p+1)) -@c This requires 6 function evaluations per integration step. -@c % Both the Dormand-Prince and Fehlberg 4(5) coefficients are from a tableu in -@c % U.M. Ascher, L.R. Petzold, Computer Methods for Ordinary Differential Equations -@c % and Differential-Agebraic Equations, Society for Industrial and Applied Mathematics -@c % (SIAM), Philadelphia, 1998 -@c % -@c % The error estimate formula and slopes are from -@c % Numerical Methods for Engineers, 2nd Ed., Chappra & Cannle, McGraw-Hill, 1985 +Integrates a system of ordinary differential equations 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 ode54 -todo +The Fehlberg @math{4(5)} of the @command{ode45} pair is established and works well, however, the Dormand--Prince @math{4(5)} 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 ode78 -Integrates a system of ordinary differential equations using 7th and 8th order formulas. -@c This is a 7th-order accurate integrator therefore the local error normally expected is O(h^8). However, because this particular implementation uses the 8th-order estimate for xout (i.e. local extrapolation) moving forward with the 8th-order estimate will yield errors on the order of O(h^9). -@c The order of the RK method is the order of the local *truncation* error, d, 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, l(h) = x_(O(h+1)) - x_(O(h)). 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 h when solving for a solution from the general RK method. Therefore, the order-p solution created by the RK method will be roughly accurate to O(h^(p+1)) since the local truncation error shows up in the solution as h*d, which is h times an O(h^(p)) term, or rather O(h^(p+1)). -@c Summary: For an order-p accurate RK method, -@c - the local truncation error is O(h^p) -@c - the local error used for stepsize adjustment and that -@c is actually realized in a solution is O(h^(p+1)) -@c -@c This requires 13 function evaluations per integration step. -@c -@c Relevant discussion on step size choice can be found on pp.90,91 in -@c U.M. Ascher, L.R. Petzold, Computer Methods for Ordinary Differential Equations -@c and Differential-Agebraic Equations, Society for Industrial and Applied Mathematics -@c (SIAM), Philadelphia, 1998 -@c -@c More may be found in the original author's text containing numerous -@c applications on ordinary and partial differential equations using Matlab: -@c -@c Howard Wilson and Louis Turcotte, 'Advanced Mathematics and -@c Mechanics Applications Using MATLAB', 2nd Ed, CRC Press, 1997 +Integrates a system of ordinary differential equations 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 table @node Mex--file Hairer--Wanner solvers, Other solvers, M--file Runge--Kutta solvers, Solver families @subsection Mex--file Hairer--Wanner solvers +The mex--file Hairer--Wanner solvers are written in Fortran (hosted at @url{http://www.unige.ch/~hairer}) and have been added to the OdePkg as a compressed file with the name @file{hairer.tgz}. The licence of these solvers is a modified BSD license (without advertising clause) and can be found as @file{licence.txt} file in the @file{hairer.tgz} package and therefore the Fortran files are GPL compatible. Papers and other details about these solvers can be found at the host adress. -Interface functions for the solvers from Ernst Hairer and Gerhard Wanner (hosted at @url{http://www.unige.ch/~hairer}) have been added to the OdePkg as a compressed file with the name @file{hairer.tgz}. The licence of these solvers is a modified BSD license (without advertising clause) and can be found as @file{licence.txt} file in the @file{hairer.tgz} package. Therefore the Fortran files are GPL compatible. +Interface functions for these solvers have been created and have been added to the OdePkg. Their names are @file{odepkg_mexsolver_xxx.c} where @file{xxx} is the name of the Fortran file that is interfaced. The corresponding @file{odepkg_mexsolver_xxx.mex} files are created automatically when installing OdePkg with the @command{pkg} command, but can also be build manually with the instructions given as a preamble of every @file{odepkg_mexsolver_xxx.c} file. + +To provide a shorter name to access these solver functions also wrapper functions have been added that do link to the interface functions, eg. the command @command{oderd} links to the interface functions @command{odepkg_mexsolver_radau} and should do exactly the same. Another reason of adding wrapper functions was that help texts, demos and tests cannot be added to the @file{odepkg_mexsolver_xxx.c} files. For accessing the help texts, demos and tests for one of these solvers you should therefore always use the name of the wrapper function, eg. @command{help oderd}. + +The mex--file Hairer--Wanner solvers have been added to the OdePkg to also solve stiff ordinary differential equations that cannot be solved with one of the m--file Runge--Kutta solvers. The following table gives an overview about which solver can be used for the different kind of problems. + +@float +@multitable {ODE--Problem} {Solver name} {Wrapper file} {@file{odepkg_mexsolver_seulex.c}} {Fortran file} +@headitem ODE--Problem @tab Solver name @tab Wrapper file @tab Interface file @tab Fortran file +@item Non--stiff @tab DOPRI5 @tab @file{ode5d.m} @tab @file{odepkg_mexsolver_dopri5.c} @tab @file{dopri5.f} +@item Non--stiff @tab DOP853 @tab @file{ode8d.m} @tab @file{odepkg_mexsolver_dop853.c} @tab @file{dop853.f} +@item Non--stiff @tab ODEX @tab @file{odeox.m} @tab @file{odepkg_mexsolver_odex.c} @tab @file{odex.f} +@item Stiff @tab RADAU @tab @file{ode2r.m} @tab @file{odepkg_mexsolver_radau.c} @tab @file{radau.f} +@item Stiff @tab RADAU5 @tab @file{ode5r.m} @tab @file{odepkg_mexsolver_radau5.c} @tab @file{radau5.f} +@item Stiff @tab RODAS @tab @file{oders.m} @tab @file{odepkg_mexsolver_rodas.c} @tab @file{rodas.f} +@item Stiff @tab SEULEX @tab @file{odesx.m} @tab @file{odepkg_mexsolver_seulex.c} @tab @file{seulex.f} +@end multitable +@caption{Overview about Fortran, Interface and Wrapper files for Hairer--Wanner solvers.} +@end float @node Other solvers, ODE solver performances, Mex--file Hairer--Wanner solvers, Solver families @subsection Other solvers -@c The solvers from Jeff Cash http://www.ma.ic.ac.uk/~jcash have not been added to the OdePkg because it seems that there may exist some unfixed bugs. Modified solver files with bug fixes can be found at http://pitagora.dm.uniba.it/~testset, but the disclaimer's part of this site is not clear and maybe the modified solver files are not GPL compatible. +The solvers from Jeff Cash http://www.ma.ic.ac.uk/~jcash have not been added to the OdePkg because it seems that there may exist some unfixed bugs. Modified solver files with bug fixes can be found at http://pitagora.dm.uniba.it/~testset, but the disclaimer's part of this site is not clear and maybe the modified solver files are not GNU--GPL compatible. -@c The people from the University of Bari at http://pitagora.dm.uniba.it/~testset have been created the solvers BIMD and GAMD. But like before the disclaimer's part of this internet site is not clear and maybe is not GPL compatible. +The people from the University of Bari at http://pitagora.dm.uniba.it/~testset created the solvers BIMD and GAMD. But like before the disclaimer's part of this internet site is not clear and maybe they are not GNU--GPL compatible. @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. |