@c Copyright (C) 1996-2022 The Octave Project Developers
@c
@c This file is part of Octave.
@c
@c Octave is free software: you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by
@c the Free Software Foundation, either version 3 of the License, or
@c (at your option) any later version.
@c
@c Octave is distributed in the hope that it will be useful, but
@c WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License for more details.
@c
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <https://www.gnu.org/licenses/>.

@node Differential Equations
@chapter Differential Equations

Octave has built-in functions for solving ordinary differential equations
(ODEs), and differential-algebraic equations (DAEs).

@menu
* Ordinary Differential Equations::
* Differential-Algebraic Equations::
* Matlab-compatible solvers::
@end menu

@cindex differential equations
@cindex ODE
@cindex DAE

@node Ordinary Differential Equations
@section Ordinary Differential Equations

The function @code{lsode} can be used to solve ODEs of the form
@tex
$$
 {dx\over dt} = f (x, t)
$$
@end tex
@ifnottex

@example
@group
dx
-- = f (x, t)
dt
@end group
@end example

@end ifnottex

@noindent
using @nospell{Hindmarsh's} ODE solver @sc{lsode}.

@DOCSTRING(lsode)

@DOCSTRING(lsode_options)

Here is an example of solving a set of three differential equations using
@code{lsode}.  Given the function

@cindex oregonator

@example
@group
## oregonator differential equation
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

An m-file for the differential equation used above is included with the
Octave distribution in the examples directory under the name
@file{oregonator.m}.


@node Differential-Algebraic Equations
@section Differential-Algebraic Equations

The function @code{daspk} can be used to solve DAEs of the form
@tex
$$
 0 = f (\dot{x}, x, t), \qquad x(t=0) = x_0, \dot{x}(t=0) = \dot{x}_0
$$
@end tex
@ifnottex

@example
0 = f (x-dot, x, t),    x(t=0) = x_0, x-dot(t=0) = x-dot_0
@end example

@end ifnottex

@noindent
where
@tex
$\dot{x} = {dx \over dt}$
@end tex
@ifnottex
@math{x-dot}
@end ifnottex
is the derivative of @math{x}.  The equation is solved using
@nospell{Petzold's} DAE solver @sc{daspk}.

@DOCSTRING(daspk)

@DOCSTRING(daspk_options)

Octave also includes @sc{dassl}, an earlier version of @sc{daspk},
and @sc{dasrt}, which can be used to solve DAEs with constraints
(stopping conditions).

@DOCSTRING(dassl)

@DOCSTRING(dassl_options)

@DOCSTRING(dasrt)

@DOCSTRING(dasrt_options)

See @nospell{K. E. Brenan}, et al., @cite{Numerical Solution of Initial-Value
Problems in Differential-Algebraic Equations}, North-Holland (1989),
@nospell{DOI}: @url{https://doi.org/10.1137/1.9781611971224},
for more information about the implementation of @sc{dassl}.


@node Matlab-compatible solvers
@section Matlab-compatible solvers

Octave also provides a set of solvers for initial value problems for ordinary
differential equations (ODEs) that have a @sc{matlab}-compatible interface.
The options for this class of methods are set using the functions.

@itemize
  @item @ref{XREFodeset,,odeset}

  @item @ref{XREFodeget,,odeget}
@end itemize

Currently implemented solvers are:

@itemize
  @item @nospell{Runge-Kutta} methods

  @itemize
    @item @ref{XREFode45,,ode45} integrates a system of non-stiff ODEs or
    index-1 differential-algebraic equations (DAEs) using the high-order,
    variable-step @nospell{Dormand-Prince} method.  It requires six function
    evaluations per integration step, but may take larger steps on smooth
    problems than @code{ode23}: potentially offering improved efficiency at
    smaller tolerances.

    @item @ref{XREFode23,,ode23} integrates a system of non-stiff ODEs or (or
    index-1 DAEs).  It uses the third-order @nospell{Bogacki-Shampine} method
    and adapts the local step size in order to satisfy a user-specified
    tolerance.  The solver requires three function evaluations per integration
    step.

    @item @ref{XREFode23s,,ode23s} integrates a system of stiff ODEs (or
    index-1 DAEs) using a modified second-order @nospell{Rosenbrock} method.
  @end itemize

  @item Linear multistep methods

  @itemize
    @item @ref{XREFode15s,,ode15s} integrates a system of stiff ODEs (or
    index-1 DAEs) using a variable step, variable order method based on
    Backward Difference Formulas (BDF).

    @item @ref{XREFode15i,,ode15i} integrates a system of fully-implicit ODEs
    (or index-1 DAEs) using the same variable step, variable order method as
    @code{ode15s}.  @ref{XREFdecic,,decic} can be used to compute consistent
    initial conditions for @code{ode15i}.
  @end itemize
@end itemize

Detailed information on the solvers are given in @nospell{L. F. Shampine} and
@nospell{M. W. Reichelt}, @cite{The MATLAB ODE Suite}, SIAM Journal on
Scientific Computing, Vol. 18, 1997, pp. 1–22,
@nospell{DOI}: @url{https://doi.org/10.1137/S1064827594276424}.

@DOCSTRING(ode45)

@DOCSTRING(ode23)

@DOCSTRING(ode23s)

@DOCSTRING(ode15s)

@DOCSTRING(ode15i)

@DOCSTRING(decic)

@DOCSTRING(odeset)

@DOCSTRING(odeget)

@DOCSTRING(odeplot)