docs for Ascher linear DAE

Author: elswit

toolbox/+otp/+ascherlineardae/+presets/Canonical.m

@@ -1,10 +1,7 @@
 classdef Canonical < otp.ascherlineardae.AscherLinearDAEProblem
-    %CANONICAL The problem formulation of the linear DAE from the literature
-    %
-    % See
-    %    Ascher, Uri. "On symmetric schemes and differential-algebraic equations."
-    %    SIAM journal on scientific and statistical computing 10.5 (1989): 937-949.
-    
+    % The original problem defined by Uri Ascher in :cite:p:`Asc89` with 
+    % $\beta = 0.5$
+    % 
     methods
         function obj = Canonical(beta)
             tspan = [0.0; 1];

toolbox/+otp/+ascherlineardae/AscherLinearDAEParameters.m

@@ -1,7 +1,8 @@
 classdef AscherLinearDAEParameters
-    %ASCHERLINEARDAEPARAMETERS 
+    % Parameters for Ascher Linear DAE problem 
     properties
-        %Beta is an arbitrary scalar parameter
+        % Beta is a scalar parameter in the linear model. It also affects the initial condition
+        % of the algebraic variable.
         Beta %MATLAB ONLY: (1,1) {mustBeNumeric} = 0.5
     end
 end

toolbox/+otp/+ascherlineardae/AscherLinearDAEProblem.m

@@ -1,7 +1,8 @@
 classdef AscherLinearDAEProblem < otp.Problem
     % A simple linear differential algebraic problem.
     %
-    % The Ascher linear DAE Problem :cite:p:`Asc89` is given by $M(t) y' = A(t) y + q(t) $ with
+    % The Ascher linear DAE Problem :cite:p:`Asc89` is an index-1 differential agebraic 
+    % equation given by $M(t) y' = A(t) y + q(t) $ where
     %
     % $$
     % M=\left(\begin{array}{cc}
@@ -16,7 +17,7 @@
     % \end{array}\right), 
     % $$
     %
-    % with $t \in [0,1]$, and $y_0 = [1, \beta]^T$.  The exact solution
+    % defined on timespan $t \in [0,1]$, and initial condition $y_0 = [1, \beta]^T$. The exact solution
     % is given by 
     %
     % $$
@@ -27,9 +28,9 @@
     % $$
     %
     % Due to its stiffness and time-dependant mass
-    % matrix and righ-hand-side function, this simple DAE problem can 
-    % become challenging to solve. This problem is used in :cite:p:`Asc89` 
-    % to study convergence of implcit solvers. 
+    % matrix, this simple DAE problem can 
+    % become challenging to solve. This problem is introduced in :cite:p:`Asc89` 
+    % to study the convergence of implcit solvers applied to DAEs.
     %
     % Notes
     % -----
@@ -43,10 +44,15 @@
     %
     % Example
     % -------
-    % >>> problem = otp.ascherlineardae.presets.Canonical;
-    % >>> sol = problem.solve();
+    % >>> problem = otp.ascherlineardae.presets.Canonical(0.1);
+    % >>> sol = problem.solve('MaxStep',1e-5);
     % >>> problem.plotPhaseSpace(sol);
-    %
+
+    properties (Access = private, Constant)
+        NumComps = 2
+        VarNames = 'yz'
+    end
+
     methods
         function obj = AscherLinearDAEProblem(timeSpan, y0, parameters)
             % Create an Ascher linear DAE problem object.
@@ -57,12 +63,12 @@
             %    The start and final time.
             % y0 : numeric(2, 1)
             %    The initial conditions.
-            % parameters : BrusselatorParameters
+            % parameters : AscherLinearDAEParameters
             %    The parameters.
             %
             % Returns
             % -------
-            % obj : BrusselatorProblem
+            % obj : AscherLinearDAEProblem
             %    The constructed problem.
             obj@otp.Problem('Ascher Linear DAE', 2, timeSpan, y0, parameters);
         end