# TuningGoal.Passivity class

Package: TuningGoal

Passivity constraint for control system tuning

## Description

A system is passive if all its I/O trajectories (u(t),y(t)) satisfy:

`${\int }_{0}^{T}y{\left(t\right)}^{T}u\left(t\right)dt>0,$`

for all T > 0. Equivalently, a system is passive if its frequency response is positive real, which means that for all ω > 0,

`$G\left(j\omega \right)+G{\left(j\omega \right)}^{H}>0$`

Use `TuningGoal.Passivity` to enforce passivity of the response between specified inputs and outputs, when using a control system tuning command such as `systune`. You can also use `TuningGoal.Passivity` to ensure a particular excess or shortage of passivity (see `getPassiveIndex`).

## Construction

`Req = TuningGoal.Passivity(inputname,outputname)` creates a tuning goal for enforcing passivity of the response from the specified inputs to the specified outputs.

`Req = TuningGoal.Passivity(inputname,outputname,nu,rho)` creates a tuning goal for enforcing:

`${\int }_{0}^{T}y{\left(t\right)}^{T}u\left(t\right)dt>\nu {\int }_{0}^{T}u{\left(t\right)}^{T}u\left(t\right)dt+\rho {\int }_{0}^{T}y{\left(t\right)}^{T}y\left(t\right)dt,$`

for all T > 0. This tuning goal enforces an excess of passivity at the inputs or outputs when `nu > 0` or `rho > 0`, respectively. The tuning goal allows for a shortage of input passivity when `nu < 0`. See `getPassiveIndex` for more information about these indices.

### Input Arguments

 `inputname` Input signals for the tuning goal, specified as a character vector or, for multiple-input tuning goals, a cell array of character vectors. If you are using the tuning goal to tune a Simulink® model of a control system, then `inputname` can include:Any model input.Any linear analysis point marked in the model.Any linear analysis point in an `slTuner` interface associated with the Simulink model. Use `addPoint` to add analysis points to the `slTuner` interface. Use `getPoints` to get the list of analysis points available in an `slTuner` interface to your model. For example, suppose that the `slTuner` interface contains analysis points `u1` and `u2`. Use `'u1'` to designate that point as an input signal when creating tuning goals. Use `{'u1','u2'}` to designate a two-channel input. If you are using the tuning goal to tune a generalized state-space (`genss`) model of a control system, then `inputname` can include: Any input of the `genss` model Any `AnalysisPoint` location in the control system modelFor example, if you are tuning a control system model, `T`, then `inputname` can be any input name in `T.InputName`. Also, if `T` contains an `AnalysisPoint` block with a location named `AP_u`, then `inputname` can include `'AP_u'`. Use `getPoints` to get a list of analysis points available in a `genss` model.If `inputname` is an `AnalysisPoint` location of a generalized model, the input signal for the tuning goal is the implied input associated with the `AnalysisPoint` block: For more information about analysis points in control system models, see Mark Signals of Interest for Control System Analysis and Design. `outputname` Output signals for the tuning goal, specified as a character vector or, for multiple-output tuning goals, a cell array of character vectors. If you are using the tuning goal to tune a Simulink model of a control system, then `outputname` can include:Any model output.Any linear analysis point marked in the model.Any linear analysis point in an `slTuner` interface associated with the Simulink model. Use `addPoint` to add analysis points to the `slTuner` interface. Use `getPoints` to get the list of analysis points available in an `slTuner` interface to your model. For example, suppose that the `slTuner` interface contains analysis points `y1` and `y2`. Use `'y1'` to designate that point as an output signal when creating tuning goals. Use `{'y1','y2'}` to designate a two-channel output. If you are using the tuning goal to tune a generalized state-space (`genss`) model of a control system, then `outputname` can include: Any output of the `genss` model Any `AnalysisPoint` location in the control system modelFor example, if you are tuning a control system model, `T`, then `outputname` can be any output name in `T.OutputName`. Also, if `T` contains an `AnalysisPoint` block with a location named `AP_u`, then `outputname` can include `'AP_u'`. Use `getPoints` to get a list of analysis points available in a `genss` model.If `outputname` is an `AnalysisPoint` location of a generalized model, the output signal for the tuning goal is the implied output associated with the `AnalysisPoint` block: For more information about analysis points in control system models, see Mark Signals of Interest for Control System Analysis and Design. `nu` Target passivity at the inputs listed in `inputname`, specified as a scalar value. The input passivity index is defined as the largest value of ν for which: `${\int }_{0}^{T}y{\left(t\right)}^{T}u\left(t\right)dt>\nu {\int }_{0}^{T}u{\left(t\right)}^{T}u\left(t\right)dt,$` for all T > 0. Equivalently, `nu` is the largest ν for which: `$G\left(j\omega \right)+G{\left(j\omega \right)}^{H}>2\nu I$` When you set a target `nu` in a `TuningGoal.Passivity` goal, the tuning software: Ensures that the specified response is input strictly passive when `nu` > 0. The magnitude of `nu` sets the required excess of passivity.Allows the response to be not input strictly passive when `nu` < 0. The magnitude of `nu` sets the permitted shortage of passivity. Default: 0 `rho` Target passivity at the outputs listed in `outputname`, specified as a scalar value. The output passivity index is defined as the largest value of ρ for which: `${\int }_{0}^{T}y{\left(t\right)}^{T}u\left(t\right)dt>\rho {\int }_{0}^{T}y{\left(t\right)}^{T}y\left(t\right)dt,$` for all T > 0. When you set a target `rho` in a `TuningGoal.Passivity` goal, the tuning software: Ensures that the specified response is output strictly passive when `rho` > 0. The magnitude of `rho` sets the required excess of passivity.Allows the response to be not output strictly passive when `rho` < 0. The magnitude of `rho` sets the permitted shortage of passivity. Default: 0

