sumblk

Summing junction for name-based interconnections

Syntax

S = sumblk(formula)

S = sumblk(formula,signalsize)

S = sumblk(formula,signames1,...,signamesN)

Description

S = sumblk(formula) creates the summing junction described by formula in the form of a transfer function (tf) model, S. The string formula specifies an equation that relates the scalar input and output signals of S, such as "e = r - y". The function sets the InputName and OutputName properties of S based on formula. Use S in conjunction with connect to interconnect dynamic system models and derive aggregate models for block diagrams.

S = sumblk(formula,signalsize) returns a vector-valued summing junction. The input and output signals are vectors with signalsize elements. sumblk sets the InputName and OutputName properties by vector expansion of the signal names in formula.

S = sumblk(formula,signames1,...,signamesN) replaces placeholders in formula by the signal names signames. Indicate a placeholder in formula by using a signal name beginning with %. The number of signames arguments must match the number of placeholders in formula. The first placeholder in formula is replaced by signames1, the second by signames2, and so on.

Examples

Summing Junction with Scalar-Valued Signals

Create the summing junction of the following illustration. All signals are scalar-valued.

This summing junction has the formula u = u1 + u2 + u3. Use this formula with sumblk to create the summing junction.

S = sumblk('u = u1 + u2 + u3');

S is the transfer function (tf) representation of the sum u = u1 + u2 + u3. That is, S is a static-gain tf with three inputs and one output, which is equal to the sum of the inputs. The transfer function S gets its input and output names from the formula.

S.OutputName

ans = 1x1 cell array
    {'u'}

S.InputName

ans = 3x1 cell
    {'u1'}
    {'u2'}
    {'u3'}

Therefore, you can use S with the name-based syntax of the connect command to build aggregate models such as the system of the following block diagram.

To do so, create LTI models for H1, H2, and H3, and name their inputs and outputs according to the diagram. For this example, use transfer functions.

H1 = tf(1,[1 2],"InputName","z1","OutputName","u1");
H2 = tf([1 -2],[1 1],"InputName","z2","OutputName","u2");
H3 = tf(2,[2 1],"InputName","u","OutputName","u3");

Connect the models and the summing junction to create an aggregate model with inputs z1 and z2 and output u. The connect command automatically connects the outputs of the components to inputs with matching names.

T = connect(H1,H2,H3,S,{"z1","z2"},{"u"});
T.InputName

ans = 2x1 cell
    {'z1'}
    {'z2'}

T.OutputName

ans = 1x1 cell array
    {'u'}

Summing Junction with Vector-Valued Signals

Create the summing junction v = u - d where u, d, v are vector-valued signals of length 2. This summing junction is shown in the following diagram, where each arrow represents two signals.

This summing junction outputs v(1) = u(1) - d(1) and v(2) = u(2) - d(2). To create this junction using sumblk, specify both the formula and the signal length.

S = sumblk('v = u - d',2);
size(S)

Transfer function with 2 outputs and 4 inputs.

The result is a transfer function with four inputs and two outputs: two inputs each for d and u, and two outputs for v. sumblk automatically performs vector expansion of the signal names and assigns them to S.InputName and S.OutputName.

S.InputName

ans = 4x1 cell
    {'u(1)'}
    {'u(2)'}
    {'d(1)'}
    {'d(2)'}

S.OutputName

ans = 2x1 cell
    {'v(1)'}
    {'v(2)'}

You can connect S to other dynamic system models to build aggregate models, as you would use any other MIMO transfer function. For instance, suppose that you want to create a model representing the following two-channel feedback loop, that is, a feedback loop in which each line in the diagram represents two signals.

Create two-input, two-output models for H1 and H2, and set their InputName and OutputName properties as indicated by the diagram. For this example, use random state-space models.

H1 = rss(3,2,2);
H1.InputName = 'v';
H1.OutputName = 'w';

H2 = rss(3,2,2);
H2.InputName = 'w';
H2.OutputName = 'd';

Note that the signal names in the dynamic system models are automatically expanded, just as sumblk expands the signal names of S. For instance, examine the outputs of H1.

H1.OutputName 

ans = 2x1 cell
    {'w(1)'}
    {'w(2)'}

The connect command also performs this expansion. Thus, you can assemble the aggregate system with the following command.

T = connect(S,H1,H2,'u','w');
size(T)

State-space model with 2 outputs, 2 inputs, and 6 states.

Specify Individual Names in Summing Junction with Vector-Valued Signals

As shown in the example Summing Junction with Vector-Valued Signals, when you create a summing junction for vector signals, by default sumblk appends an index to the signal names that you provide. If you need to specify distinct signal names instead of this vector expansion, use a placeholder in the summing-junction formula to represent the signals you want to name. Then, use the signames input argument to provide the specific names to substitute for the placeholder in creating the summing junction.

For instance, create a summing junction having the following formula.

$$\begin{array}{l}e\left(1\right)=setpoint\left(1\right)-alpha\\ e\left(2\right)=setpoint\left(2\right)-q\end{array}$$

This formula is the summing junction shown in the following diagram, where setpoint represents two inputs and e represents two outputs.

To create this summing junction, allow sumblk to expand e and setpoint, but use a signal name beginning with % as a placeholder for the specific signal names you provide in the signames argument.

