[python-control-discuss] Major updates from the Princeton group

[Lauren P. <lpa...@pr...>]

Richard and developers,

We are writing this note to discuss the major changes that we, the Princeton group, have made to our internal python-control repository.  We have more or less completed our contribution to the project, and would like to push our changes to the SVN repository.

== Unfinished business ==

- The ss2tf and tf2ss conversions are carried out in SLICOT, wrapped in Slycot, then wrapped in statesp._convertToStateSpace() and xferfcn._convertToTransferFunction().  (As for the user interface, these are then wrapped by tf2ss() and ss2tf(), and finally wrapped by ss() and tf().)  The conversions seem to be buggy sometimes.  This can be seen by running TestConvert.py, which makes a random state space (sys1), converts it to a transfer function (sys2), back to a state space (sys3), and back to a transfer function (sys4).  Sometimes the outputs are correct; other times they are not; and yet other times, our machines enter an infinite loop.  We did not have time to solve this issue completely, so it remains open.
- hsvd() works, but there are better ways to compute the Hankel singular values.  Better algorithms, however, may be substantial and difficult to program.  Also, we did include MATLAB's baldata output.  balred() can return the balancing data.
- balred() does not yet support MatchDC.
- h2syn() and hinfsyn() are implemented, but not yet tested.
- We used Sphinx to create our python-control documentation, as previously discussed on this board.  For the most part, however, we only added Sphinx-style documentation to the functions we worked on directly.  Some of the docstrings in the library should be updated to this format, if it's desirable to continue using Sphinx.
- Plotting MIMO systems has not been implemented.  In the future, we envision the following common interface for most plotting routines (step, bode, impulse, ...):
    1.  return (i,j,k) array where i = # inputs, j = # outputs, k = # frequencies or times
    2.  plot=True optional argument to actually plot instead of just returning values
    3.  squeeze output so that for SISO system, return is not an (i,j,k), but rather a (k,).  
- It may be desirable to have the TransferFunction class represent SISO numerators and denominators as numpy arrays, instead of lists of lists of arrays.  This might be nontrivial to implement.

== LTI Class structure ==

As previously discussed on this board, we decided to remove the use of scipy.signal.lti as a parent class.  Its restriction to SISO and SIMO systems makes it impractical to use.  Therefore, we now have our own structure.  The parent class, "Lti," currently only has two fields and nothing else, but this can be expanded in the future.  "StateSpace" and "TransferFunction" are now child classes of "Lti," and almost have full MIMO functionality.

In addition to implementing this new class structure, the classes themselves have been developed quite a bit.  For instance, both StateSpace.__init__() and TransferFunction.__init__() now have guards to make sure the inputs are valid.  In addition, many (but not all) functions have been expanded to support MIMO.  For instance, almost all of the operator overloads in TransferFunction were completely rewritten to support MIMO; however, __div__() and __rdiv__() are not yet implemented for MIMO.  See the source code for more details.  Functions not completed raise NotImplementedError.

== Slycot ==

We have wrapped five additional SLICOT functions into Slycot.  These Slycot wrappers are used in h2syn(), hinfsyn(), ss2tf(), tf2ss(), and balred().  We are working with Enrico Avventi to merge our changes to his Slycot repository on github. We anticipate some iteration with Enrico before a fully integrated Slycot library is available for download. Until then, we will email a patch and instructions for use by python-control developers and users.
    
== Unit tests ==

The unit tests are packaged, and can be run together using
    >>> import control
    >>> control.tests()

There are a total of nine unit test files (Test*.py).  Most of these should be self-explanatory.  However, these may not be:
    - TestConvert.py: This file is not finished.  Ideally, it would convert random state spaces back and forth between state space and transfer function form, and check that the conversions are correct.  However, the conversions are sometimes buggy (see Unfinished Business below).
    - TestFreqResp.py: This is not a unit test, but can be used to check for errors and exceptions in freqresp.py and matlab.bode().
    - TestSlycot.py: Also not a unit test.  This checks for correct functionality of the ss2tf and tf2ss Slycot wrappers tb04ad and td04ad. 

== Functions implemented ==

This is a brief list of functions we either created or revised significantly.

- StateSpace, TransferFunction
    - As stated above, these two classes were heavily revamped.  In addition to these revisions, we added:
    - __init__(): The initializer can now also act as a copy constructor.  StateSpace(ss_obj) and TransferFunction(tf_obj) perform deep copies.  I believe that Python does not support assignment (=) overloading.  Generally speaking, one should never use
          >>> sys1 = sys2
      since this will be a shallow copy.
    - returnScipySignalLti: scipy.signal.lti is still useful for its few methods.  For a MIMO LTI system, this function returns a list of a list of SISO scipy.signal.lti objects--one object for each element of the MIMO transfer function.  We use this in lsim, step, initial, and impulse.
    - We also added some "private" methods to these two classes.  (E.g., TransferFunction._truncatecoeff(), TransferFunction._common_den(), etc.)  In general, these methods are for bookkeeping and do not affect the interface.
- Random state space generation
    - rss()
    - drss()
    - the generating function _rss_generate()
- Controllability and observability functions
    - gram()
    - obsv()
    - ctrb()
- Model reduction tools
    - modred()
    - hsvd()
    - balred()
    - markov()
- Synthesis tools; these have not been tested
    - h2syn()
    - hinfsyn()
- Plotting tools
    - matlab.bode()
    - freqresp.bode()
    - default_frequency_range()
    - step()
    - impulse()

== Contact ==

If you need to contact us in the future, email us at
- bb...@pr...
- sbr...@pr...
- kk...@pr...
- lpa...@pr...

Happy coding,
Brandt, Steve, Kevin, and Lauren