From 90d4c58335f6225623de85afcdc317f57154f6fe Mon Sep 17 00:00:00 2001 From: Steven Roberts Date: Sat, 20 Apr 2024 22:19:08 -0700 Subject: [PATCH] Add docs to linear problem (#128) --- docs/conf.py | 10 ++++++ toolbox/+otp/+linear/+presets/Alpha.m | 21 ++++++++++- toolbox/+otp/+linear/+presets/Canonical.m | 11 ++++++ toolbox/+otp/+linear/LinearParameters.m | 2 +- toolbox/+otp/+linear/LinearProblem.m | 44 ++++++++++++++++++++++- 5 files changed, 85 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 3e1c771a..4a0f0304 100644 --- a/docs/conf.py +++ b/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' diff --git a/toolbox/+otp/+linear/+presets/Alpha.m b/toolbox/+otp/+linear/+presets/Alpha.m index c17382ba..24205042 100644 --- a/toolbox/+otp/+linear/+presets/Alpha.m +++ b/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); diff --git a/toolbox/+otp/+linear/+presets/Canonical.m b/toolbox/+otp/+linear/+presets/Canonical.m index 8e3fa8f4..5478d644 100644 --- a/toolbox/+otp/+linear/+presets/Canonical.m +++ b/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); diff --git a/toolbox/+otp/+linear/LinearParameters.m b/toolbox/+otp/+linear/LinearParameters.m index 53f77788..17881a65 100644 --- a/toolbox/+otp/+linear/LinearParameters.m +++ b/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 diff --git a/toolbox/+otp/+linear/LinearProblem.m b/toolbox/+otp/+linear/LinearProblem.m index 26a876da..e4f65f90 100644 --- a/toolbox/+otp/+linear/LinearProblem.m +++ b/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