Repository navigation
Expand file tree
/
Copy pathiosys.py
More file actions
2986 lines (2438 loc) · 120 KB
/
Copy pathiosys.py
File metadata and controls
2986 lines (2438 loc) · 120 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# iosys.py - input/output system module
#
# RMM, 28 April 2019
#
# Additional features to add
# * Allow constant inputs for MIMO input_output_response (w/out ones)
# * Add support for constants/matrices as part of operators (1 + P)
# * Add unit tests (and example?) for time-varying systems
# * Allow time vector for discrete time simulations to be multiples of dt
# * Check the way initial outputs for discrete time systems are handled
#
"""The :mod:`~control.iosys` module contains the
:class:`~control.InputOutputSystem` class that represents (possibly nonlinear)
input/output systems. The :class:`~control.InputOutputSystem` class is a
general class that defines any continuous or discrete time dynamical system.
Input/output systems can be simulated and also used to compute equilibrium
points and linearizations.
"""
__author__ = "Richard Murray"
__copyright__ = "Copyright 2019, California Institute of Technology"
__credits__ = ["Richard Murray"]
__license__ = "BSD"
__maintainer__ = "Richard Murray"
__email__ = "murray@cds.caltech.edu"
import numpy as np
import scipy as sp
import copy
from warnings import warn
from .lti import LTI
from .namedio import NamedIOSystem, _process_signal_list, \
_process_namedio_keywords, isctime, isdtime, common_timebase
from .statesp import StateSpace, tf2ss, _convert_to_statespace
from .statesp import _rss_generate
from .xferfcn import TransferFunction
from .timeresp import _check_convert_array, _process_time_response, \
TimeResponseData
from . import config
__all__ = ['InputOutputSystem', 'LinearIOSystem', 'NonlinearIOSystem',
'InterconnectedSystem', 'LinearICSystem', 'input_output_response',
'find_eqpt', 'linearize', 'ss', 'rss', 'drss', 'ss2io', 'tf2io',
'interconnect', 'summing_junction']
# Define module default parameter values
_iosys_defaults = {
'iosys.state_name_delim': '_',
'iosys.duplicate_system_name_prefix': '',
'iosys.duplicate_system_name_suffix': '$copy',
'iosys.linearized_system_name_prefix': '',
'iosys.linearized_system_name_suffix': '$linearized'
}
class InputOutputSystem(NamedIOSystem):
"""A class for representing input/output systems.
The InputOutputSystem class allows (possibly nonlinear) input/output
systems to be represented in Python. It is intended as a parent
class for a set of subclasses that are used to implement specific
structures and operations for different types of input/output
dynamical systems.
Parameters
----------
inputs : int, list of str, or None
Description of the system inputs. This can be given as an integer
count or a list of strings that name the individual signals. If an
integer count is specified, the names of the signal will be of the
form `s[i]` (where `s` is one of `u`, `y`, or `x`). If this parameter
is not given or given as `None`, the relevant quantity will be
determined when possible based on other information provided to
functions using the system.
outputs : int, list of str, or None
Description of the system outputs. Same format as `inputs`.
states : int, list of str, or None
Description of the system states. Same format as `inputs`.
dt : None, True or float, optional
System timebase. 0 (default) indicates continuous time, True
indicates discrete time with unspecified sampling time, positive
number is discrete time with specified sampling time, None indicates
unspecified timebase (either continuous or discrete time).
name : string, optional
System name (used for specifying signals). If unspecified, a generic
name <sys[id]> is generated with a unique integer id.
params : dict, optional
Parameter values for the systems. Passed to the evaluation functions
for the system as default values, overriding internal defaults.
Attributes
----------
ninputs, noutputs, nstates : int
Number of input, output and state variables
input_index, output_index, state_index : dict
Dictionary of signal names for the inputs, outputs and states and the
index of the corresponding array
dt : None, True or float
System timebase. 0 (default) indicates continuous time, True indicates
discrete time with unspecified sampling time, positive number is
discrete time with specified sampling time, None indicates unspecified
timebase (either continuous or discrete time).
params : dict, optional
Parameter values for the systems. Passed to the evaluation functions
for the system as default values, overriding internal defaults.
name : string, optional
System name (used for specifying signals)
Notes
-----
The :class:`~control.InputOuputSystem` class (and its subclasses) makes
use of two special methods for implementing much of the work of the class:
* _rhs(t, x, u): compute the right hand side of the differential or
difference equation for the system. This must be specified by the
subclass for the system.
* _out(t, x, u): compute the output for the current state of the system.
The default is to return the entire system state.
"""
# Allow ndarray * InputOutputSystem to give IOSystem._rmul_() priority
__array_priority__ = 12 # override ndarray, matrix, SS types
def __init__(self, params=None, **kwargs):
"""Create an input/output system.
The InputOutputSystem constructor is used to create an input/output
object with the core information required for all input/output
systems. Instances of this class are normally created by one of the
input/output subclasses: :class:`~control.LinearICSystem`,
:class:`~control.LinearIOSystem`, :class:`~control.NonlinearIOSystem`,
:class:`~control.InterconnectedSystem`.
"""
# Store the system name, inputs, outputs, and states
name, inputs, outputs, states, dt = _process_namedio_keywords(
kwargs, end=True)
# Initialize the data structure
# Note: don't use super() to override LinearIOSystem/StateSpace MRO
NamedIOSystem.__init__(
self, inputs=inputs, outputs=outputs,
states=states, name=name, dt=dt)
# default parameters
self.params = {} if params is None else params.copy()
def __mul__(sys2, sys1):
"""Multiply two input/output systems (series interconnection)"""
# Note: order of arguments is flipped so that self = sys2,
# corresponding to the ordering convention of sys2 * sys1
# Convert sys1 to an I/O system if needed
if isinstance(sys1, (int, float, np.number)):
sys1 = LinearIOSystem(StateSpace(
[], [], [], sys1 * np.eye(sys2.ninputs)))
elif isinstance(sys1, np.ndarray):
sys1 = LinearIOSystem(StateSpace([], [], [], sys1))
elif isinstance(sys1, (StateSpace, TransferFunction)) and \
not isinstance(sys1, LinearIOSystem):
sys1 = LinearIOSystem(sys1)
elif not isinstance(sys1, InputOutputSystem):
raise TypeError("Unknown I/O system object ", sys1)
# Make sure systems can be interconnected
if sys1.noutputs != sys2.ninputs:
raise ValueError("Can't multiply systems with incompatible "
"inputs and outputs")
# Make sure timebase are compatible
dt = common_timebase(sys1.dt, sys2.dt)
# Create a new system to handle the composition
inplist = [(0, i) for i in range(sys1.ninputs)]
outlist = [(1, i) for i in range(sys2.noutputs)]
newsys = InterconnectedSystem(
(sys1, sys2), inplist=inplist, outlist=outlist)
# Set up the connection map manually
newsys.set_connect_map(np.block(
[[np.zeros((sys1.ninputs, sys1.noutputs)),
np.zeros((sys1.ninputs, sys2.noutputs))],
[np.eye(sys2.ninputs, sys1.noutputs),
np.zeros((sys2.ninputs, sys2.noutputs))]]
))
# If both systems are linear, create LinearICSystem
if isinstance(sys1, StateSpace) and isinstance(sys2, StateSpace):
ss_sys = StateSpace.__mul__(sys2, sys1)
return LinearICSystem(newsys, ss_sys)
# Return the newly created InterconnectedSystem
return newsys
def __rmul__(sys1, sys2):
"""Pre-multiply an input/output systems by a scalar/matrix"""
# Convert sys2 to an I/O system if needed
if isinstance(sys2, (int, float, np.number)):
sys2 = LinearIOSystem(StateSpace(
[], [], [], sys2 * np.eye(sys1.noutputs)))
elif isinstance(sys2, np.ndarray):
sys2 = LinearIOSystem(StateSpace([], [], [], sys2))
elif isinstance(sys2, (StateSpace, TransferFunction)) and \
not isinstance(sys2, LinearIOSystem):
sys2 = LinearIOSystem(sys2)
elif not isinstance(sys2, InputOutputSystem):
raise TypeError("Unknown I/O system object ", sys2)
return InputOutputSystem.__mul__(sys2, sys1)
def __add__(sys1, sys2):
"""Add two input/output systems (parallel interconnection)"""
# Convert sys1 to an I/O system if needed
if isinstance(sys2, (int, float, np.number)):
sys2 = LinearIOSystem(StateSpace(
[], [], [], sys2 * np.eye(sys1.ninputs)))
elif isinstance(sys2, np.ndarray):
sys2 = LinearIOSystem(StateSpace([], [], [], sys2))
elif isinstance(sys2, (StateSpace, TransferFunction)) and \
not isinstance(sys2, LinearIOSystem):
sys2 = LinearIOSystem(sys2)
elif not isinstance(sys2, InputOutputSystem):
raise TypeError("Unknown I/O system object ", sys2)
# Make sure number of input and outputs match
if sys1.ninputs != sys2.ninputs or sys1.noutputs != sys2.noutputs:
raise ValueError("Can't add systems with incompatible numbers of "
"inputs or outputs.")
ninputs = sys1.ninputs
noutputs = sys1.noutputs
# Create a new system to handle the composition
inplist = [[(0, i), (1, i)] for i in range(ninputs)]
outlist = [[(0, i), (1, i)] for i in range(noutputs)]
newsys = InterconnectedSystem(
(sys1, sys2), inplist=inplist, outlist=outlist)
# If both systems are linear, create LinearICSystem
if isinstance(sys1, StateSpace) and isinstance(sys2, StateSpace):
ss_sys = StateSpace.__add__(sys2, sys1)
return LinearICSystem(newsys, ss_sys)
# Return the newly created InterconnectedSystem
return newsys
def __radd__(sys1, sys2):
"""Parallel addition of input/output system to a compatible object."""
# Convert sys2 to an I/O system if needed
if isinstance(sys2, (int, float, np.number)):
sys2 = LinearIOSystem(StateSpace(
[], [], [], sys2 * np.eye(sys1.noutputs)))
elif isinstance(sys2, np.ndarray):
sys2 = LinearIOSystem(StateSpace([], [], [], sys2))
elif isinstance(sys2, (StateSpace, TransferFunction)) and \
not isinstance(sys2, LinearIOSystem):
sys2 = LinearIOSystem(sys2)
elif not isinstance(sys2, InputOutputSystem):
raise TypeError("Unknown I/O system object ", sys2)
return InputOutputSystem.__add__(sys2, sys1)
def __sub__(sys1, sys2):
"""Subtract two input/output systems (parallel interconnection)"""
# Convert sys1 to an I/O system if needed
if isinstance(sys2, (int, float, np.number)):
sys2 = LinearIOSystem(StateSpace(
[], [], [], sys2 * np.eye(sys1.ninputs)))
elif isinstance(sys2, np.ndarray):
sys2 = LinearIOSystem(StateSpace([], [], [], sys2))
elif isinstance(sys2, (StateSpace, TransferFunction)) and \
not isinstance(sys2, LinearIOSystem):
sys2 = LinearIOSystem(sys2)
elif not isinstance(sys2, InputOutputSystem):
raise TypeError("Unknown I/O system object ", sys2)
# Make sure number of input and outputs match
if sys1.ninputs != sys2.ninputs or sys1.noutputs != sys2.noutputs:
raise ValueError("Can't add systems with incompatible numbers of "
"inputs or outputs.")
ninputs = sys1.ninputs
noutputs = sys1.noutputs
# Create a new system to handle the composition
inplist = [[(0, i), (1, i)] for i in range(ninputs)]
outlist = [[(0, i), (1, i, -1)] for i in range(noutputs)]
newsys = InterconnectedSystem(
(sys1, sys2), inplist=inplist, outlist=outlist)
# If both systems are linear, create LinearICSystem
if isinstance(sys1, StateSpace) and isinstance(sys2, StateSpace):
ss_sys = StateSpace.__sub__(sys1, sys2)
return LinearICSystem(newsys, ss_sys)
# Return the newly created InterconnectedSystem
return newsys
def __rsub__(sys1, sys2):
"""Parallel subtraction of I/O system to a compatible object."""
# Convert sys2 to an I/O system if needed
if isinstance(sys2, (int, float, np.number)):
sys2 = LinearIOSystem(StateSpace(
[], [], [], sys2 * np.eye(sys1.noutputs)))
elif isinstance(sys2, np.ndarray):
sys2 = LinearIOSystem(StateSpace([], [], [], sys2))
elif isinstance(sys2, (StateSpace, TransferFunction)) and \
not isinstance(sys2, LinearIOSystem):
sys2 = LinearIOSystem(sys2)
elif not isinstance(sys2, InputOutputSystem):
raise TypeError("Unknown I/O system object ", sys2)
return InputOutputSystem.__sub__(sys2, sys1)
def __neg__(sys):
"""Negate an input/output systems (rescale)"""
if sys.ninputs is None or sys.noutputs is None:
raise ValueError("Can't determine number of inputs or outputs")
# Create a new system to hold the negation
inplist = [(0, i) for i in range(sys.ninputs)]
outlist = [(0, i, -1) for i in range(sys.noutputs)]
newsys = InterconnectedSystem(
(sys,), dt=sys.dt, inplist=inplist, outlist=outlist)
# If the system is linear, create LinearICSystem
if isinstance(sys, StateSpace):
ss_sys = StateSpace.__neg__(sys)
return LinearICSystem(newsys, ss_sys)
# Return the newly created system
return newsys
# Update parameters used for _rhs, _out (used by subclasses)
def _update_params(self, params, warning=False):
if warning:
warn("Parameters passed to InputOutputSystem ignored.")
def _rhs(self, t, x, u):
"""Evaluate right hand side of a differential or difference equation.
Private function used to compute the right hand side of an
input/output system model. Intended for fast
evaluation; for a more user-friendly interface
you may want to use :meth:`dynamics`.
"""
NotImplemented("Evaluation not implemented for system of type ",
type(self))
def dynamics(self, t, x, u, params=None):
"""Compute the dynamics of a differential or difference equation.
Given time `t`, input `u` and state `x`, returns the value of the
right hand side of the dynamical system. If the system is continuous,
returns the time derivative
dx/dt = f(t, x, u[, params])
where `f` is the system's (possibly nonlinear) dynamics function.
If the system is discrete-time, returns the next value of `x`:
x[t+dt] = f(t, x[t], u[t][, params])
where `t` is a scalar.
The inputs `x` and `u` must be of the correct length. The `params`
argument is an optional dictionary of parameter values.
Parameters
----------
t : float
the time at which to evaluate
x : array_like
current state
u : array_like
input
params : dict (optional)
system parameter values
Returns
-------
dx/dt or x[t+dt] : ndarray
"""
self._update_params(params)
return self._rhs(t, x, u)
def _out(self, t, x, u):
"""Evaluate the output of a system at a given state, input, and time
Private function used to compute the output of of an input/output
system model given the state, input, parameters. Intended for fast
evaluation; for a more user-friendly interface you may want to use
:meth:`output`.
"""
# If no output function was defined in subclass, return state
return x
def output(self, t, x, u, params=None):
"""Compute the output of the system
Given time `t`, input `u` and state `x`, returns the output of the
system:
y = g(t, x, u[, params])
The inputs `x` and `u` must be of the correct length.
Parameters
----------
t : float
the time at which to evaluate
x : array_like
current state
u : array_like
input
params : dict (optional)
system parameter values
Returns
-------
y : ndarray
"""
self._update_params(params)
return self._out(t, x, u)
def feedback(self, other=1, sign=-1, params=None):
"""Feedback interconnection between two input/output systems
Parameters
----------
sys1: InputOutputSystem
The primary process.
sys2: InputOutputSystem
The feedback process (often a feedback controller).
sign: scalar, optional
The sign of feedback. `sign` = -1 indicates negative feedback,
and `sign` = 1 indicates positive feedback. `sign` is an optional
argument; it assumes a value of -1 if not specified.
Returns
-------
out: InputOutputSystem
Raises
------
ValueError
if the inputs, outputs, or timebases of the systems are
incompatible.
"""
# TODO: add conversion to I/O system when needed
if not isinstance(other, InputOutputSystem):
# Try converting to a state space system
try:
other = _convert_to_statespace(other)
except TypeError:
raise TypeError(
"Feedback around I/O system must be an I/O system "
"or convertable to an I/O system.")
other = LinearIOSystem(other)
# Make sure systems can be interconnected
if self.noutputs != other.ninputs or other.noutputs != self.ninputs:
raise ValueError("Can't connect systems with incompatible "
"inputs and outputs")
# Make sure timebases are compatible
dt = common_timebase(self.dt, other.dt)
inplist = [(0, i) for i in range(self.ninputs)]
outlist = [(0, i) for i in range(self.noutputs)]
# Return the series interconnection between the systems
newsys = InterconnectedSystem(
(self, other), inplist=inplist, outlist=outlist,
params=params, dt=dt)
# Set up the connecton map manually
newsys.set_connect_map(np.block(
[[np.zeros((self.ninputs, self.noutputs)),
sign * np.eye(self.ninputs, other.noutputs)],
[np.eye(other.ninputs, self.noutputs),
np.zeros((other.ninputs, other.noutputs))]]
))
if isinstance(self, StateSpace) and isinstance(other, StateSpace):
# Special case: maintain linear systems structure
ss_sys = StateSpace.feedback(self, other, sign=sign)
return LinearICSystem(newsys, ss_sys)
# Return the newly created system
return newsys
def linearize(self, x0, u0, t=0, params=None, eps=1e-6,
name=None, copy=False, **kwargs):
"""Linearize an input/output system at a given state and input.
Return the linearization of an input/output system at a given state
and input value as a StateSpace system. See
:func:`~control.linearize` for complete documentation.
"""
#
# If the linearization is not defined by the subclass, perform a
# numerical linearization use the `_rhs()` and `_out()` member
# functions.
#
# Figure out dimensions if they were not specified.
nstates = _find_size(self.nstates, x0)
ninputs = _find_size(self.ninputs, u0)
# Convert x0, u0 to arrays, if needed
if np.isscalar(x0):
x0 = np.ones((nstates,)) * x0
if np.isscalar(u0):
u0 = np.ones((ninputs,)) * u0
# Compute number of outputs by evaluating the output function
noutputs = _find_size(self.noutputs, self._out(t, x0, u0))
# Update the current parameters
self._update_params(params)
# Compute the nominal value of the update law and output
F0 = self._rhs(t, x0, u0)
H0 = self._out(t, x0, u0)
# Create empty matrices that we can fill up with linearizations
A = np.zeros((nstates, nstates)) # Dynamics matrix
B = np.zeros((nstates, ninputs)) # Input matrix
C = np.zeros((noutputs, nstates)) # Output matrix
D = np.zeros((noutputs, ninputs)) # Direct term
# Perturb each of the state variables and compute linearization
for i in range(nstates):
dx = np.zeros((nstates,))
dx[i] = eps
A[:, i] = (self._rhs(t, x0 + dx, u0) - F0) / eps
C[:, i] = (self._out(t, x0 + dx, u0) - H0) / eps
# Perturb each of the input variables and compute linearization
for i in range(ninputs):
du = np.zeros((ninputs,))
du[i] = eps
B[:, i] = (self._rhs(t, x0, u0 + du) - F0) / eps
D[:, i] = (self._out(t, x0, u0 + du) - H0) / eps
# Create the state space system
linsys = LinearIOSystem(
StateSpace(A, B, C, D, self.dt, remove_useless_states=False),
name=name, **kwargs)
# Set the names the system, inputs, outputs, and states
if copy:
if name is None:
linsys.name = \
config.defaults['iosys.linearized_system_name_prefix'] + \
self.name + \
config.defaults['iosys.linearized_system_name_suffix']
linsys.ninputs, linsys.input_index = self.ninputs, \
self.input_index.copy()
linsys.noutputs, linsys.output_index = \
self.noutputs, self.output_index.copy()
linsys.nstates, linsys.state_index = \
self.nstates, self.state_index.copy()
return linsys
class LinearIOSystem(InputOutputSystem, StateSpace):
"""Input/output representation of a linear (state space) system.
This class is used to implement a system that is a linear state
space system (defined by the StateSpace system object).
Parameters
----------
linsys : StateSpace or TransferFunction
LTI system to be converted
inputs : int, list of str or None, optional
Description of the system inputs. This can be given as an integer
count or as a list of strings that name the individual signals. If an
integer count is specified, the names of the signal will be of the
form `s[i]` (where `s` is one of `u`, `y`, or `x`). If this parameter
is not given or given as `None`, the relevant quantity will be
determined when possible based on other information provided to
functions using the system.
outputs : int, list of str or None, optional
Description of the system outputs. Same format as `inputs`.
states : int, list of str, or None, optional
Description of the system states. Same format as `inputs`.
dt : None, True or float, optional
System timebase. 0 (default) indicates continuous time, True indicates
discrete time with unspecified sampling time, positive number is
discrete time with specified sampling time, None indicates unspecified
timebase (either continuous or discrete time).
name : string, optional
System name (used for specifying signals). If unspecified, a
generic name <sys[id]> is generated with a unique integer id.
params : dict, optional
Parameter values for the systems. Passed to the evaluation functions
for the system as default values, overriding internal defaults.
Attributes
----------
ninputs, noutputs, nstates, dt, etc
See :class:`InputOutputSystem` for inherited attributes.
A, B, C, D
See :class:`~control.StateSpace` for inherited attributes.
"""
def __init__(self, linsys, **kwargs):
"""Create an I/O system from a state space linear system.
Converts a :class:`~control.StateSpace` system into an
:class:`~control.InputOutputSystem` with the same inputs, outputs, and
states. The new system can be a continuous or discrete time system.
"""
if isinstance(linsys, TransferFunction):
# Convert system to StateSpace
linsys = _convert_to_statespace(linsys)
elif not isinstance(linsys, StateSpace):
raise TypeError("Linear I/O system must be a state space "
"or transfer function object")
# Process keyword arguments
name, inputs, outputs, states, dt = _process_namedio_keywords(
kwargs, linsys, end=True)
# Create the I/O system object
# Note: don't use super() to override StateSpace MRO
InputOutputSystem.__init__(
self, inputs=inputs, outputs=outputs, states=states,
params=None, dt=dt, name=name)
# Initalize additional state space variables
StateSpace.__init__(
self, linsys, remove_useless_states=False, init_namedio=False)
# The following text needs to be replicated from StateSpace in order for
# this entry to show up properly in sphinx doccumentation (not sure why,
# but it was the only way to get it to work).
#
#: Deprecated attribute; use :attr:`nstates` instead.
#:
#: The ``state`` attribute was used to store the number of states for : a
#: state space system. It is no longer used. If you need to access the
#: number of states, use :attr:`nstates`.
states = property(StateSpace._get_states, StateSpace._set_states)
def _update_params(self, params=None, warning=True):
# Parameters not supported; issue a warning
if params and warning:
warn("Parameters passed to LinearIOSystems are ignored.")
def _rhs(self, t, x, u):
# Convert input to column vector and then change output to 1D array
xdot = self.A @ np.reshape(x, (-1, 1)) \
+ self.B @ np.reshape(u, (-1, 1))
return np.array(xdot).reshape((-1,))
def _out(self, t, x, u):
# Convert input to column vector and then change output to 1D array
y = self.C @ np.reshape(x, (-1, 1)) \
+ self.D @ np.reshape(u, (-1, 1))
return np.array(y).reshape((-1,))
def __repr__(self):
# Need to define so that I/O system gets used instead of StateSpace
return InputOutputSystem.__repr__(self)
def __str__(self):
return InputOutputSystem.__str__(self) + "\n\n" \
+ StateSpace.__str__(self)
class NonlinearIOSystem(InputOutputSystem):
"""Nonlinear I/O system.
Creates an :class:`~control.InputOutputSystem` for a nonlinear system by
specifying a state update function and an output function. The new system
can be a continuous or discrete time system (Note: discrete-time systems
are not yet supported by most functions.)
Parameters
----------
updfcn : callable
Function returning the state update function
`updfcn(t, x, u, params) -> array`
where `x` is a 1-D array with shape (nstates,), `u` is a 1-D array
with shape (ninputs,), `t` is a float representing the currrent
time, and `params` is a dict containing the values of parameters
used by the function.
outfcn : callable
Function returning the output at the given state
`outfcn(t, x, u, params) -> array`
where the arguments are the same as for `upfcn`.
inputs : int, list of str or None, optional
Description of the system inputs. This can be given as an integer
count or as a list of strings that name the individual signals.
If an integer count is specified, the names of the signal will be
of the form `s[i]` (where `s` is one of `u`, `y`, or `x`). If
this parameter is not given or given as `None`, the relevant
quantity will be determined when possible based on other
information provided to functions using the system.
outputs : int, list of str or None, optional
Description of the system outputs. Same format as `inputs`.
states : int, list of str, or None, optional
Description of the system states. Same format as `inputs`.
dt : timebase, optional
The timebase for the system, used to specify whether the system is
operating in continuous or discrete time. It can have the
following values:
* dt = 0: continuous time system (default)
* dt > 0: discrete time system with sampling period 'dt'
* dt = True: discrete time with unspecified sampling period
* dt = None: no timebase specified
name : string, optional
System name (used for specifying signals). If unspecified, a
generic name <sys[id]> is generated with a unique integer id.
params : dict, optional
Parameter values for the systems. Passed to the evaluation
functions for the system as default values, overriding internal
defaults.
"""
def __init__(self, updfcn, outfcn=None, params=None, **kwargs):
"""Create a nonlinear I/O system given update and output functions."""
# Process keyword arguments
name, inputs, outputs, states, dt = _process_namedio_keywords(
kwargs, end=True)
# Initialize the rest of the structure
super().__init__(
inputs=inputs, outputs=outputs, states=states,
params=params, dt=dt, name=name
)
# Store the update and output functions
self.updfcn = updfcn
self.outfcn = outfcn
# Check to make sure arguments are consistent
if updfcn is None:
if self.nstates is None:
self.nstates = 0
else:
raise ValueError("States specified but no update function "
"given.")
if outfcn is None:
# No output function specified => outputs = states
if self.noutputs is None and self.nstates is not None:
self.noutputs = self.nstates
elif self.noutputs is not None and self.noutputs == self.nstates:
# Number of outputs = number of states => all is OK
pass
elif self.noutputs is not None and self.noutputs != 0:
raise ValueError("Outputs specified but no output function "
"(and nstates not known).")
# Initialize current parameters to default parameters
self._current_params = {} if params is None else params.copy()
def __str__(self):
return f"{InputOutputSystem.__str__(self)}\n\n" + \
f"Update: {self.updfcn}\n" + \
f"Output: {self.outfcn}"
# Return the value of a static nonlinear system
def __call__(sys, u, params=None, squeeze=None):
"""Evaluate a (static) nonlinearity at a given input value
If a nonlinear I/O system has no internal state, then evaluating the
system at an input `u` gives the output `y = F(u)`, determined by the
output function.
Parameters
----------
params : dict, optional
Parameter values for the system. Passed to the evaluation function
for the system as default values, overriding internal defaults.
squeeze : bool, optional
If True and if the system has a single output, return the system
output as a 1D array rather than a 2D array. If False, return the
system output as a 2D array even if the system is SISO. Default
value set by config.defaults['control.squeeze_time_response'].
"""
# Make sure the call makes sense
if not sys._isstatic():
raise TypeError(
"function evaluation is only supported for static "
"input/output systems")
# If we received any parameters, update them before calling _out()
if params is not None:
sys._update_params(params)
# Evaluate the function on the argument
out = sys._out(0, np.array((0,)), np.asarray(u))
_, out = _process_time_response(
None, out, issiso=sys.issiso(), squeeze=squeeze)
return out
def _update_params(self, params, warning=False):
# Update the current parameter values
self._current_params = self.params.copy()
if params:
self._current_params.update(params)
def _rhs(self, t, x, u):
xdot = self.updfcn(t, x, u, self._current_params) \
if self.updfcn is not None else []
return np.array(xdot).reshape((-1,))
def _out(self, t, x, u):
y = self.outfcn(t, x, u, self._current_params) \
if self.outfcn is not None else x
return np.array(y).reshape((-1,))
class InterconnectedSystem(InputOutputSystem):
"""Interconnection of a set of input/output systems.
This class is used to implement a system that is an interconnection of
input/output systems. The sys consists of a collection of subsystems
whose inputs and outputs are connected via a connection map. The overall
system inputs and outputs are subsets of the subsystem inputs and outputs.
See :func:`~control.interconnect` for a list of parameters.
"""
def __init__(self, syslist, connections=None, inplist=None, outlist=None,
params=None, warn_duplicate=None, **kwargs):
"""Create an I/O system from a list of systems + connection info."""
# Convert input and output names to lists if they aren't already
if inplist is not None and not isinstance(inplist, (list, tuple)):
inplist = [inplist]
if outlist is not None and not isinstance(outlist, (list, tuple)):
outlist = [outlist]
# Check if dt argument was given; if not, pull from systems
dt = kwargs.pop('dt', None)
# Process keyword arguments (except dt)
defaults = {
'inputs': len(inplist or []),
'outputs': len(outlist or [])}
name, inputs, outputs, states, _ = _process_namedio_keywords(
kwargs, defaults, end=True)
# Initialize the system list and index
self.syslist = syslist
self.syslist_index = {}
# Initialize the input, output, and state counts, indices
nstates, self.state_offset = 0, []
ninputs, self.input_offset = 0, []
noutputs, self.output_offset = 0, []
# Keep track of system objects and names we have already seen
sysobj_name_dct = {}
sysname_count_dct = {}
# Go through the system list and keep track of counts, offsets
for sysidx, sys in enumerate(syslist):
# If we were passed a SS or TF system, convert to LinearIOSystem
if isinstance(sys, (StateSpace, TransferFunction)) and \
not isinstance(sys, LinearIOSystem):
sys = LinearIOSystem(sys)
syslist[sysidx] = sys
# Make sure time bases are consistent
dt = common_timebase(dt, sys.dt)
# Make sure number of inputs, outputs, states is given
if sys.ninputs is None or sys.noutputs is None or \
sys.nstates is None:
raise TypeError("System '%s' must define number of inputs, "
"outputs, states in order to be connected" %
sys.name)
# Keep track of the offsets into the states, inputs, outputs
self.input_offset.append(ninputs)
self.output_offset.append(noutputs)
self.state_offset.append(nstates)
# Keep track of the total number of states, inputs, outputs
nstates += sys.nstates
ninputs += sys.ninputs
noutputs += sys.noutputs
# Check for duplicate systems or duplicate names
# Duplicates are renamed sysname_1, sysname_2, etc.
if sys in sysobj_name_dct:
# Make a copy of the object using a new name
if warn_duplicate is None and sys._generic_name_check():
# Make a copy w/out warning, using generic format
sys = sys.copy(use_prefix_suffix=False)
warn_flag = False
else:
sys = sys.copy()
warn_flag = warn_duplicate
# Warn the user about the new object
if warn_flag is not False:
warn("duplicate object found in system list; "
"created copy: %s" % str(sys.name), stacklevel=2)
# Check to see if the system name shows up more than once
if sys.name is not None and sys.name in sysname_count_dct:
count = sysname_count_dct[sys.name]
sysname_count_dct[sys.name] += 1
sysname = sys.name + "_" + str(count)
sysobj_name_dct[sys] = sysname
self.syslist_index[sysname] = sysidx
if warn_duplicate is not False:
warn("duplicate name found in system list; "
"renamed to {}".format(sysname), stacklevel=2)
else:
sysname_count_dct[sys.name] = 1
sysobj_name_dct[sys] = sys.name
self.syslist_index[sys.name] = sysidx
if states is None:
states = []
state_name_delim = config.defaults['iosys.state_name_delim']
for sys, sysname in sysobj_name_dct.items():
states += [sysname + state_name_delim +
statename for statename in sys.state_index.keys()]
# Make sure we the state list is the right length (internal check)
if isinstance(states, list) and len(states) != nstates:
raise RuntimeError(
f"construction of state labels failed; found: "
f"{len(states)} labels; expecting {nstates}")
# Create the I/O system
# Note: don't use super() to override LinearICSystem/StateSpace MRO
InputOutputSystem.__init__(
self, inputs=inputs, outputs=outputs,
states=states, params=params, dt=dt, name=name)
# Convert the list of interconnections to a connection map (matrix)
self.connect_map = np.zeros((ninputs, noutputs))
for connection in connections or []:
input_index = self._parse_input_spec(connection[0])
for output_spec in connection[1:]:
output_index, gain = self._parse_output_spec(output_spec)
if self.connect_map[input_index, output_index] != 0:
warn("multiple connections given for input %d" %
input_index + ". Combining with previous entries.")
self.connect_map[input_index, output_index] += gain
# Convert the input list to a matrix: maps system to subsystems
self.input_map = np.zeros((ninputs, self.ninputs))
for index, inpspec in enumerate(inplist or []):
if isinstance(inpspec, (int, str, tuple)):