control.interconnect

control.interconnect(syslist, connections=None, inplist=None, outlist=None, params=None, check_unused=True, add_unused=False, ignore_inputs=None, ignore_outputs=None, warn_duplicate=None, debug=False, **kwargs)

Interconnect a set of input/output systems.

This function creates a new system that is an interconnection of a set of input/output systems. If all of the input systems are linear I/O systems (type StateSpace) then the resulting system will be a linear interconnected I/O system (type LinearICSystem) with the appropriate inputs, outputs, and states. Otherwise, an interconnected I/O system (type InterconnectedSystem) will be created.

Parameters:

syslistlist of NonlinearIOSystem

The list of (state-based) input/output systems to be connected.

connectionslist of connections, optional

Description of the internal connections between the subsystems:

[connection1, connection2, ...]

Each connection is itself a list that describes an input to one of the subsystems. The entries are of the form:

[input-spec, output-spec1, output-spec2, ...]

The input-spec can be in a number of different forms. The lowest level representation is a tuple of the form (subsys_i, inp_j) where subsys_i is the index into syslist and inp_j is the index into the input vector for the subsystem. If the signal index is omitted, then all subsystem inputs are used. If systems and signals are given names, then the forms ‘sys.sig’ or (‘sys’, ‘sig’) are also recognized. Finally, for multivariable systems the signal index can be given as a list, for example ‘(subsys_i, [inp_j1, …, inp_jn])’; or as a slice, for example, ‘sys.sig[i:j]’; or as a base name ‘sys.sig’ (which matches ‘sys.sig[i]’).

Similarly, each output-spec should describe an output signal from one of the subsystems. The lowest level representation is a tuple of the form (subsys_i, out_j, gain). The input will be constructed by summing the listed outputs after multiplying by the gain term. If the gain term is omitted, it is assumed to be 1. If the subsystem index ‘subsys_i’ is omitted, then all outputs of the subsystem are used. If systems and signals are given names, then the form ‘sys.sig’, (‘sys’, ‘sig’) or (‘sys’, ‘sig’, gain) are also recognized, and the special form ‘-sys.sig’ can be used to specify a signal with gain -1. Lists, slices, and base names can also be used, as long as the number of elements for each output spec matches the input spec.

If omitted, the interconnect function will attempt to create the interconnection map by connecting all signals with the same base names (ignoring the system name). Specifically, for each input signal name in the list of systems, if that signal name corresponds to the output signal in any of the systems, it will be connected to that input (with a summation across all signals if the output name occurs in more than one system).

The connections keyword can also be set to False, which will leave the connection map empty and it can be specified instead using the low-level InterconnectedSystem.set_connect_map method.

inplistlist of input connections, optional

List of connections for how the inputs for the overall system are mapped to the subsystem inputs. The entries for a connection are of the form:

[input-spec1, input-spec2, ...]

Each system input is added to the input for the listed subsystem. If the system input connects to a subsystem with a single input, a single input specification can be given (without the inner list).

If omitted the input parameter will be used to identify the list of input signals to the overall system.

outlistlist of output connections, optional

List of connections for how the outputs from the subsystems are mapped to overall system outputs. The entries for a connection are of the form:

[output-spec1, output-spec2, ...]

If an output connection contains more than one signal specification, then those signals are added together (multiplying by the any gain term) to form the system output.

If omitted, the output map can be specified using the InterconnectedSystem.set_output_map method.

inputsint, 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.

outputsint, list of str or None, optional

Description of the system outputs. Same format as inputs.

statesint, list of str, or None, optional

Description of the system states. Same format as inputs. The default is None, in which case the states will be given names of the form ‘<subsys_name><delim><state_name>’, for each subsys in syslist and each state_name of each subsys, where <delim> is the value of config.defaults['iosys.state_name_delim'].

paramsdict, optional

Parameter values for the systems. Passed to the evaluation functions for the system as default values, overriding internal defaults. If not specified, defaults to parameters from subsystems.

dttimebase, 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

namestring, optional

System name (used for specifying signals). If unspecified, a generic name ‘sys[id]’ is generated with a unique integer id.

Returns:

sysInterconnectedSystem

