Minor improvements to the documentation.

Thanks to @debdeepbh.
Closes #59.

RK-coeff-opt/README.rst

@@ -4,7 +4,7 @@ Constraints on the stability polynomial (possibly obtained using **polyopt** or
 can optionally be provided.
 
 To run the tests, execute the MATLAB commands
-```
+``
 results_rkopt = runtests('test_rkopt.m');
 table(results_rkopt)
-```
+``

RK-coeff-opt/check_RK_order.m

@@ -2,8 +2,11 @@
 % function p = check_RK_order(A,b,c)
 % Determines order of a RK method, up to sixth order.
 %
-% For an s-stage method, input `A` should be a `s \times s` matrix;
-% `b` and `c` should be column vectors of length `s`.
+% Inputs:
+%       * A, b, c: Butcher coefficients of the method
+%       * p = order of accuracy
+%       * problem_class: 'nonlinear' (default) or 'linear'
+%         if set to 'linear', only order conditions for linear problems are checked.
 
 if nargin<4
     problem_class='nonlinear';

RK-coeff-opt/oc_albrecht.m

@@ -2,19 +2,20 @@
 % function coneq=oc_albrecht(A,b,c,p)
 %
 % Order conditions for SSP RK methods.
-%
 % This version is based on Albrecht's approach.
 
-% ..warning:: 
+% Inputs:
+%       * A, b, c: Butcher coefficients of the method
+%       * p = order of accuracy
 %
-%         Here we assume a certain minimum stage order,
-%         which is necessarily true for methods with
-%         strictly positive abscissae (b>0).
-%         This assumption dramatically reduces the
-%         number of order conditions that must be
-%         considered for high-order methods.
-%         For methods that do not satisfy b>0, this
-%         assumption may be unnecessarily restrictive.
+% Here we assume the method has a certain minimum stage order,
+% which is necessarily true for methods with
+% strictly positive abscissae (b>0).
+% This assumption dramatically reduces the
+% number of order conditions that must be
+% considered for high-order methods.
+% For methods that do not satisfy b>0, this
+% assumption may be unnecessarily restrictive.
 
 %min_stage_order = floor((p-1)/2.);
 min_stage_order = 1;

RK-coeff-opt/oc_butcher.m

@@ -5,6 +5,10 @@
 % This version is based on Butcher's approach.
 %
 % Assumes `p>1`.
+%
+% Inputs:
+%       * A, b, c: Butcher coefficients of the method
+%       * p = order of accuracy
 
 coneq(1)=c'*b-1/2;
 

RK-coeff-opt/oc_ksrk.m

@@ -1,17 +1,17 @@
 function coneq= oc_ksrk(A,b,D,theta,p)
 % function coneq= oc_ksrk(A,b,D,theta,p)
 % Order conditions for multistep-RK methods.
+% See the paper :cite:`2017_msrk` for details
+% and for the meaning of the input coefficients.
 %
-% ..warning::
-%
-%         Here we assume a certain minimum stage order,
-%         which is necessarily true for methods with
-%         strictly positive abscissae (b>0).
-%         This assumption dramatically reduces the
-%         number of order conditions that must be
-%         considered for high-order methods.
-%         For methods that do not satisfy b>0, this
-%         assumption may be unnecessarily restrictive.
+%  Here we assume a certain minimum stage order,
+%  which is necessarily true for methods with
+%  strictly positive abscissae (b>0).
+%  This assumption dramatically reduces the
+%  number of order conditions that must be
+%  considered for high-order methods.
+%  For methods that do not satisfy b>0, this
+%  assumption may be unnecessarily restrictive.
 
 
 k=length(theta);

RK-coeff-opt/rk_obj.m

@@ -3,14 +3,14 @@
 %
 % Objective function for RK optimization.
 %
-% The meaning of the input arguments is as follows:
+% Inputs:
 %     * :math:`x`: vector of the unknowns.
 %     * class: class of method to search ('erk' = explicit RK; 'irk' = implicit RK; 'dirk' = diagonally implicit RK; 'sdirk' = singly diagonally implicit RK; '2S', '3S', '2S*', '3S*' = low-storage formulations).
 %     * :math:`s`:number of stages.
 %     * :math:`p`: order of the RK scheme.
 %     * objective: objective function ('ssp' = maximize SSP coefficient; 'acc' = minimize leading truncation error coefficient).
 %
-% The meaning of the output arguments is as follows:
+% Outputs:
 %     * r: it is a scalar containing the radius of absolute monotonicity if objective = 'ssp' or the value of the leading truncation error coefficient if objective = 'acc'.
 %     * g: a vector containing the gradient of the objective function respect to the unknowns.  It is an array with all zero elements except for the last component which is equal to one if objective = 'ssp' or it is an empty array if objective = 'acc'. 
 

RK-coeff-opt/rk_opt.m

@@ -33,7 +33,7 @@
 %     * suppress_warnings: whether to suppress all warnings
 %
 %     .. note::
-%        **numerical experiments have shown that when the objective function is the minimization of the leading truncation error coefficient, the interior-point algorithm performs much better than the sqp one.**
+%        **Numerical experiments have shown that when the objective function is the minimization of the leading truncation error coefficient, the interior-point algorithm performs much better than the sqp one.**
 %
 %     * display: level of display of fmincon solver ('off', 'iter', 'notify' or 'final'). The default value is 'notify'.
 %     * problem_class: class of problems for which the RK is designed ('linear' or 'nonlinear' problems). This option changes the type of order conditions check, i.e. linear or nonlinear order conditions control. The default value is 'nonlinear'.

RK-coeff-opt/unpack_msrk.m

@@ -2,6 +2,8 @@
 % function [A,Ahat,b,bhat,D,theta] =  unpack_msrk(X,s,k,class)
 %
 % Extract the coefficient arrays from the optimization vector
+% See the paper :cite:`msrk_2017` for details and a description
+% of what the coefficients mean.
 
 switch class 
     % TODO: clean up the following code

RKtools/am_radius.m

@@ -19,7 +19,7 @@
 %    rK(I+rA)^{-1}e_m \\le & e_{m+1}
 %    \\end{align*}
 %
-%    where $$ K = \\left(\\begin{array}{c} A \\\\\\ b^T \\end{array}\\right) $$
+%    where $$ K = \\left(\\begin{array}{c} A \\\\\\ b^T \\end{array}\\right).$$
 
 
 if nargin<5 rmax=50; end

doc/refs.bib

@@ -38,3 +38,11 @@ @article{2012_optimal_stability_polynomials
 }
 
 
+@article{2017_msrk,
+	Author = {Bresten, Christopher and Gottlieb, Sigal and Grant, Zachary and Higgs, Daniel and Ketcheson, David I. and N{\'e}meth, Adrian},
+	Journal = {Math. of Comp.},
+	Pages = {747-769},
+	Title = {Strong Stability Preserving Multistep {R}unge-{K}utta Methods},
+	Volume = {86},
+	Year = {2017}}
+

doc/started.rst

@@ -21,7 +21,8 @@ Obtaining RK-Opt
 
     $ git clone https://github.com/ketch/RK-Opt.git
 
-After unzipping/cloning, add the subdirectory ``RK-Opt/RKtools`` to your MATLAB path.
+After unzipping/cloning, add the subdirectory ``RK-Opt/RKtools`` to your MATLAB path
+(see https://www.mathworks.com/help/matlab/ref/addpath.html).
 
 
 =========================

polyopt/README.rst

@@ -9,7 +9,7 @@ Inputs to reproduce the examples from the paper are given in examples.txt.
 
 
 To run the tests, execute the MATLAB commands
-```
+``
 results_polyopt = runtests('test_polyopt.m');
 table(results_polyopt)
-```
+``

polyopt/opt_poly_bisect.m

@@ -17,7 +17,7 @@
 %                 A function used to generate the appropriate spectrum
 %                 at each bisection step, instead of using a fixed (scaled) spectrum.
 %                 Used for instance to find the longest rectangle of a fixed height
-%                 (see Figure 10 of the CAMCoS paper).
+%                 (see Figure 10 of :cite:`2012_optimal_stability_polynomials`).
 %
 % Examples:
 %