## Properties

 `IPX` Target passivity at the inputs, stored as a scalar value. This value specifies the required amount of passivity at the inputs listed in `inputname`. The initial value of this property is set by the input argument `nu` when you create the `TuningGoal.Passivity` goal. Default: 0 `OPX` Target passivity at the outputs, stored as a scalar value. This value specifies the required amount of passivity at the outputs listed in `outputname` The initial value of this property is set by the input argument `rho` when you create the `TuningGoal.Passivity` goal. Default: 0 `Focus` Frequency band in which tuning goal is enforced, specified as a row vector of the form `[min,max]`. Set the `Focus` property to limit enforcement of the tuning goal to a particular frequency band. Express this value in the frequency units of the control system model you are tuning (rad/`TimeUnit`). For example, suppose `Req` is a tuning goal that you want to apply only between 1 and 100 rad/s. To restrict the tuning goal to this band, use the following command:`Req.Focus = [1,100];` Default: `[0,Inf]` for continuous time; `[0,pi/Ts]` for discrete time, where `Ts` is the model sample time. `Input` Input signal names, specified as a cell array of character vectors. The input signal names specify the input locations for determining passivity, initially populated by the `inputname` argument. `Output` Output signal names, specified as a cell array of character vectors. The output signal names specify the output locations for determining passivity, initially populated by the `outputname` argument. `Models` Models to which the tuning goal applies, specified as a vector of indices. Use the `Models` property when tuning an array of control system models with `systune`, to enforce a tuning goal for a subset of models in the array. For example, suppose you want to apply the tuning goal, `Req`, to the second, third, and fourth models in a model array passed to `systune`. To restrict enforcement of the tuning goal, use the following command: `Req.Models = 2:4;` When `Models = NaN`, the tuning goal applies to all models. Default: `NaN` `Openings` Feedback loops to open when evaluating the tuning goal, specified as a cell array of character vectors that identify loop-opening locations. The tuning goal is evaluated against the open-loop configuration created by opening feedback loops at the locations you identify. If you are using the tuning goal to tune a Simulink model of a control system, then `Openings` can include any linear analysis point marked in the model, or any linear analysis point in an `slTuner` interface associated with the Simulink model. Use `addPoint` to add analysis points and loop openings to the `slTuner` interface. Use `getPoints` to get the list of analysis points available in an `slTuner` interface to your model. If you are using the tuning goal to tune a generalized state-space (`genss`) model of a control system, then `Openings` can include any `AnalysisPoint` location in the control system model. Use `getPoints` to get the list of analysis points available in the `genss` model. For example, if `Openings = {'u1','u2'}`, then the tuning goal is evaluated with loops open at analysis points `u1` and `u2`. Default: `{}` `Name` Name of the tuning goal, specified as a character vector. For example, if `Req` is a tuning goal: `Req.Name = 'LoopReq';` Default: `[]`

## Examples

collapse all

Create a requirement that ensures passivity in the response from an input or analysis point `'u'` to an output or analysis point `'y'` in a control system.

`TG = TuningGoal.Passivity('u','y');`

Use `viewGoal` to visualize the tuning goal.

`viewGoal(TG)`

The requirement is satisfied when the relative passivity index R < 1 at all frequencies. The shaded area represents the region where the requirement is violated. When you use this requirement to tune a control system `CL`, `viewGoal(TG,CL)` shows R for the specified inputs and outputs on this plot, enabling you to identify frequency ranges in which the passivity requirement is violated.

Create a requirement that ensures that the response from an input `'u'` to an output `'y'` is input strictly passive, with an excess of passivity of 2.

`TGi = TuningGoal.Passivity('u','y',2,0);`

Restrict the requirement to apply only within the frequency range between 0 and 10 rad/s.

`TGi.Focus = [0 10];`

## Tips

• Use `viewGoal` to visualize this tuning goal. For enforcing passivity with ```nu = 0``` and `rho = 0`, `viewGoal` plots the relative passivity indices as a function of frequency (see `passiveplot`). These are the singular values of $\left(I-G\left(j\omega \right)\right){\left(I-G\left(j\omega \right)\right)}^{-1}$. The transfer function G from `inputname` to `outputname` (evaluated with loops open as specified in `Openings`) is passive when the largest singular value is less than 1 at all frequencies.

For nonzero `nu` or `rho`, `viewGoal` plots the relative index as described in Algorithms.

• This tuning goal imposes an implicit minimum-phase constraint on the transfer function G + I. The transmission zeros of G + I are the stabilized dynamics for this tuning goal. The `MinDecay` and `MaxRadius` options of `systuneOptions` control the bounds on these implicitly constrained dynamics. If the optimization fails to meet the default bounds, or if the default bounds conflict with other requirements, use `systuneOptions` to change these defaults.

## Algorithms

When you tune a control system using a `TuningGoal`, the software converts the tuning goal into a normalized scalar value f(x), where x is the vector of free (tunable) parameters in the control system. The software then adjusts the parameter values to minimize f(x) or to drive f(x) below 1 if the tuning goal is a hard constraint.

For the `TuningGoal.Passivity` goal, for a closed-loop transfer function `G(s,x)` from `inputname` to `outputname`, f(x) is given by:

`$f\left(x\right)=\frac{R}{1+R/{R}_{\mathrm{max}}},\text{ }{R}_{\mathrm{max}}={10}^{6}.$`

R is the relative sector index (see `getSectorIndex`) of `[G(s,x);I]`, for the sector represented by:

`$Q=\left(\begin{array}{cc}2\rho & -I\\ -I& 2\nu \end{array}\right),$`

using the values of the `OPX` and `IPX` properties for ρ and ν, respectively.