Mercurial > octave

changeset 22941:d92ec2901770

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Make ode15i,ode15s doc consistent with other ode functions. * ode15i.m, ode15s.m: Make doc consistent with other ode functions. Add missing closing ']' to error() function calls.
author Rik <rik@octave.org>
date Mon, 26 Dec 2016 15:20:44 -0800
parents 2d7eb612d043
children 7627ebcf194d
files scripts/ode/ode15i.m scripts/ode/ode15s.m
diffstat 2 files changed, 57 insertions(+), 58 deletions(-) [+]
line wrap: on
line diff
--- a/scripts/ode/ode15i.m	Mon Dec 26 08:49:42 2016 -0800
+++ b/scripts/ode/ode15i.m	Mon Dec 26 15:20:44 2016 -0800
@@ -21,6 +21,7 @@
 ## @deftypefnx {} {[@var{t}, @var{y}] =} ode15i (@var{fun}, @var{trange}, @var{y0}, @var{yp0}, @var{ode_opt})
 ## @deftypefnx {} {[@var{t}, @var{y}, @var{te}, @var{ye}, @var{ie}] =} ode15i (@dots{})
 ## @deftypefnx {} {@var{solution} =} ode15i (@dots{})
+## @deftypefnx {} {} ode15i (@dots{})
 ##
 ## Solve a set of full-implicit Ordinary Differential Equations and
 ## Differential Algebraic Equations (DAEs) of index 1, with the variable-step,
@@ -28,16 +29,16 @@
 ## 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{f(@var{t},@var{y},@var{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
+## name of the function that defines the ODE: @code{y' = 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}.
 ##
 ## @var{trange} specifies the time interval over which the ODE will be
 ## evaluated.  Typically, it is a two-element vector specifying the initial and
 ## final times (@code{[tinit, tfinal]}).  If there are more than two elements
-## then the solution will also be evaluated at these intermediate time.
+## then the solution will also be evaluated at these intermediate time
+## instances.
 ##
 ## @var{y0} and @var{yp0} contain the initial values for the unknowns @var{y}
 ## and @var{yp}.  If they are row vectors then the solution @var{y} will be a
@@ -45,8 +46,8 @@
 ## value in @var{y0} and @var{yp0}.
 ##
 ## @var{y0} and @var{yp0} must be consistent initial conditions, meaning that
-## @code{f(@var{t},@var{y0},@var{yp0})=0} is satisfied. You can use function
-## decic to compute consistent initial conditions, given initial guesses.
+## @code{f(t,y0,yp0) = 0} is satisfied.  You can use function @code{decic} to
+## compute consistent initial conditions, given initial guesses.
 ##
 ## The optional fifth argument @var{ode_opt} specifies non-default options to
 ## the ODE solver.  It is a structure generated by @code{odeset}.
@@ -57,35 +58,32 @@
 ## unknown of the problem and each row corresponds to a time in @var{t}.
 ##
 ## The output can also be returned as a structure @var{solution} which
-## has field @var{x} containing the time where the solution was evaluated and
-## field @var{y} containing the solution matrix for the times in @var{x}.
+## has a field @var{x} containing a row vector of times where the solution
+## was evaluated and a field @var{y} containing the solution matrix such
+## that each column corresponds to a time in @var{x}.
 ## Use @code{fieldnames (@var{solution})} to see the other fields and
 ## additional information returned.
 ##
+## If no output arguments are requested, and no @code{OutputFcn} is
+## specified in @var{ode_opt}, then the @code{OutputFcn} is set to
+## @code{odeplot} and the results of the solver are plotted immediately.
+##
 ## If using the @qcode{"Events"} option then three additional outputs may
 ## be returned.  @var{te} holds the time when an Event function returned a
 ## zero.  @var{ye} holds the value of the solution at time @var{te}.  @var{ie}
 ## contains an index indicating which Event function was triggered in the case
 ## of multiple Event functions.
 ##
