octave_packages/control-2.3.52/@frd/frd.m

   1 ## Copyright (C) 2010, 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{sys} =} frd (@var{sys})
  20 ## @deftypefnx {Function File} {@var{sys} =} frd (@var{sys}, @var{w})
  21 ## @deftypefnx {Function File} {@var{sys} =} frd (@var{H}, @var{w}, @dots{})
  22 ## @deftypefnx {Function File} {@var{sys} =} frd (@var{H}, @var{w}, @var{tsam}, @dots{})
  23 ## Create or convert to frequency response data.
  24 ##
  25 ## @strong{Inputs}
  26 ## @table @var
  27 ## @item sys
  28 ## LTI model to be converted to frequency response data.
  29 ## If second argument @var{w} is omitted, the interesting
  30 ## frequency range is calculated by the zeros and poles of @var{sys}.
  31 ## @item H
  32 ## Frequency response array (p-by-m-by-lw).  H(i,j,k) contains the
  33 ## response from input j to output i at frequency k.  In the SISO case,
  34 ## a vector (lw-by-1) or (1-by-lw) is accepted as well.
  35 ## @item w
  36 ## Frequency vector (lw-by-1) in radian per second [rad/s].
  37 ## Frequencies must be in ascending order.
  38 ## @item tsam
  39 ## Sampling time in seconds.  If @var{tsam} is not specified,
  40 ## a continuous-time model is assumed.
  41 ## @item @dots{}
  42 ## Optional pairs of properties and values.
  43 ## Type @command{set (frd)} for more information.
  44 ## @end table
  45 ##
  46 ## @strong{Outputs}
  47 ## @table @var
  48 ## @item sys
  49 ## Frequency response data object.
  50 ## @end table
  51 ##
  52 ## @seealso{dss, ss, tf}
  53 ## @end deftypefn
  54
  55 ## Author: Lukas Reichlin <lukas.reichlin@gmail.com>
  56 ## Created: February 2010
  57 ## Version: 0.1
  58
  59 function sys = frd (H = [], w = [], varargin)
  60
  61   ## NOTE: * There's no such thing as a static gain
  62   ##         because FRD objects are measurements,
  63   ##         not models.
  64   ##       * If something like  sys1 = frd (5)  existed,
  65   ##         it would cause troubles in cases like
  66   ##         sys2 = ss (...), sys = sys1 * sys2
  67   ##         because sys2 needs to be converted to FRD,
  68   ##         but sys1 contains no valid frequencies.
  69   ##       * However, things like  frd (ss (5))  should
  70   ##         be possible.
  71
  72   ## model precedence: frd > ss > zpk > tf > double
  73   superiorto ("ss", "zpk", "tf", "double");
  74
  75   argc = 0;                             # initialize argument count
  76
  77   switch (nargin)
  78     case 0                              # empty object  sys = frd ()
  79       tsam = -2;                        # undefined sampling time
  80
  81     case 1
  82       if (isa (H, "frd"))               # already in frd form  sys = frd (frdsys)
  83         sys = H;
  84         return;                         # nothing more to do here
  85       elseif (isa (H, "lti"))           # another lti object  sys = frd (sys)
  86         [sys, alti] = __sys2frd__ (H);
  87         sys.lti = alti;                 # preserve lti properties
  88         return;                         # nothing more to do here
  89       else                              # sys = frd (H)  *must* fail
  90         print_usage ();
  91       endif
  92
  93     case 2
  94       if (isa (H, "lti"))               # another lti object  sys = frd (sys, w)
  95         [sys, alti] = __sys2frd__ (H, w);
  96         sys.lti = alti;                 # preserve lti properties
  97         return;                         # nothing more to do here
  98       else                              # sys = frd (H, w)
  99         tsam = 0;                       # continuous-time
 100       endif
 101
 102     otherwise                           # default case
 103       argc = numel (varargin);          # number of additional arguments after H and w
 104       if (issample (varargin{1}, -10))  # sys = frd (H, w, tsam, "prop1", val1, ...)
 105         tsam = varargin{1};             # sampling time, could be 0 as well
 106         argc--;                         # tsam is not a property-value pair
 107         if (argc > 0)                   # if there are any properties and values ...
 108           varargin = varargin(2:end);   # remove tsam from property-value list
 109         endif
 110       else                              # sys = frd (H, w, "prop1", val1, ...)
 111         tsam = 0;                       # continuous-time
 112       endif
 113   endswitch
 114
 115   [H, w] = __adjust_frd_data__ (H, w);
 116   [p, m] = __frd_dim__ (H, w);          # determine number of outputs and inputs
 117
 118   frdata = struct ("H", H, "w", w);     # struct for frd-specific data
 119   ltisys = lti (p, m, tsam);            # parent class for general lti data
 120
 121   sys = class (frdata, "frd", ltisys);  # create frd object
 122
 123   if (argc > 0)                         # if there are any properties and values, ...
 124     sys = set (sys, varargin{:});       # use the general set function
 125   endif
 126
 127 endfunction