Add docs to Problem

toolbox/+otp/+utils/+movie/+recorder/FileRecorder.m

@@ -43,8 +43,8 @@ function stop(obj)
             obj.VideoWriter.close();
         end
 
-        function h = play(obj)
-            h = implay(fullfile(obj.VideoWriter.Path, obj.VideoWriter.Filename), obj.VideoWriter.FrameRate);
+        function play(obj)
+            implay(fullfile(obj.VideoWriter.Path, obj.VideoWriter.Filename), obj.VideoWriter.FrameRate);
         end
     end
 end

toolbox/+otp/+utils/+movie/+recorder/MemoryRecorder.m

@@ -29,8 +29,12 @@ function stop(~)
             % Nothing to do
         end
 
-        function h = play(obj)
-            h = implay(obj.Mov, obj.FrameRate);
+        function play(obj)
+            if exist('implay', 'file')
+                implay(obj.Mov, obj.FrameRate);
+            else
+                movie(obj.Mov, 1, obj.FrameRate);
+            end
         end
     end
 end

toolbox/+otp/+utils/+movie/+recorder/NullRecorder.m

@@ -24,9 +24,8 @@ function stop(~)
             % Nothing to do
         end
 
-        function h = play(~)
-            h = 'Movie not saved for playback';
-            error('OTP:movieNotSaved', h);
+        function play(~)
+            error('OTP:movieNotSaved', 'Movie not saved for playback');
         end
     end
 end

toolbox/+otp/+utils/+movie/Movie.m

@@ -17,7 +17,7 @@
             p = inputParser;
             p.addParameter('Save', false);
             p.addParameter('FrameRate', otp.utils.movie.Movie.DefaultFramerate);
-            p.addParameter('TargetDuration', [], @(d) d > 0);
+            p.addParameter('Duration', [], @(d) d > 0);
             p.addParameter('Size', [], @(s) length(s) == 2 && all(s > 0));
             p.addParameter('Smooth', true, @islogical);
             p.parse(varargin{:});
@@ -46,27 +46,27 @@ function record(obj, t, y)
             totalSteps = length(t);
             [state.numVars, state.totalSteps] = size(y);
             if length(t) ~= state.totalSteps
-                error('OTP:invalidSolution', ...
-                    'Expected y to have %d columns but has %d', ...
-                    length(t), state.totalSteps);
+                error('OTP:invalidSolution', 'Expected y to have %d columns but has %d', length(t), state.totalSteps);
             end
 
             state.t = t;
             state.y = y;
             state.step = 0;
             state.frame = 0;
 
-            if isempty(obj.Config.TargetDuration)
+            if isempty(obj.Config.Duration)
                 state.totalFrames = totalSteps;
             else
-                state.totalFrames = round(obj.Config.TargetDuration * obj.FrameRate);
+                state.totalFrames = round(obj.Config.Duration * obj.FrameRate);
             end
 
             [t0, tEnd] = bounds(t);
 
             fig = figure;
             if ~isempty(obj.Config.Size)
-                fig.Position = [0; 0; obj.Config.Size(:)];
+                pos = get(fig, 'position');
+                pos(3:4) = obj.Config.Size;
+                set(fig, 'position', pos);
             end
 
             obj.init(fig, state);
@@ -97,8 +97,8 @@ function record(obj, t, y)
             obj.Recorder.stop();
         end
 
-        function h = play(obj)
-            h = obj.Recorder.play();
+        function play(obj)
+            obj.Recorder.play();
         end
     end
 

toolbox/+otp/RHS.m

@@ -4,16 +4,22 @@
     % This immutable class contains properties required by time integrators and other numerical methods to describe the
     % following differential equation:
     %
-    % $$M(t, y) y' = f(t, y)$$
+    % $$M(t, y(t); p) y'(t) = f(t, y(t); p)$$
     %
