octave_packages/control-2.3.52/spaconred.m

   1 ## Copyright (C) 2011   Lukas F. Reichlin
   2 ##
   3 ## This file is part of LTI Syncope.
   4 ##
   5 ## LTI Syncope is free software: you can redistribute it and/or modify
   6 ## it under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation, either version 3 of the License, or
   8 ## (at your option) any later version.
   9 ##
  10 ## LTI Syncope is distributed in the hope that it will be useful,
  11 ## but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 ## GNU General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with LTI Syncope.  If not, see <http://www.gnu.org/licenses/>.
  17
  18 ## -*- texinfo -*-
  19 ## @deftypefn{Function File} {[@var{Kr}, @var{info}] =} spaconred (@var{G}, @var{K}, @dots{})
  20 ## @deftypefnx{Function File} {[@var{Kr}, @var{info}] =} spaconred (@var{G}, @var{K}, @var{ncr}, @dots{})
  21 ## @deftypefnx{Function File} {[@var{Kr}, @var{info}] =} spaconred (@var{G}, @var{K}, @var{opt}, @dots{})
  22 ## @deftypefnx{Function File} {[@var{Kr}, @var{info}] =} spaconred (@var{G}, @var{K}, @var{ncr}, @var{opt}, @dots{})
  23 ##
  24 ## Controller reduction by frequency-weighted Singular Perturbation Approximation (SPA).
  25 ## Given a plant @var{G} and a stabilizing controller @var{K}, determine a reduced
  26 ## order controller @var{Kr} such that the closed-loop system is stable and closed-loop
  27 ## performance is retained.
  28 ##
  29 ## The algorithm tries to minimize the frequency-weighted error
  30 ## @iftex
  31 ## @tex
  32 ## $$ || V \\ (K - K_r) \\ W ||_{\\infty} = min $$
  33 ## @end tex
  34 ## @end iftex
  35 ## @ifnottex
  36 ## @example
  37 ## ||V (K-Kr) W||    = min
  38 ##               inf
  39 ## @end example
  40 ## @end ifnottex
  41 ## where @var{V} and @var{W} denote output and input weightings.
  42 ##
  43 ##
  44 ## @strong{Inputs}
  45 ## @table @var
  46 ## @item G
  47 ## LTI model of the plant.
  48 ## It has m inputs, p outputs and n states.
  49 ## @item K
  50 ## LTI model of the controller.
  51 ## It has p inputs, m outputs and nc states.
  52 ## @item ncr
  53 ## The desired order of the resulting reduced order controller @var{Kr}.
  54 ## If not specified, @var{ncr} is chosen automatically according
  55 ## to the description of key @var{'order'}.
  56 ## @item @dots{}
  57 ## Optional pairs of keys and values.  @code{"key1", value1, "key2", value2}.
  58 ## @item opt
  59 ## Optional struct with keys as field names.
  60 ## Struct @var{opt} can be created directly or
  61 ## by command @command{options}.  @code{opt.key1 = value1, opt.key2 = value2}.
  62 ## @end table
  63 ##
  64 ## @strong{Outputs}
  65 ## @table @var
  66 ## @item Kr
  67 ## State-space model of reduced order controller.
  68 ## @item info
  69 ## Struct containing additional information.
  70 ## @table @var
  71 ## @item info.ncr
  72 ## The order of the obtained reduced order controller @var{Kr}.
  73 ## @item info.ncs
  74 ## The order of the alpha-stable part of original controller @var{K}.
  75 ## @item info.hsvc
  76 ## The Hankel singular values of the alpha-stable part of @var{K}.
  77 ## The @var{ncs} Hankel singular values are ordered decreasingly.
  78 ## @end table
  79 ## @end table
  80 ##
  81 ## @strong{Option Keys and Values}
  82 ## @table @var
  83 ## @item 'order', 'ncr'
  84 ## The desired order of the resulting reduced order controller @var{Kr}.
  85 ## If not specified, @var{ncr} is chosen automatically such that states with
  86 ## Hankel singular values @var{info.hsvc} > @var{tol1} are retained.
  87 ##
  88 ## @item 'method'
  89 ## Order reduction approach to be used as follows:
  90 ## @table @var
  91 ## @item 'sr', 's'
  92 ## Use the square-root Singular Perturbation Approximation method.
  93 ## @item 'bfsr', 'p'
  94 ## Use the balancing-free square-root Singular Perturbation Approximation method.  Default method.
  95 ## @end table
  96 ##
  97 ## @item 'weight'
  98 ## Specifies the type of frequency-weighting as follows:
  99 ## @table @var
 100 ## @item 'none'
 101 ## No weightings are used (V = I, W = I).
 102 ##
 103 ## @item 'left', 'output'
 104 ## Use stability enforcing left (output) weighting
 105 ## @iftex
 106 ## @tex
 107 ## $$ V = (I - G K)^{-1} G,  \\qquad W = I $$
 108 ## @end tex
 109 ## @end iftex
 110 ## @ifnottex
 111 ## @example
 112 ##           -1
 113 ## V = (I-G*K) *G ,  W = I
 114 ## @end example
 115 ## @end ifnottex
 116 ##
 117 ## @item 'right', 'input'
 118 ## Use stability enforcing right (input) weighting
 119 ## @iftex
 120 ## @tex
 121 ## $$ V = I,  \\qquad W = (I - G K)^{-1} G  $$
 122 ## @end tex
 123 ## @end iftex
 124 ## @ifnottex
 125 ## @example
 126 ##                    -1
 127 ## V = I ,  W = (I-G*K) *G
 128 ## @end example
 129 ## @end ifnottex
 130 ##
 131 ## @item 'both', 'performance'
 132 ## Use stability and performance enforcing weightings
 133 ## @iftex
 134 ## @tex
 135 ## $$ V = (I - G K)^{-1} G,  \\qquad W = (I - G K)^{-1}  $$
 136 ## @end tex
 137 ## @end iftex
 138 ## @ifnottex
 139 ## @example
 140 ##           -1                -1
 141 ## V = (I-G*K) *G ,  W = (I-G*K)
 142 ## @end example
 143 ## @end ifnottex
 144 ## Default value.
 145 ## @end table
 146 ##
 147 ## @item 'feedback'
 148 ## Specifies whether @var{K} is a positive or negative feedback controller:
 149 ## @table @var
 150 ## @item '+'
 151 ## Use positive feedback controller.  Default value.
 152 ## @item '-'
 153 ## Use negative feedback controller.
 154 ## @end table
 155 ##
 156 ## @item 'alpha'
 157 ## Specifies the ALPHA-stability boundary for the eigenvalues
 158 ## of the state dynamics matrix @var{K.A}.  For a continuous-time
 159 ## controller, ALPHA <= 0 is the boundary value for
 160 ## the real parts of eigenvalues, while for a discrete-time
 161 ## controller, 0 <= ALPHA <= 1 represents the
 162 ## boundary value for the moduli of eigenvalues.
 163 ## The ALPHA-stability domain does not include the boundary.
 164 ## Default value is 0 for continuous-time controllers and
 165 ## 1 for discrete-time controllers.
 166 ##
 167 ## @item 'tol1'
 168 ## If @var{'order'} is not specified, @var{tol1} contains the tolerance for
 169 ## determining the order of the reduced controller.
 170 ## For model reduction, the recommended value of @var{tol1} is
 171 ## c*info.hsvc(1), where c lies in the interval [0.00001, 0.001].
 172 ## Default value is info.ncs*eps*info.hsvc(1).
 173 ## If @var{'order'} is specified, the value of @var{tol1} is ignored.
 174 ##
 175 ## @item 'tol2'
 176 ## The tolerance for determining the order of a minimal
 177 ## realization of the ALPHA-stable part of the given
 178 ## controller.  TOL2 <= TOL1.
 179 ## If not specified, ncs*eps*info.hsvc(1) is chosen.
 180 ##
 181 ## @item 'gram-ctrb'
 182 ## Specifies the choice of frequency-weighted controllability
 183 ## Grammian as follows:
 184 ## @table @var
 185 ## @item 'standard'
 186 ## Choice corresponding to standard Enns' method [1].  Default method.
 187 ## @item 'enhanced'
 188 ## Choice corresponding to the stability enhanced
 189 ## modified Enns' method of [2].
 190 ## @end table
 191 ##
 192 ## @item 'gram-obsv'
 193 ## Specifies the choice of frequency-weighted observability
 194 ## Grammian as follows:
 195 ## @table @var
 196 ## @item 'standard'
 197 ## Choice corresponding to standard Enns' method [1].  Default method.
 198 ## @item 'enhanced'
 199 ## Choice corresponding to the stability enhanced
 200 ## modified Enns' method of [2].
 201 ## @end table
 202 ##
 203 ## @item 'equil', 'scale'
 204 ## Boolean indicating whether equilibration (scaling) should be
 205 ## performed on @var{G} and @var{K} prior to order reduction.
 206 ## Default value is false if both @code{G.scaled == true, K.scaled == true}
 207 ## and true otherwise.
 208 ## Note that for @acronym{MIMO} models, proper scaling of both inputs and outputs
 209 ## is of utmost importance.  The input and output scaling can @strong{not}
 210 ## be done by the equilibration option or the @command{prescale} command
 211 ## because these functions perform state transformations only.
 212 ## Furthermore, signals should not be scaled simply to a certain range.
 213 ## For all inputs (or outputs), a certain change should be of the same
 214 ## importance for the model.
 215 ## @end table
 216 ##
 217 ## @strong{Algorithm}@*
 218 ## Uses SLICOT SB16AD by courtesy of
 219 ## @uref{http://www.slicot.org, NICONET e.V.}
 220 ## @end deftypefn
 221
 222 ## Author: Lukas Reichlin <lukas.reichlin@gmail.com>
 223 ## Created: December 2011
 224 ## Version: 0.1
 225
 226 function [Kr, info] = spaconred (varargin)
 227
 228   [Kr, info] = __conred_sb16ad__ ("spa", varargin{:});
 229
 230 endfunction
 231
 232 ## TODO: add a test