python-control-discuss

[python-control-discuss] Implementation of lsim, step, initial, impulse

[Eike W. <eik...@gm...>]

Hello!

I have written a patch for the Python Control Systems Library with the 
following contents:

* An implementation of the four simulation functions ``lsim``, ``step``, 
``initial``, and ``impulse`` of the module ``matlab``. 

* It also adds a function ``dcgain`` to the ``matlab`` module, which computes 
the gain of a linear system for steady state and constant input.

* The patch contains a bug fix for class ``StateSpace``, which enables it to 
work properly together with Scipy's ``signal`` module. 

* The simulation functions' return values are changed (back?) to arrays, 
because matrices confuse Matplotlib.

http://sourceforge.net/tracker/?func=detail&aid=3301246&group_id=282523&atid=1198311


Would you include my patch into the library? 

What do you think about the parameter convention below? IMHO a detailed 
section that explains the used convention should be included in the module's 
documentation. The documentation of the individual functions should link to 
it. 

What is the proper communication channel for the library's developers?

If you include my patch, my next step would be to extend ``lsim`` to MIMO 
systems (by copying the code from ``scipy.signal.lsim2``); and to convert the 
module's documentation to proper reStructuredText.


Implementation Notes
-------------------

The implementation is centered around ``lsim``, which checks the parameters 
thoroughly, and generates useful error messages. It then calls 
``scipy.signal.lsim2`` to solve the differential equations. The other 
simulation functions (``step``, ``initial``, ``impulse``) are small and call 
``lsim``.


Parameter Convention
--------------------

The new convention for parameters and return values harmonizes with the way 
how the system equations are written. It can be generalized to MIMO systems, 
and it also works well with Matplotlib:

All parameters can be arrays, matrices, or nested lists. 

The time vector is either 1D, or 2D with shape (1, n)::
 
      T = [[t1,     t2,     t3,     ..., tn    ]]  
      
Input, state, and output all follow the same convention. Columns are different 
points in time, rows are different components. When there is only one row, a 
1D object is accepted or returned, which adds convenience for SISO systems::

      U = [[u1(t1), u1(t2), u1(t3), ..., u1(tn)]
           [u2(t1), u2(t2), u2(t3), ..., u2(tn)]
           ...
           ...
           [ui(t1), ui(t2), ui(t3), ..., ui(tn)]]
      
      Same for X, Y

The initial conditions are either 1D, or 2D with shape (j, 1)::

     X0 = [[u1]
           [u2]
           ...
           ...
           [uj]]

So, U[:,2] is the system's input at the third point in time; and U[1] or 
U[1,:] is the sequence of values for the system's second input. 

As all simulation functions return array plotting is convenient::

    t, y = step(sys)
    plot(t, y)

The output of a MIMO system would be plotted like this::

    t, y, x = lsim(sys, u, t)
    plot(t, y[0], label='y_0')
    plot(t, y[1], label='y_1')


Yours,
Eike.

Re: [python-control-discuss] Implementation of lsim, step, initial, impulse

[Richard M. <mu...@cd...>]

Hi Eike.  Thanks for your interest in python-control!

I'll take a look at your patches as soon as possible (developers: if anyone else wants to volunteer, just let me know!).  We have had some discussion about the output formats and have a plan for how to implement that, so might have to sort through some of the changes below if they are not consistent with the current plan (see the discussion list archives for more info).

Will respond to the parameter convention suggestion a bit later (busy few weeks ahead).  I've added you to the discuss list so that we can have a conversation about it.

-richard

On 12 May 2011, at 16:11 , Eike Welk wrote:

