|
1 | 1 | # timeresp.py - time-domain simulation routes |
2 | | -""" |
3 | | -Time domain simulation. |
4 | | -
|
5 | | -This file contains a collection of functions that calculate |
6 | | -time responses for linear systems. |
7 | | -
|
8 | | -.. _time-series-convention: |
9 | | -
|
10 | | -Convention for Time Series |
11 | | --------------------------- |
12 | | -
|
13 | | -This is a convention for function arguments and return values that |
14 | | -represent time series: sequences of values that change over time. It |
15 | | -is used throughout the library, for example in the functions |
16 | | -:func:`forced_response`, :func:`step_response`, :func:`impulse_response`, |
17 | | -and :func:`initial_response`. |
18 | | -
|
19 | | -.. note:: |
20 | | - This convention is different from the convention used in the library |
21 | | - :mod:`scipy.signal`. In Scipy's convention the meaning of rows and columns |
22 | | - is interchanged. Thus, all 2D values must be transposed when they are |
23 | | - used with functions from :mod:`scipy.signal`. |
24 | | -
|
25 | | -Types: |
26 | | -
|
27 | | - * **Arguments** can be **arrays**, **matrices**, or **nested lists**. |
28 | | - * **Return values** are **arrays** (not matrices). |
29 | | -
|
30 | | -The time vector is either 1D, or 2D with shape (1, n):: |
31 | | -
|
32 | | - T = [[t1, t2, t3, ..., tn ]] |
33 | | -
|
34 | | -Input, state, and output all follow the same convention. Columns are different |
35 | | -points in time, rows are different components. When there is only one row, a |
36 | | -1D object is accepted or returned, which adds convenience for SISO systems:: |
37 | | -
|
38 | | - U = [[u1(t1), u1(t2), u1(t3), ..., u1(tn)] |
39 | | - [u2(t1), u2(t2), u2(t3), ..., u2(tn)] |
40 | | - ... |
41 | | - ... |
42 | | - [ui(t1), ui(t2), ui(t3), ..., ui(tn)]] |
| 2 | +"""Time domain simulation. |
43 | 3 |
|
44 | | - Same for X, Y |
| 4 | +This file contains a collection of functions that calculate time |
| 5 | +responses for linear systems. |
45 | 6 |
|
46 | | -So, U[:,2] is the system's input at the third point intime; and U[1] or U[1,:] |
47 | | -is the sequence of values for the system's second input. |
| 7 | +See doc/conventions.rst#time-series-conventions_ for more information |
| 8 | +on how time series data are represented. |
48 | 9 |
|
49 | | -The initial conditions are either 1D, or 2D with shape (j, 1):: |
50 | | -
|
51 | | - X0 = [[x1] |
52 | | - [x2] |
53 | | - ... |
54 | | - ... |
55 | | - [xj]] |
56 | | -
|
57 | | -As all simulation functions return *arrays*, plotting is convenient:: |
58 | | -
|
59 | | - t, y = step(sys) |
60 | | - plot(t, y) |
61 | | -
|
62 | | -The output of a MIMO system can be plotted like this:: |
63 | | -
|
64 | | - t, y, x = lsim(sys, u, t) |
65 | | - plot(t, y[0], label='y_0') |
66 | | - plot(t, y[1], label='y_1') |
67 | | -
|
68 | | -The convention also works well with the state space form of linear systems. If |
69 | | -``D`` is the feedthrough *matrix* of a linear system, and ``U`` is its input |
70 | | -(*matrix* or *array*), then the feedthrough part of the system's response, |
71 | | -can be computed like this:: |
72 | | -
|
73 | | - ft = D * U |
74 | | -
|
75 | | ----------------------------------------------------------------- |
76 | 10 | """ |
77 | 11 |
|
78 | 12 | """Copyright (c) 2011 by California Institute of Technology |
@@ -453,6 +387,9 @@ def step_response(sys, T=None, X0=0., input=None, output=None, |
453 | 387 | If True, transpose all input and output arrays (for backward |
454 | 388 | compatibility with MATLAB and scipy.signal.lsim) |
455 | 389 |
|
| 390 | + return_x: bool |
| 391 | + If True, return the state vector (default = False). |
| 392 | +
|
456 | 393 | Returns |
457 | 394 | ------- |
458 | 395 | T: array |
@@ -529,6 +466,9 @@ def initial_response(sys, T=None, X0=0., input=0, output=None, |
529 | 466 | If True, transpose all input and output arrays (for backward |
530 | 467 | compatibility with MATLAB and scipy.signal.lsim) |
531 | 468 |
|
| 469 | + return_x: bool |
| 470 | + If True, return the state vector (default = False). |
| 471 | +
|
532 | 472 | Returns |
533 | 473 | ------- |
534 | 474 | T: array |
@@ -599,6 +539,9 @@ def impulse_response(sys, T=None, X0=0., input=0, output=None, |
599 | 539 | If True, transpose all input and output arrays (for backward |
600 | 540 | compatibility with MATLAB and scipy.signal.lsim) |
601 | 541 |
|
| 542 | + return_x: bool |
| 543 | + If True, return the state vector (default = False). |
| 544 | +
|
602 | 545 | Returns |
603 | 546 | ------- |
604 | 547 | T: array |
|