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)[source]

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

  • 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 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 namess can also be used, as long as the number of elements for each output spec mataches 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 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 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.

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

  • check_unused (bool, 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_unused (bool, optional) – If True, subsystem signals that are not connected to other components are added as inputs and outputs of the interconnected system.

  • ignore_inputs (list 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_outputs (list 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_duplicate (None, 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.

  • debug (bool, default=False) – Print out information about how signals are being processed that may be useful in understanding why something is not working.

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_block() 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')

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