# HG changeset patch
# User Colin Macdonald <cbm@m.fsf.org>
# Date 1522137149 25200
#      Tue Mar 27 00:52:29 2018 -0700
# Node ID e6a96f2a05c4cd4cf9b31143ba25cc9c16de016f
# Parent  d0f9826f677ddb79a6da2db289ee93a93dc23027
docs: improve differential eqn docs and mention ode15i/ode15s

* doc/interpreter/diffeq.txi: add ode15i/ode15s (bug #51965), reword ode45/ode23, fix hyphens.
* scripts/ode/ode15i.m: fix typo in problem type, clarify meaning of variables.
* scripts/ode/ode23.m: seealso ode15s.
* scripts/ode/ode45.m: seealso ode15s.

diff -r d0f9826f677d -r e6a96f2a05c4 doc/interpreter/diffeq.txi
--- a/doc/interpreter/diffeq.txi	Mon Mar 26 21:17:17 2018 -0700
+++ b/doc/interpreter/diffeq.txi	Tue Mar 27 00:52:29 2018 -0700
@@ -133,20 +133,34 @@
 Currently implemented solvers are:
 
 @itemize
-  @item @nospell{Runge-Kutta} methods
+  @item @nospell{Runge--Kutta} methods
 
   @itemize
-    @item @code{ode45} Integrates a system of non--stiff ordinary differential equations
-    (non--stiff ODEs and DAEs) using second order @nospell{Dormand-Prince}
-    method.  This is a fourth--order accurate integrator therefore the local
-    error normally expected is @math{O(h^5)}.  This solver requires six
-    function evaluations per integration step.
+    @item @code{ode23} Integrates a system of non-stiff ordinary differential
+    equations (ODEs) or index-1 differential-algebraic equations (DAEs).  It
+    uses the third-order @nospell{Bogacki--Shampine} method and attempts to
+    ensure the error satisfies a user-specified tolerance by adapting the local
+    step size.  The solver requires three function evaluations per integration
+    step.
 
-    @item @code{ode23} Integrates a system of non--stiff ordinary differential equations
-    (non-stiff ODEs and DAEs) using second order @nospell{Bogacki-Shampine}
-    method.  This is a second-order accurate integrator therefore the local
-    error normally expected is @math{O(h^3)}.  This solver requires three
-    function evaluations per integration step.
+    @item @code{ode45} Integrates a system of non-stiff ODEs (or index-1 DAEs)
+    using the high-order accurate variable-step @nospell{Dormand--Prince}
+    method.  It requires six function evaluations per integration step but may
+    take larger steps compared to @code{ode23} on smooth problems, potentially
+    offering improved efficiency at smaller tolerances.
+  @end itemize
+
+  @item Linear multistep methods
+
+  @itemize
+    @item @code{ode15s} Integrates a system of stiff ODEs (or index-1 DAEs)
+    using a variable-step variable-order method based on backward difference
+    formulas.
+
+    @item @code{ode15i} Integrates a system of fully-implicit ODEs (or index-1
+    DAEs) using the same variable-step variable-order method as @code{ode15s}.
+    The function @code{decic} can be used to compute consistent initial
+    conditions.
   @end itemize
 @end itemize
 
@@ -155,6 +169,12 @@
 
 @DOCSTRING(ode23)
 
+@DOCSTRING(ode15s)
+
+@DOCSTRING(ode15i)
+
+@DOCSTRING(decic)
+
 @DOCSTRING(odeset)
 
 @DOCSTRING(odeget)
diff -r d0f9826f677d -r e6a96f2a05c4 scripts/ode/ode15i.m
--- a/scripts/ode/ode15i.m	Mon Mar 26 21:17:17 2018 -0700
+++ b/scripts/ode/ode15i.m	Tue Mar 27 00:52:29 2018 -0700
@@ -29,10 +29,10 @@
 ## ranges from order 1 to 5.
 ##
 ## @var{fun} is a function handle, inline function, or string containing the
-## name of the function that defines the ODE: @code{y' = f(t,y,yp)}.  The
+## name of the function that defines the ODE: @code{0 = f(t,y,yp)}.  The
 ## function must accept three inputs where the first is time @var{t}, the
-## second is a column vector of unknowns @var{y}, and the third is a column
-## vector of unknowns @var{yp}.
+## second is the function value @var{y} (a column vector), and the third
+## is the derivative value @var{yp} (a column vector).
 ##
 ## @var{trange} specifies the time interval over which the ODE will be
 ## evaluated.  Typically, it is a two-element vector specifying the initial and
diff -r d0f9826f677d -r e6a96f2a05c4 scripts/ode/ode23.m
--- a/scripts/ode/ode23.m	Mon Mar 26 21:17:17 2018 -0700
+++ b/scripts/ode/ode23.m	Tue Mar 27 00:52:29 2018 -0700
@@ -85,7 +85,7 @@
 ## [@var{t},@var{y}] = ode23 (fvdp, [0, 20], [2, 0]);
 ## @end group
 ## @end example
-## @seealso{odeset, odeget, ode45}
+## @seealso{odeset, odeget, ode45, ode15s}
 ## @end deftypefn
 
 function varargout = ode23 (fun, trange, init, varargin)
diff -r d0f9826f677d -r e6a96f2a05c4 scripts/ode/ode45.m
--- a/scripts/ode/ode45.m	Mon Mar 26 21:17:17 2018 -0700
+++ b/scripts/ode/ode45.m	Tue Mar 27 00:52:29 2018 -0700
@@ -83,7 +83,7 @@
 ## [@var{t},@var{y}] = ode45 (fvdp, [0, 20], [2, 0]);
 ## @end group
 ## @end example
-## @seealso{odeset, odeget, ode23}
+## @seealso{odeset, odeget, ode23, ode15s}
 ## @end deftypefn
 
 function varargout = ode45 (fun, trange, init, varargin)
