Skip to content

Commit

Permalink
Improve documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@tobolar
tobolar committed May 15, 2024
1 parent 6216caf commit 211dcd2
Show file tree
Hide file tree
Showing 3 changed files with 96 additions and 47 deletions.
48 changes: 33 additions & 15 deletions Modelica_LinearSystems2/Math/Matrices/Internal/reorderRSF.mo
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
within Modelica_LinearSystems2.Math.Matrices.Internal;
function reorderRSF
"Reorders a real Schur factorization according to a given pattern of the eigenvalues"
"Reorder a real Schur factorization according to a given pattern of the eigenvalues"
extends Modelica.Icons.Function;

input Boolean iscontinuous;
input Real T[:,:];
input Real Q[:,size(T, 2)];
input Real T[:,:] "Upper quasi-triangular matrix in Schur canonical form";
input Real Q[:,size(T, 2)] "Matrix of Schur vectors";
input Real alphaReal[size(T, 1)]
"Real part of eigenvalue=alphaReal+i*alphaImag";
"Real part of eigenvalue = alphaReal + i*alphaImag";
input Real alphaImag[size(T, 1)]
"Imaginary part of eigenvalue=(alphaReal+i*alphaImag";
"Imaginary part of eigenvalue = alphaReal + i*alphaImag";

output Real To[size(T, 1),size(T, 2)];
output Real Qo[size(T, 1),size(T, 2)];
output Real wr[size(T, 2)];
output Real wi[size(T, 2)];
output Real To[size(T, 1),size(T, 2)] "Reordered Schur form";
output Real Qo[size(T, 1),size(T, 2)] "Reordered Schur vectors";
output Real wr[size(T, 2)] "Reordered eigenvalues, real part";
output Real wi[size(T, 2)] "Reordered eigenvalues, imaginary part";

protected
Integer n=size(T, 2);
Expand All @@ -35,11 +35,29 @@ algorithm
end for;
end if;

(To,Qo,wr,wi) := Modelica.Math.Matrices.LAPACK.dtrsen(
"E",
"V",
select,
T,
Q);
(To, Qo, wr, wi) := Modelica.Math.Matrices.LAPACK.dtrsen("E", "V", select, T, Q);