formula = 'e = setpoint - %y';
signames = ["alpha","q"];
S = sumblk(formula,signames);

sumblk replaces the placeholder %y with the signal names alpha and q and expands the other signal names. Note that sumblk takes the size of the vector signals from the number of signals in signames. Thus, the setpoint input and e output of S each contain two signals.

S.InputName

ans = 4x1 cell
    {'setpoint(1)'}
    {'setpoint(2)'}
    {'alpha'      }
    {'q'          }

S.OutputName

ans = 2x1 cell
    {'e(1)'}
    {'e(2)'}

This syntax is particularly useful when you want to create a summing junction to connect existing models whose InputName or OutputName properties are already set. For instance, consider the following two-input, two-output state-space model.

A = [-0.004 0.03; 0.03 -0.19];
B = [0.3 0.2; -0.06 0];
C = [0.99 0.5; 0 0];
D = 0;
G = ss(A,B,C,D);
G.InputName = {'angle','rate'};
G.OutputName = {'current','temp'};

Create a summing junction that subtracts the outputs of G from a pair of reference inputs, such that

$$\begin{array}{l}e\left(1\right)=ref\left(1\right)-current\\ e\left(2\right)=ref\left(2\right)-temp\end{array}$$

To do so, use a placeholder for these signals in the formula. Then, use G.OutputName as the signames input.

S = sumblk('e = ref - %outputs',G.OutputName);
S.InputName

ans = 4x1 cell
    {'ref(1)' }
    {'ref(2)' }
    {'current'}
    {'temp'   }

You can use multiple placeholders to replace multiple elements of the formula. sumblk replaces the placeholders in the order you provide them. For instance, give the reference signals specific names instead of ref(1) and ref(2).

refnames = ["refcur","reftemp"];
S = sumblk('e = %refs - %outputs',refnames,G.OutputName);
S.InputName

ans = 4x1 cell
    {'refcur' }
    {'reftemp'}
    {'current'}
    {'temp'   }

Input Arguments

formula — Equation relating input and output signals of summing junction

string | character vector

Equation that relates the input and output signals of the summing junction transfer function S, specified as a string or character vector. For example, consider the summing junction of the following diagram.

To represent this summing junction as a three-input, one-output transfer function, use the following commands.

formula = "e = r + d - y";
S = sumblk(formula);

For vector-valued signals, you can optionally use one or more placeholders in formula to control the names that sumblk assigns to S.InputName and S.OutputName. To put a placeholder in formula, use a signal name that begins with %. When assigning signal names to S, the sumblk command replaces each placeholder with the names you provide in the signames argument.

Such placeholders are particularly useful for creating summing junctions for connecting existing models that have named signals. For example, if C and G are dynamic system models with nonempty InputName and OutputName properties, respectively, you can create a summing junction using the following expression.

S = sumblk("%e = r - %y",C.InputName,G.OutputName)

sumblk uses the values of C.InputName and G.OutputName in place of %e and %y, respectively. The vector dimension of C.InputName and G.OutputName must match. sumblk assigns the signal r the same dimension. For an example, see Specify Individual Names in Summing Junction with Vector-Valued Signals.

signalsize — Number of elements in each signal

1 (default) | positive integer

Number of elements in each input and output signal of S, specified as a positive integer. Setting signalsize greater than 1 lets you specify a summing junction that operates on vector-valued signals. For instance, S = sumblk("e = r - y",2) creates a summing junction where each of the inputs r and y and the output e is a vector signal with two elements. See Summing Junction with Vector-Valued Signals.

signames — Substitute signal names for a placeholder

string array | cell array of character vectors

Substitute signal names for a placeholder (signal name beginning with %) in the argument formula, specified as a string array or a cell array of character vectors. Provide one signames argument for each placeholder in formula.

Specify signames as:

• A string array, such as ["alpha","q"].

• A cell array of signal names, such as {'alpha','q'}.

• The InputName or OutputName property of a model in the MATLAB^® workspace. For example:

  S = sumblk("%e = r - y",C.InputName)

  This command creates a summing junction whose outputs have the same name as the inputs of the model C in the MATLAB workspace. For an example showing how to use signames, see Specify Individual Names in Summing Junction with Vector-Valued Signals.

  If you use placeholders and the signames argument, then sumblk sets the vector length of the signals of S. If you use multiple placeholders, then all signames arguments must have the same number of signals.

Output Arguments

S — Transfer function for summing junction

tf model

Transfer function for the summing junction, returned as a tf model.

sumblk sets the InputName and OutputName properties of S using the signal names in formula. For instance, if you enter S = sumblk("e = r + d - y"), then sumblk creates S with S.InputName = {'r';'d';'y'} and S.OutputName = {'e'}. Use these input and output names to interconnect S with other dynamic system models to build composite systems. For an example, see Summing Junction with Scalar-Valued Signals.

If signalsize is greater than 1, then S has signalsize inputs (or outputs) per signal name in formula. The function sets S.InputName and S.OutputName by applying vector expansion to the signal name specified in formula, such as {'e(1)','e(2)',...}. For an example, see Summing Junction with Vector-Valued Signals.

If you use placeholders in formula, then sumblk sets the InputName and OutputName properties of S using the names you provide in signames. For an example, see Specify Individual Names in Summing Junction with Vector-Valued Signals.

Version History

Introduced in R2008a