> Hello!
> 
> I have written a patch for the Python Control Systems Library with the 
> following contents:
> 
> * An implementation of the four simulation functions ``lsim``, ``step``, 
> ``initial``, and ``impulse`` of the module ``matlab``. 
> 
> * It also adds a function ``dcgain`` to the ``matlab`` module, which computes 
> the gain of a linear system for steady state and constant input.
> 
> * The patch contains a bug fix for class ``StateSpace``, which enables it to 
> work properly together with Scipy's ``signal`` module. 
> 
> * The simulation functions' return values are changed (back?) to arrays, 
> because matrices confuse Matplotlib.
> 
> http://sourceforge.net/tracker/?func=detail&aid=3301246&group_id=282523&atid=1198311
> 
> 
> Would you include my patch into the library? 
> 
> What do you think about the parameter convention below? IMHO a detailed 
> section that explains the used convention should be included in the module's 
> documentation. The documentation of the individual functions should link to 
> it. 
> 
> What is the proper communication channel for the library's developers?
> 
> If you include my patch, my next step would be to extend ``lsim`` to MIMO 
> systems (by copying the code from ``scipy.signal.lsim2``); and to convert the 
> module's documentation to proper reStructuredText.
> 
> 
> Implementation Notes
> -------------------
> 
> The implementation is centered around ``lsim``, which checks the parameters 
> thoroughly, and generates useful error messages. It then calls 
> ``scipy.signal.lsim2`` to solve the differential equations. The other 
> simulation functions (``step``, ``initial``, ``impulse``) are small and call 
> ``lsim``.
> 
> 
> Parameter Convention
> --------------------
> 
> The new convention for parameters and return values harmonizes with the way 
> how the system equations are written. It can be generalized to MIMO systems, 
> and it also works well with Matplotlib:
> 
> All parameters can be arrays, matrices, or nested lists. 
> 
> The time vector is either 1D, or 2D with shape (1, n)::
> 
>      T = [[t1,     t2,     t3,     ..., tn    ]]  
> 
> Input, state, and output all follow the same convention. Columns are different 
> points in time, rows are different components. When there is only one row, a 
> 1D object is accepted or returned, which adds convenience for SISO systems::
> 
>      U = [[u1(t1), u1(t2), u1(t3), ..., u1(tn)]
>           [u2(t1), u2(t2), u2(t3), ..., u2(tn)]
>           ...
>           ...
>           [ui(t1), ui(t2), ui(t3), ..., ui(tn)]]
> 
>      Same for X, Y
> 
> The initial conditions are either 1D, or 2D with shape (j, 1)::
> 
>     X0 = [[u1]
>           [u2]
>           ...
>           ...
>           [uj]]
> 
> So, U[:,2] is the system's input at the third point in time; and U[1] or 
> U[1,:] is the sequence of values for the system's second input. 
> 
> As all simulation functions return array plotting is convenient::
> 
>    t, y = step(sys)
>    plot(t, y)
> 
> The output of a MIMO system would be plotted like this::
> 
>    t, y, x = lsim(sys, u, t)
>    plot(t, y[0], label='y_0')
>    plot(t, y[1], label='y_1')
> 
> 
> Yours,
> Eike.
> <make-matlab-work.patch>

Re: [python-control-discuss] Implementation of lsim, step, initial, impulse

[Eike W. <eik...@gm...>]

I've created a new patch, that adds MIMO capabilities to the ``matlab`` 
module.

https://sourceforge.net/tracker/?func=detail&aid=3315485&group_id=282523&atid=1198311

I'm doing the development in a separate Mercurial repository:
https://bitbucket.org/eike_welk/python-control/

Re: [python-control-discuss] Implementation of lsim, step, initial, impulse

[Richard M. <mu...@cd...>]

Thanks, Eike!  I am just finishing up a busy term and hope to put some time into python-control over the next several weeks.  Getting MIMO functionality in is a great boost.

-richard

On 12 Jun 2011, at 10:05 , Eike Welk wrote:

> I've created a new patch, that adds MIMO capabilities to the ``matlab`` 
> module.
> 
> https://sourceforge.net/tracker/?func=detail&aid=3315485&group_id=282523&atid=1198311
> 
> I'm doing the development in a separate Mercurial repository:
> https://bitbucket.org/eike_welk/python-control/
> 
> ------------------------------------------------------------------------------
> EditLive Enterprise is the world's most technically advanced content
> authoring tool. Experience the power of Track Changes, Inline Image
> Editing and ensure content is compliant with Accessibility Checking.
> http://p.sf.net/sfu/ephox-dev2dev
> _______________________________________________
> python-control-discuss mailing list
> pyt...@li...
> https://lists.sourceforge.net/lists/listinfo/python-control-discuss

Re: [python-control-discuss] Implementation of lsim, step, initial, impulse

[Richard M. <mu...@cd...>]

Eike,

I'm working on integrating some of the functionality that you contributed to the python-control package.  Your new convention for simulation inputs and outputs has a lot of nice features, but it does "break" current code (eg, try running examples/pvtol-nested.py).  In addition, it is not compatible with the way MATLAB or scipy.signal does things, which could be confusing.

