Skip to content

Commit 06b5fe4

Browse files
murrayrmmurrayrm
committed
DOC: created conventions section in manual + moved doc for time series conventions to a single place
1 parent 4cbd4cb commit 06b5fe4

File tree

4 files changed

+82
-139
lines changed

4 files changed

+82
-139
lines changed

‎control/timeresp.py‎

Lines changed: 5 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,78 +1,12 @@
11
# 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)]]
43-
44-
Same for X, Y
45-
46-
So, U[:,2] is the system's input at the third point in time; and U[1] or U[1,:]
47-
is the sequence of values for the system's second input.
48-
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')
2+
"""Time domain simulation.
673
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::
4+
This file contains a collection of functions that calculate time
5+
responses for linear systems.
726
73-
ft = D * U
7+
See doc/conventions.rst#time-series-conventions_ for more information
8+
on how time series data are represented.
749
75-
----------------------------------------------------------------
7610
"""
7711

7812
"""Copyright (c) 2011 by California Institute of Technology

‎doc/control.rst‎

Lines changed: 0 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -47,74 +47,6 @@ Time domain simulation
4747
step_response
4848
phase_plot
4949

50-
.. _time-series-convention:
51-
52-
Convention for Time Series
53-
--------------------------
54-
55-
This is a convention for function arguments and return values that
56-
represent time series: sequences of values that change over time. It
57-
is used throughout the library, for example in the functions
58-
:func:`forced_response`, :func:`step_response`, :func:`impulse_response`,
59-
and :func:`initial_response`.
60-
61-
.. note::
62-
This convention is different from the convention used in the library
63-
:mod:`scipy.signal`. In Scipy's convention the meaning of rows and columns
64-
is interchanged. Thus, all 2D values must be transposed when they are
65-
used with functions from :mod:`scipy.signal`.
66-
67-
Types:
68-
69-
* **Arguments** can be **arrays**, **matrices**, or **nested lists**.
70-
* **Return values** are **arrays** (not matrices).
71-
72-
The time vector is either 1D, or 2D with shape (1, n)::
73-
74-
T = [[t1, t2, t3, ..., tn ]]
75-
76-
Input, state, and output all follow the same convention. Columns are different
77-
points in time, rows are different components. When there is only one row, a
78-
1D object is accepted or returned, which adds convenience for SISO systems::
79-
80-
U = [[u1(t1), u1(t2), u1(t3), ..., u1(tn)]
81-
[u2(t1), u2(t2), u2(t3), ..., u2(tn)]
82-
...
83-
...
84-
[ui(t1), ui(t2), ui(t3), ..., ui(tn)]]
85-
86-
Same for X, Y
87-
88-
So, U[:,2] is the system's input at the third point in time; and U[1] or U[1,:]
89-
is the sequence of values for the system's second input.
90-
91-
The initial conditions are either 1D, or 2D with shape (j, 1)::
92-
93-
X0 = [[x1]
94-
[x2]
95-
...
96-
...
97-
[xj]]
98-
99-
As all simulation functions return *arrays*, plotting is convenient::
100-
101-
t, y = step(sys)
102-
plot(t, y)
103-
104-
The output of a MIMO system can be plotted like this::
105-
106-
t, y, x = lsim(sys, u, t)
107-
plot(t, y[0], label='y_0')
108-
plot(t, y[1], label='y_1')
109-
110-
The convention also works well with the state space form of linear systems. If
111-
``D`` is the feedthrough *matrix* of a linear system, and ``U`` is its input
112-
(*matrix* or *array*), then the feedthrough part of the system's response,
113-
can be computed like this::
114-
115-
ft = D * U
116-
117-
11850
Block diagram algebra
11951
=====================
12052
.. autosummary::

‎doc/conventions.rst‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
.. _conventions-ref:
2+
3+
###################
4+
Library conventions
5+
###################
6+
7+
The python-control library uses a set of standard conventions for the way
8+
that different types of standard information used by the library.
9+
10+
.. _time-series-convention:
11+
12+
Time series data
13+
================
14+
15+
This is a convention for function arguments and return values that
16+
represent time series: sequences of values that change over time. It
17+
is used throughout the library, for example in the functions
18+
:func:`forced_response`, :func:`step_response`, :func:`impulse_response`,
19+
and :func:`initial_response`.
20+
21+
.. note::
22+
This convention is different from the convention used in the library
23+
:mod:`scipy.signal`. In Scipy's convention the meaning of rows and columns
24+
is interchanged. Thus, all 2D values must be transposed when they are
25+
used with functions from :mod:`scipy.signal`.
26+
27+
Types:
28+
29+
* **Arguments** can be **arrays**, **matrices**, or **nested lists**.
30+
* **Return values** are **arrays** (not matrices).
31+
32+
The time vector is either 1D, or 2D with shape (1, n)::
33+
34+
T = [[t1, t2, t3, ..., tn ]]
35+
36+
Input, state, and output all follow the same convention. Columns are different
37+
points in time, rows are different components. When there is only one row, a
38+
1D object is accepted or returned, which adds convenience for SISO systems::
39+
40+
U = [[u1(t1), u1(t2), u1(t3), ..., u1(tn)]
41+
[u2(t1), u2(t2), u2(t3), ..., u2(tn)]
42+
...
43+
...
44+
[ui(t1), ui(t2), ui(t3), ..., ui(tn)]]
45+
46+
Same for X, Y
47+
48+
So, U[:,2] is the system's input at the third point in time; and U[1] or U[1,:]
49+
is the sequence of values for the system's second input.
50+
51+
The initial conditions are either 1D, or 2D with shape (j, 1)::
52+
53+
X0 = [[x1]
54+
[x2]
55+
...
56+
...
57+
[xj]]
58+
59+
As all simulation functions return *arrays*, plotting is convenient::
60+
61+
t, y = step(sys)
62+
plot(t, y)
63+
64+
The output of a MIMO system can be plotted like this::
65+
66+
t, y, x = lsim(sys, u, t)
67+
plot(t, y[0], label='y_0')
68+
plot(t, y[1], label='y_1')
69+
70+
The convention also works well with the state space form of linear systems. If
71+
``D`` is the feedthrough *matrix* of a linear system, and ``U`` is its input
72+
(*matrix* or *array*), then the feedthrough part of the system's response,
73+
can be computed like this::
74+
75+
ft = D * U
76+

‎doc/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ implements basic operations for analysis and design of feedback control systems.
2626
:maxdepth: 2
2727

2828
intro
29+
conventions
2930
control
3031
classes
3132
matlab

0 commit comments

Comments
 (0)