annotation (Documentation(info="<html>
<h4>Syntax</h4>
<blockquote><pre>
(To, Qo, wr, wi) = Matrices.Internal.<strong>reorderRSF</strong>(iscontinuous, T, Q, alphaReal, alphaImag)
</pre></blockquote>
<h4>Description</h4>
<p>
Reorder real Schur form used for pole assignment design for continuous or discrete systems.
For a&nbsp;continuous system (<code>iscontinuous&nbsp;= true</code>), those eigenvalues
of&nbsp;A will not be modified by the eigenvalue assignment algorithm which real part is negative.
For a&nbsp;discrete system (<code>iscontinuous&nbsp;= false</code>), eigenvalues of moduli less
then one will not be modified.
</p>
<h4>See also</h4>
<p>
<a href=\"modelica://Modelica_LinearSystems2.Math.Matrices.Internal.reorderRSFc\">reorderRSFc</a>
for continuous systems or
<a href=\"modelica://Modelica_LinearSystems2.Math.Matrices.Internal.reorderRSFd\">reorderRSFd</a>
for discrete systems.
</p>
</html>"));
end reorderRSF;
48 changes: 32 additions & 16 deletions Modelica_LinearSystems2/Math/Matrices/Internal/reorderRSFc.mo
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
within Modelica_LinearSystems2.Math.Matrices.Internal;
function reorderRSFc
"Reorders a real Schur factorization for poleAssignmentMI design for continuous systems"
"Reorder a real Schur factorization for pole assignment design for continuous systems"
extends Modelica.Icons.Function;

input Real T[:,:] "upper quasi-triangular matrix in Schur canonical form";
input Real Q[:,size(T, 2)] "matrix of Schur vectors";
input Real T[:,:] "Upper quasi-triangular matrix in Schur canonical form";
input Real Q[:,size(T, 2)] "Matrix of Schur vectors";
input Real alphaReal[size(T, 1)]
"Real part of eigenvalue=alphaReal+i*alphaImag";
"Real part of eigenvalue = alphaReal + i*alphaImag";
input Real alphaImag[size(T, 1)]
"Imaginary part of eigenvalue=(alphaReal+i*alphaImag";
"Imaginary part of eigenvalue = alphaReal + i*alphaImag";
input Real alpha
"maximum admissible value for real parts(continuous) or for moduli (discrete) of the eigenvalues of A which will not be modified by the eigenvalue assignment algorithm";
"Maximum admissible value for real parts of the eigenvalues of A which will not be modified by the eigenvalue assignment algorithm";

output Real To[size(T, 1),size(T, 2)];
output Real Qo[size(T, 1),size(T, 2)];
output Real wr[size(T, 2)];
output Real wi[size(T, 2)];
output Real To[size(T, 1),size(T, 2)] "Reordered Schur form";
output Real Qo[size(T, 1),size(T, 2)] "Reordered Schur vectors";
output Real wr[size(T, 2)] "Reordered eigenvalues, real part";
output Real wi[size(T, 2)] "Reordered eigenvalues, imaginary part";

protected
Integer n=size(T, 2);
Expand All @@ -28,11 +28,27 @@ algorithm
end if;
end for;

(To,Qo,wr,wi) := Modelica.Math.Matrices.LAPACK.dtrsen(
"E",
"V",
select,
T,
Q);
(To, Qo, wr, wi) := Modelica.Math.Matrices.LAPACK.dtrsen("E", "V", select, T, Q);

annotation (Documentation(info="<html>
<h4>Syntax</h4>
<blockquote><pre>
(To, Qo, wr, wi) = Matrices.Internal.<strong>reorderRSFc</strong>(T, Q, alphaReal, alphaImag, alpha)
</pre></blockquote>
<h4>Description</h4>
<p>
Reorder real Schur form according to <code>alpha</code>, as used e.g. in
<a href=\"modelica://Modelica_LinearSystems2.StateSpace.Design.assignPolesMI\">assignPolesMI</a>
for <em>continuous</em> systems.
</p>
<h4>See also</h4>
<p>
<a href=\"modelica://Modelica_LinearSystems2.Math.Matrices.Internal.reorderRSF\">reorderRSF</a>
or
<a href=\"modelica://Modelica_LinearSystems2.Math.Matrices.Internal.reorderRSFd\">reorderRSFd</a>
(for discrete systems).
</p>
</html>"));
end reorderRSFc;
47 changes: 31 additions & 16 deletions Modelica_LinearSystems2/Math/Matrices/Internal/reorderRSFd.mo
View file
Original file line number Diff line number Diff line change
@@ -1,21 +1,21 @@
within Modelica_LinearSystems2.Math.Matrices.Internal;
function reorderRSFd
"Reorders a real Schur factorization for poleAssignmentMI design for discrete systems"
"Reorder a real Schur factorization for pole assignment design for discrete systems"
extends Modelica.Icons.Function;

input Real T[:,:] "upper quasi-triangular matrix in Schur canonical form";
input Real Q[:,size(T, 2)] "matrix of Schur vectors";
input Real T[:,:] "Upper quasi-triangular matrix in Schur canonical form";
input Real Q[:,size(T, 2)] "Matrix of Schur vectors";
input Real alphaReal[size(T, 1)]
"Real part of eigenvalue=alphaReal+i*alphaImag";
"Real part of eigenvalue = alphaReal + i*alphaImag";
input Real alphaImag[size(T, 1)]
"Imaginary part of eigenvalue=(alphaReal+i*alphaImag";
"Imaginary part of eigenvalue = alphaReal + i*alphaImag";
input Real alpha
"maximum admissible value for real parts(continuous) or for moduli (discrete) of the eigenvalues of A which will not be modified by the eigenvalue assignment algorithm";
"Maximum admissible value for moduli of the eigenvalues of A which will not be modified by the eigenvalue assignment algorithm";

output Real To[size(T, 1),size(T, 2)];
output Real Qo[size(T, 1),size(T, 2)];
output Real wr[size(T, 2)];
output Real wi[size(T, 2)];
output Real To[size(T, 1),size(T, 2)] "Reordered Schur form";
output Real Qo[size(T, 1),size(T, 2)] "Reordered Schur vectors";
output Real wr[size(T, 2)] "Reordered eigenvalues, real part";
output Real wi[size(T, 2)] "Reordered eigenvalues, imaginary part";

protected
Integer n=size(T, 2);
Expand All @@ -28,11 +28,26 @@ algorithm
end if;
end for;

(To,Qo,wr,wi) := Modelica.Math.Matrices.LAPACK.dtrsen(
"E",
"V",
select,
T,
Q);
(To, Qo, wr, wi) := Modelica.Math.Matrices.LAPACK.dtrsen("E", "V", select, T, Q);

annotation (Documentation(info="<html>
<h4>Syntax</h4>
<blockquote><pre>
(To, Qo, wr, wi) = Matrices.Internal.<strong>reorderRSFd</strong>(T, Q, alphaReal, alphaImag, alpha)
</pre></blockquote>
<h4>Description</h4>
<p>
Reorder real Schur form according to <code>alpha</code>, as used e.g. in
<a href=\"modelica://Modelica_LinearSystems2.DiscreteStateSpace.Design.assignPolesMI\">assignPolesMI</a>
for <em>discrete</em> systems.
</p>
<h4>See also</h4>
<p>
<a href=\"modelica://Modelica_LinearSystems2.Math.Matrices.Internal.reorderRSF\">reorderRSF</a>
or
<a href=\"modelica://Modelica_LinearSystems2.Math.Matrices.Internal.reorderRSFc\">reorderRSFc</a>
(for continuous systems).
</html>"));
end reorderRSFd;

0 comments on commit 211dcd2

Please sign in to comment.