As a general principle, I think that if a user imports control.matlab, they should get as MATLAB like an environment as possible (since control.matlab is the MATLAB emulation module in the package).  However, I see now reason why we need to maintain MATLAB compatibility within the underlying library itself, where we can do things in a more python-like way.  But breaking the convention used by scipy.signal could get confusing...

Here is one possible fix:

* We move your current lsim, initial, step and impulse code into a separate module (timesim.py or something) in the control-python package.  

* We create version of the code in matlab.py that convert the arguments from MATLAB (and scipy.signal) form into the form you use, and back.

* In addition, we could include a flag in all of the simulation routines that let them swap around the convention if the flag was turned out (eg, 'scipy-signal-convention = true' would make things work in the way that is compatible with the signal module).

This approach has the advantage that we get a pretty clean interface for python users, but something that is consistent with MATLAB in the emulation library.  On the other hand, it could be incredibly confusing for people who use both interfaces.

Let me know what you think about this (others on the list as well).  If we do decide to switch the way time series are represented from the current version, we would have to update the version number to something like 0.5a (instead of 0.4d) since we would be breaking existing code.

-richard

On 12 May 2011, at 16:11 , Eike Welk wrote:

> Hello!
> 
> I have written a patch for the Python Control Systems Library with the 
> following contents:
> 
> * An implementation of the four simulation functions ``lsim``, ``step``, 
> ``initial``, and ``impulse`` of the module ``matlab``. 
> 
> * It also adds a function ``dcgain`` to the ``matlab`` module, which computes 
> the gain of a linear system for steady state and constant input.
> 
> * The patch contains a bug fix for class ``StateSpace``, which enables it to 
> work properly together with Scipy's ``signal`` module. 
> 
> * The simulation functions' return values are changed (back?) to arrays, 
> because matrices confuse Matplotlib.
> 
> http://sourceforge.net/tracker/?func=detail&aid=3301246&group_id=282523&atid=1198311
> 
> 
> Would you include my patch into the library? 
> 
> What do you think about the parameter convention below? IMHO a detailed 
> section that explains the used convention should be included in the module's 
> documentation. The documentation of the individual functions should link to 
> it. 
> 
> What is the proper communication channel for the library's developers?
> 
> If you include my patch, my next step would be to extend ``lsim`` to MIMO 
> systems (by copying the code from ``scipy.signal.lsim2``); and to convert the 
> module's documentation to proper reStructuredText.
> 
> 
> Implementation Notes
> -------------------
> 
> The implementation is centered around ``lsim``, which checks the parameters 
> thoroughly, and generates useful error messages. It then calls 
> ``scipy.signal.lsim2`` to solve the differential equations. The other 
> simulation functions (``step``, ``initial``, ``impulse``) are small and call 
> ``lsim``.
> 
> 
> Parameter Convention
> --------------------
> 
> The new convention for parameters and return values harmonizes with the way 
> how the system equations are written. It can be generalized to MIMO systems, 
> and it also works well with Matplotlib:
> 
> All parameters can be arrays, matrices, or nested lists. 
> 
> The time vector is either 1D, or 2D with shape (1, n)::
> 
>      T = [[t1,     t2,     t3,     ..., tn    ]]  
> 
> Input, state, and output all follow the same convention. Columns are different 
> points in time, rows are different components. When there is only one row, a 
> 1D object is accepted or returned, which adds convenience for SISO systems::
> 
>      U = [[u1(t1), u1(t2), u1(t3), ..., u1(tn)]
>           [u2(t1), u2(t2), u2(t3), ..., u2(tn)]
>           ...
>           ...
>           [ui(t1), ui(t2), ui(t3), ..., ui(tn)]]
> 
>      Same for X, Y
> 
> The initial conditions are either 1D, or 2D with shape (j, 1)::
> 
>     X0 = [[u1]
>           [u2]
>           ...
>           ...
>           [uj]]
> 
> So, U[:,2] is the system's input at the third point in time; and U[1] or 
> U[1,:] is the sequence of values for the system's second input. 
> 
> As all simulation functions return array plotting is convenient::
> 
>    t, y = step(sys)
>    plot(t, y)
> 
> The output of a MIMO system would be plotted like this::
> 
>    t, y, x = lsim(sys, u, t)
>    plot(t, y[0], label='y_0')
>    plot(t, y[1], label='y_1')
> 
> 
> Yours,
> Eike.
> <make-matlab-work.patch>