-## This function can be called with two output arguments: @var{t} and @var{y}.
-## Variable @var{t} is a column vector and contains the time stamps, instead
-## @var{y} is a matrix in which each column refers to a different unknown of
-## the problem and the rows number is the same of @var{t} rows number so
-## that each row of @var{y} contains the values of all unknowns at the time
-## value contained in the corresponding row in @var{t}.
-##
-## Example: Solve the @nospell{Robetson}'s equations:
+## Example: Solve the @nospell{Robetson's} equations:
 ##
 ## @example
 ## @group
-## function res = robertsidae(@var{t}, @var{y}, @var{yp})
-## res = [-(@var{yp}(1) + 0.04*@var{y}(1) - 1e4*@var{y}(2)*@var{y}(3));
-##        -(@var{yp}(2) - 0.04*@var{y}(1) + 1e4*@var{y}(2)*@var{y}(3) +
-##        3e7*@var{y}(2)^2);
+## function r = robertsidae (@var{t}, @var{y}, @var{yp})
+##   r = [-(@var{yp}(1) + 0.04*@var{y}(1) - 1e4*@var{y}(2)*@var{y}(3));
+##        -(@var{yp}(2) - 0.04*@var{y}(1) + 1e4*@var{y}(2)*@var{y}(3) + 3e7*@var{y}(2)^2);
 ##        @var{y}(1) + @var{y}(2) + @var{y}(3) - 1];
 ## endfunction
-## [@var{t},@var{y}] = ode15i (@@robertsidae, [0 1e3], [1; 0; 0], [-1e-4; 1e-4; 0]);
+## [@var{t},@var{y}] = ode15i (@@robertsidae, [0, 1e3], [1; 0; 0], [-1e-4; 1e-4; 0]);
 ## @end group
 ## @end example
 ## @seealso{decic, odeset, odeget}
@@ -133,7 +131,7 @@
       end_try_catch
       if (! isa (options.OutputFcn, "function_handle"))
         error ("Octave:invalid-input-arg",
-               [solver ": invalid value assigned to field 'OutputFcn'");
+               [solver ": invalid value assigned to field 'OutputFcn'"]);
       endif
     endif
   endif
@@ -148,7 +146,7 @@
       if (! isa (options.Events, "function_handle")
           && ! ismatrix (options.Events))
         error ("Octave:invalid-input-arg",
-               [solver ": invalid value assigned to field 'Events'");
+               [solver ": invalid value assigned to field 'Events'"]);
       endif
     endif
   endif
@@ -189,11 +187,11 @@
             || ! isreal (options.Jacobian{1})
             || ! isreal (options.Jacobian{2}))
           error ("Octave:invalid-input-arg",
-                 [solver ": invalid value assigned to field 'Jacobian'");
+                 [solver ": invalid value assigned to field 'Jacobian'"]);
         endif
       else
         error ("Octave:invalid-input-arg",
-               [solver ": invalid value assigned to field 'Jacobian'");
+               [solver ": invalid value assigned to field 'Jacobian'"]);
       endif
 
     elseif (isa (options.Jacobian, "function_handle"))
@@ -208,15 +206,15 @@
             || ! isnumeric (A) || ! isnumeric (B) || ! isreal (A)
             || ! isreal (B))
           error ("Octave:invalid-input-arg",
-                 [solver ": invalid value assigned to field 'Jacobian'");
+                 [solver ": invalid value assigned to field 'Jacobian'"]);
         endif
       else
         error ("Octave:invalid-input-arg",
-               [solver ": invalid value assigned to field 'Jacobian'");
+               [solver ": invalid value assigned to field 'Jacobian'"]);
       endif
     else
         error ("Octave:invalid-input-arg",
-               [solver ": invalid value assigned to field 'Jacobian'");
+               [solver ": invalid value assigned to field 'Jacobian'"]);
     endif
   endif
 
