Skip to content

Commit 1ca9dec

Browse files
sawyerbfullerbnavigator
sawyerbfuller
authored and
bnavigator
committed
fixes to docstrings and conventions.rst to match convention of dt=0 as default system timebase
1 parent 0223b82 commit 1ca9dec

5 files changed

Lines changed: 101 additions & 82 deletions

File tree

‎control/dtime.py‎

Lines changed: 33 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -53,21 +53,19 @@
5353

5454
# Sample a continuous time system
5555
def sample_system(sysc, Ts, method='zoh', alpha=None, prewarp_frequency=None):
56-
"""Convert a continuous time system to discrete time
57-
58-
Creates a discrete time system from a continuous time system by
59-
sampling. Multiple methods of conversion are supported.
56+
"""
57+
Convert a continuous time system to discrete time by sampling
6058
6159
Parameters
6260
----------
63-
sysc : linsys
61+
sysc : LTI (StateSpace or TransferFunction)
6462
Continuous time system to be converted
65-
Ts : real
63+
Ts : real > 0
6664
Sampling period
6765
method : string
68-
Method to use for conversion: 'matched', 'tustin', 'zoh' (default)
66+
Method to use for conversion, e.g. 'bilinear', 'zoh' (default)
6967
70-
prewarp_frequency : float within [0, infinity)
68+
prewarp_frequency : real within [0, infinity)
7169
The frequency [rad/s] at which to match with the input continuous-
7270
time system's magnitude and phase
7371
@@ -78,13 +76,13 @@ def sample_system(sysc, Ts, method='zoh', alpha=None, prewarp_frequency=None):
7876
7977
Notes
8078
-----
81-
See `TransferFunction.sample` and `StateSpace.sample` for
79+
See :meth:`StateSpace.sample` or :meth:`TransferFunction.sample`` for
8280
further details.
8381
8482
Examples
8583
--------
8684
>>> sysc = TransferFunction([1], [1, 2, 1])
87-
>>> sysd = sample_system(sysc, 1, method='matched')
85+
>>> sysd = sample_system(sysc, 1, method='bilinear')
8886
"""
8987

9088
# Make sure we have a continuous time system
@@ -95,35 +93,39 @@ def sample_system(sysc, Ts, method='zoh', alpha=None, prewarp_frequency=None):
9593

9694

9795
def c2d(sysc, Ts, method='zoh', prewarp_frequency=None):
98-
'''
99-
Return a discrete-time system
96+
"""
97+
Convert a continuous time system to discrete time by sampling
10098
10199
Parameters
102100
----------
103-
sysc: LTI (StateSpace or TransferFunction), continuous
104-
System to be converted
101+
sysc : LTI (StateSpace or TransferFunction)
102+
Continuous time system to be converted
103+
Ts : real > 0
104+
Sampling period
105+
method : string
106+
Method to use for conversion, e.g. 'bilinear', 'zoh' (default)
105107
106-
Ts: number
107-
Sample time for the conversion
108+
prewarp_frequency : real within [0, infinity)
109+
The frequency [rad/s] at which to match with the input continuous-
110+
time system's magnitude and phase
108111
109-
method: string, optional
110-
Method to be applied,
111-
'zoh' Zero-order hold on the inputs (default)
112-
'foh' First-order hold, currently not implemented
113-
'impulse' Impulse-invariant discretization, currently not implemented
114-
'tustin' Bilinear (Tustin) approximation, only SISO
115-
'matched' Matched pole-zero method, only SISO
112+
Returns
113+
-------
114+
sysd : linsys
115+
Discrete time system, with sampling rate Ts
116+
117+
Notes
118+
-----
119+
See :meth:`StateSpace.sample` or :meth:`TransferFunction.sample`` for
120+
further details.
116121
117-
prewarp_frequency : float within [0, infinity)
118-
The frequency [rad/s] at which to match with the input continuous-
119-
time system's magnitude and phase
122+
Examples
123+
--------
124+
>>> sysc = TransferFunction([1], [1, 2, 1])
125+
>>> sysd = sample_system(sysc, 1, method='bilinear')
126+
"""
120127

121-
'''
122128
# Call the sample_system() function to do the work
123129
sysd = sample_system(sysc, Ts, method, prewarp_frequency)
124130

125-
# TODO: is this check needed? If sysc is StateSpace, sysd is too?
126-
if isinstance(sysc, StateSpace) and not isinstance(sysd, StateSpace):
127-
return _convertToStateSpace(sysd) # pragma: no cover
128-
129131
return sysd

‎control/iosys.py‎

Lines changed: 26 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -72,9 +72,11 @@ class for a set of subclasses that are used to implement specific
7272
states : int, list of str, or None
7373
Description of the system states. Same format as `inputs`.
7474
dt : None, True or float, optional
75-
System timebase. None (default) indicates continuous time, True
76-
indicates discrete time with undefined sampling time, positive number
77-
is discrete time with specified sampling time.
75+
System timebase. 0 (default) indicates continuous
76+
time, True indicates discrete time with unspecified sampling
77+
time, positive number is discrete time with specified
78+
sampling time, None indicates unspecified timebase (either
79+
continuous or discrete time).
7880
params : dict, optional
7981
Parameter values for the systems. Passed to the evaluation functions
8082
for the system as default values, overriding internal defaults.
@@ -90,9 +92,11 @@ class for a set of subclasses that are used to implement specific
9092
Dictionary of signal names for the inputs, outputs and states and the
9193
index of the corresponding array
9294
dt : None, True or float
93-
System timebase. None (default) indicates continuous time, True
94-
indicates discrete time with undefined sampling time, positive number
95-
is discrete time with specified sampling time.
95+
System timebase. 0 (default) indicates continuous
96+
time, True indicates discrete time with unspecified sampling
97+
time, positive number is discrete time with specified
98+
sampling time, None indicates unspecified timebase (either
99+
continuous or discrete time).
96100
params : dict, optional
97101
Parameter values for the systems. Passed to the evaluation functions
98102
for the system as default values, overriding internal defaults.
@@ -146,10 +150,11 @@ def __init__(self, inputs=None, outputs=None, states=None, params={},
146150
states : int, list of str, or None
147151
Description of the system states. Same format as `inputs`.
148152
dt : None, True or float, optional
149-
System timebase. None (default) indicates continuous
150-
time, True indicates discrete time with undefined sampling
153+
System timebase. 0 (default) indicates continuous
154+
time, True indicates discrete time with unspecified sampling
151155
time, positive number is discrete time with specified
152-
sampling time.
156+
sampling time, None indicates unspecified timebase (either
157+
continuous or discrete time).
153158
params : dict, optional
154159
Parameter values for the systems. Passed to the evaluation
155160
functions for the system as default values, overriding internal
@@ -584,10 +589,11 @@ def __init__(self, linsys, inputs=None, outputs=None, states=None,
584589
states : int, list of str, or None, optional
585590
Description of the system states. Same format as `inputs`.
586591
dt : None, True or float, optional
587-
System timebase. None (default) indicates continuous
588-
time, True indicates discrete time with undefined sampling
592+
System timebase. 0 (default) indicates continuous
593+
time, True indicates discrete time with unspecified sampling
589594
time, positive number is discrete time with specified
590-
sampling time.
595+
sampling time, None indicates unspecified timebase (either
596+
continuous or discrete time).
591597
params : dict, optional
592598
Parameter values for the systems. Passed to the evaluation
593599
functions for the system as default values, overriding internal
@@ -707,10 +713,10 @@ def __init__(self, updfcn, outfcn=None, inputs=None, outputs=None,
707713
operating in continuous or discrete time. It can have the
708714
following values:
709715
710-
* dt = None No timebase specified
711-
* dt = 0 Continuous time system
712-
* dt > 0 Discrete time system with sampling time dt
713-
* dt = True Discrete time with unspecified sampling time
716+
* dt = 0: continuous time system (default)
717+
* dt > 0: discrete time system with sampling period 'dt'
718+
* dt = True: discrete time with unspecified sampling period
719+
* dt = None: no timebase specified
714720
715721
name : string, optional
716722
System name (used for specifying signals). If unspecified, a generic
@@ -877,10 +883,10 @@ def __init__(self, syslist, connections=[], inplist=[], outlist=[],
877883
operating in continuous or discrete time. It can have the
878884
following values:
879885
880-
* dt = None No timebase specified
881-
* dt = 0 Continuous time system
882-
* dt > 0 Discrete time system with sampling time dt
883-
* dt = True Discrete time with unspecified sampling time
886+
* dt = 0: continuous time system (default)
887+
* dt > 0: discrete time system with sampling period 'dt'
888+
* dt = True: discrete time with unspecified sampling period
889+
* dt = None: no timebase specified
884890
885891
name : string, optional
886892
System name (used for specifying signals). If unspecified, a generic

‎control/statesp.py‎

Lines changed: 17 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -148,15 +148,22 @@ class StateSpace(LTI):
148148
`numpy.ndarray` objects. The :func:`~control.use_numpy_matrix` function
149149
can be used to set the storage type.
150150
151-
Discrete-time state space system are implemented by using the 'dt'
152-
instance variable and setting it to the sampling period. If 'dt' is not
153-
None, then it must match whenever two state space systems are combined.
154-
Setting dt = 0 specifies a continuous system, while leaving dt = None
155-
means the system timebase is not specified. If 'dt' is set to True, the
156-
system will be treated as a discrete time system with unspecified sampling
157-
time. The default value of 'dt' is 0 and can be changed by changing the
158-
value of ``control.config.defaults['control.default_dt']``.
159-
151+
A discrete time system is created by specifying a nonzero 'timebase', dt
152+
when the system is constructed:
153+
154+
* dt = 0: continuous time system (default)
155+
* dt > 0: discrete time system with sampling period 'dt'
156+
* dt = True: discrete time with unspecified sampling period
157+
* dt = None: no timebase specified
158+
159+
Systems must have compatible timebases in order to be combined. A discrete
160+
time system with unspecified sampling time (`dt = True`) can be combined
161+
with a system having a specified sampling time; the result will be a
162+
discrete time system with the sample time of the latter system. Similarly,
163+
a system with timebase `None` can be combined with a system having any
164+
timebase; the result will have the timebase of the latter system.
165+
The default value of dt can be changed by changing the value of
166+
``control.config.defaults['control.default_dt']``.
160167
"""
161168