Re: [python-control-discuss] Implementation of lsim, step, initial, impulse

[Richard M. <mu...@cd...>]

Hi Eike.  Thanks for the comments.  I'm cc'ing the discussion list since it would be useful to get the perspective of others as well before making a final decision.  

I agree that the default behavior should be something that is well thought out and consistent.  Then the question is whether in cases where that conflicts with MATLAB, we provide any sort of support for the MATLAB convention.

-richard

On 18 Jun 2011, at 17:24 , Eike Welk wrote:

> Hello Richard!
> 
> On Saturday 18.06.2011 03:02:07 you wrote:
>> Eike,
>> 
>> I'm working on integrating some of the functionality that you contributed
>> to the python-control package.  Your new convention for simulation inputs
>> and outputs has a lot of nice features, but it does "break" current code
>> (eg, try running examples/pvtol-nested.py).  In addition, it is not
>> compatible with the way MATLAB or scipy.signal does things, which could be
>> confusing.
> 
> You should devise a convention, and I'll convert my code to this convention.
> 
> A good alternative IMHO would be to transpose all matrices of my convention. 
> This is compatible to Matlab's ``lsim`` and ``scipy.integrate.odeint``. Also 
> Matplotlib is OK with it, if it's done right.
> 
> I personally don't like to use matrices as return values for ``lsim``, because 
> of their confusing behavior. Also you usually don't do linear algebra with a 
> time series of values. On the other hand, the users (who are probably not 
> experienced programmers) might be confused if they have to consider different 
> data types (matrices and arrays). 
> 
> But make sure, that simple things are simple. For example this should work:
> 
>>>> t, y = step(sys)
>>>> plot(t, y)
> 
> For the compatibility of matrices with Matplotlib see:
> 
> #This works:
> In [7]: t1 = array([1, 2, 3])
> 
> In [8]: t2 = matrix('1; 2; 3')
> 
> In [9]: y = matrix('1; 4; 9')
> 
> In [10]: plot(t1, y)
> Out[10]: [<matplotlib.lines.Line2D object at 0x26d3d90>]
> 
> In [11]: plot(t2, y)
> Out[11]: [<matplotlib.lines.Line2D object at 0x26de850>]
> 
> 
> #But this results in a ``ValueError``:
> In [12]: t3 = matrix('1, 2, 3')
> 
> In [13]: plot(t3, y)
> 
> 
>> 
>> As a general principle, I think that if a user imports control.matlab, they
>> should get as MATLAB like an environment as possible (since control.matlab
>> is the MATLAB emulation module in the package).  However, I see now reason
>> why we need to maintain MATLAB compatibility within the underlying library
>> itself, where we can do things in a more python-like way.  But breaking
>> the convention used by scipy.signal could get confusing...
> 
> Trying to emulate Matlab closely is IMHO unnecessary, and also impossible. You 
> will never get the elegance of Matlab, since the language is optimized for its 
> specific task. 
> 
> Especially: 
> * Python has no ``.*`` operator. 
> * Python functions don't know how many return values are requested.
> 
> I think the functions should have the same names as in Matlab, so that Matlab 
> users can quickly find the functionality that they need. The arguments need 
> only to be roughly equivalent. For details, the users should be educated to 
> type ``function_name?`` in IPython, or to look at the documentation website.
> 
> Instead of closely emulating Matlab you should strive for a consistent user 
> interface, and good integration with the rest of Numpy, Scipy and Matplotlib.
> 
>> 
>> Here is one possible fix:
>> 
> ...
> ...
>> Let me know what you think about this (others on the list as well).  If we
>> do decide to switch the way time series are represented from the current
>> version, we would have to update the version number to something like 0.5a
>> (instead of 0.4d) since we would be breaking existing code.
> 
> Just tell me how you think it would be best, and I'll port it to this form. A 
> library of incongruous  parts, is IMHO less useful than a parameter 
> convention, that I find somewhat impractical.
> 
> There don't seem to be many users currently, so breaking the interface should 
> be not very problematic.
> 
> I have an other patch, that converts big part of the module documentation to 
> proper Sphinx markup, so that you can soon put the generated documentation on 
> a server. Something which I find very important. 
> 
> 
> Yours,
> Eike.