@@ -225,7 +223,7 @@
 
   if (numel (options.AbsTol) != 1 && numel (options.AbsTol) != n)
     error ("Octave:invalid-input-arg",
-           [solver ": invalid value assigned to field 'AbsTol'");
+           [solver ": invalid value assigned to field 'AbsTol'"]);
 
   elseif (numel (options.AbsTol) == n)
     options.haveabstolvec = true;
--- a/scripts/ode/ode15s.m	Mon Dec 26 08:49:42 2016 -0800
+++ b/scripts/ode/ode15s.m	Mon Dec 26 15:20:44 2016 -0800
@@ -21,21 +21,23 @@
 ## @deftypefnx {} {[@var{t}, @var{y}] =} ode15s (@var{fun}, @var{trange}, @var{y0}, @var{ode_opt})
 ## @deftypefnx {} {[@var{t}, @var{y}, @var{te}, @var{ye}, @var{ie}] =} ode15s (@dots{})
 ## @deftypefnx {} {@var{solution} =} ode15s (@dots{})
+## @deftypefnx {} {} ode15s (@dots{})
 ##
 ## Solve a set of stiff Ordinary Differential Equations and stiff semi-explicit
 ## Differential Algebraic Equations (DAEs) of index 1, with the variable-step,
-## variable order BDF (Backward Differentiation Formula) method, which
-## ranges from order 1 to 5.
+## variable order BDF (Backward Differentiation Formula) method, which 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{f(@var{t},@var{y})}.
-## The function must accept two inputs where the first is time @var{t} and the
-## second is a column vector of unknowns @var{y}.
+## name of the function that defines the ODE: @code{y' = f(t,y)}.  The function
+## must accept two inputs where the first is time @var{t} and the second is a
+## column vector of unknowns @var{y}.
 ##
 ## @var{trange} specifies the time interval over which the ODE will be
 ## evaluated.  Typically, it is a two-element vector specifying the initial and
 ## final times (@code{[tinit, tfinal]}).  If there are more than two elements
-## then the solution will also be evaluated at these intermediate time.
+## then the solution will also be evaluated at these intermediate time
+## instances.
 ##
 ## @var{init} contains the initial value for the unknowns.  If it is a row
 ## vector then the solution @var{y} will be a matrix in which each column is
@@ -50,34 +52,33 @@
 ## unknown of the problem and each row corresponds to a time in @var{t}.
 ##
 ## The output can also be returned as a structure @var{solution} which
-## has field @var{x} containing the time where the solution was evaluated and
-## field @var{y} containing the solution matrix for the times in @var{x}.
+## has a field @var{x} containing a row vector of times where the solution
+## was evaluated and a field @var{y} containing the solution matrix such
+## that each column corresponds to a time in @var{x}.
 ## Use @code{fieldnames (@var{solution})} to see the other fields and
 ## additional information returned.
 ##
+## If no output arguments are requested, and no @code{OutputFcn} is
+## specified in @var{ode_opt}, then the @code{OutputFcn} is set to
+## @code{odeplot} and the results of the solver are plotted immediately.
+##
 ## If using the @qcode{"Events"} option then three additional outputs may
 ## be returned.  @var{te} holds the time when an Event function returned a
 ## zero.  @var{ye} holds the value of the solution at time @var{te}.  @var{ie}
 ## contains an index indicating which Event function was triggered in the case
 ## of multiple Event functions.
 ##
-## This function can be called with two output arguments: @var{t} and @var{y}.
-## Variable @var{t} is a column vector and contains the time stamps, instead
-## @var{y} is a matrix in which each column refers to a different unknown of
-## the problem and the rows number is the same of @var{t} rows number so
-## that each row of @var{y} contains the values of all unknowns at the time
-## value contained in the corresponding row in @var{t}.
+## Example: Solve the @nospell{Robetson's} equations:
 ##
-## Example: Solve the @nospell{Robetson}'s equations:
 ## @example
 ## @group