162169
# Allow ndarray * StateSpace to give StateSpace._rmul_() priority
@@ -1317,8 +1324,7 @@ def ss(*args):
13171324
Output matrix
13181325
D: array_like or string
13191326
Feed forward matrix
1320-
dt: If present, specifies the sampling period and a discrete time
1321-
system is created
1327+
dt: If present, specifies the timebase of the system
13221328
13231329
Returns
13241330
-------

‎control/xferfcn.py‎

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,6 @@
7373
_xferfcn_defaults = {}
7474

7575
class TransferFunction(LTI):
76-
7776
"""TransferFunction(num, den[, dt])
7877
7978
A class for representing transfer functions
@@ -89,12 +88,21 @@ class TransferFunction(LTI):
8988
means that the numerator of the transfer function from the 6th input to the
9089
3rd output is set to s^2 + 4s + 8.
9190
92-
Discrete-time transfer functions are implemented by using the 'dt'
93-
instance variable and setting it to something other than 'None'. If 'dt'
94-
has a non-zero value, then it must match whenever two transfer functions
95-
are combined. If 'dt' is set to True, the system will be treated as a
96-
discrete time system with unspecified sampling time. The default value of
97-
'dt' is 0 and can be changed by changing the value of
91+
A discrete time transfer function is created by specifying a nonzero
92+
'timebase' dt when the system is constructed:
93+
94+
* dt = 0: continuous time system (default)
95+
* dt > 0: discrete time system with sampling period 'dt'
96+
* dt = True: discrete time with unspecified sampling period
97+
* dt = None: no timebase specified
98+
99+
Systems must have compatible timebases in order to be combined. A discrete
100+
time system with unspecified sampling time (`dt = True`) can be combined
101+
with a system having a specified sampling time; the result will be a
102+
discrete time system with the sample time of the latter system. Similarly,
103+
a system with timebase `None` can be combined with a system having any
104+
timebase; the result will have the timebase of the latter system.
105+
The default value of dt can be changed by changing the value of
98106
``control.config.defaults['control.default_dt']``.
99107
100108
The TransferFunction class defines two constants ``s`` and ``z`` that
@@ -104,8 +112,8 @@ class TransferFunction(LTI):
104112
105113
>>> s = TransferFunction.s
106114
>>> G = (s + 1)/(s**2 + 2*s + 1)
107-
108115
"""
116+
109117
def __init__(self, *args):
110118
"""TransferFunction(num, den[, dt])
111119

‎doc/conventions.rst‎

Lines changed: 9 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -80,27 +80,24 @@ Discrete time systems
8080
A discrete time system is created by specifying a nonzero 'timebase', dt.
8181
The timebase argument can be given when a system is constructed:
8282

83-
* dt = None: no timebase specified (default)
84-
* dt = 0: continuous time system
83+
* dt = 0: continuous time system (default)
8584
* dt > 0: discrete time system with sampling period 'dt'
8685
* dt = True: discrete time with unspecified sampling period
86+
* dt = None: no timebase specified
8787

8888
Only the :class:`StateSpace`, :class:`TransferFunction`, and
8989
:class:`InputOutputSystem` classes allow explicit representation of
9090
discrete time systems.
9191

92-
Systems must have compatible timebases in order to be combined. A system
93-
with timebase `None` can be combined with a system having a specified
94-
timebase; the result will have the timebase of the latter system.
95-
Similarly, a discrete time system with unspecified sampling time (`dt =
96-
True`) can be combined with a system having a specified sampling time;
97-
the result will be a discrete time system with the sample time of the latter
98-
system. For continuous time systems, the :func:`sample_system` function or
99-
the :meth:`StateSpace.sample` and :meth:`TransferFunction.sample` methods
92+
Systems must have compatible timebases in order to be combined. A discrete time
93+
system with unspecified sampling time (`dt = True`) can be combined with a system
94+
having a specified sampling time; the result will be a discrete time system with the sample time of the latter
95+
system. Similarly, a system with timebase `None` can be combined with a system having a specified
96+
timebase; the result will have the timebase of the latter system. For continuous
97+
time systems, the :func:`sample_system` function or the :meth:`StateSpace.sample` and :meth:`TransferFunction.sample` methods
10098
can be used to create a discrete time system from a continuous time system.
10199
See :ref:`utility-and-conversions`. The default value of 'dt' can be changed by
102-
changing the values of ``control.config.defaults['statesp.default_dt']`` and
103-
``control.config.defaults['xferfcn.default_dt']``.
100+
changing the value of ``control.config.defaults['control.default_dt']``.
104101

105102
Conversion between representations
106103
----------------------------------

0 commit comments

Comments
 (0)