--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/interpreter/diffeq.txi	Tue Oct 19 10:08:42 1999 +0000
@@ -0,0 +1,189 @@
+@c Copyright (C) 1996, 1997 John W. Eaton
+@c This is part of the Octave manual.
+@c For copying conditions, see the file gpl.texi.
+
+@node Differential Equations, Optimization, Quadrature, Top
+@chapter Differential Equations
+
+Octave has two built-in functions for solving differential equations.
+Both are based on reliable ODE solvers written in Fortran.
+
+@menu
+* Ordinary Differential Equations::  
+* Differential-Algebraic Equations::  
+@end menu
+
+@cindex Differential Equations
+@cindex ODE
+@cindex DAE
+
+@node Ordinary Differential Equations, Differential-Algebraic Equations, Differential Equations, Differential Equations
+@section Ordinary Differential Equations
+
+The function @code{lsode} can be used to solve ODEs of the form
+@iftex
+@tex
+$$
+ {dx\over dt} = f (x, t)
+$$
+@end tex
+@end iftex
+@ifinfo
+
+@example
+dx
+-- = f (x, t)
+dt
+@end example
+@end ifinfo
+
+@noindent
+using Hindmarsh's ODE solver @sc{Lsode}.
+
+@deftypefn {Loadable Function} {} lsode (@var{fcn}, @var{x0}, @var{t}, @var{t_crit})
+Return a matrix of @var{x} as a function of @var{t}, given the initial
+state of the system @var{x0}.  Each row in the result matrix corresponds
+to one of the elements in the vector @var{t}.  The first element of
+@var{t} corresponds to the initial state @var{x0}, so that the first row
+of the output is @var{x0}.
+
+The first argument, @var{fcn}, is a string that names the function to
+call to compute the vector of right hand sides for the set of equations.
+It must have the form
+
+@example
+@var{xdot} = f (@var{x}, @var{t})
+@end example
+
+@noindent
+where @var{xdot} and @var{x} are vectors and @var{t} is a scalar.
+
+The fourth argument is optional, and may be used to specify a set of
+times that the ODE solver should not integrate past.  It is useful for
+avoiding difficulties with singularities and points where there is a
+discontinuity in the derivative.
+@end deftypefn
+
+Here is an example of solving a set of three differential equations using
+@code{lsode}.  Given the function
+
+@cindex oregonator
+
+@example
+@group
+function xdot = f (x, t)
+
+  xdot = zeros (3,1);
+
+  xdot(1) = 77.27 * (x(2) - x(1)*x(2) + x(1) \
+            - 8.375e-06*x(1)^2);
+  xdot(2) = (x(3) - x(1)*x(2) - x(2)) / 77.27;
+  xdot(3) = 0.161*(x(1) - x(3));
+
+endfunction
+@end group
+@end example
+
+@noindent
+and the initial condition @code{x0 = [ 4; 1.1; 4 ]}, the set of
+equations can be integrated using the command
+
+@example
+@group
+t = linspace (0, 500, 1000);
+
+y = lsode ("f", x0, t);
+@end group
+@end example
+
+If you try this, you will see that the value of the result changes
+dramatically between @var{t} = 0 and 5, and again around @var{t} = 305.
+A more efficient set of output points might be
+
+@example
+@group
+t = [0, logspace (-1, log10(303), 150), \
+        logspace (log10(304), log10(500), 150)];
+@end group
+@end example
+
+@deftypefn {Loadable Function} {} lsode_options (@var{opt}, @var{val})
+When called with two arguments, this function allows you set options
+parameters for the function @code{lsode}.  Given one argument,
+@code{lsode_options} returns the value of the corresponding option.  If
+no arguments are supplied, the names of all the available options and
+their current values are displayed.
+@end deftypefn
+
+See Alan C. Hindmarsh, @cite{ODEPACK, A Systematized Collection of ODE
+Solvers}, in Scientific Computing, R. S. Stepleman, editor, (1983) for
+more information about the inner workings of @code{lsode}.
+
+@node Differential-Algebraic Equations,  , Ordinary Differential Equations, Differential Equations
+@section Differential-Algebraic Equations
+
+The function @code{dassl} can be used to solve DAEs of the form
+@iftex
+@tex
+$$
+ 0 = f (\dot{x}, x, t), \qquad x(t=0) = x_0, \dot{x}(t=0) = \dot{x}_0
+$$
+@end tex
+@end iftex
+@ifinfo
+
+@example
+0 = f (x-dot, x, t),    x(t=0) = x_0, x-dot(t=0) = x-dot_0
+@end example
+@end ifinfo
+
+@noindent
+using Petzold's DAE solver @sc{Dassl}.
+
+@deftypefn {Loadable Function} {[@var{x}, @var{xdot}] =} dassl (@var{fcn}, @var{x0}, @var{xdot0}, @var{t}, @var{t_crit})
+Return a matrix of states and their first derivatives with respect to
+@var{t}.  Each row in the result matrices correspond to one of the
+elements in the vector @var{t}.  The first element of @var{t}
+corresponds to the initial state @var{x0} and derivative @var{xdot0}, so
+that the first row of the output @var{x} is @var{x0} and the first row
+of the output @var{xdot} is @var{xdot0}.
+
+The first argument, @var{fcn}, is a string that names the function to
+call to compute the vector of residuals for the set of equations.
+It must have the form
+
+@example
+@var{res} = f (@var{x}, @var{xdot}, @var{t})
+@end example
+
+@noindent
+where @var{x}, @var{xdot}, and @var{res} are vectors, and @var{t} is a
+scalar.
+
+The second and third arguments to @code{dassl} specify the initial
+condition of the states and their derivatives, and the fourth argument
+specifies a vector of output times at which the solution is desired, 
+including the time corresponding to the initial condition.
+
+The set of initial states and derivatives are not strictly required to
+be consistent.  In practice, however, @sc{Dassl} is not very good at
+determining a consistent set for you, so it is best if you ensure that
+the initial values result in the function evaluating to zero.
+
+The fifth argument is optional, and may be used to specify a set of
+times that the DAE solver should not integrate past.  It is useful for
+avoiding difficulties with singularities and points where there is a
+discontinuity in the derivative.
+@end deftypefn
+
+@deftypefn {Loadable Function} {} dassl_options (@var{opt}, @var{val})
+When called with two arguments, this function allows you set options
+parameters for the function @code{lsode}.  Given one argument,
+@code{dassl_options} returns the value of the corresponding option.  If
+no arguments are supplied, the names of all the available options and
+their current values are displayed.
+@end deftypefn
+
+See K. E. Brenan, et al., @cite{Numerical Solution of Initial-Value
+Problems in Differential-Algebraic Equations}, North-Holland (1989) for
+more information about the implementation of @sc{Dassl}.