X-Git-Url: https://git.creatis.insa-lyon.fr/pubgit/?p=CreaPhase.git;a=blobdiff_plain;f=octave_packages%2Fodepkg-0.8.2%2Fdoc.info;fp=octave_packages%2Fodepkg-0.8.2%2Fdoc.info;h=1b913ac7eafd2860625d10bb7605c80c11ecc553;hp=0000000000000000000000000000000000000000;hb=f5f7a74bd8a4900f0b797da6783be80e11a68d86;hpb=1705066eceaaea976f010f669ce8e972f3734b05 diff --git a/octave_packages/odepkg-0.8.2/doc.info b/octave_packages/odepkg-0.8.2/doc.info new file mode 100644 index 0000000..1b913ac --- /dev/null +++ b/octave_packages/odepkg-0.8.2/doc.info @@ -0,0 +1,2758 @@ +Dies ist odepkg.info, hergestellt von Makeinfo Version 4.8 aus +odepkg.texi. + + +File: odepkg.info, Node: Top, Next: Beginners Guide, Prev: (dir), Up: (dir) + +Copyright +********* + +Copyright (C) 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. + +* 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 + + +File: odepkg.info, Node: Beginners Guide, Next: Users Guide, Prev: Top, Up: Top + +1 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 *Note About OdePkg:: and how OdePkg grew up from the beginning +in *Note OdePkg history and roadmap::. In *Note 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 *Note Reporting Bugs:: how these bugs can be reported. In the *Note +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 + + +File: odepkg.info, Node: About OdePkg, Next: OdePkg history and roadmap, Prev: Beginners Guide, Up: Beginners Guide + +1.1 About OdePkg +================ + +OdePkg is part of the 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 `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. + + OdePkg includes commands for setting up various options, output +functions etc. before solving a set of differential equations with the +solver functions that are included. The package formerly was initiated +in autumn 2006 to solve ordinary differential equations (ODEs) only but +there are already improvements so that differential algebraic equations +(DAEs) in explicit form and in implicit form (IDEs) and delay +differential equations (DDEs) can also be solved. The goal of OdePkg is +to have a package for solving differential equations that is mostly +compatible to proprietary solver products. + + +File: odepkg.info, Node: OdePkg history and roadmap, Next: Installation and deinstallation, Prev: About OdePkg, Up: Beginners Guide + +1.2 OdePkg history and roadmap +============================== + +OdePkg Version The initial release was a modification of the old +0.0.1 "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 (`odeprint', `odeplot', `odephas2' + and `odephas3') have been added along with other + examples that initially have not been there. +OdePkg Version The major milestone along versions 0.1.x was that +0.1.x four stable solvers have been implemented (ie. + `ode23', `ode45', `ode54' and `ode78') supporting all + options that can be set for these kind of solvers and + also all necessary functions for setting their + options (eg. `odeset', `odepkg_structure_check, + odepkg_event_handle'). Since version 0.1.3 there is + also source code available that interfaces the + Fortran solver `dopri5.f' (that is written by Ernst + Hairer and Gerhard Wanner, cf. + `odepkg_mexsolver_dopri5.c' and the helper files + `odepkgext.c' and `odepkgmex.c'). +OdePkg Version The main work along version 0.2.x was to make the +0.2.x 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. `ode2r', `ode5r', `oders'). Six testsuite + functions have been added to check the performance of + the different solvers (eg. + `odepkg_testsuite_chemakzo', + `odepkg_testsuite_oregonator'). +OdePkg Version Fixed some minor bugs along version 0.3.x. Thanks to +0.3.x Jeff Cash, who released his Fortran `mebdfX' solvers + under the GNU GPL V2 after some discussion. The first + IDE solver `odebdi' appeared that is an interface + function for Cash's `mebdfi' Fortran core solver. + With version 0.3.5 of OdePkg a first new interface + function was created based on Octave's C++ + `DEFUN_DLD' interface to achieve the highest + performance available. Added more examples and + testsuite functions (eg. `odepkg_equations_ilorenz', + `odepkg_testsuite_implrober'). Porting all at this + time present Mex-file solvers to Octave's C++ + `DEFUN_DLD' interface. Ongoing work with this manual. +OdePkg Version Added a new solver function `odekdi' for the direct +0.4.x method (not the Krylov method) of the `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. +OdePkg Version Added new solver functions `ode23d', `ode45d', +0.5.x `ode54d' and `ode78d' for solving non-stiff delay + differential equations (non-stiff DDEs). These + solvers are based on the Runge-Kutta solvers + `ode23'..`ode78'. Tests and demos have been included + for this type of solvers. Added new functions + `odeexamples', `odepkg_examples_ode', + `odepkg_examples_dae', `odepkg_examples_ide' and + `odepkg_examples_ide'. Ongoing work with this manual. +OdePkg Version A lot of compatibility tests, improvements, bugfixes, +0.6.x etc. +(current) Version Final releases before version 1.0.0. +0.8.x +(future) Version Completed OdePkg release 1.0.0 with M-solvers and +1.0.0 DLD-solvers. + + +File: odepkg.info, Node: Installation and deinstallation, Next: Reporting Bugs, Prev: OdePkg history and roadmap, Up: Beginners Guide + +1.3 Installation and deinstallation +=================================== + +OdePkg can be installed easily using the `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 + pkg install odepkg-x.x.x.tar.gz + where `x.x.x' in the name of the `*.tar.gz' file is the current +release number of OdePkg that is available. If you want to deinstall +resp. remove OdePkg then simply type + pkg uninstall odepkg + and make sure that OdePkg has been removed completely and does not +appear in the list of installed packages anymore with the following +command + pkg list + + +File: odepkg.info, Node: Reporting Bugs, Next: The "foo" example, Prev: Installation and deinstallation, Up: Beginners Guide + +1.4 Reporting Bugs +================== + +If you encounter problems during the installation process of OdePkg +with the `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 +. 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). + + +File: odepkg.info, Node: The "foo" example, Prev: Reporting Bugs, Up: Beginners Guide + +1.5 The "foo" example +===================== + +Have a look at the first ordinary differential equation with the name +"`foo'". The `foo' equation of second order may be of the form y"(t) + +C_1 y'(t) + C_2 y(t) = C_3. With the substitutions y_1(t) = y(t) and +y_2(t) = y'(t) this differential equation of second order can be split +into two differential equations of first order, ie. y'_1(t) = y_2(t) +and y'_2(t) = - C_1 y_2(t) - C_2 y_1(t) + C_3. Next the numerical +values for the constants need to be defined, ie. C_1 = 2.0, C_2 = 5.0, +C_3 = 10.0. This set of ordinary differential equations can then be +written as an Octave M-file function like + 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 + 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 VT followed by a solution array argument `vy' as the +second input argument and a variable size input argument `varargin' +that can be used to set up user defined constants or control variables. + + As it is known that `foo' is a set of ordinary differential +equations we can choose one of the four Runge-Kutta solvers (cf. *Note +Solver families::). It is also known that the time period of interest +may be between t_0 = 0.0 and t_e = 5.0 as well as that the initial +values of the ODEs are y_1(t=0) = 0.0 and y_2(t=0) = 0.0. Solving this +set of ODEs can be done by typing the following commands in Octave + ode45 (@foo, [0 5], [0 0]); + 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. + ode45 (@foo, [0:0.1:5], [0 0]); + 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. + [t, y] = ode45 (@foo, [0 5], [0 0]); + 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 `S.x' and `S.y'. + S = ode45 (@foo, [0 5], [0 0]); + 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 `varargin' can be +used for. So rewrite the function `foo' into `newfoo' the following way + 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 + 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 `newfoo' as before with the +function `foo' (ie. the parameters are directly feed through from the +caller routine `ode45' to the function `newfoo') + ode45 (@newfoo, [0 5], [0 0], 2.0, 5.0, 10.0); + OdePkg can do much more while solving differential equations, eg. +setting up other output functions instead of the function `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 `odeset' + A = odeset ('OutputFcn', @odeprint); + ode45 (@newfoo, [0 5], [0 0], A, 2.0, 5.0, 10.0); + or + A = odeset ('OutputFcn', @odeprint, 'AbsTol', 1e-5, \ + 'RelTol', 1e-5, 'NormControl', 'on'); + ode45 (@newfoo, [0 5], [0 0], A, 2.0, 5.0, 10.0); + The options structure `A' that can be set up with with the 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 `A' +must be the fifth input argument (cf. *Note Solver families::). The +various options that can be set with the command `odeset' are described +in *Note ODE/DAE/IDE/DDE options::. + + Further examples have also been implemented. These example files and +functions are of the form `odepkg_examples_*'. Different testsuite +examples have been added that are stored in files with filenames +`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 + help fcnname + in the Octave window where `fcnname' is the name of the function for +the help text to be viewed. Type + demo fcnname + in the Octave window where `fcnname' is the name of the function for +the demo to run. Finally write + doc odepkg + for opening this manual in the texinfo reader of the Octave window. + + +File: odepkg.info, Node: Users Guide, Next: Programmers Guide, Prev: Beginners Guide, Up: Top + +2 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 *Note Differential Equations::. It will be +explained which solvers can be used for the different kind of equations +in *Note Solver families:: and which options can be set for the +optimization of the solving process in *Note 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 *Note M-File Function +Reference:: and *Note Oct-File Function Reference::. + +* Menu: + +* Differential Equations:: The different kind of problems that can be solved with OdePkg +* Solver families:: The different kind of solvers within OdePkg +* ODE/DAE/IDE/DDE options:: The options that can be set for a solving process +* M-File Function Reference:: The description about all `*.m'-file functions +* Oct-File Function Reference:: The description about all DLD-functions from `*.oct'-files + + +File: odepkg.info, Node: Differential Equations, Next: Solver families, Prev: Users Guide, Up: Users Guide + +2.1 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 *Note ODE equations:: +followed by the description of explicetly formulated differential +algebraic equations in section *Note DAE equations::, implicetely +formulated differential algebraic equations in section *Note IDE +equations:: and delay differential algebraic equations in section *Note +DDE equations::. + +* Menu: + +* ODE equations:: Ordinary differential equations +* DAE equations:: Differential algebraic equations in explicit form +* IDE equations:: Differential algebraic equations in implicit form +* DDE equations:: Delay differential equations + + +File: odepkg.info, Node: ODE equations, Next: DAE equations, Prev: Differential Equations, Up: Differential Equations + +2.1.1 ODE equations +------------------- + +ODE equations in general are of the form y'(t) = f(t,y) where y'(t) may +be a scalar or vector of derivatives. The variable t always is a scalar +describing one point of time and the variable 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 *Note +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 *Note Hairer-Wanner solvers::. An ODE equation definition in Octave +must look like + function [dy] = ODEequation (t, y, varargin) + + +File: odepkg.info, Node: DAE equations, Next: IDE equations, Prev: ODE equations, Up: Differential Equations + +2.1.2 DAE equations +------------------- + +DAE equations in general are of the form M(t,y) \cdot y'(t) = f(t,y) +where y'(t) may be a scalar or vector of derivatives. The variable t +always is a scalar describing one point of time and the variable y(t) +is a scalar or vector of solutions from the set of differential +algebraic equations. The variable M(t,y) is the squared singular mass +matrix that may depend on y and t. If M(t,y) is not 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 `odeset' to pass the mass +matrix information to the solver function (cf. *Note ODE/DAE/IDE/DDE +options::). If the equation is non-stiff then the *Note 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 *Note +Hairer-Wanner solvers::. A DAE equation definition in Octave must look +like + function [dy] = DAEequation (t, y, varargin) + 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 `odeset' (cf. option `Mass' of section +*Note ODE/DAE/IDE/DDE options::). + + +File: odepkg.info, Node: IDE equations, Next: DDE equations, Prev: DAE equations, Up: Differential Equations + +2.1.3 IDE equations +------------------- + +IDE equations in general are of the form y'(t) + f(t,y) = 0 where y'(t) +may be a scalar or vector of derivatives. The variable t always is a +scalar describing one point of time and the variable y(t) is a scalar +or vector of solutions from the set of implicit differential equations. +Only IDE solvers from section *Note Cash modified BDF solvers:: or +section *Note DDaskr direct method solver:: can be used to solve such +kind of differential equations. A DAE equation definition in Octave +must look like + function [residual] = IDEequation (t, y, dy, varargin) + + +File: odepkg.info, Node: DDE equations, Prev: IDE equations, Up: Differential Equations + +2.1.4 DDE equations +------------------- + +DDE equations in general are of the form y'(t) = +f(t,y(t),y(t-\tau_1),...,y(t-\tau_n)) where y'(t) may be a scalar or +vector of derivatives. The variable t always is a scalar describing one +point of time and the variables y(t-\tau_i) are scalars or vectors from +the past. Only DDE solvers from section *Note Modified Runge-Kutta +solvers:: can be used to solve such kind of differential equations. A +DDE equation definition in Octave must look like + function [dy] = DDEequation (t, y, z, varargin) + NOTE: Only DDEs with constant delays y(t-\tau_i) can be solved with +OdePkg. + + +File: odepkg.info, Node: Solver families, Next: ODE/DAE/IDE/DDE options, Prev: Differential Equations, Up: Users Guide + +2.2 Solver families +=================== + +In this section the different kind of solvers are introduced that have +been implemented in OdePkg. This section starts with the basic +Runge-Kutta solvers in section *Note Runge-Kutta solvers:: and is +continued with the Mex-file Hairer-Wanner solvers in section *Note +Hairer-Wanner solvers::. Performance tests have also been added to the +OdePkg. Some of these performance results have been added to section +*Note ODE solver performances::. + +* Menu: + +* Runge-Kutta solvers:: ODE solvers written as `*.m' files +* Hairer-Wanner solvers:: DAE solvers interfaced by `*.cc' files +* Cash modified BDF solvers:: A DAE and an IDE solver interfaced by `*.cc' files +* DDaskr direct method solver:: An IDE solver interfaced by a `*.cc' file +* Modified Runge-Kutta solvers:: DDE solvers written as `*.m' files +* ODE solver performances:: Cross math-engine performance tests + + +File: odepkg.info, Node: Runge-Kutta solvers, Next: Hairer-Wanner solvers, Prev: Solver families, Up: Solver families + +2.2.1 Runge-Kutta solvers +------------------------- + +The Runge-Kutta solvers are written in the Octave language and that are +saved as `m'-files. There have been implemented four different solvers +with a very similiar structure, ie. `ode23', `ode45', `ode54' and +`ode78'(1). The Runge-Kutta solvers have been added to the OdePkg to +solve non-stiff ODEs and DAEs, stiff equations of that form cannot be +solved with these solvers. + + The order of all of the following Runge-Kutta methods is the order +of the local truncation error, which is the principle error term in the +portion of the Taylor series expansion that gets dropped, or +intentionally truncated. This is different from the local error which +is the difference between the estimated solution and the actual, or +true solution. The local error is used in stepsize selection and may be +approximated by the difference between two estimates of different order, +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 Runge-Kutta method. +Therefore, the order-p solution created by the Runge-Kunge method will +be roughly accurate to O(h^(p+1)) since the local truncation error +shows up in the solution as e = h\cdot d which is h-times an +O(h^p)-term, or rather O(h^(p+1)). + +`ode23'Integrates a system of non-stiff ordinary differential equations + (non-stiff ODEs and DAEs) using second and third order Runge-Kutta + formulas. This particular third order method reduces to Simpson's + 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 O(h^4) and O(h^3) respectively and yield exact + results when the solution is a cubic (the variable h is the step + size from one integration step to another integration step). This + solver requires three function evaluations per integration step. +`ode45'Integrates a system of non-stiff ordinary differential equations + (non-stiff ODEs and DAEs) using fourth and fifth order embedded + formulas from Fehlberg. This is a fourth-order accurate integrator + therefore the local error normally expected is O(h^5). However, + because this particular implementation uses the fifth-order + estimate for x_out (ie. local extrapolation) moving forward with + the fifth-order estimate should yield local error of O(h^6). This + solver requires six function evaluations per integration step. +`ode54'Integrates a system of non-stiff ordinary differential equations + (non-stiff ODEs and DAEs) using fifth and fourth order Runge-Kutta + formulas. The Fehlberg 4(5) of the `ode45' pair is established and + works well, however, the Dormand-Prince 5(4) pair minimizes the + local truncation error in the fifth-order estimate which is what + is used to step forward (local extrapolation). Generally it + produces more accurate results and costs roughly the same + computationally. This solver requires seven function evaluations + per integration step. +`ode78'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 O(h^8). However, + because this particular implementation uses the eighth-order + estimate for x_out moving forward with the eighth-order estimate + will yield errors on the order of O(h^9). This solver requires + thirteen function evaluations per integration step. + + ---------- Footnotes ---------- + + (1) 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". + + +File: odepkg.info, Node: Hairer-Wanner solvers, Next: Cash modified BDF solvers, Prev: Runge-Kutta solvers, Up: Solver families + +2.2.2 Hairer-Wanner solvers +--------------------------- + +The Hairer-Wanner solvers have been written by Ernst Hairer and Gerhard +Wanner. They are written in the Fortran language (hosted at +`http://www.unige.ch/~hairer') and that have been added to the OdePkg +as a compressed file with the name `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 `licence.txt' file in the `hairer.tgz' package. The Hairer-Wanner +solvers have been added to the OdePkg to solve non-stiff and stiff ODEs +and DAEs that cannot be solved with any of the Runge-Kutta solvers. + + Interface functions for these solvers have been created and have +been added to the OdePkg. Their names are `odepkg_octsolver_XXX.cc' +where `XXX' is the name of the Fortran file that is interfaced. The +file `dldsolver.oct' is created automatically when installing OdePkg +with the command `pkg', but developers can also build each solver +manually with the instructions given as a preamble of every +`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 `ode2r' calls the solver `radau' from the Fortran file +`radau.f'. The other wrapper functions for the Hairer-Wanner solvers +are `ode5r' for the `radau5' solver, `oders' for the `rodas' solver and +`odesx' for the `seulex' solver. The help text of all these solver +functions can be diaplyed by calling `help wrapper' where wrapper is +one of `ode2r', `ode5r', `oders' or `odesx'. + + +File: odepkg.info, Node: Cash modified BDF solvers, Next: DDaskr direct method solver, Prev: Hairer-Wanner solvers, Up: Solver families + +2.2.3 Cash modified BDF solvers +------------------------------- + +The backward differentiation algorithm solvers have been written by +Jeff Cash in the Fortran language and that are hosted at +`http://pitagora.dm.uniba.it/~testset'. They have been added to the +OdePkg as a compressed file with the name `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 `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 `odepkg_octsolver_XXX.cc' +where `XXX' is the name of the Fortran file that is interfaced. The +file `dldsolver.oct' is created automatically when installing OdePkg +with the command `pkg', but developers can also build each solver +manually with the instructions given as a preamble of every +`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 +`odebda' calls the solver `mebdfdae' from the Fortran file `mebdf.f' +and the `odebdi' calls the solver `mebdfi' from the Fortran file +`mebdfi.f'. + + +File: odepkg.info, Node: DDaskr direct method solver, Next: Modified Runge-Kutta solvers, Prev: Cash modified BDF solvers, Up: Solver families + +2.2.4 DDaskr direct method solver +--------------------------------- + +The direct method from the Krylov solver 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 +`http://www.netlib.org'. 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 `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 `ddaskr.f'. The +direct method solver of the 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 +`odepkg_octsolver_ddaskr.cc'. The binary function can be found in the +file `dldsolver.oct' that is created automatically when installing +OdePkg with the command `pkg', but developers can also build the solver +wrapper manually with the instructions given as a preamble of the +`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 +`odekdi' calls the direct method of the solver `ddaskr' from the +Fortran file `ddaskr.f'. + + +File: odepkg.info, Node: Modified Runge-Kutta solvers, Next: ODE solver performances, Prev: DDaskr direct method solver, Up: Solver families + +2.2.5 Modified Runge-Kutta solvers +---------------------------------- + +The modified Runge-Kutta solvers are written in the Octave language and +that are saved as m-files. There have been implemented four different +solvers that do have a very similiar structure to that solvers found in +section *Note Runge-Kutta solvers::. Their names are `ode23d', +`ode45d', `ode54d' and `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 *Note Runge-Kutta solvers::. + + Note: The four DDE solvers of OdePkg are not syntax compatible to +propietary solvers. The reason is that the input arguments of the +propietary DDE-solvers are completely mixed up in comparison to ODE, +DAE and IDE propietary solvers. The DDE solvers of OdePkg have been +implemented in form of a syntax compatible way to the other family +solvers, eg. propietary solver calls look like + + 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 + whereas in OdePkg the same examples would look like + 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 + + Further, the commands `ddeset' and `ddeget' have not been +implemented in OdePkg. Use the functions `odeset' and `odeget' for +setting and returning DDE options instead. + + +File: odepkg.info, Node: ODE solver performances, Prev: Modified Runge-Kutta solvers, Up: Solver families + +2.2.6 ODE solver performances +----------------------------- + +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). + + >> 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 + ----------------------------------------------------------------------------------------- + + 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 + ----------------------------------------------------------------------------------------- + + 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). + + >> odepkg ('odepkg_performance_matchemakzo'); + ----------------------------------------------------------------------------------------- + Solver RelTol AbsTol Init Mescd Scd Steps Accept FEval JEval LUdec Time + ----------------------------------------------------------------------------------------- + ode113 1e-007 1e-007 1e-007 NaN Inf - - - - - - + ode23 1e-007 1e-007 1e-007 NaN Inf 15 15 47 0.431 + ode45 1e-007 1e-007 1e-007 NaN Inf 15 15 92 0.170 + ode15s 1e-007 1e-007 1e-007 7.04 6.20 161 154 4 35 0.521 + ode23s 1e-007 1e-007 1e-007 7.61 6.77 1676 1676 5029 1676 1677 2.704 + ode23t 1e-007 1e-007 1e-007 5.95 5.11 406 404 3 39 0.611 + ode23tb 1e-007 1e-007 1e-007 NaN Inf 607 3036 1 608 6.730 + ----------------------------------------------------------------------------------------- + + octave:1> odepkg ('odepkg_performance_octavechemakzo'); + ----------------------------------------------------------------------------------------- + Solver RelTol AbsTol Init Mescd Scd Steps Accept FEval JEval LUdec Time + ----------------------------------------------------------------------------------------- + ode23 1e-07 1e-07 1e-07 2.95 2.06 424 385 1269 1.270 + ode45 1e-07 1e-07 1e-07 2.95 2.06 256 218 1530 1.281 + ode54 1e-07 1e-07 1e-07 2.95 2.06 197 195 1372 1.094 + ode78 1e-07 1e-07 1e-07 2.95 2.06 184 156 2379 1.933 + ode2r 1e-07 1e-07 1e-07 8.50 7.57 39 39 372 39 43 0.280 + ode5r 1e-07 1e-07 1e-07 8.50 7.57 39 39 372 39 43 0.238 + oders 1e-07 1e-07 1e-07 7.92 7.04 67 66 401 66 67 0.336 + odesx 1e-07 1e-07 1e-07 7.19 6.26 19 19 457 19 82 0.248 + odebda 1e-07 1e-07 1e-07 7.47 6.54 203 203 307 25 25 0.182 + ----------------------------------------------------------------------------------------- + + 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 `odepkg_testsuite_XXX.m' with +`XXX' being the name of the testsuite equation that has been +implemented. + + +File: odepkg.info, Node: ODE/DAE/IDE/DDE options, Next: M-File Function Reference, Prev: Solver families, Up: Users Guide + +2.3 ODE/DAE/IDE/DDE options +=========================== + +The default values of an OdePkg options structure can be displayed with +the command `odeset'. If `odeset' is called without any input argument +and one output argument then a OdePkg options structure with default +values is created, eg. + A = odeset (); + disp (A); + There also is an 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 `odeset'. The function description of the +commands `odeset' and `odeget' can be found in the *Note M-File +Function Reference::. The values that can be set with the `odeset' +command are + +`RelTol' + The option `RelTol' is used to set the relative error tolerance + for the error estimation of the solver that is used while solving. + It can either be a positive scalar or a vector with every element + of the vector being a positive scalar (this depends on the solver + that is used if both variants are supported). The definite error + estimation equation also depends on the solver that is used but + generalized (eg. for the solvers `ode23', `ode45', `ode54' and + `ode78') it may be a form like e(t) = max (r_tol^T y(t), a_tol). + Run the following example to illustrate the effect if this option + is used + 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); + +`AbsTol' + The option `AbsTol' is used to set the absolute error tolerance + for the error estimation of the solver that is used while solving. + It can either be a positive scalar or a vector with every element + of the vector being a positive scalar (it depends on the solver + that is used if both variants are supported). The definite error + estimation equation also depends on the solver that is used but + generalized (eg. for the solvers `ode23', `ode45', `ode54' and + `ode78') it may be a form like e(t) = max (r_tol^T y(t), a_tol). + Run the following example to illustrate the effect if this option + is used + ## 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); + +`NormControl' + The option `NormControl' is used to set the type of error + tolerance calculation of the solver that is used while solving. It + can either be the string `"on"' or `"off"'. At the time the solver + starts solving a warning message may be displayed if the solver + will ignore the `"on"' setting of this option because of an + unhandled resp. missing implementation. If set `"on"' then the + definite error estimation equation also depends on the solver that + is used but generalized (eg. for the solvers `ode23', `ode45', + `ode54' and `ode78') it may be a form like e(t) = max (r_tol^T max + (norm (y(t), \infty)), a_tol). Run the following example to + illustrate the effect if this option is used + 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); + +`MaxStep' + The option `MaxStep' is used to set the maximum step size for the + solver that is used while solving. It can only be a positive + scalar. By default this value is set internally by every solver + and also may differ when using different solvers. Run the + following example to illustrate the effect if this option is used + 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); + +`InitialStep' + The option `InitialStep' is used to set the initial first step + size for the solver. It can only be a positive scalar. By default + this value is set internally by every solver and also may be + different when using different solvers. Run the following example + to illustrate the effect if this option is used + 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); + +`InitialSlope' + The option `InitialSlope' is not handled by any of the solvers by + now. +`OutputFcn' + The option `OutputFcn' can be used to set up an output function + for displaying the results of the solver while solving. It must be + a function handle to a valid function. There are four predefined + output functions available with OdePkg. `odeprint' prints the + actual time values and results in the Octave window while solving, + `odeplot' plots the results over time in a new figure window while + solving, `odephas2' plots the first result over the second result + as a two-dimensional plot while solving and `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 + 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); + User defined output functions can also be used. A typical + framework for a self-made output function may then be of the form + function [vret] = odeoutput (vt, vy, vdeci, varargin) + switch vdeci + case "init" + ## Do everything needed to intialize output function + case "calc" + ## Do everything needed to create output + case "done" + ## Do everything needed to clean up output function + endswitch + endfunction + The output function `odeplot' is also set automatically if the + solver calculation routine is called without any output argument. + Run the following example to illustrate the effect if this option + is not used and no output argument is given + ## 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]); + +`Refine' + The option `Refine' is used to set the interpolation factor that + is used to increase the quality for the output values if an output + function is also set with the option `OutputFcn'. It can only be a + integer value 0<=`Refine'<=5. Run the following example to + illustrate the effect if this option is used + 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); + +`OutputSel' + The option `OutputSel' is used to set the components for which + output has to be performed if an output function is also set with + the option `OutputFcn'. It can only be a vector of integer values. + Run the following example to illustrate the effect if this option + is used + 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); + +`Stats' + The option `Stats' is used to print cost statistics about the + solving process after solving has been finished. It can either be + the string `"on"' or `"off"'. Run the following example to + illustrate the effect if this option is used + 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); + 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 `stats' of the output arguemnt structure. + Run the following example to illustrate the effect if this option + is used + S = ode78 (@fvanderpol, [0 2], [2 0], B); + disp (S); + +`Jacobian' + The option `Jacobian' can be used to set up an external Jacobian + function or Jacobian matrix for DAE solvers to achieve faster and + better results (ODE Runge-Kutta solvers do not need to handle a + Jacobian function handle or Jacobian matrix). It must either be a + function handle to a valid function or a full constant matrix of + size squared the dimension of the set of differential equations. + User defined Jacobian functions must have the form `function + [vjac] = fjac (vt, vy, varargin)'. Run the following example to + illustrate the effect if this option is used + 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); + Note: The function definition for Jacobian calculations of IDE + equations must have the form `function [vjac, vdjc] = fjac (vt, + vy, vyd, varargin)'. Run the following example to illustrate the + effect if this option is used + 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); + +`JPattern' + The option `JPattern' is not handled by any of the solvers by now. +`Vectorized' + The option `Vectorized' is not handled by any of the solvers by + now. +`Mass' + The option `Mass' can be used to set up an external Mass function + or Mass matrix for solving DAE equations. It depends on the solver + that is used if `Mass' is supported or not. It must either be a + function handle to a valid function or a full constant matrix of + size squared the dimension of the set of differential equations. + User defined Jacobian functions must have the form `function vmas + = fmas (vt, vy, varargin)'. Run the following example to + illustrate the effect if this option is used + 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); + Note: The function definition for Mass calculations of DDE + equations must have the form `function vmas = fmas (vt, vy, vz, + varargin)'. +`MStateDependence' + The option `MStateDependence' can be used to set up the type of + the external Mass function for solving DAE equations if a Mass + function handle is set with the option `Mass'. It depends on the + solver that is used if `MStateDependence' is supported or not. It + must be a string of the form `"none"', `"weak"' or `"strong"'. Run + the following example to illustrate the effect if this option is + used + 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); + User defined Mass functions must have the form as described before + (ie. `function vmas = fmas (vt, varargin)' if the option + `MStateDependence' was set to `"none"', otherwise the user defined + Mass function must have the form `function vmas = fmas (vt, vy, + varargin)' if the option `MStateDependence' was set to either + `"weak"' or `"strong"'. +`MvPattern' + The option `MvPattern' is not handled by any of the solvers by now. +`MassSingular' + The option `MassSingular' is not handled by any of the solvers by + now. +`NonNegative' + The option `NonNegative' can be used to set solution variables to + zero even if their real solution would be a negative value. It + must be a vector describing the positions in the solution vector + for which the option `NonNegative' should be used. Run the + following example to illustrate the effect if this option is used + 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); + +`Events' + The option `Events' can be used to set up an Event function, ie. + the Event function can be used to find zero crossings in one of + the results. It must either be a function handle to a valid + function. Run the following example to illustrate the effect if + this option is used + 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)); + Note: The function definition for Events calculations of DDE + equations must have the form `function [veve, vterm, vdir] = feve + (vt, vy, vz, varargin)' and the function definition for Events + calculations of IDE equations must have the form `function [veve, + vterm, vdir] = feve (vt, vy, vyd, varargin)'. +`MaxOrder' + The option `MaxOrder' can be used to set the maximum order of the + backward differentiation algorithm of the `odebdi' and `odebda' + solvers. It must be a scalar integer value between 1 and 7. Run + the following example to illustrate the effect if this option is + used + 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:"); + +`BDF' + The option `BDF' is only supported by the `odebdi' and `odebda' + solvers. Using these solvers the option `BDF' will automatically + be set `"on"' (even if it was set `"off"' before) because the + `odebdi' and `odebda' solvers all use the backward differentiation + algorithm to solve the different kind of equations. + +`NewtonTol' + TODO + +`MaxNewtonIterations' + TODO + + +File: odepkg.info, Node: M-File Function Reference, Next: Oct-File Function Reference, Prev: ODE/DAE/IDE/DDE options, Up: Users Guide + +2.4 M-File Function Reference +============================= + +The help texts of this section are autogenerated and refer to commands +that all can be found in the files `*.m'. All commands that are listed +below are loaded automatically everytime you launch Octave. + -- Function File: [] = ode23 (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, + ...]) + -- Command: [SOL] = ode23 (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, ...]) + -- Command: [T, Y, [XE, YE, IE]] = ode23 (@FUN, SLOT, INIT, [OPT], + [PAR1, PAR2, ...]) + This function file can be used to solve a set of non-stiff + ordinary differential equations (non-stiff ODEs) or non-stiff + differential algebraic equations (non-stiff DAEs) with the well + known explicit Runge-Kutta method of order (2,3). + + If this function is called with no return argument then plot the + solution over time in a figure window while solving the set of + ODEs that are defined in a function and specified by the function + handle @FUN. The second input argument SLOT is a double vector + that defines the time slot, INIT is a double vector that defines + the initial values of the states, OPT can optionally be a + structure array that keeps the options created with the command + `odeset' and PAR1, PAR2, ... can optionally be other input + arguments of any type that have to be passed to the function + defined by @FUN. + + If this function is called with one return argument then return + the solution SOL of type structure array after solving the set of + ODEs. The solution SOL has the fields X of type double column + vector for the steps chosen by the solver, Y of type double column + vector for the solutions at each time step of X, SOLVER of type + string for the solver name and optionally the extended time stamp + information XE, the extended solution information YE and the + extended index information IE all of type double column vector + that keep the informations of the event function if an event + function handle is set in the option argument OPT. + + If this function is called with more than one return argument then + return the time stamps T, the solution values Y and optionally the + extended time stamp information XE, the extended solution + information YE and the extended index information IE all of type + double column vector. + + For example, solve an anonymous implementation of the Van der Pol + equation + + fvdb = @(vt,vy) [vy(2); (1 - vy(1)^2) * vy(2) - vy(1)]; + + vopt = odeset ("RelTol", 1e-3, "AbsTol", 1e-3, \ + "NormControl", "on", "OutputFcn", @odeplot); + ode23 (fvdb, [0 20], [2 0], vopt); + + -- Function File: [] = ode23d (@FUN, SLOT, INIT, LAGS, HIST, [OPT], + [PAR1, PAR2, ...]) + -- Command: [SOL] = ode23d (@FUN, SLOT, INIT, LAGS, HIST, [OPT], + [PAR1, PAR2, ...]) + -- Command: [T, Y, [XE, YE, IE]] = ode23d (@FUN, SLOT, INIT, LAGS, + HIST, [OPT], [PAR1, PAR2, ...]) + This function file can be used to solve a set of non-stiff delay + differential equations (non-stiff DDEs) with a modified version of + the well known explicit Runge-Kutta method of order (2,3). + + If this function is called with no return argument then plot the + solution over time in a figure window while solving the set of + DDEs that are defined in a function and specified by the function + handle @FUN. The second input argument SLOT is a double vector + that defines the time slot, INIT is a double vector that defines + the initial values of the states, LAGS is a double vector that + describes the lags of time, HIST is a double matrix and describes + the history of the DDEs, OPT can optionally be a structure array + that keeps the options created with the command `odeset' and PAR1, + PAR2, ... can optionally be other input arguments of any type that + have to be passed to the function defined by @FUN. + + In other words, this function will solve a problem of the form + dy/dt = fun (t, y(t), y(t-lags(1), y(t-lags(2), ...))) + y(slot(1)) = init + y(slot(1)-lags(1)) = hist(1), y(slot(1)-lags(2)) = hist(2), ... + + If this function is called with one return argument then return + the solution SOL of type structure array after solving the set of + DDEs. The solution SOL has the fields X of type double column + vector for the steps chosen by the solver, Y of type double column + vector for the solutions at each time step of X, SOLVER of type + string for the solver name and optionally the extended time stamp + information XE, the extended solution information YE and the + extended index information IE all of type double column vector + that keep the informations of the event function if an event + function handle is set in the option argument OPT. + + If this function is called with more than one return argument then + return the time stamps T, the solution values Y and optionally the + extended time stamp information XE, the extended solution + information YE and the extended index information IE all of type + double column vector. + + For example: + - the following code solves an anonymous implementation of a + chaotic behavior + + fcao = @(vt, vy, vz) [2 * vz / (1 + vz^9.65) - vy]; + + vopt = odeset ("NormControl", "on", "RelTol", 1e-3); + vsol = ode23d (fcao, [0, 100], 0.5, 2, 0.5, vopt); + + vlag = interp1 (vsol.x, vsol.y, vsol.x - 2); + plot (vsol.y, vlag); legend ("fcao (t,y,z)"); + + - to solve the following problem with two delayed state + variables + + d y1(t)/dt = -y1(t) + d y2(t)/dt = -y2(t) + y1(t-5) + d y3(t)/dt = -y3(t) + y2(t-10)*y1(t-10) + + one might do the following + + function f = fun (t, y, yd) + f(1) = -y(1); %% y1' = -y1(t) + f(2) = -y(2) + yd(1,1); %% y2' = -y2(t) + y1(t-lags(1)) + f(3) = -y(3) + yd(2,2)*yd(1,2); %% y3' = -y3(t) + y2(t-lags(2))*y1(t-lags(2)) + endfunction + T = [0,20] + res = ode23d (@fun, T, [1;1;1], [5, 10], ones (3,2)); + + + -- Function File: [] = ode45 (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, + ...]) + -- Command: [SOL] = ode45 (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, ...]) + -- Command: [T, Y, [XE, YE, IE]] = ode45 (@FUN, SLOT, INIT, [OPT], + [PAR1, PAR2, ...]) + This function file can be used to solve a set of non-stiff + ordinary differential equations (non-stiff ODEs) or non-stiff + differential algebraic equations (non-stiff DAEs) with the well + known explicit Runge-Kutta method of order (4,5). + + If this function is called with no return argument then plot the + solution over time in a figure window while solving the set of + ODEs that are defined in a function and specified by the function + handle @FUN. The second input argument SLOT is a double vector + that defines the time slot, INIT is a double vector that defines + the initial values of the states, OPT can optionally be a + structure array that keeps the options created with the command + `odeset' and PAR1, PAR2, ... can optionally be other input + arguments of any type that have to be passed to the function + defined by @FUN. + + If this function is called with one return argument then return + the solution SOL of type structure array after solving the set of + ODEs. The solution SOL has the fields X of type double column + vector for the steps chosen by the solver, Y of type double column + vector for the solutions at each time step of X, SOLVER of type + string for the solver name and optionally the extended time stamp + information XE, the extended solution information YE and the + extended index information IE all of type double column vector + that keep the informations of the event function if an event + function handle is set in the option argument OPT. + + If this function is called with more than one return argument then + return the time stamps T, the solution values Y and optionally the + extended time stamp information XE, the extended solution + information YE and the extended index information IE all of type + double column vector. + + For example, solve an anonymous implementation of the Van der Pol + equation + + fvdb = @(vt,vy) [vy(2); (1 - vy(1)^2) * vy(2) - vy(1)]; + + vopt = odeset ("RelTol", 1e-3, "AbsTol", 1e-3, \ + "NormControl", "on", "OutputFcn", @odeplot); + ode45 (fvdb, [0 20], [2 0], vopt); + + -- Function File: [] = ode45d (@FUN, SLOT, INIT, LAGS, HIST, [OPT], + [PAR1, PAR2, ...]) + -- Command: [SOL] = ode45d (@FUN, SLOT, INIT, LAGS, HIST, [OPT], + [PAR1, PAR2, ...]) + -- Command: [T, Y, [XE, YE, IE]] = ode45d (@FUN, SLOT, INIT, LAGS, + HIST, [OPT], [PAR1, PAR2, ...]) + This function file can be used to solve a set of non-stiff delay + differential equations (non-stiff DDEs) with a modified version of + the well known explicit Runge-Kutta method of order (4,5). + + If this function is called with no return argument then plot the + solution over time in a figure window while solving the set of + DDEs that are defined in a function and specified by the function + handle @FUN. The second input argument SLOT is a double vector + that defines the time slot, INIT is a double vector that defines + the initial values of the states, LAGS is a double vector that + describes the lags of time, HIST is a double matrix and describes + the history of the DDEs, OPT can optionally be a structure array + that keeps the options created with the command `odeset' and PAR1, + PAR2, ... can optionally be other input arguments of any type that + have to be passed to the function defined by @FUN. + + In other words, this function will solve a problem of the form + dy/dt = fun (t, y(t), y(t-lags(1), y(t-lags(2), ...))) + y(slot(1)) = init + y(slot(1)-lags(1)) = hist(1), y(slot(1)-lags(2)) = hist(2), ... + + If this function is called with one return argument then return + the solution SOL of type structure array after solving the set of + DDEs. The solution SOL has the fields X of type double column + vector for the steps chosen by the solver, Y of type double column + vector for the solutions at each time step of X, SOLVER of type + string for the solver name and optionally the extended time stamp + information XE, the extended solution information YE and the + extended index information IE all of type double column vector + that keep the informations of the event function if an event + function handle is set in the option argument OPT. + + If this function is called with more than one return argument then + return the time stamps T, the solution values Y and optionally the + extended time stamp information XE, the extended solution + information YE and the extended index information IE all of type + double column vector. + + For example: + - the following code solves an anonymous implementation of a + chaotic behavior + + fcao = @(vt, vy, vz) [2 * vz / (1 + vz^9.65) - vy]; + + vopt = odeset ("NormControl", "on", "RelTol", 1e-3); + vsol = ode45d (fcao, [0, 100], 0.5, 2, 0.5, vopt); + + vlag = interp1 (vsol.x, vsol.y, vsol.x - 2); + plot (vsol.y, vlag); legend ("fcao (t,y,z)"); + + - to solve the following problem with two delayed state + variables + + d y1(t)/dt = -y1(t) + d y2(t)/dt = -y2(t) + y1(t-5) + d y3(t)/dt = -y3(t) + y2(t-10)*y1(t-10) + + one might do the following + + function f = fun (t, y, yd) + f(1) = -y(1); %% y1' = -y1(t) + f(2) = -y(2) + yd(1,1); %% y2' = -y2(t) + y1(t-lags(1)) + f(3) = -y(3) + yd(2,2)*yd(1,2); %% y3' = -y3(t) + y2(t-lags(2))*y1(t-lags(2)) + endfunction + T = [0,20] + res = ode45d (@fun, T, [1;1;1], [5, 10], ones (3,2)); + + + -- Function File: [] = ode54 (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, + ...]) + -- Command: [SOL] = ode54 (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, ...]) + -- Command: [T, Y, [XE, YE, IE]] = ode54 (@FUN, SLOT, INIT, [OPT], + [PAR1, PAR2, ...]) + This function file can be used to solve a set of non-stiff + ordinary differential equations (non-stiff ODEs) or non-stiff + differential algebraic equations (non-stiff DAEs) with the well + known explicit Runge-Kutta method of order (5,4). + + If this function is called with no return argument then plot the + solution over time in a figure window while solving the set of + ODEs that are defined in a function and specified by the function + handle @FUN. The second input argument SLOT is a double vector + that defines the time slot, INIT is a double vector that defines + the initial values of the states, OPT can optionally be a + structure array that keeps the options created with the command + `odeset' and PAR1, PAR2, ... can optionally be other input + arguments of any type that have to be passed to the function + defined by @FUN. + + If this function is called with one return argument then return + the solution SOL of type structure array after solving the set of + ODEs. The solution SOL has the fields X of type double column + vector for the steps chosen by the solver, Y of type double column + vector for the solutions at each time step of X, SOLVER of type + string for the solver name and optionally the extended time stamp + information XE, the extended solution information YE and the + extended index information IE all of type double column vector + that keep the informations of the event function if an event + function handle is set in the option argument OPT. + + If this function is called with more than one return argument then + return the time stamps T, the solution values Y and optionally the + extended time stamp information XE, the extended solution + information YE and the extended index information IE all of type + double column vector. + + For example, solve an anonymous implementation of the Van der Pol + equation + + fvdb = @(vt,vy) [vy(2); (1 - vy(1)^2) * vy(2) - vy(1)]; + + vopt = odeset ("RelTol", 1e-3, "AbsTol", 1e-3, \ + "NormControl", "on", "OutputFcn", @odeplot); + ode54 (fvdb, [0 20], [2 0], vopt); + + -- Function File: [] = ode54d (@FUN, SLOT, INIT, LAGS, HIST, [OPT], + [PAR1, PAR2, ...]) + -- Command: [SOL] = ode54d (@FUN, SLOT, INIT, LAGS, HIST, [OPT], + [PAR1, PAR2, ...]) + -- Command: [T, Y, [XE, YE, IE]] = ode54d (@FUN, SLOT, INIT, LAGS, + HIST, [OPT], [PAR1, PAR2, ...]) + This function file can be used to solve a set of non-stiff delay + differential equations (non-stiff DDEs) with a modified version of + the well known explicit Runge-Kutta method of order (2,3). + + If this function is called with no return argument then plot the + solution over time in a figure window while solving the set of + DDEs that are defined in a function and specified by the function + handle @FUN. The second input argument SLOT is a double vector + that defines the time slot, INIT is a double vector that defines + the initial values of the states, LAGS is a double vector that + describes the lags of time, HIST is a double matrix and describes + the history of the DDEs, OPT can optionally be a structure array + that keeps the options created with the command `odeset' and PAR1, + PAR2, ... can optionally be other input arguments of any type that + have to be passed to the function defined by @FUN. + + In other words, this function will solve a problem of the form + dy/dt = fun (t, y(t), y(t-lags(1), y(t-lags(2), ...))) + y(slot(1)) = init + y(slot(1)-lags(1)) = hist(1), y(slot(1)-lags(2)) = hist(2), ... + + If this function is called with one return argument then return + the solution SOL of type structure array after solving the set of + DDEs. The solution SOL has the fields X of type double column + vector for the steps chosen by the solver, Y of type double column + vector for the solutions at each time step of X, SOLVER of type + string for the solver name and optionally the extended time stamp + information XE, the extended solution information YE and the + extended index information IE all of type double column vector + that keep the informations of the event function if an event + function handle is set in the option argument OPT. + + If this function is called with more than one return argument then + return the time stamps T, the solution values Y and optionally the + extended time stamp information XE, the extended solution + information YE and the extended index information IE all of type + double column vector. + + For example: + - the following code solves an anonymous implementation of a + chaotic behavior + + fcao = @(vt, vy, vz) [2 * vz / (1 + vz^9.65) - vy]; + + vopt = odeset ("NormControl", "on", "RelTol", 1e-3); + vsol = ode54d (fcao, [0, 100], 0.5, 2, 0.5, vopt); + + vlag = interp1 (vsol.x, vsol.y, vsol.x - 2); + plot (vsol.y, vlag); legend ("fcao (t,y,z)"); + + - to solve the following problem with two delayed state + variables + + d y1(t)/dt = -y1(t) + d y2(t)/dt = -y2(t) + y1(t-5) + d y3(t)/dt = -y3(t) + y2(t-10)*y1(t-10) + + one might do the following + + function f = fun (t, y, yd) + f(1) = -y(1); %% y1' = -y1(t) + f(2) = -y(2) + yd(1,1); %% y2' = -y2(t) + y1(t-lags(1)) + f(3) = -y(3) + yd(2,2)*yd(1,2); %% y3' = -y3(t) + y2(t-lags(2))*y1(t-lags(2)) + endfunction + T = [0,20] + res = ode54d (@fun, T, [1;1;1], [5, 10], ones (3,2)); + + + -- Function File: [] = ode78 (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, + ...]) + -- Command: [SOL] = ode78 (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, ...]) + -- Command: [T, Y, [XE, YE, IE]] = ode78 (@FUN, SLOT, INIT, [OPT], + [PAR1, PAR2, ...]) + This function file can be used to solve a set of non-stiff + ordinary differential equations (non-stiff ODEs) or non-stiff + differential algebraic equations (non-stiff DAEs) with the well + known explicit Runge-Kutta method of order (7,8). + + If this function is called with no return argument then plot the + solution over time in a figure window while solving the set of + ODEs that are defined in a function and specified by the function + handle @FUN. The second input argument SLOT is a double vector + that defines the time slot, INIT is a double vector that defines + the initial values of the states, OPT can optionally be a + structure array that keeps the options created with the command + `odeset' and PAR1, PAR2, ... can optionally be other input + arguments of any type that have to be passed to the function + defined by @FUN. + + If this function is called with one return argument then return + the solution SOL of type structure array after solving the set of + ODEs. The solution SOL has the fields X of type double column + vector for the steps chosen by the solver, Y of type double column + vector for the solutions at each time step of X, SOLVER of type + string for the solver name and optionally the extended time stamp + information XE, the extended solution information YE and the + extended index information IE all of type double column vector + that keep the informations of the event function if an event + function handle is set in the option argument OPT. + + If this function is called with more than one return argument then + return the time stamps T, the solution values Y and optionally the + extended time stamp information XE, the extended solution + information YE and the extended index information IE all of type + double column vector. + + For example, solve an anonymous implementation of the Van der Pol + equation + + fvdb = @(vt,vy) [vy(2); (1 - vy(1)^2) * vy(2) - vy(1)]; + + vopt = odeset ("RelTol", 1e-3, "AbsTol", 1e-3, \ + "NormControl", "on", "OutputFcn", @odeplot); + ode78 (fvdb, [0 20], [2 0], vopt); + + -- Function File: [] = ode78d (@FUN, SLOT, INIT, LAGS, HIST, [OPT], + [PAR1, PAR2, ...]) + -- Command: [SOL] = ode78d (@FUN, SLOT, INIT, LAGS, HIST, [OPT], + [PAR1, PAR2, ...]) + -- Command: [T, Y, [XE, YE, IE]] = ode78d (@FUN, SLOT, INIT, LAGS, + HIST, [OPT], [PAR1, PAR2, ...]) + This function file can be used to solve a set of non-stiff delay + differential equations (non-stiff DDEs) with a modified version of + the well known explicit Runge-Kutta method of order (7,8). + + If this function is called with no return argument then plot the + solution over time in a figure window while solving the set of + DDEs that are defined in a function and specified by the function + handle @FUN. The second input argument SLOT is a double vector + that defines the time slot, INIT is a double vector that defines + the initial values of the states, LAGS is a double vector that + describes the lags of time, HIST is a double matrix and describes + the history of the DDEs, OPT can optionally be a structure array + that keeps the options created with the command `odeset' and PAR1, + PAR2, ... can optionally be other input arguments of any type that + have to be passed to the function defined by @FUN. + + In other words, this function will solve a problem of the form + dy/dt = fun (t, y(t), y(t-lags(1), y(t-lags(2), ...))) + y(slot(1)) = init + y(slot(1)-lags(1)) = hist(1), y(slot(1)-lags(2)) = hist(2), ... + + If this function is called with one return argument then return + the solution SOL of type structure array after solving the set of + DDEs. The solution SOL has the fields X of type double column + vector for the steps chosen by the solver, Y of type double column + vector for the solutions at each time step of X, SOLVER of type + string for the solver name and optionally the extended time stamp + information XE, the extended solution information YE and the + extended index information IE all of type double column vector + that keep the informations of the event function if an event + function handle is set in the option argument OPT. + + If this function is called with more than one return argument then + return the time stamps T, the solution values Y and optionally the + extended time stamp information XE, the extended solution + information YE and the extended index information IE all of type + double column vector. + + For example: + - the following code solves an anonymous implementation of a + chaotic behavior + + fcao = @(vt, vy, vz) [2 * vz / (1 + vz^9.65) - vy]; + + vopt = odeset ("NormControl", "on", "RelTol", 1e-3); + vsol = ode78d (fcao, [0, 100], 0.5, 2, 0.5, vopt); + + vlag = interp1 (vsol.x, vsol.y, vsol.x - 2); + plot (vsol.y, vlag); legend ("fcao (t,y,z)"); + + - to solve the following problem with two delayed state + variables + + d y1(t)/dt = -y1(t) + d y2(t)/dt = -y2(t) + y1(t-5) + d y3(t)/dt = -y3(t) + y2(t-10)*y1(t-10) + + one might do the following + + function f = fun (t, y, yd) + f(1) = -y(1); %% y1' = -y1(t) + f(2) = -y(2) + yd(1,1); %% y2' = -y2(t) + y1(t-lags(1)) + f(3) = -y(3) + yd(2,2)*yd(1,2); %% y3' = -y3(t) + y2(t-lags(2))*y1(t-lags(2)) + endfunction + T = [0,20] + res = ode78d (@fun, T, [1;1;1], [5, 10], ones (3,2)); + + + -- Function File: [] = odebwe (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, + ...]) + -- Command: [SOL] = odebwe (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, ...]) + -- Command: [T, Y, [XE, YE, IE]] = odebwe (@FUN, SLOT, INIT, [OPT], + [PAR1, PAR2, ...]) + This function file can be used to solve a set of stiff ordinary + differential equations (stiff ODEs) or stiff differential + algebraic equations (stiff DAEs) with the Backward Euler method. + + If this function is called with no return argument then plot the + solution over time in a figure window while solving the set of + ODEs that are defined in a function and specified by the function + handle @FUN. The second input argument SLOT is a double vector + that defines the time slot, INIT is a double vector that defines + the initial values of the states, OPT can optionally be a + structure array that keeps the options created with the command + `odeset' and PAR1, PAR2, ... can optionally be other input + arguments of any type that have to be passed to the function + defined by @FUN. + + If this function is called with one return argument then return + the solution SOL of type structure array after solving the set of + ODEs. The solution SOL has the fields X of type double column + vector for the steps chosen by the solver, Y of type double column + vector for the solutions at each time step of X, SOLVER of type + string for the solver name and optionally the extended time stamp + information XE, the extended solution information YE and the + extended index information IE all of type double column vector + that keep the informations of the event function if an event + function handle is set in the option argument OPT. + + If this function is called with more than one return argument then + return the time stamps T, the solution values Y and optionally the + extended time stamp information XE, the extended solution + information YE and the extended index information IE all of type + double column vector. + + For example, solve an anonymous implementation of the Van der Pol + equation + + fvdb = @(vt,vy) [vy(2); (1 - vy(1)^2) * vy(2) - vy(1)]; + vjac = @(vt,vy) [0, 1; -1 - 2 * vy(1) * vy(2), 1 - vy(1)^2]; + vopt = odeset ("RelTol", 1e-3, "AbsTol", 1e-3, \ + "NormControl", "on", "OutputFcn", @odeplot, \ + "Jacobian",vjac); + odebwe (fvdb, [0 20], [2 0], vopt); + + -- Function File: [] = odeexamples () + Open the differential equations examples menu and allow the user + to select a submenu of ODE, DAE, IDE or DDE examples. + + -- Function File: [VALUE] = odeget (ODESTRUCT, OPTION, [DEFAULT]) + -- Command: [VALUES] = odeget (ODESTRUCT, {OPT1, OPT2, ...}, [{DEF1, + DEF2, ...}]) + If this function is called with two input arguments and the first + input argument ODESTRUCT is of type structure array and the second + input argument OPTION is of type string then return the option + value VALUE that is specified by the option name OPTION in the + OdePkg option structure ODESTRUCT. Optionally if this function is + called with a third input argument then return the default value + DEFAULT if OPTION is not set in the structure ODESTRUCT. + + If this function is called with two input arguments and the first + input argument ODESTRUCT is of type structure array and the second + input argument OPTION is of type cell array of strings then return + the option values VALUES that are specified by the option names + OPT1, OPT2, ... in the OdePkg option structure ODESTRUCT. + Optionally if this function is called with a third input argument + of type cell array then return the default value DEF1 if OPT1 is + not set in the structure ODESTRUCT, DEF2 if OPT2 is not set in the + structure ODESTRUCT, ... + + Run examples with the command + demo odeget + + -- Function File: [RET] = odephas2 (T, Y, FLAG) + Open a new figure window and plot the first result from the + variable Y that is of type double column vector over the second + result from the variable Y while solving. The types and the values + of the input parameter T and the output parameter RET depend on + the input value FLAG that is of type string. If FLAG is + ``"init"'' + then T must be a double column vector of length 2 with the + first and the last time step and nothing is returned from + this function, + + ``""'' + then T must be a double scalar specifying the actual time + step and the return value is false (resp. value 0) for 'not + stop solving', + + ``"done"'' + then T must be a double scalar specifying the last time step + and nothing is returned from this function. + + This function is called by a OdePkg solver function if it was + specified in an OdePkg options structure with the `odeset'. This + function is an OdePkg internal helper function therefore it should + never be necessary that this function is called directly by a + user. There is only little error detection implemented in this + function file to achieve the highest performance. + + For example, solve an anonymous implementation of the "Van der + Pol" equation and display the results while solving in a 2D plane + fvdb = @(vt,vy) [vy(2); (1 - vy(1)^2) * vy(2) - vy(1)]; + + vopt = odeset ('OutputFcn', @odephas2, 'RelTol', 1e-6); + vsol = ode45 (fvdb, [0 20], [2 0], vopt); + + -- Function File: [RET] = odephas3 (T, Y, FLAG) + Open a new figure window and plot the first result from the + variable Y that is of type double column vector over the second + and the third result from the variable Y while solving. The types + and the values of the input parameter T and the output parameter + RET depend on the input value FLAG that is of type string. If FLAG + is + ``"init"'' + then T must be a double column vector of length 2 with the + first and the last time step and nothing is returned from + this function, + + ``""'' + then T must be a double scalar specifying the actual time + step and the return value is false (resp. value 0) for 'not + stop solving', + + ``"done"'' + then T must be a double scalar specifying the last time step + and nothing is returned from this function. + + This function is called by a OdePkg solver function if it was + specified in an OdePkg options structure with the `odeset'. This + function is an OdePkg internal helper function therefore it should + never be necessary that this function is called directly by a + user. There is only little error detection implemented in this + function file to achieve the highest performance. + + For example, solve the "Lorenz attractor" and display the results + while solving in a 3D plane + function vyd = florenz (vt, vx) + vyd = [10 * (vx(2) - vx(1)); + vx(1) * (28 - vx(3)); + vx(1) * vx(2) - 8/3 * vx(3)]; + endfunction + + vopt = odeset ('OutputFcn', @odephas3); + vsol = ode23 (@florenz, [0:0.01:7.5], [3 15 1], vopt); + + -- Function File: [] = odepkg () + OdePkg is part of the GNU Octave Repository (the Octave-Forge + project). 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. At this time OdePkg is under development with the main + target to make a package that is mostly compatible to proprietary + solver products. + + If this function is called without any input argument then open + the OdePkg tutorial in the Octave window. The tutorial can also be + opened with the following command + + doc odepkg + + -- Function File: [SOL] = odepkg_event_handle (@FUN, TIME, Y, FLAG, + [PAR1, PAR2, ...]) + Return the solution of the event function that is specified as the + first input argument @FUN in form of a function handle. The second + input argument TIME is of type double scalar and specifies the + time of the event evaluation, the third input argument Y either is + of type double column vector (for ODEs and DAEs) and specifies the + solutions or is of type cell array (for IDEs and DDEs) and + specifies the derivatives or the history values, the third input + argument FLAG is of type string and can be of the form + ``"init"'' + then initialize internal persistent variables of the function + `odepkg_event_handle' and return an empty cell array of size + 4, + + ``"calc"'' + then do the evaluation of the event function and return the + solution SOL as type cell array of size 4, + + ``"done"'' + then cleanup internal variables of the function + `odepkg_event_handle' and return an empty cell array of size + 4. + Optionally if further input arguments PAR1, PAR2, ... of any type + are given then pass these parameters through `odepkg_event_handle' + to the event function. + + This function is an OdePkg internal helper function therefore it + should never be necessary that this function is called directly by + a user. There is only little error detection implemented in this + function file to achieve the highest performance. + + -- Function File: [] = odepkg_examples_dae () + Open the DAE examples menu and allow the user to select a demo + that will be evaluated. + + -- Function File: [] = odepkg_examples_dde () + Open the DDE examples menu and allow the user to select a demo + that will be evaluated. + + -- Function File: [] = odepkg_examples_ide () + Open the IDE examples menu and allow the user to select a demo + that will be evaluated. + + -- Function File: [] = odepkg_examples_ode () + Open the ODE examples menu and allow the user to select a demo + that will be evaluated. + + -- Function File: [NEWSTRUCT] = odepkg_structure_check (OLDSTRUCT, + ["SOLVER"]) + If this function is called with one input argument of type + structure array then check the field names and the field values of + the OdePkg structure OLDSTRUCT and return the structure as + NEWSTRUCT if no error is found. Optionally if this function is + called with a second input argument "SOLVER" of type string taht + specifies the name of a valid OdePkg solver then a higher level + error detection is performed. The function does not modify any of + the field names or field values but terminates with an error if an + invalid option or value is found. + + This function is an OdePkg internal helper function therefore it + should never be necessary that this function is called directly by + a user. There is only little error detection implemented in this + function file to achieve the highest performance. + + Run examples with the command + demo odepkg_structure_check + + -- Function File: [MESCD] = odepkg_testsuite_calcmescd (SOLUTION, + REFERENCE, ABSTOL, RELTOL) + If this function is called with four input arguments of type + double scalar or column vector then return a normalized value for + the minimum number of correct digits MESCD that is calculated from + the solution at the end of an integration interval SOLUTION and a + set of reference values REFERENCE. The input arguments ABSTOL and + RELTOL are used to calculate a reference solution that depends on + the relative and absolute error tolerances. + + Run examples with the command + demo odepkg_testsuite_calcmescd + + This function has been ported from the "Test Set for IVP solvers" + which is developed by the INdAM Bari unit project group "Codes and + Test Problems for Differential Equations", coordinator F. Mazzia. + + -- Function File: [SCD] = odepkg_testsuite_calcscd (SOLUTION, + REFERENCE, ABSTOL, RELTOL) + If this function is called with four input arguments of type + double scalar or column vector then return a normalized value for + the minimum number of correct digits SCD that is calculated from + the solution at the end of an integration interval SOLUTION and a + set of reference values REFERENCE. The input arguments ABSTOL and + RELTOL are unused but present because of compatibility to the + function `odepkg_testsuite_calcmescd'. + + Run examples with the command + demo odepkg_testsuite_calcscd + + This function has been ported from the "Test Set for IVP solvers" + which is developed by the INdAM Bari unit project group "Codes and + Test Problems for Differential Equations", coordinator F. Mazzia. + + -- Function File: [SOLUTION] = odepkg_testsuite_chemakzo (@SOLVER, + RELTOL) + If this function is called with two input arguments and the first + input argument @SOLVER is a function handle describing an OdePkg + solver and the second input argument RELTOL is a double scalar + describing the relative error tolerance then return a cell array + SOLUTION with performance informations about the chemical AKZO + Nobel testsuite of differential algebraic equations after solving + (DAE-test). + + Run examples with the command + demo odepkg_testsuite_chemakzo + + This function has been ported from the "Test Set for IVP solvers" + which is developed by the INdAM Bari unit project group "Codes and + Test Problems for Differential Equations", coordinator F. Mazzia. + + -- Function File: [SOLUTION] = odepkg_testsuite_hires (@SOLVER, RELTOL) + If this function is called with two input arguments and the first + input argument @SOLVER is a function handle describing an OdePkg + solver and the second input argument RELTOL is a double scalar + describing the relative error tolerance then return a cell array + SOLUTION with performance informations about the HIRES testsuite + of ordinary differential equations after solving (ODE-test). + + Run examples with the command + demo odepkg_testsuite_hires + + This function has been ported from the "Test Set for IVP solvers" + which is developed by the INdAM Bari unit project group "Codes and + Test Problems for Differential Equations", coordinator F. Mazzia. + + -- Function File: [SOLUTION] = odepkg_testsuite_implakzo (@SOLVER, + RELTOL) + If this function is called with two input arguments and the first + input argument @SOLVER is a function handle describing an OdePkg + solver and the second input argument RELTOL is a double scalar + describing the relative error tolerance then return a cell array + SOLUTION with performance informations about the chemical AKZO + Nobel testsuite of implicit differential algebraic equations after + solving (IDE-test). + + Run examples with the command + demo odepkg_testsuite_implakzo + + This function has been ported from the "Test Set for IVP solvers" + which is developed by the INdAM Bari unit project group "Codes and + Test Problems for Differential Equations", coordinator F. Mazzia. + + -- Function File: [SOLUTION] = odepkg_testsuite_implrober (@SOLVER, + RELTOL) + If this function is called with two input arguments and the first + input argument @SOLVER is a function handle describing an OdePkg + solver and the second input argument RELTOL is a double scalar + describing the relative error tolerance then return a cell array + SOLUTION with performance informations about the implicit form of + the modified ROBERTSON testsuite of implicit differential + algebraic equations after solving (IDE-test). + + Run examples with the command + demo odepkg_testsuite_implrober + + This function has been ported from the "Test Set for IVP solvers" + which is developed by the INdAM Bari unit project group "Codes and + Test Problems for Differential Equations", coordinator F. Mazzia. + + -- Function File: [SOLUTION] = odepkg_testsuite_oregonator (@SOLVER, + RELTOL) + If this function is called with two input arguments and the first + input argument @SOLVER is a function handle describing an OdePkg + solver and the second input argument RELTOL is a double scalar + describing the relative error tolerance then return a cell array + SOLUTION with performance informations about the OREGONATOR + testsuite of ordinary differential equations after solving + (ODE-test). + + Run examples with the command + demo odepkg_testsuite_oregonator + + This function has been ported from the "Test Set for IVP solvers" + which is developed by the INdAM Bari unit project group "Codes and + Test Problems for Differential Equations", coordinator F. Mazzia. + + -- Function File: [SOLUTION] = odepkg_testsuite_pollution (@SOLVER, + RELTOL) + If this function is called with two input arguments and the first + input argument @SOLVER is a function handle describing an OdePkg + solver and the second input argument RELTOL is a double scalar + describing the relative error tolerance then return the cell array + SOLUTION with performance informations about the POLLUTION + testsuite of ordinary differential equations after solving + (ODE-test). + + Run examples with the command + demo odepkg_testsuite_pollution + + This function has been ported from the "Test Set for IVP solvers" + which is developed by the INdAM Bari unit project group "Codes and + Test Problems for Differential Equations", coordinator F. Mazzia. + + -- Function File: [SOLUTION] = odepkg_testsuite_robertson (@SOLVER, + RELTOL) + If this function is called with two input arguments and the first + input argument @SOLVER is a function handle describing an OdePkg + solver and the second input argument RELTOL is a double scalar + describing the relative error tolerance then return a cell array + SOLUTION with performance informations about the modified + ROBERTSON testsuite of differential algebraic equations after + solving (DAE-test). + + Run examples with the command + demo odepkg_testsuite_robertson + + This function has been ported from the "Test Set for IVP solvers" + which is developed by the INdAM Bari unit project group "Codes and + Test Problems for Differential Equations", coordinator F. Mazzia. + + -- Function File: [SOLUTION] = odepkg_testsuite_transistor (@SOLVER, + RELTOL) + If this function is called with two input arguments and the first + input argument @SOLVER is a function handle describing an OdePkg + solver and the second input argument RELTOL is a double scalar + describing the relative error tolerance then return the cell array + SOLUTION with performance informations about the TRANSISTOR + testsuite of differential algebraic equations after solving + (DAE-test). + + Run examples with the command + demo odepkg_testsuite_transistor + + This function has been ported from the "Test Set for IVP solvers" + which is developed by the INdAM Bari unit project group "Codes and + Test Problems for Differential Equations", coordinator F. Mazzia. + + -- Function File: [RET] = odeplot (T, Y, FLAG) + Open a new figure window and plot the results from the variable Y + of type column vector over time while solving. The types and the + values of the input parameter T and the output parameter RET + depend on the input value FLAG that is of type string. If FLAG is + ``"init"'' + then T must be a double column vector of length 2 with the + first and the last time step and nothing is returned from + this function, + + ``""'' + then T must be a double scalar specifying the actual time + step and the return value is false (resp. value 0) for 'not + stop solving', + + ``"done"'' + then T must be a double scalar specifying the last time step + and nothing is returned from this function. + + This function is called by a OdePkg solver function if it was + specified in an OdePkg options structure with the `odeset'. This + function is an OdePkg internal helper function therefore it should + never be necessary that this function is called directly by a + user. There is only little error detection implemented in this + function file to achieve the highest performance. + + For example, solve an anonymous implementation of the "Van der + Pol" equation and display the results while solving + fvdb = @(vt,vy) [vy(2); (1 - vy(1)^2) * vy(2) - vy(1)]; + + vopt = odeset ('OutputFcn', @odeplot, 'RelTol', 1e-6); + vsol = ode45 (fvdb, [0 20], [2 0], vopt); + + -- Function File: [RET] = odeprint (T, Y, FLAG) + Display the results of the set of differential equations in the + Octave window while solving. The first column of the screen output + shows the actual time stamp that is given with the input arguemtn + T, the following columns show the results from the function + evaluation that are given by the column vector Y. The types and + the values of the input parameter T and the output parameter RET + depend on the input value FLAG that is of type string. If FLAG is + ``"init"'' + then T must be a double column vector of length 2 with the + first and the last time step and nothing is returned from + this function, + + ``""'' + then T must be a double scalar specifying the actual time + step and the return value is false (resp. value 0) for 'not + stop solving', + + ``"done"'' + then T must be a double scalar specifying the last time step + and nothing is returned from this function. + + This function is called by a OdePkg solver function if it was + specified in an OdePkg options structure with the `odeset'. This + function is an OdePkg internal helper function therefore it should + never be necessary that this function is called directly by a + user. There is only little error detection implemented in this + function file to achieve the highest performance. + + For example, solve an anonymous implementation of the "Van der + Pol" equation and print the results while solving + fvdb = @(vt,vy) [vy(2); (1 - vy(1)^2) * vy(2) - vy(1)]; + + vopt = odeset ('OutputFcn', @odeprint, 'RelTol', 1e-6); + vsol = ode45 (fvdb, [0 20], [2 0], vopt); + + -- Function File: [ODESTRUCT] = odeset () + -- Command: [ODESTRUCT] = odeset ("FIELD1", VALUE1, "FIELD2", VALUE2, + ...) + -- Command: [ODESTRUCT] = odeset (OLDSTRUCT, "FIELD1", VALUE1, + "FIELD2", VALUE2, ...) + -- Command: [ODESTRUCT] = odeset (OLDSTRUCT, NEWSTRUCT) + If this function is called without an input argument then return a + new OdePkg options structure array that contains all the necessary + fields and sets the values of all fields to default values. + + If this function is called with string input arguments "FIELD1", + "FIELD2", ... identifying valid OdePkg options then return a new + OdePkg options structure with all necessary fields and set the + values of the fields "FIELD1", "FIELD2", ... to the values VALUE1, + VALUE2, ... + + If this function is called with a first input argument OLDSTRUCT + of type structure array then overwrite all values of the options + "FIELD1", "FIELD2", ... of the structure OLDSTRUCT with new values + VALUE1, VALUE2, ... and return the modified structure array. + + If this function is called with two input argumnets OLDSTRUCT and + NEWSTRUCT of type structure array then overwrite all values in the + fields from the structure OLDSTRUCT with new values of the fields + from the structure NEWSTRUCT. Empty values of NEWSTRUCT will not + overwrite values in OLDSTRUCT. + + For a detailed explanation about valid fields and field values in + an OdePkg structure aaray have a look at the `odepkg.pdf', Section + 'ODE/DAE/IDE/DDE options' or run the command `doc odepkg' to open + the tutorial. + + Run examples with the command + demo odeset + + +File: odepkg.info, Node: Oct-File Function Reference, Prev: M-File Function Reference, Up: Users Guide + +2.5 Oct-File Function Reference +=============================== + +The help texts of this section are autogenerated and refer to commands +that all can be found in the file `dldsolver.oct'. The file +`dldsolver.oct' is generated automatically if you install OdePkg with +the command `pkg'. All commands that are listed below are loaded +automatically everytime you launch Octave. + -- Command: [] = odebda (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, ...]) + -- Command: [SOL] = odebda (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, ...]) + -- Command: [T, Y, [XE, YE, IE]] = odebda (@FUN, SLOT, INIT, [OPT], + [PAR1, PAR2, ...]) + This function file can be used to solve a set of non-stiff or + stiff ordinary differential equations (ODEs) and non-stiff or + stiff differential algebraic equations (DAEs). This function file + is a wrapper file that uses Jeff Cash's Fortran solver + `mebdfdae.f'. + + If this function is called with no return argument then plot the + solution over time in a figure window while solving the set of + ODEs that are defined in a function and specified by the function + handle @FUN. The second input argument SLOT is a double vector + that defines the time slot, INIT is a double vector that defines + the initial values of the states, OPT can optionally be a + structure array that keeps the options created with the command + `odeset' and PAR1, PAR2, ... can optionally be other input + arguments of any type that have to be passed to the function + defined by @FUN. + + If this function is called with one return argument then return + the solution SOL of type structure array after solving the set of + ODEs. The solution SOL has the fields X of type double column + vector for the steps chosen by the solver, Y of type double column + vector for the solutions at each time step of X, SOLVER of type + string for the solver name and optionally the extended time stamp + information XE, the extended solution information YE and the + extended index information IE all of type double column vector + that keep the informations of the event function if an event + function handle is set in the option argument OPT. + + If this function is called with more than one return argument then + return the time stamps T, the solution values Y and optionally the + extended time stamp information XE, the extended solution + information YE and the extended index information IE all of type + double column vector. + + For example, + function y = odepkg_equations_lorenz (t, x) + y = [10 * (x(2) - x(1)); + x(1) * (28 - x(3)); + x(1) * x(2) - 8/3 * x(3)]; + endfunction + + vopt = odeset ("InitialStep", 1e-3, "MaxStep", 1e-1, \\ + "OutputFcn", @odephas3, "Refine", 5); + odebda (@odepkg_equations_lorenz, [0, 25], [3 15 1], vopt); + + -- Command: [] = odebdi (@FUN, SLOT, Y0, DY0, [OPT], [P1, P2, ...]) + -- Command: [SOL] = odebdi (@FUN, SLOT, Y0, DY0, [OPT], [P1, P2, ...]) + -- Command: [T, Y, [XE, YE, IE]] = odebdi (@FUN, SLOT, Y0, DY0, [OPT], + [P1, P2, ...]) + This function file can be used to solve a set of non-stiff and + stiff implicit differential equations (IDEs). This function file + is a wrapper file that uses Jeff Cash's Fortran solver `mebdfi.f'. + + If this function is called with no return argument then plot the + solution over time in a figure window while solving the set of + IDEs that are defined in a function and specified by the function + handle @FUN. The second input argument SLOT is a double vector + that defines the time slot, Y0 is a double vector that defines the + initial values of the states, DY0 is a double vector that defines + the initial values of the derivatives, OPT can optionally be a + structure array that keeps the options created with the command + `odeset' and PAR1, PAR2, ... can optionally be other input + arguments of any type that have to be passed to the function + defined by @FUN. + + If this function is called with one return argument then return + the solution SOL of type structure array after solving the set of + IDEs. The solution SOL has the fields X of type double column + vector for the steps chosen by the solver, Y of type double column + vector for the solutions at each time step of X, SOLVER of type + string for the solver name and optionally the extended time stamp + information XE, the extended solution information YE and the + extended index information IE all of type double column vector + that keep the informations of the event function if an event + function handle is set in the option argument OPT. + + If this function is called with more than one return argument then + return the time stamps T, the solution values Y and optionally the + extended time stamp information XE, the extended solution + information YE and the extended index information IE all of type + double column vector. + + For example, + function res = odepkg_equations_ilorenz (t, y, yd) + res = [10 * (y(2) - y(1)) - yd(1); + y(1) * (28 - y(3)) - yd(2); + y(1) * y(2) - 8/3 * y(3) - yd(3)]; + endfunction + + vopt = odeset ("InitialStep", 1e-3, "MaxStep", 1e-1, \\ + "OutputFcn", @odephas3, "Refine", 5); + odebdi (@odepkg_equations_ilorenz, [0, 25], [3 15 1], \\ + [120 81 42.333333], vopt); + + -- Command: [] = odekdi (@FUN, SLOT, Y0, DY0, [OPT], [P1, P2, ...]) + -- Command: [SOL] = odekdi (@FUN, SLOT, Y0, DY0, [OPT], [P1, P2, ...]) + -- Command: [T, Y, [XE, YE, IE]] = odekdi (@FUN, SLOT, Y0, DY0, [OPT], + [P1, P2, ...]) + This function file can be used to solve a set of non-stiff or + stiff implicit differential equations (IDEs). This function file + is a wrapper file that uses the direct method (not the Krylov + method) of Petzold's, Brown's, Hindmarsh's and Ulrich's Fortran + solver `ddaskr.f'. + + If this function is called with no return argument then plot the + solution over time in a figure window while solving the set of + IDEs that are defined in a function and specified by the function + handle @FUN. The second input argument SLOT is a double vector + that defines the time slot, Y0 is a double vector that defines the + initial values of the states, DY0 is a double vector that defines + the initial values of the derivatives, OPT can optionally be a + structure array that keeps the options created with the command + `odeset' and PAR1, PAR2, ... can optionally be other input + arguments of any type that have to be passed to the function + defined by @FUN. + + If this function is called with one return argument then return + the solution SOL of type structure array after solving the set of + IDEs. The solution SOL has the fields X of type double column + vector for the steps chosen by the solver, Y of type double column + vector for the solutions at each time step of X, SOLVER of type + string for the solver name and optionally the extended time stamp + information XE, the extended solution information YE and the + extended index information IE all of type double column vector + that keep the informations of the event function if an event + function handle is set in the option argument OPT. + + If this function is called with more than one return argument then + return the time stamps T, the solution values Y and optionally the + extended time stamp information XE, the extended solution + information YE and the extended index information IE all of type + double column vector. + + For example, + function res = odepkg_equations_ilorenz (t, y, yd) + res = [10 * (y(2) - y(1)) - yd(1); + y(1) * (28 - y(3)) - yd(2); + y(1) * y(2) - 8/3 * y(3) - yd(3)]; + endfunction + + vopt = odeset ("InitialStep", 1e-3, "MaxStep", 1e-1, \\ + "OutputFcn", @odephas3, "Refine", 5); + odekdi (@odepkg_equations_ilorenz, [0, 25], [3 15 1], \\ + [120 81 42.333333], vopt); + + -- Command: [] = ode2r (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, ...]) + -- Command: [SOL] = ode2r (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, ...]) + -- Command: [T, Y, [XE, YE, IE]] = ode2r (@FUN, SLOT, INIT, [OPT], + [PAR1, PAR2, ...]) + This function file can be used to solve a set of non-stiff or + stiff ordinary differential equations (ODEs) and non-stiff or + stiff differential algebraic equations (DAEs). This function file + is a wrapper to Hairer's and Wanner's Fortran solver `radau.f'. + + If this function is called with no return argument then plot the + solution over time in a figure window while solving the set of + ODEs that are defined in a function and specified by the function + handle @FUN. The second input argument SLOT is a double vector + that defines the time slot, INIT is a double vector that defines + the initial values of the states, OPT can optionally be a + structure array that keeps the options created with the command + `odeset' and PAR1, PAR2, ... can optionally be other input + arguments of any type that have to be passed to the function + defined by @FUN. + + If this function is called with one return argument then return + the solution SOL of type structure array after solving the set of + ODEs. The solution SOL has the fields X of type double column + vector for the steps chosen by the solver, Y of type double column + vector for the solutions at each time step of X, SOLVER of type + string for the solver name and optionally the extended time stamp + information XE, the extended solution information YE and the + extended index information IE all of type double column vector + that keep the informations of the event function if an event + function handle is set in the option argument OPT. + + If this function is called with more than one return argument then + return the time stamps T, the solution values Y and optionally the + extended time stamp information XE, the extended solution + information YE and the extended index information IE all of type + double column vector. + + For example, + function y = odepkg_equations_lorenz (t, x) + y = [10 * (x(2) - x(1)); + x(1) * (28 - x(3)); + x(1) * x(2) - 8/3 * x(3)]; + endfunction + + vopt = odeset ("InitialStep", 1e-3, "MaxStep", 1e-1, \\ + "OutputFcn", @odephas3, "Refine", 5); + ode2r (@odepkg_equations_lorenz, [0, 25], [3 15 1], vopt); + + -- Command: [] = ode5r (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, ...]) + -- Command: [SOL] = ode5r (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, ...]) + -- Command: [T, Y, [XE, YE, IE]] = ode5r (@FUN, SLOT, INIT, [OPT], + [PAR1, PAR2, ...]) + This function file can be used to solve a set of non-stiff or + stiff ordinary differential equations (ODEs) and non-stiff or + stiff differential algebraic equations (DAEs). This function file + is a wrapper to Hairer's and Wanner's Fortran solver `radau5.f'. + + If this function is called with no return argument then plot the + solution over time in a figure window while solving the set of + ODEs that are defined in a function and specified by the function + handle @FUN. The second input argument SLOT is a double vector + that defines the time slot, INIT is a double vector that defines + the initial values of the states, OPT can optionally be a + structure array that keeps the options created with the command + `odeset' and PAR1, PAR2, ... can optionally be other input + arguments of any type that have to be passed to the function + defined by @FUN. + + If this function is called with one return argument then return + the solution SOL of type structure array after solving the set of + ODEs. The solution SOL has the fields X of type double column + vector for the steps chosen by the solver, Y of type double column + vector for the solutions at each time step of X, SOLVER of type + string for the solver name and optionally the extended time stamp + information XE, the extended solution information YE and the + extended index information IE all of type double column vector + that keep the informations of the event function if an event + function handle is set in the option argument OPT. + + If this function is called with more than one return argument then + return the time stamps T, the solution values Y and optionally the + extended time stamp information XE, the extended solution + information YE and the extended index information IE all of type + double column vector. + + For example, + function y = odepkg_equations_lorenz (t, x) + y = [10 * (x(2) - x(1)); + x(1) * (28 - x(3)); + x(1) * x(2) - 8/3 * x(3)]; + endfunction + + vopt = odeset ("InitialStep", 1e-3, "MaxStep", 1e-1, \\ + "OutputFcn", @odephas3, "Refine", 5); + ode5r (@odepkg_equations_lorenz, [0, 25], [3 15 1], vopt); + + -- Function File: [] = oders (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, + ...]) + -- Command: [SOL] = oders (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, ...]) + -- Command: [T, Y, [XE, YE, IE]] = oders (@FUN, SLOT, INIT, [OPT], + [PAR1, PAR2, ...]) + This function file can be used to solve a set of non-stiff or + stiff ordinary differential equations (ODEs) and non-stiff or + stiff differential algebraic equations (DAEs). This function file + is a wrapper to Hairer's and Wanner's Fortran solver `rodas.f'. + + If this function is called with no return argument then plot the + solution over time in a figure window while solving the set of + ODEs that are defined in a function and specified by the function + handle @FUN. The second input argument SLOT is a double vector + that defines the time slot, INIT is a double vector that defines + the initial values of the states, OPT can optionally be a + structure array that keeps the options created with the command + `odeset' and PAR1, PAR2, ... can optionally be other input + arguments of any type that have to be passed to the function + defined by @FUN. + + If this function is called with one return argument then return + the solution SOL of type structure array after solving the set of + ODEs. The solution SOL has the fields X of type double column + vector for the steps chosen by the solver, Y of type double column + vector for the solutions at each time step of X, SOLVER of type + string for the solver name and optionally the extended time stamp + information XE, the extended solution information YE and the + extended index information IE all of type double column vector + that keep the informations of the event function if an event + function handle is set in the option argument OPT. + + If this function is called with more than one return argument then + return the time stamps T, the solution values Y and optionally the + extended time stamp information XE, the extended solution + information YE and the extended index information IE all of type + double column vector. + + For example, + function y = odepkg_equations_lorenz (t, x) + y = [10 * (x(2) - x(1)); + x(1) * (28 - x(3)); + x(1) * x(2) - 8/3 * x(3)]; + endfunction + + vopt = odeset ("InitialStep", 1e-3, "MaxStep", 1e-1, \\ + "OutputFcn", @odephas3, "Refine", 5); + oders (@odepkg_equations_lorenz, [0, 25], [3 15 1], vopt); + + -- Command: [] = odesx (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, ...]) + -- Command: [SOL] = odesx (@FUN, SLOT, INIT, [OPT], [PAR1, PAR2, ...]) + -- Command: [T, Y, [XE, YE, IE]] = odesx (@FUN, SLOT, INIT, [OPT], + [PAR1, PAR2, ...]) + This function file can be used to solve a set of stiff or + non-stiff ordinary differential equations (ODEs) and non-stiff or + stiff differential algebraic equations (DAEs). This function file + is a wrapper to Hairer's and Wanner's Fortran solver `seulex.f'. + + If this function is called with no return argument then plot the + solution over time in a figure window while solving the set of + ODEs that are defined in a function and specified by the function + handle @FUN. The second input argument SLOT is a double vector + that defines the time slot, INIT is a double vector that defines + the initial values of the states, OPT can optionally be a + structure array that keeps the options created with the command + `odeset' and PAR1, PAR2, ... can optionally be other input + arguments of any type that have to be passed to the function + defined by @FUN. + + If this function is called with one return argument then return + the solution SOL of type structure array after solving the set of + ODEs. The solution SOL has the fields X of type double column + vector for the steps chosen by the solver, Y of type double column + vector for the solutions at each time step of X, SOLVER of type + string for the solver name and optionally the extended time stamp + information XE, the extended solution information YE and the + extended index information IE all of type double column vector + that keep the informations of the event function if an event + function handle is set in the option argument OPT. + + If this function is called with more than one return argument then + return the time stamps T, the solution values Y and optionally the + extended time stamp information XE, the extended solution + information YE and the extended index information IE all of type + double column vector. + + For example, + function y = odepkg_equations_lorenz (t, x) + y = [10 * (x(2) - x(1)); + x(1) * (28 - x(3)); + x(1) * x(2) - 8/3 * x(3)]; + endfunction + + vopt = odeset ("InitialStep", 1e-3, "MaxStep", 1e-1, \\ + "OutputFcn", @odephas3, "Refine", 5); + odesx (@odepkg_equations_lorenz, [0, 25], [3 15 1], vopt); + + +File: odepkg.info, Node: Programmers Guide, Next: Function Index, Prev: Users Guide, Up: Top + +3 Programmers Guide +******************* + +* Menu: + +* Missing features:: The TODO-list for missing features + + +File: odepkg.info, Node: Missing features, Prev: Programmers Guide, Up: Programmers Guide + +3.1 Missing features +==================== + +If somebody want to help improving OdePkg then please contact the +Octave-Forge developer team sending your modifications via the +mailing-list . Here is a TODO-list +about missing features: + * 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). + + * Some options that can be set with propietary solver products are + not available within OdePkg. Have a look at section *Note + ODE/DAE/IDE/DDE options:: about which options can be set and which + options are not supported and help improving the command `odeset', + `odepkg_structure_check' and the solvers that have to deal with + these options. + + * OdePkg currently is missing the command `decic' which computes an + initial constraint for IDEs before solving. The command `deval' + also is missing that interpolates the results that can be obtained + from the solvers after solving and then plots the results in a new + figure. However, instead of using `deval' any of the commands + `interpX'. + + * If you want to include your own solver within OdePkg then either + code in `*.m' or `*.cc'. Solvers in `*.m' are preferred. Choose a + GPL compatible license for your solver and send your solver file + to the mailing list. + + * 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 `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: + + * Cecilia Magherini and Luigi Brugnano from the University of + Bari created the BIMD solver that is available at + `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. + + * Francesca Mazzia and Felice Iavernaro from the University of + Bari created the GAMD solver that is available at + `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. + + * 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 `http://www.unige.ch/~hairer/software.html' are + explicit Runge-Kutta methods `dopri5' and `dop853' and + extrapolation methods `odex' and `odex2' for solving ODEs, + `retard' and `radar5' for solving DDEs. + + * Jeff Cash has released some more Fortran77 solvers for + different kinds of differential equation problems than are + interfaced by OdePkg, check his website at + `http://www.ma.ic.ac.uk/~jcash'. + + + +File: odepkg.info, Node: Function Index, Next: Index, Prev: Programmers Guide, Up: Top + +Function Index +************** + +[index] +* Menu: + +* ode23: M-File Function Reference. + (line 14) +* ode23d: M-File Function Reference. + (line 60) +* ode2r: Oct-File Function Reference. + (line 164) +* ode45: M-File Function Reference. + (line 133) +* ode45d: M-File Function Reference. + (line 181) +* ode54: M-File Function Reference. + (line 254) +* ode54d: M-File Function Reference. + (line 300) +* ode5r: Oct-File Function Reference. + (line 210) +* ode78: M-File Function Reference. + (line 375) +* ode78d: M-File Function Reference. + (line 423) +* odebda: Oct-File Function Reference. + (line 12) +* odebdi: Oct-File Function Reference. + (line 62) +* odebwe: M-File Function Reference. + (line 496) +* odeexamples: M-File Function Reference. + (line 541) +* odeget: M-File Function Reference. + (line 545) +* odekdi: Oct-File Function Reference. + (line 113) +* odephas2: M-File Function Reference. + (line 569) +* odephas3: M-File Function Reference. + (line 603) +* odepkg: M-File Function Reference. + (line 642) +* odepkg_event_handle: M-File Function Reference. + (line 658) +* odepkg_examples_dae: M-File Function Reference. + (line 689) +* odepkg_examples_dde: M-File Function Reference. + (line 693) +* odepkg_examples_ide: M-File Function Reference. + (line 697) +* odepkg_examples_ode: M-File Function Reference. + (line 701) +* odepkg_structure_check: M-File Function Reference. + (line 706) +* odepkg_testsuite_calcmescd: M-File Function Reference. + (line 726) +* odepkg_testsuite_calcscd: M-File Function Reference. + (line 743) +* odepkg_testsuite_chemakzo: M-File Function Reference. + (line 760) +* odepkg_testsuite_hires: M-File Function Reference. + (line 776) +* odepkg_testsuite_implakzo: M-File Function Reference. + (line 792) +* odepkg_testsuite_implrober: M-File Function Reference. + (line 809) +* odepkg_testsuite_oregonator: M-File Function Reference. + (line 826) +* odepkg_testsuite_pollution: M-File Function Reference. + (line 843) +* odepkg_testsuite_robertson: M-File Function Reference. + (line 860) +* odepkg_testsuite_transistor: M-File Function Reference. + (line 877) +* odeplot: M-File Function Reference. + (line 893) +* odeprint: M-File Function Reference. + (line 926) +* oders: Oct-File Function Reference. + (line 259) +* odeset: M-File Function Reference. + (line 966) +* odesx: Oct-File Function Reference. + (line 306) + + +File: odepkg.info, Node: Index, Prev: Function Index, Up: Top + +Index +***** + +[index] +* Menu: + +* About OdePkg: About OdePkg. (line 6) +* AbsTol option: ODE/DAE/IDE/DDE options. + (line 41) +* BDF option: ODE/DAE/IDE/DDE options. + (line 373) +* BDF solver: Cash modified BDF solvers. + (line 6) +* Beginners guide: Beginners Guide. (line 6) +* bugs: Reporting Bugs. (line 6) +* Cash modified BDF: Cash modified BDF solvers. + (line 6) +* dae equations: DAE equations. (line 6) +* dae options: ODE/DAE/IDE/DDE options. + (line 6) +* ddaskr solver: DDaskr direct method solver. + (line 6) +* dde equations: DDE equations. (line 6) +* dde options: ODE/DAE/IDE/DDE options. + (line 6) +* decic: Missing features. (line 28) +* deinstallation: Installation and deinstallation. + (line 6) +* deval: Missing features. (line 28) +* differential equations: Differential Equations. + (line 6) +* Events option: ODE/DAE/IDE/DDE options. + (line 326) +* foo example: The "foo" example. (line 6) +* Hairer-Wanner: Hairer-Wanner solvers. + (line 6) +* history: OdePkg history and roadmap. + (line 6) +* ide equations: IDE equations. (line 6) +* ide options: ODE/DAE/IDE/DDE options. + (line 6) +* InitialSlope option: ODE/DAE/IDE/DDE options. + (line 114) +* InitialStep option: ODE/DAE/IDE/DDE options. + (line 98) +* installation: Installation and deinstallation. + (line 6) +* Jacobian option: ODE/DAE/IDE/DDE options. + (line 211) +* JPattern option: ODE/DAE/IDE/DDE options. + (line 251) +* m-file reference: M-File Function Reference. + (line 6) +* Mass option: ODE/DAE/IDE/DDE options. + (line 256) +* MassSingular option: ODE/DAE/IDE/DDE options. + (line 308) +* MaxNewtonIterations option: ODE/DAE/IDE/DDE options. + (line 383) +* MaxOrder option: ODE/DAE/IDE/DDE options. + (line 351) +* MaxStep option: ODE/DAE/IDE/DDE options. + (line 82) +* missing features: Missing features. (line 6) +* MStateDependence option: ODE/DAE/IDE/DDE options. + (line 280) +* MvPattern option: ODE/DAE/IDE/DDE options. + (line 306) +* NewtonTol option: ODE/DAE/IDE/DDE options. + (line 380) +* NonNegative option: ODE/DAE/IDE/DDE options. + (line 311) +* NormControl option: ODE/DAE/IDE/DDE options. + (line 60) +* oct-file reference: Oct-File Function Reference. + (line 6) +* ode equations: ODE equations. (line 6) +* ode options: ODE/DAE/IDE/DDE options. + (line 6) +* OutputFcn option: ODE/DAE/IDE/DDE options. + (line 117) +* OutputSel option: ODE/DAE/IDE/DDE options. + (line 173) +* performance: ODE solver performances. + (line 6) +* Programmers guide: Programmers Guide. (line 6) +* Refine option: ODE/DAE/IDE/DDE options. + (line 157) +* RelTol option: ODE/DAE/IDE/DDE options. + (line 20) +* roadmap: OdePkg history and roadmap. + (line 6) +* Runge-Kutta: Runge-Kutta solvers. (line 6) +* Runge-Kutta modified: Modified Runge-Kutta solvers. + (line 6) +* solver families: Solver families. (line 6) +* Stats option: ODE/DAE/IDE/DDE options. + (line 189) +* Users guide: Users Guide. (line 6) +* Vectorized option: ODE/DAE/IDE/DDE options. + (line 253) + + + +Tag Table: +Node: Top77 +Node: Beginners Guide1175 +Node: About OdePkg2340 +Node: OdePkg history and roadmap3448 +Node: Installation and deinstallation8050 +Node: Reporting Bugs8926 +Node: The "foo" example9602 +Node: Users Guide14647 +Node: Differential Equations15889 +Node: ODE equations16848 +Node: DAE equations17635 +Node: IDE equations19119 +Node: DDE equations19840 +Node: Solver families20556 +Node: Runge-Kutta solvers21606 +Ref: Runge-Kutta solvers-Footnote-125521 +Node: Hairer-Wanner solvers25973 +Node: Cash modified BDF solvers27800 +Node: DDaskr direct method solver29441 +Node: Modified Runge-Kutta solvers31110 +Node: ODE solver performances32910 +Node: ODE/DAE/IDE/DDE options38580 +Node: M-File Function Reference56436 +Node: Oct-File Function Reference105239 +Node: Programmers Guide123795 +Node: Missing features124013 +Node: Function Index127528 +Node: Index133329 + +End Tag Table