Documentation |
Use the TuningGoal.Poles object to specify a tuning requirement for constraining the closed-loop dynamics of a control system or of specific feedback loops within the control system. You can use this requirement for control system tuning with tuning commands, such as systune or looptune. A TuningGoal.Poles requirement can ensure a minimum decay rate or minimum damping of the poles of the control system or loop. The requirement can also eliminate fast dynamics in the tuned system.
Req = TuningGoal.Poles(mindecay,mindamping,maxfreq) creates a default template for constraining the closed-loop pole locations. The minimum decay rate, minimum damping constant, and maximum natural frequency define a region of the complex plane in which poles of the component must lie. Set mindecay = 0, mindamping = 0, or maxfreq = Inf to skip any of the three constraints.
Req = TuningGoal.Poles(location,mindecay,mindamping,maxfreq) constrains the poles of the sensitivity function measured at a specified location in the control system. (See getSensitivity for information about sensitivity functions.) Use this syntax to narrow the scope of the requirement to a particular feedback loop.
If you want to constrain the poles of the system with one or more feedback loops opened, set the Openings property. To limit the enforcement of this requirement to poles having natural frequency within a specified frequency range, set the Focus property. (See Properties.)
mindecay |
Minimum decay rate of poles of tunable component, specified as a nonnegative scalar value in the frequency units of the control system model you are tuning. When you tune the control system using this requirement, the closed-loop poles of the control system are constrained to satisfy:
Set mindecay = 0 to impose no constraint on the decay rate. |
mindamping |
Desired minimum damping ratio of the closed-loop poles, specified as a value between 0 and 1. Poles that depend on the tunable parameters are constrained to satisfy Re(s) < -mindamping*|s|. In discrete time, the damping ratio is computed using s=log(z)/Ts. Set mindamping = 0 to impose no constraint on the damping ratio. |
maxfreq |
Desired maximum natural frequency of closed-loop poles, specified as a scalar value in the frequency units of the control system model you are tuning. Poles are constrained to satisfy |s| < maxfreq for continuous time, or |log(z)| < maxfreq*Ts for discrete-time systems with sample time Ts. This constraint prevents fast dynamics in the closed-loop system. Set maxfreq = Inf to impose no constraint on the natural frequency. |
location |
Location at which poles are assessed, specified as a string or cell array of strings. When you use this input, the requirement constrains the poles of the sensitivity function measured at this location. (See getSensitivity for information about sensitivity functions.) What locations are available depends on what kind of system you are tuning:
If location is a cell array, then the sensitivity requirement applies to the MIMO loop. |
MinDecay |
Minimum decay rate of closed-loop poles of tunable component, specified as a positive scalar value in the frequency units of the control system you are tuning. The initial value of this property is set by the mindecay input argument. When you tune the control system using this requirement, closed-loop poles are constrained to satisfy Re(s) < -MinDecay for continuous-time systems, or log(|z|) < -MinDecay*Ts for discrete-time systems with sample time Ts. You can use dot notation to change the value of this property after you create the requirement. For example, suppose Req is a TuningGoal.Poles requirement. Change the minimum decay rate to 0.001: Req.MinDecay = 0.001; Default: 0 |
MinDamping |
Desired minimum damping ratio of closed-loop poles, specified as a value between 0 and 1. The initial value of this property is set by the mindamping input argument. Poles that depend on the tunable parameters are constrained to satisfy Re(s) < -MinDamping*|s|. In discrete time, the damping ratio is computed using s=log(z)/Ts. Default: 0 |
MaxFrequency |
Desired maximum natural frequency of closed-poles, specified as a scalar value in the frequency units of the control system model you are tuning. The initial value of this property is set by the maxfreq input argument. Poles of the block are constrained to satisfy |s| < maxfreq for continuous-time systems, or |log(z)| < maxfreq*Ts for discrete-time systems with sample time Ts. This constraint prevents fast dynamics in the tuned control system. You can use dot notation to change the value of this property after you create the requirement. For example, suppose Req is a TuningGoal.ControllerPoles requirement. Change the maximum frequency to 1000: Req.MaxFrequency = 1000; Default: Inf |
Focus |
Frequency band in which tuning requirement is enforced, specified as a row vector of the form [min,max]. Set the Focus property to limit enforcement of the requirement 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 requirement that you want to apply only between 1 and 100 rad/s. To restrict the requirement 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 sampling time. |
Location |
Location at which poles are assessed, specified as a string or cell array of strings that identify one or more analysis-point locations in the control system to tune. The value of the Location property is set by the location input argument when you create the TuningGoal.Poles requirement. |
Models |
Models to which the tuning requirement 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 requirement for a subset of models in the array. For example, suppose you want to apply the tuning requirement, Req, to the second, third, and fourth models in a model array passed to systune. To restrict enforcement of the requirement, use the following command: Req.Models = 2:4; When Models = NaN, the tuning requirement applies to all models. Default: NaN |
Openings |
Feedback loops to open when evaluating the requirement, specified as a cell array of strings that identify loop-opening locations. The tuning requirement is evaluated against the open-loop configuration created by opening feedback loops at the locations you identify. If you are using the requirement 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 requirement 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. Default: {} |
Name |
Name of the requirement object, specified as a string. For example, if Req is a requirement: Req.Name = 'LoopReq'; Default: [] |
TuningGoal.Poles restricts the closed-loop dynamics of the tuned control system. To constrain the dynamics or ensure the stability of a single tunable component, use TuningGoal.ControllerPoles.
When you use a TuningGoal object to specify a tuning requirement, the software converts the requirement into a normalized scalar value f(x). 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 requirement is a hard constraint.
For TuningGoal.Poles, f(x) reflects the relative satisfaction or violation of the goal. For example, if you attempt to constrain the closed-loop poles of a feedback loop to a minimum damping of ζ = 0.5, then:
f(x) = 1 means the smallest damping among the constrained poles is ζ = 0.5 exactly.
f(x) = 1.1 means the smallest damping ζ = 0.5/1.1 = 0.45, roughly 10% less than the target.
f(x) = 0.9 means the smallest damping ζ = 0.5/0.9 = 0.55, roughly 10% better than the target.