classdef (SupportExtensionMethods=true) StateSpaceModel < DynamicSystem
   % State-Space Model objects.
   %
   %   State-space models are dynamic systems described in the time domain by
   %   first-order differential equations. There are two main types of state-space
   %   models in Control System Toolbox:
   %     * Linear state-space models (SS) described by equations of the form
   %          dx/dt = Ax(t) + Bu(t)
   %           y(t) = Cx(t) + Du(t)
   %       or their discrete-time counterpart
   %     * Generalized state-space models (GENSS) obtained by combining SS models
   %       with Control Design blocks. Such models support specific tasks like
   %       automated tuning of fixed-architecture control systems (see SYSTUNE).
   %
   %   See also SS, GENSS, CONTROLDESIGNBLOCK, DYNAMICSYSTEM.
   
%   Author(s): P. Gahinet
%   Copyright 1986-2023 The MathWorks, Inc.
               
   methods

      function sys = augstate(sys)
         %AUGSTATE  Appends states to the outputs of a state-space model.
         %
         %   ASYS = AUGSTATE(SYS)  appends the states to the outputs of
         %   the state-space model SYS.  The resulting model is:
         %      .                       .
         %      x  = A x + B u   (or  E x = A x + B u for descriptor SS)
         %
         %     |y| = [C] x + [D] u
         %     |x|   [I]     [0]
         %
         %   This command is useful to close the loop on a full-state
         %   feedback gain  u = Kx.  After preparing the plant with
         %   AUGSTATE,  you can use the FEEDBACK command to derive the
         %   closed-loop model.
         %
         %   See also FEEDBACK, SS.
         narginchk(1,1)
         if nmodels(sys)==0
            return
         end
         % Update state-space data
         try
            [sys,nx] = augstate_(sys);
         catch E
            ltipack.throw(E,'command','augstate',class(sys))
         end
         sys.IOSize_(1) = sys.IOSize_(1) + nx;
         sys.Notes_ = strings(0,1);  sys.UserData = [];
      end

      function sys = augoffset(sys)
         %AUGOFFSET  Map offset contribution to extra input channel.
         %
         %   ASYS = AUGOFFSET(SYS) takes a state-space model SYS with offsets
         %   and returns an offset-free state-space model ASYS with one extra
         %   input channel. This model is constructed such that the response
         %   of SYS to an input u(t) matches the response of ASYS to [u(t);1]
         %   (with a unit step applied to the extra input channel).
         %
         %   The transfer function of ASYS is [H(s) h(s)] where H(s) and h(s)
         %   are the linear and affine parts of SYS. The frequency response is
         %      Y(s) = H(s) U(s) + h(s) (1/s)
         %           = [H(s) h(s)]  [U(s);1/s]
         %   which is the frequency-domain expression of the time-domain
         %   connection between SYS and ASYS.
         %
         %   See also SS.
         narginchk(1,1)
         if nmodels(sys)==0
            return
         end
         try
            sys = augoffset_(sys);
         catch E
            ltipack.throw(E,'command','augoffset',class(sys))
         end
         sys.IOSize_(2) = sys.IOSize_(2) + 1;
         sys.Notes_ = strings(0,1);  sys.UserData = [];
      end

      function sys = xperm(sys,perm)
         %XPERM  Reorders states in state-space models.
         %
         %   SYS = XPERM(SYS,P) reorders the states of the state-space model SYS
         %   according to the permutation P. The vector P should be a permutation of 
         %   1:NX where NX is the number of states in SYS. For GENSS or USS models, 
         %   the permutation P applies to the state vector of the interconnection 
         %   model (first output argument of GETLFTMODEL).
         %
         %   For second-order models (see MECHSS), the permutation P applied to the
         %   vector q of displacements.
         %
         %   Example: To flip the states of a third-order model SYS, use
         %      psys = xperm(sys,[3 2 1])
         %
         %   See also XSORT, SS, SPARSS, MECHSS, GENSS, GETLFTMODEL.
         perm = perm(:);
         nx = numel(perm);
         if ~isnumeric(perm) || ~isequal(sort(perm),(1:nx)')
            error(message('Control:transformation:xperm',nx))
         end
         try
            sys = xperm_(sys,perm);
         catch E
            ltipack.throw(E,'command','xperm',class(sys))
         end         
      end

      function sys = modred(sys,varargin)
         %MODRED  Model simplification by state elimination.
         %
         %   MODRED is obsolete, use XELIM instead.
         %
         %   See also XELIM.
         sys = xelim(sys,varargin{:});
      end
      
   end
end