-    % The mass matrix $M(t, y)$ is permitted to be singular in which case the problem is a differential-algebraic
-    % equation. ``RHS`` includes most of the properties available in
-    % `odeset <https://www.mathworks.com/help/matlab/ref/odeset.html>`_ so that it can easily be used with built-in ODE
-    % solvers.
+    % Despite the name, an ``RHS`` includes information about the mass matrix $M(t, y(t); p)$ on the left-hand side. The
+    % mass matrix is permitted to be singular in which case the problem is a differential-algebraic equation. ``RHS``
+    % also includes most of the properties available in MATLAB`s `odeset`_ so that it can easily be used with built-in
+    % solvers like ``ode15s``.
+    %
+    % Note
+    % ----
+    % The parameters $p$ do not appear explicitly in the arguments of functions in this class. Rather, they can be
+    % provided through the closure of an anonymous function.
     %
     % Examples
     % --------
-    % >>> rhs = otp.RHS(@(t, y) [y(2) + t; y(1) * y(2)], ...
+    % >>> param = 1;
+    % >>> rhs = otp.RHS(@(t, y) [y(2) + param * t; y(1) * y(2)], ...
     % ...     'Jacobian', @(~, y) [0, 1; y(2), y(1)], ...
     % ...     'Mass', [1, 2; 3, 4]);
     % >>> sol = ode23s(rhs.F, [0, 1], [1, -1], rhs.odeset());
@@ -35,14 +41,14 @@
     % odeset : https://www.mathworks.com/help/matlab/ref/odeset.html
 
     properties (SetAccess = private)
-        % The function handle for $f$ in the differential equation $M(t, y) y' = f(t, y)$.
+        % The function handle for $f$ in the differential equation.
         %
         % Parameters
         % ----------
         % t : numeric
         %    The time at which $f$ is evaluated.
         % y : numeric(:, 1) or numeric(:, :)
-        %    The state at which $f$ is evaluated. If :attr:`Vectorized` in ``'on'``, it can be a matrix where each
+        %    The state at which $f$ is evaluated. If :attr:`Vectorized` is ``'on'``, it can be a matrix where each
         %    column is a state.
         %
         % Returns
@@ -55,7 +61,7 @@
         %
         % This follows the same specifications as in `odeset <https://www.mathworks.com/help/matlab/ref/odeset.html>`_.
         % If set, it is a matrix if it is independent of t and y or a function handle. In either case, it provides a
-        % square matrix in which element $(i,j)$ is $\frac{\partial f_i(t, y)}{\partial y_j}$. If ``Jacobian`` is a
+        % square matrix in which element $(i,j)$ is $\frac{\partial f_i(t, y; p)}{\partial y_j}$. If ``Jacobian`` is a
         % function handle, it has the following signature:
         %
         % Parameters
@@ -78,12 +84,12 @@
 
         % The sparsity pattern of the Jacobian matrix.
         %
-        % This follows the same specifications as in `odeset <https://www.mathworks.com/help/matlab/ref/odeset.html>`_.
+        % This follows the same specifications as in `odeset`_.
         JPattern
 
-        % The mass matrix $M(t, y)$.
+        % The mass matrix $M(t, y(t); p)$.
         %
-        % This follows the same specifications as in `odeset <https://www.mathworks.com/help/matlab/ref/odeset.html>`_.
+        % This follows the same specifications as in `odeset`_.
         %
         % See Also
         % --------
@@ -93,27 +99,27 @@
 
         % Whether the mass matrix is singular, i.e., the problem is a differential-algebraic equation.
         %
-        % This follows the same specifications as in `odeset <https://www.mathworks.com/help/matlab/ref/odeset.html>`_.
+        % This follows the same specifications as in `odeset`_.
         MassSingular
 
         % State dependence of the mass matrix.
         %
-        % This follows the same specifications as in `odeset <https://www.mathworks.com/help/matlab/ref/odeset.html>`_.
+        % This follows the same specifications as in `odeset`_.
         MStateDependence
 
-        % The sparsity pattern of $\frac{\partial}{\partial y} M(t, y) v$.
+        % The sparsity pattern of $\frac{\partial}{\partial y} M(t, y; p) v$.
         %
-        % This follows the same specifications as in `odeset <https://www.mathworks.com/help/matlab/ref/odeset.html>`_.
+        % This follows the same specifications as in `odeset`_.
         MvPattern
 
         % A vector of solution components which should be nonnegative.
         %
-        % This follows the same specifications as in `odeset <https://www.mathworks.com/help/matlab/ref/odeset.html>`_.
+        % This follows the same specifications as in `odeset`_.
         NonNegative
 
         % Whether $f$ can be evaluated at multiple states.
         %
-        % This follows the same specifications as in `odeset <https://www.mathworks.com/help/matlab/ref/odeset.html>`_.
+        % This follows the same specifications as in `odeset`_.
         %
         % Warning
         % -------
@@ -122,10 +128,10 @@
 
         % A function which detects events and determines whether to terminate the integration.
         %
-        % This follows the same specifications as in `odeset <https://www.mathworks.com/help/matlab/ref/odeset.html>`_.
+        % This follows the same specifications as in `odeset`_.
         Events
 
-        % Response to a terminal event occuring.
+        % Response to a terminal event occurring.
         %
         % If set, it is a function handle with the following signature:
         %
@@ -134,7 +140,7 @@
         % sol : struct
         %    The solution generated by an ODE solver once an event occurs.
         % problem : Problem
-        %    The problem for which the event occured. This should not be modified by the function.
+        %    The problem for which the event occurred. This should not be modified by the function.
         %
         % Returns
         % -------
@@ -147,7 +153,7 @@
         % Warning
         % -------
         % With Octave solvers, event data in ``sol`` is transposed compared to MATLAB. Therefore, we recommend accessing
-        % the state at which the event occured with ``sol.y(:, end)`` as opposed to ``sol.ye(:, end)``.
+        % the state at which the event occurred with ``sol.y(:, end)`` as opposed to ``sol.ye(:, end)``.
         OnEvent
 
         % The action of the Jacobian multiplying a vector.