-## function res = robertsidae(@var{t}, @var{y})
-## res = [-0.04*@var{y}(1) + 1e4*@var{y}(2)*@var{y}(3);
+## function r = robertsidae (@var{t}, @var{y})
+##   r = [-0.04*@var{y}(1) + 1e4*@var{y}(2)*@var{y}(3);
 ##         0.04*@var{y}(1) - 1e4*@var{y}(2)*@var{y}(3) - 3e7*@var{y}(2)^2;
 ##         @var{y}(1) + @var{y}(2) + @var{y}(3) - 1];
 ## endfunction
 ## opt = odeset ("Mass", [1 0 0; 0 1 0; 0 0 0], "MStateDependence", "none");
-## [@var{t},@var{y}] = ode15s (@@robertsidae, [0 1e3], [1; 0; 0], opt);
+## [@var{t},@var{y}] = ode15s (@@robertsidae, [0, 1e3], [1; 0; 0], opt);
 ## @end group
 ## @end example
 ## @seealso{decic, odeset, odeget}
@@ -181,7 +182,7 @@
         options.havemasssparse = issparse (M);
         if (any (size (M) != [n n]) || ! isnumeric (M) || ! isreal (M))
           error ("Octave:invalid-input-arg",
-                 [solver ": invalid value assigned to field 'Mass'");
+                 [solver ": invalid value assigned to field 'Mass'"]);
         endif
       elseif (nargin (options.Mass) == 1)
         options.havetimedep = true;
@@ -189,22 +190,22 @@
         options.havemasssparse = issparse (M);
         if (any (size (M) != [n n]) || ! isnumeric (M) || ! isreal (M))
           error ("Octave:invalid-input-arg",
-                 [solver ": invalid value assigned to field 'Mass'");
+                 [solver ": invalid value assigned to field 'Mass'"]);
         endif
       else
         error ("Octave:invalid-input-arg",
-               [solver ": invalid value assigned to field 'Mass'");
+               [solver ": invalid value assigned to field 'Mass'"]);
       endif
     elseif (ismatrix (options.Mass))
       options.havemasssparse = issparse (options.Mass);
       if (any (size (options.Mass) != [n n]) ||
           ! isnumeric (options.Mass) || ! isreal (options.Mass))
         error ("Octave:invalid-input-arg",
-               [solver ": invalid value assigned to field 'Mass'");
+               [solver ": invalid value assigned to field 'Mass'"]);
       endif
     else
       error ("Octave:invalid-input-arg",
-             [solver ": invalid value assigned to field 'Mass'");
+             [solver ": invalid value assigned to field 'Mass'"]);
     endif
   endif
 
@@ -224,11 +225,11 @@
         endif
         if (any (size (A) != [n n]) || ! isnumeric (A) || ! isreal (A))
           error ("Octave:invalid-input-arg",
-                 [solver ": invalid value assigned to field 'Jacobian'");
+                 [solver ": invalid value assigned to field 'Jacobian'"]);
         endif
       else
         error ("Octave:invalid-input-arg",
-               [solver ": invalid value assigned to field 'Jacobian'");
+               [solver ": invalid value assigned to field 'Jacobian'"]);
       endif
     elseif (ismatrix (options.Jacobian))
       if (issparse (options.Jacobian))
@@ -236,11 +237,11 @@
       endif
       if (! issquare (options.Jacobian))
         error ("Octave:invalid-input-arg",
-               [solver ": invalid value assigned to field 'Jacobian'");
+               [solver ": invalid value assigned to field 'Jacobian'"]);
       endif
     else
       error ("Octave:invalid-input-arg",
-             [solver ": invalid value assigned to field 'Jacobian'");
+             [solver ": invalid value assigned to field 'Jacobian'"]);
     endif
   endif
 
@@ -282,7 +283,7 @@
 
   if (numel (options.AbsTol) != 1 && numel (options.AbsTol) != n)
     error ("Octave:invalid-input-arg",
-           [solver ": invalid value assigned to field 'AbsTol'");
+           [solver ": invalid value assigned to field 'AbsTol'"]);
   elseif (numel (options.AbsTol) == n)
     options.haveabstolvec = true;
   endif