Matrix Canonical Structure (MCS) Toolbox for Matlab
Version 0.7

A Matlab toolbox for computing and representing canonical structure information.

(Matlab is registered trademark of The MathWorks, Inc.)

CONTENTS
  - Introduction
  - Installation
  - StratiGraph Connection
  - Compatibility
  - Contact
  - Developers and collaborators


INTRODUCTION

The Matrix Canonical Structure (MCS) Toolbox for Matlab provides a framework
with data type objects for representing canonical structures and computational
functions related to canonical forms. See further the 'Matrix Canonical
Structure Toolbox User's manual' provided with the toolbox, and [DJK13].

Current version supports canonical structures of:

 * Matrices (under similarity, congruence, and *congruence).
 * Matrix pencils G-sH (under equivalence, and symmetric and 
                        skew-symmetric under congruence).
 * System pencils (under feedback-injection equivalence)

      [A B]      [I 0]
      [C D]  - s [0 0]

   corresponding to the state-space system

      dx/dt = Ax(t) + Bu(t), 
          y = Cx(t) + Du(t).

 * Matrix polynomials P(s) = P_d s^d + ... + P_1 + P_0, 
   where P_d ~= 0.

The MCS toolbox includes routines for computing the canonical structure
information using staircase algorithms. These are based on the GUPTRI
(Generalized UPper TRIangular) algorithm [DK93] for matrix pencils. The GUPTRI
form reveals the fine canonical structure information of a matrix pencil. For
example, for a linearized model we can compute its canonical structure and then
let StratiGraph determine and visualize nearby structures in the closure
hierarchy.

The toolbox is based on the prototype Matrix Canonical Structure toolbox
described in [J06], however, the majority of the code has been rewritten and
many of the functions are modified or have been removed.


INSTALLATION

Save the code in desired loaction and add it (and subdirectories) to the Matlab
path.

To avoid problems together with StratiGraph, do not put MCS toolbox in a path
which has a blank space in it.

For the function gsylve for solving the generalized Sylvester matrix equation,
the toolbox includes pre-compiled mex-file for MS Windows. If needed or to run
guptri on Linux or macOS, the included source file guptri/private/gsylve.cpp can
be compiled as shown below. It requires to have a compatible C++ compiler and
Matlab R2018a or higher. Depending on OS, run the appropriate call below in
Matlab.

MS Windows:

> mex -llibmwlapack gsylve.cpp

Linux or macOS:

> mex -lmwlapack gsylve.cpp
 

STRATIGRAPH CONNECTION

There exist interface functions for communicating with the complementary
software StratiGraph. These functions are distributed together with the Matlab
plug-in for StratiGraph. For installation and usage see the README-file in the
StratiGraph distribution.


COMPATIBILITY

For full functionality the toolbox requires Matlab version 9.4 (R2018a) or
later. The requirements for the individual parts are:

Functions        Minimum Matlab version
 Core              7.6 (R2008a)
 Guptri            9.4 (R2018a)
 SG interface      8.2 (R2013b)


CONTACT

For questions and comments please contact: 

  Stefan Johansson, stefanj@cs.umu.se

  Department of Computing Science
  Umeå University
  SE - 901 87 Umeå, Sweden

DEVELOPERS AND COLLABORATORS

MCS Toolbox is developed at the Department of Computing Science, 
Umeå University (Sweden) by the following people.
Programming: Stefan Johansson and partly by Pedher Johansson and Andrii Dmytryshyn.
Scientific contribution: Bo Kågström, Erik Elmroth, Pedher Johansson, 
Stefan Johansson, and Andrii Dmytryshyn.

A Special thanks to our collaborators: 
Alan Edelman (MIT, Massachusetts) and Paul Van Dooren (UCL, Belgium).


REFERENCES

[DK93] J. Demmel and B. Kågström.
    The Generalized Schur Decomposition of an Arbitrary Pencil A - lambda B: 
    Robust Software with Error Bounds and Applications. Part I: Theory and 
    Algorithms and Part II: Software and Applications.
    ACM Trans. Math. Software, Vol.19(2), pp.160-174, 175-201, June 1993.

[DJK13] A. Dmytryshyn, S. Johansson, and B. Kågström.
    Codimension computations of congruence orbits of matrices, symmetric 
    and skew symmetric matrix pencils using Matlab.
    Technical Report UMINF 13.18, Department of Computing Science, 
    Umeå University, Sweden, 2013.

[J06] P. Johansson. 
    Matrix Canonical Structure Toolbox. 
    Technical Report UMINF 06.15, Department of Computing Science, 
    Umeå University, Sweden, 2006.