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

   1 ## Copyright (C) 2009, 2010   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} =} ss (@var{sys})
  20 ## @deftypefnx {Function File} {@var{sys} =} ss (@var{d})
  21 ## @deftypefnx {Function File} {@var{sys} =} ss (@var{a}, @var{b})
  22 ## @deftypefnx {Function File} {@var{sys} =} ss (@var{a}, @var{b}, @var{c})
  23 ## @deftypefnx {Function File} {@var{sys} =} ss (@var{a}, @var{b}, @var{c}, @var{d}, @dots{})
  24 ## @deftypefnx {Function File} {@var{sys} =} ss (@var{a}, @var{b}, @var{c}, @var{d}, @var{tsam}, @dots{})
  25 ## Create or convert to state-space model.
  26 ##
  27 ## @strong{Inputs}
  28 ## @table @var
  29 ## @item sys
  30 ## LTI model to be converted to state-space.
  31 ## @item a
  32 ## State transition matrix (n-by-n).
  33 ## @item b
  34 ## Input matrix (n-by-m).
  35 ## @item c
  36 ## Measurement matrix (p-by-n).
  37 ## If @var{c} is empty @code{[]} or not specified, an identity matrix is assumed.
  38 ## @item d
  39 ## Feedthrough matrix (p-by-m).
  40 ## If @var{d} is empty @code{[]} or not specified, a zero matrix is assumed.
  41 ## @item tsam
  42 ## Sampling time in seconds.  If @var{tsam} is not specified, a continuous-time model is assumed.
  43 ## @item @dots{}
  44 ## Optional pairs of properties and values.
  45 ## Type @command{set (ss)} for more information.
  46 ## @end table
  47 ##
  48 ## @strong{Outputs}
  49 ## @table @var
  50 ## @item sys
  51 ## State-space model.
  52 ## @end table
  53 ##
  54 ## @strong{Example}
  55 ## @example
  56 ## @group
  57 ## octave:1> a = [1 2 3; 4 5 6; 7 8 9];
  58 ## octave:2> b = [10; 11; 12];
  59 ## octave:3> stname = @{"V", "A", "kJ"@};
  60 ## octave:4> sys = ss (a, b, [], [], "stname", stname)
  61 ##
  62 ## sys.a =
  63 ##         V   A  kJ
  64 ##    V    1   2   3
  65 ##    A    4   5   6
  66 ##    kJ   7   8   9
  67 ##
  68 ## sys.b =
  69 ##        u1
  70 ##    V   10
  71 ##    A   11
  72 ##    kJ  12
  73 ##
  74 ## sys.c =
  75 ##         V   A  kJ
  76 ##    y1   1   0   0
  77 ##    y2   0   1   0
  78 ##    y3   0   0   1
  79 ##
  80 ## sys.d =
  81 ##        u1
  82 ##    y1   0
  83 ##    y2   0
  84 ##    y3   0
  85 ##
  86 ## Continuous-time model.
  87 ## octave:5>
  88 ## @end group
  89 ## @end example
  90 ##
  91 ## @seealso{tf, dss}
  92 ## @end deftypefn
  93
  94 ## Author: Lukas Reichlin <lukas.reichlin@gmail.com>
  95 ## Created: September 2009
  96 ## Version: 0.3
  97
  98 function sys = ss (a = [], b = [], c = [], d = [], varargin)
  99
 100   ## model precedence: frd > ss > zpk > tf > double
 101   ## inferiorto ("frd");
 102   superiorto ("zpk", "tf", "double");
 103
 104   argc = 0;                             # initialize argument count
 105   tsam = 0;                             # initialize sampling time
 106
 107   if (nargin == 1)
 108     if (isa (a, "ss"))                  # already in ss form  sys = ss (sssys)
 109       sys = a;
 110       return;
 111     elseif (isa (a, "lti"))             # another lti object  sys = ss (sys)
 112       [sys, alti] = __sys2ss__ (a);
 113       sys.lti = alti;                   # preserve lti properties
 114       return;
 115     elseif (is_real_matrix (a))         # static gain  sys = ss (5), sys = ss (matrix)
 116       d = a;
 117       a = [];
 118     else
 119       print_usage ();
 120     endif
 121   elseif (nargin > 4)                   # default case  sys = ss (a, b, c, d, "prop1", val1, ...)
 122     argc = numel (varargin);            # number of additional arguments after d
 123     if (issample (varargin{1}, -10))    # sys = ss (a, b, c, d, tsam, "prop1, "val1", ...)
 124       tsam = varargin{1};               # sampling time, could be 0 as well
 125       argc--;                           # tsam is not a property-value pair
 126       if (argc > 0)                     # if there are any properties and values ...
 127         varargin = varargin(2:end);     # remove tsam from property-value list
 128       endif
 129     endif
 130   endif                                 # nothing to do for ss (), ss (a, b), ss (a, b, c), ss (a, b, c, d)
 131
 132   [a, b, c, d, tsam] = __adjust_ss_data__ (a, b, c, d, tsam);
 133   [p, m, n] = __ss_dim__ (a, b, c, d);  # determine number of outputs, inputs and states
 134
 135   stname = repmat ({""}, n, 1);         # cell with empty state names
 136
 137   ssdata = struct ("a", a, "b", b,
 138                    "c", c, "d", d,
 139                    "e", [],
 140                    "stname", {stname},
 141                    "scaled", false);    # struct for ss-specific data
 142
 143   ltisys = lti (p, m, tsam);            # parent class for general lti data
 144
 145   sys = class (ssdata, "ss", ltisys);   # create ss object
 146
 147   if (argc > 0)                         # if there are any properties and values, ...
 148     sys = set (sys, varargin{:});       # use the general set function
 149   endif
 150
 151 endfunction