control.interconnect

control.interconnect(syslist, connections=None, inplist=[], outlist=[], inputs=None, outputs=None, states=None, params={}, dt=None, name=None, **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 LinearIOSystem) 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
  • syslist (list of InputOutputSystems) – The list of input/output systems to be connected

  • connections (list 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 subsys_i has a single input, then the subsystem index subsys_i can be listed as the input-spec. If systems and signals are given names, then the form ‘sys.sig’ or (‘sys’, ‘sig’) are also recognized.

    Similarly, each output-spec should describe an output signal from one of the susystems. 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 system has a single output, then the subsystem index subsys_i can be listed as the input-spec. 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.

    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 set_connect_map() method.

  • inplist (list of input connections, optional) –

    List of connections for how the inputs for the overall system are mapped to the subsystem inputs. The input specification is similar to the form defined in the connection specification, except that connections do not specify an input-spec, since these are the system inputs. The entries for a connection are thus 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 only one subsystem input, a single input specification can be given (without the inner list).

    If omitted, the input map can be specified using the set_input_map() method.

  • outlist (list of output connections, optional) –

    List of connections for how the outputs from the subsystems are mapped to overall system outputs. The output connection description is the same as the form defined in the inplist specification (including the optional gain term). Numbered outputs must be chosen from the list of subsystem outputs, but named outputs can also be contained in the list of subsystem inputs.

    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 set_output_map() method.

  • 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. The default is None, in which case the states will be given names of the form ‘<subsys_name>.<state_name>’, for each subsys in syslist and each state_name of each subsys.

  • params (dict, optional) – Parameter values for the systems. Passed to the evaluation functions for the system as default values, overriding internal defaults.

  • 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.

Example

>>> P = control.LinearIOSystem(
>>>        control.rss(2, 2, 2, strictly_proper=True), name='P')
>>> C = control.LinearIOSystem(control.rss(2, 2, 2), name='C')
>>> T = control.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]'],
>>> )

For a SISO system, this example can be simplified by using the summing_block() function and the ability to automatically interconnect signals with the same names:

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

Notes

If a system is duplicated in the list of systems to be connected, a warning is generated 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.linearized_system_name_prefix’] and config.defaults[‘iosys.linearized_system_name_suffix’], with the default being to add the suffix ‘$copy’$ to the system name.

It is possible to replace lists in most of arguments with tuples instead, but strictly speaking 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, check your use of tuples.

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