NonlinearIOSystem consisting of the interconnected subsystems.

Other Parameters:

input_prefix, output_prefix, state_prefixstring, optional

Set the prefix for input, output, and state signals. Defaults = ‘u’, ‘y’, ‘x’.

check_unusedbool, optional

If True, check for unused sub-system signals. This check is not done if connections is False, and neither input nor output mappings are specified.

add_unusedbool, optional

If True, subsystem signals that are not connected to other components are added as inputs and outputs of the interconnected system.

ignore_inputslist of input-spec, optional

A list of sub-system inputs known not to be connected. This is only used in checking for unused signals, and does not disable use of the input.

Besides the usual input-spec forms (see connections), an input-spec can be just the signal base name, in which case all signals from all sub-systems with that base name are considered ignored.

ignore_outputslist of output-spec, optional

A list of sub-system outputs known not to be connected. This is only used in checking for unused signals, and does not disable use of the output.

Besides the usual output-spec forms (see connections), an output-spec can be just the signal base name, in which all outputs from all sub-systems with that base name are considered ignored.

warn_duplicateNone, True, or False, optional

Control how warnings are generated if duplicate objects or names are detected. In None (default), then warnings are generated for systems that have non-generic names. If False, warnings are not generated and if True then warnings are always generated.

debugbool, default=False

Print out information about how signals are being processed that may be useful in understanding why something is not working.

Notes

If a system is duplicated in the list of systems to be connected, a warning is generated and a copy of the system is created with the name of the new system determined by adding the prefix and suffix strings in config.defaults['iosys.duplicate_system_name_prefix'] and config.defaults['iosys.duplicate_system_name_suffix'], with the default being to add the suffix ‘$copy’ to the system name.

In addition to explicit lists of system signals, it is possible to lists vectors of signals, using one of the following forms:

(subsys, [i1, ..., iN], gain)   # signals with indices i1, ..., in
'sysname.signal[i:j]'           # range of signal names, i through j-1
'sysname.signal[:]'             # all signals with given prefix

While in many Python functions tuples can be used in place of lists, for the interconnect() function the only use of tuples should be in the specification of an input- or output-signal via the tuple notation (subsys_i, signal_j, gain) (where gain is optional). If you get an unexpected error message about a specification being of the wrong type or not being found, check to make sure you are not using a tuple where you should be using a list.

In addition to its use for general nonlinear I/O systems, the interconnect function allows linear systems to be interconnected using named signals (compared with the legacy connect function, which uses signal indices) and to be treated as both a StateSpace system as well as an InputOutputSystem.

The input and output keywords can be used instead of inputs and outputs, for more natural naming of SISO systems.

Examples

>>> P = ct.rss(2, 2, 2, strictly_proper=True, name='P')
>>> C = ct.rss(2, 2, 2, name='C')
>>> T = ct.interconnect(
...     [P, C],
...     connections=[
...         ['P.u[0]', 'C.y[0]'], ['P.u[1]', 'C.y[1]'],
...         ['C.u[0]', '-P.y[0]'], ['C.u[1]', '-P.y[1]']],
...     inplist=['C.u[0]', 'C.u[1]'],
...     outlist=['P.y[0]', 'P.y[1]'],
... )

This expression can be simplified using either slice notation or just signal basenames:

>>> T = ct.interconnect(
...     [P, C], connections=[['P.u[:]', 'C.y[:]'], ['C.u', '-P.y']],
...     inplist='C.u', outlist='P.y[:]')

or further simplified by omitting the input and output signal specifications (since all inputs and outputs are used):

>>> T = ct.interconnect(
...     [P, C], connections=[['P', 'C'], ['C', '-P']],
...     inplist=['C'], outlist=['P'])

A feedback system can also be constructed using the summing_junction function and the ability to automatically interconnect signals with the same names:

>>> P = ct.tf(1, [1, 0], inputs='u', outputs='y')
>>> C = ct.tf(10, [1, 1], inputs='e', outputs='u')
>>> sumblk = ct.summing_junction(inputs=['r', '-y'], output='e')
>>> T = ct.interconnect([P, C, sumblk], inputs='r', outputs='y')