@@ -167,7 +173,7 @@
         % Returns
         % -------
         % jvp : numeric(:, 1)
-        %    A vector in which element $i$ is $\sum_j \frac{\partial f_i(t, y)}{\partial y_j} v_j$.
+        %    A vector in which element $i$ is $\sum_j \frac{\partial f_i(t, y; p)}{\partial y_j} v_j$.
         JacobianVectorProduct
 
         % The action of the adjoint (conjugate transpose) of the Jacobian multiplying a vector.
@@ -187,7 +193,7 @@
         % Returns
         % -------
         % javp : numeric(:, 1)
-        %    A vector in which element $i$ is $\sum_j \frac{\partial \overline{f_j(t, y)}}{\partial y_i} v_j$.
+        %    A vector in which element $i$ is $\sum_j \frac{\partial \overline{f_j(t, y; p)}}{\partial y_i} v_j$.
         JacobianAdjointVectorProduct
 
         % The partial derivative of $f$ with respect to parameters.
@@ -222,7 +228,7 @@
         % Returns
         % -------
         % pdt : numeric(:, 1)
-        %    A vector in which element $i$ is $\frac{\partial f_i(t, y)}{\partial t}$.
+        %    A vector in which element $i$ is $\frac{\partial f_i(t, y; p)}{\partial t}$.
         %
         % Note
         % ----
@@ -246,7 +252,7 @@
         % -------
         % hvp : numeric(:, 1)
         %    A vector in which element $i$ is
-        %    $\sum_{j,k} \frac{\partial^2 f_i(t, y)}{\partial y_j \partial y_k} u_j v_k$.
+        %    $\sum_{j,k} \frac{\partial^2 f_i(t, y; p)}{\partial y_j \partial y_k} u_j v_k$.
         HessianVectorProduct
 
         % The action of a vector on the partial derivative of :attr:`JacobianAdjointVectorProduct` with respect to $y$.
@@ -266,18 +272,18 @@
         % -------
         % havp : numeric(:, 1)
         %    A vector in which element $i$ is
-        %    $\sum_{j,k} \frac{\partial^2 \overline{f_j(t, y)}}{\partial y_i \partial y_k} u_j v_k$.
+        %    $\sum_{j,k} \frac{\partial^2 \overline{f_j(t, y; p)}}{\partial y_i \partial y_k} u_j v_k$.
         HessianAdjointVectorProduct
     end
 
     properties (Dependent)
-        % A dependent property which retruns :attr:`Jacobian` if it is a matrix and ``[]`` if it is a function handle.
+        % A dependent property which returns :attr:`Jacobian` if it is a matrix and ``[]`` if it is a function handle.
         JacobianMatrix
 
         % A dependent property which wraps :attr:`Jacobian` in a function handle if necessary.
         JacobianFunction
 
-        % A dependent property which retruns :attr:`Mass` if it is a matrix and ``[]`` if it is a function handle.
+        % A dependent property which returns :attr:`Mass` if it is a matrix and ``[]`` if it is a function handle.
         MassMatrix
 
         % A dependent property which wraps :attr:`Mass` in a function handle if necessary.
@@ -291,7 +297,7 @@
             % Parameters
             % ----------
             % F : function_handle
-            %    The function handle for $f$ in the differential equation $M(t, y) y' = f(t, y)$.
+            %    The function handle for $f$ in the differential equation.
             % varargin
             %    A variable number of name-value pairs. A name can be any property of this class, and the subsequent
             %    value initializes that property.
@@ -381,17 +387,29 @@
         end
 
         function opts = odeset(obj, varargin)
-            % Convert an ``RHS`` to a struct which can be used by built-in ODE solvers.
+            % Convert an ``RHS`` to a options structure which can be used by built-in ODE solvers.
             %
             % Parameters
             % ----------
             % varargin
-            %    Additional name-value pairs which have precedence over the values in this class.
+            %    Additional name-value pairs which have precedence over the values in this class when constructing the
+            %    options structure. Accept names include those supported by the built-in ``odeset``.
             %
             % Returns
             % -------
             % opts : struct
-            %    An options strucutre containing the subset of properties compatible with built-in ODE solvers.
+            %    An options structure containing the subset of properties compatible with built-in ODE solvers.
+            %
+            % Example
+            % -------
+            % >>> problem = otp.oregonator.presets.Canonical;
+            % >>> opts = problem.RHS.odeset('AbsTol', 1e-12, 'RelTol', 1e-4);
+            % >>> sol = ode23s(problem.RHS.F, problem.TimeSpan, problem.Y0, opts);
+            %
+            % See Also
+            % --------
+            %
+            % odeset : https://www.mathworks.com/help/matlab/ref/odeset.html
 
             opts = odeset( ...
                 'Events', obj.Events, ...