Add docs to linear problem (#128)

Author: Steven-Roberts

docs/conf.py

@@ -32,6 +32,16 @@
     'show-inheritance': True
 }
 
+mathjax3_config = {
+    'tex': {
+        'macros': {
+            'diag': ['\\operatorname{diag}']
+        }
+    }
+}
+
+myst_heading_anchors = 2
+
 bibtex_bibfiles = ['references.bib']
 
 html_theme = 'sphinx_rtd_theme'

toolbox/+otp/+linear/+presets/Alpha.m

@@ -1,8 +1,27 @@
 classdef Alpha < otp.linear.LinearProblem
-    %ALPHA
+    % A diagonal linear preset with eigenvalues logarithmically spaced between distances $r_{min}$ and $r_{max}$ from
+    % the origin at an angle $α$ measured in degrees clockwise from the negative real axis. It can be used to check for
+    % $A(α)$ stability of a time integration scheme. This preset uses $t ∈ [0, 1]$, $y_0 = [1, 1, …, 1]^T$, and
     %
+    % $$
+    % Λ_1 &= \diag(-r_1 e^{-i π α / 180}, -r_2 e^{-i π α / 180}, …, -r_N e^{-i π α / 180}), \\
+    % r_j &= r_{min}^{\frac{N - j}{N - 1}} r_{max}^{\frac{j - 1}{N - 1}}.
+    % $$
+
     methods
         function obj = Alpha(varargin)
+            % Create the alpha linear problem object.
+            %
+            % Parameters
+            % ----------
+            % varargin
+            %    A variable number of name-value pairs. The accepted names are
+            %
+            %    - ``Alpha`` – The angle $α$ measured in degrees clockwise from the negative real axis.
+            %    - ``N`` – The number of eigenvalues $N$.
+            %    - ``Range`` – The range $[r_{min}, r_{max}]$ of the eigenvalues.
+            %    - ``Sparse`` – If true, the matrix will be in sparse format. Otherwise, it will be dense.
+
             p = inputParser();
             p.addParameter('Alpha', 0);
             p.addParameter('N', 10);

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

@@ -1,6 +1,17 @@
 classdef Canonical < otp.linear.LinearProblem
+    % A scalar linear preset with $t ∈ [0, 1]$, $y_0 = 1$, and $Λ_1 = -1$.
+
     methods
         function obj = Canonical(varargin)
+            % Create the canonical linear problem object.
+            %
+            % Parameters
+            % ----------
+            % varargin
+            %    A variable number of name-value pairs. The accepted names are
+            %
+            %    - ``Lambda`` – Cell array of matrices for each partition $Λ_i y$.
+
             params = otp.linear.LinearParameters('Lambda', {-1}, varargin{:});
             tspan = [0, 1];
             y0 = ones(size(params.Lambda{1}, 1), 1);

toolbox/+otp/+linear/LinearParameters.m

@@ -2,7 +2,7 @@
     % Parameters for the linear problem.
 
     properties
-        %LAMBDA is a cell array of same size inputs
+        % A cell array of matrices for each partition $Λ_i y$.
         Lambda %MATLAB ONLY: {mustBeNonempty, otp.utils.validation.mustBeNumericalCell} = {-1}
     end
 

toolbox/+otp/+linear/LinearProblem.m

@@ -1,14 +1,56 @@
 classdef LinearProblem < otp.Problem
+    % A linear, constant coefficient, homogeneous ODE which supports a partitioned right-hand side.
+    %
+    % The linear problem is given by
+    %
+    % $$
+    % y' = \sum_{i=1}^{p} Λ_i y,
+    % $$
+    %
+    % where $p$ is the number of partitions and $Λ_i ∈ ℂ^{N × N}$ for $i = 1, …, p$.
+    % 
+    % This is often used to assess the stability of time integration methods, with the case of $p = N = 1$ referred to
+    % as the Dahlquist test problem.
+    %
+    % Notes
+    % -----
+    % +---------------------+----------------------------------------------------------------+
+    % | Type                | ODE                                                            |
+    % +---------------------+----------------------------------------------------------------+
+    % | Number of Variables | arbitrary                                                      |
+    % +---------------------+----------------------------------------------------------------+
+    % | Stiff               | possibly, depending on the eigenvalues of $\sum_{i=1}^{p} Λ_i$ |
+    % +---------------------+----------------------------------------------------------------+
+    %
+    % Example
+    % -------
+    % >>> problem = otp.linear.presets.Canonical('Lambda', {-1, -2, -3});
+    % >>> problem.RHSPartitions{2}.JacobianMatrix
+    % ans = -2
+
     properties (SetAccess = private)
-       RHSPartitions
+        % A cell array of $p$ right-hand sides for each partition $Λ_i y$.
+        RHSPartitions
     end
 
     properties (Dependent)
+        % The number of partitions $p$.
         NumPartitions
     end
 
     methods
         function obj = LinearProblem(timeSpan, y0, parameters)
+            % Create a linear problem object.
+            %
+            % Parameters
+            % ----------
+            % timeSpan : numeric(1, 2)
+            %    The start and final time.
+            % y0 : numeric(:, 1)
+            %    The initial conditions.
+            % parameters : LinearParameters
+            %    The parameters.
+            
             obj@otp.Problem('Linear', [], timeSpan, y0, parameters);
         end