octave_packages/control-2.3.52/filt.m

   1 ## Copyright (C) 2012   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} =} filt (@var{num}, @var{den}, @dots{})
  20 ## @deftypefnx {Function File} {@var{sys} =} filt (@var{num}, @var{den}, @var{tsam}, @dots{})
  21 ## Create discrete-time transfer function model from data in DSP format.
  22 ##
  23 ## @strong{Inputs}
  24 ## @table @var
  25 ## @item num
  26 ## Numerator or cell of numerators.  Each numerator must be a row vector
  27 ## containing the coefficients of the polynomial in ascending powers of z^-1.
  28 ## num@{i,j@} contains the numerator polynomial from input j to output i.
  29 ## In the SISO case, a single vector is accepted as well.
  30 ## @item den
  31 ## Denominator or cell of denominators.  Each denominator must be a row vector
  32 ## containing the coefficients of the polynomial in ascending powers of z^-1.
  33 ## den@{i,j@} contains the denominator polynomial from input j to output i.
  34 ## In the SISO case, a single vector is accepted as well.
  35 ## @item tsam
  36 ## Sampling time in seconds.  If @var{tsam} is not specified,
  37 ## default value -1 (unspecified) is taken.
  38 ## @item @dots{}
  39 ## Optional pairs of properties and values.
  40 ## Type @command{set (filt)} for more information.
  41 ## @end table
  42 ##
  43 ## @strong{Outputs}
  44 ## @table @var
  45 ## @item sys
  46 ## Discrete-time transfer function model.
  47 ## @end table
  48 ##
  49 ## @strong{Example}
  50 ## @example
  51 ## @group
  52 ##                 3 z^-1
  53 ## H(z^-1) = -------------------
  54 ##           1 + 4 z^-1 + 2 z^-2
  55 ##
  56 ## octave:1> H = filt ([0, 3], [1, 4, 2])
  57 ##
  58 ## Transfer function 'H' from input 'u1' to output ...
  59 ##
  60 ##             3 z^-1
  61 ##  y1:  -------------------
  62 ##       1 + 4 z^-1 + 2 z^-2
  63 ##
  64 ## Sampling time: unspecified
  65 ## Discrete-time model.
  66 ## @end group
  67 ## @end example
  68 ##
  69 ## @seealso{tf}
  70 ## @end deftypefn
  71
  72 ## Author: Lukas Reichlin <lukas.reichlin@gmail.com>
  73 ## Created: April 2012
  74 ## Version: 0.1
  75
  76 function sys = filt (num = {}, den = {}, tsam = -1, varargin)
  77
  78   switch (nargin)
  79     case 0              # filt ()
  80       sys = tf ();
  81       ## sys.inv = true;
  82       return;
  83
  84     case 1              # filt (sys), filt (matrix)
  85       if (isa (num, "lti") || is_real_matrix (num))
  86         sys = tf (num);
  87         ## sys.inv = true;  # would be a problem for continuous-time LTI models
  88         return;
  89       else
  90         print_usage ();
  91       endif
  92
  93     otherwise           # filt (num, den, ...)
  94       if (! iscell (num))
  95         num = {num};
  96       endif
  97       if (! iscell (den))
  98         den = {den};
  99       endif
 100
 101       ## convert from z^-1 to z
 102       ## expand each channel by z^x, where x is the largest exponent of z^-1 (z^-x)
 103
 104       ## remove trailing zeros
 105       ## such that polynomials are as short as possible
 106       num = cellfun (@__remove_trailing_zeros__, num, "uniformoutput", false);
 107       den = cellfun (@__remove_trailing_zeros__, den, "uniformoutput", false);
 108
 109       ## make numerator and denominator polynomials equally long
 110       ## by adding trailing zeros
 111       lnum = cellfun (@length, num, "uniformoutput", false);
 112       lden = cellfun (@length, den, "uniformoutput", false);
 113
 114       lmax = cellfun (@max, lnum, lden, "uniformoutput", false);
 115
 116       num = cellfun (@postpad, num, lmax, "uniformoutput", false);
 117       den = cellfun (@postpad, den, lmax, "uniformoutput", false);
 118
 119       ## use standard tf constructor
 120       ## sys is stored in standard z form, not z^-1
 121       ## so we can mix it with regular transfer function models
 122       ## property "inv", true displays sys in z^-1 form
 123       sys = tf (num, den, tsam, "inv", true, varargin{:});
 124   endswitch
 125
 126 endfunction
 127
 128 %!shared num, den, n1, d1, n2, d2, n2e, d2e
 129 %! num = [0, 3];
 130 %! den = [1, 4, 2];
 131 %! sys = filt (num, den);
 132 %! [n1, d1] = filtdata (sys, "vector");
 133 %! [n2, d2] = tfdata (sys, "vector");
 134 %! n2e = [3, 0];
 135 %! d2e = [1, 4, 2];
 136 %!assert (n1, num, 1e-4);
 137 %!assert (d1, den, 1e-4);
 138 %!assert (n2, n2e, 1e-4);
 139 %!assert (d2, d2e, 1e-4);