@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}.