Home > classes > @ssm > ssm.m

ssm

PURPOSE ^

SSM statespace model class constructor.

SYNOPSIS ^

This is a script file.

DESCRIPTION ^

 SSM statespace model class constructor.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

 DESCRIPTION: SSM statespace model class constructor.

 ** This class is written using the new OO structures of MATLAB R2008a and
 will not work with earlier MATLAB versions.

     Public properties (read-only):

     Public properties (read/write):
       name       - name of analysis object

     Possible constructors:

       s = ssm()            - creates an empty statespace model
       s = ssm('a1.xml')    - creates a new statespace model by loading the
                              object from disk.
       s = ssm('a1.mat')    - creates a new statespace model by loading the
                              object from disk.
       a = ssm(plist)       - creates a statespace model from the description
                              given in the parameter list
       a = ssm(struct)      - creates a statespace model from the
                              structure returned by struct(ssm).

 Parameter sets for plist constructor (in order of priority):

 From XML File
 -------------
   Construct a statespace model by loading it from an XML file.

   'filename' - construct a statespace model from a filename.
                Example: plist('filename', 'ss1.xml')
                [default: empty string]

 From MAT File
 -------------
   Construct a statespace model by loading it from a MAT file.

   'filename' - construct a statespace model from a filename.
                Example: plist('filename', 'ss1.mat')
                [default: empty string]

 From Built-in System
 ----------------
   Construct a statespace model by specifying one of the built-in system
   names. Built-in models are stored in directories specified by
   SSM_MODELS in ltpda_startup. You can list multiple directories. A
   built-in model m-file must follow the naming convention ssm_model_*.m.

   'Buit-in' - A system name.
               Example: plist('filename', 'model_LPF_Dynamics_noparams')
               Example: plist('Built-in', ' ')
               will show the names of all the existing systems

   'dim'     - Optional parameter to reduce the model to 1, 3, or 6
               dimension. [Default: empty [] - return full model]
 
 From Repository
 ---------------
   Construct a statespace model by retrieving it from an LTPDA repository.

   'Hostname' - the repository hostname. Only those objects which
                are statespace models are returned.
                [default: 'localhost'];

                Additional parameters:

                'Database'   - The database name [default: 'ltpda']
                'ID'         - A vector of object IDs. [default: []]
                'CID'        - Retrieve all SSM objects from a particular
                               collection.

 From a Miir
 ---------------
   Construct a statespace model out of a MIIR object.

     example :  sys = ssm(themiir);

 From PZ model
 ---------------
   Construct a statespace model by retrieving it from an LTPDA repository.

     example :  sys=ssm(thepzmodel);


 From Description
 ----------------
 Construct a statespace model from a full description of the system.

     'isADescription' >> special filed to tell the constructor which set to use

     compulsory fields:
               'name','ssnames', 'outputnames', 'inputnames', 'timestep', 'amats', ...
               'bmats', 'cmats', 'dmats', 'paramnames', 'paramvalues'

     optionnals fields :
                'mmats' 'amats_handles' 'bmats_handles' 'cmats_handles' 'dmats_handles'...
                'inputvarnames'  'ssvarnames' 'outputvarnames'  'paramsigmas'

     example :
                 name = 'sys';
                 ssnames = {'ss1' 'ss2' 'ss3'};
                 ssvarnames = {{'ssvar1'} {'ssvar2'} {'ssvar31' 'ssvar32'}};
                 inputnames = {'input1' 'input2' 'input3'};
                 inputvarnames = {{'inputvar1'} {'inputvar2'} {'inputvar31' 'inputvar32'}};
                 outputnames = {'output1' 'output2' 'output3'};
                 outputvarnames = {{'outputvar1'} {'outputvar2'} {'outputvar31' 'outputvar32'}};
                 timestep = 0;
                 paramnames = {};
                 paramvalues = [];
                 amats = cell(3,3);
                 bmats = cell(3,3);
                 cmats = cell(3,3);
                 dmats = cell(3,3);
                 amats{1,1} = -1;
                 amats{2,2} = -2;
                 amats{3,3} = -3*eye(2);
                 amats{3,1} = [-1;-3];
                 bmats{1,1} = 1;
                 bmats{2,2} = 2;
                 bmats{3,3} = 3*eye(2);
                 cmats{1,1} = 1;
                 cmats{2,2} = 1;
                 cmats{3,3} = eye(2);
                 dmats{1,3} = [6 6];
                 dmats{2,1} = 6;
                 dmats{3,2} = [6;6];
                 sys = ssm(plist('isADescription', '' ,'name', name , ...
                   'timestep', timestep  ,    'paramnames', paramnames ,'paramvalues', paramvalues ,...
                   'inputnames', inputnames , 'outputnames',outputnames  ,'ssnames', ssnames,...
                   'inputvarnames', inputvarnames , 'outputvarnames',outputvarnames  ,'ssvarnames', ssvarnames,...
                   'amats', amats ,'bmats', bmats ,'cmats', cmats ,'dmats', dmats ));


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:

SUBFUNCTIONS ^

SOURCE CODE ^

0001 % SSM statespace model class constructor.
0002 %
0003 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0004 %
0005 % DESCRIPTION: SSM statespace model class constructor.
0006 %
0007 % ** This class is written using the new OO structures of MATLAB R2008a and
0008 % will not work with earlier MATLAB versions.
0009 %
0010 %     Public properties (read-only):
0011 %
0012 %     Public properties (read/write):
0013 %       name       - name of analysis object
0014 %
0015 %     Possible constructors:
0016 %
0017 %       s = ssm()            - creates an empty statespace model
0018 %       s = ssm('a1.xml')    - creates a new statespace model by loading the
0019 %                              object from disk.
0020 %       s = ssm('a1.mat')    - creates a new statespace model by loading the
0021 %                              object from disk.
0022 %       a = ssm(plist)       - creates a statespace model from the description
0023 %                              given in the parameter list
0024 %       a = ssm(struct)      - creates a statespace model from the
0025 %                              structure returned by struct(ssm).
0026 %
0027 % Parameter sets for plist constructor (in order of priority):
0028 %
0029 % From XML File
0030 % -------------
0031 %   Construct a statespace model by loading it from an XML file.
0032 %
0033 %   'filename' - construct a statespace model from a filename.
0034 %                Example: plist('filename', 'ss1.xml')
0035 %                [default: empty string]
0036 %
0037 % From MAT File
0038 % -------------
0039 %   Construct a statespace model by loading it from a MAT file.
0040 %
0041 %   'filename' - construct a statespace model from a filename.
0042 %                Example: plist('filename', 'ss1.mat')
0043 %                [default: empty string]
0044 %
0045 % From Built-in System
0046 % ----------------
0047 %   Construct a statespace model by specifying one of the built-in system
0048 %   names. Built-in models are stored in directories specified by
0049 %   SSM_MODELS in ltpda_startup. You can list multiple directories. A
0050 %   built-in model m-file must follow the naming convention ssm_model_*.m.
0051 %
0052 %   'Buit-in' - A system name.
0053 %               Example: plist('filename', 'model_LPF_Dynamics_noparams')
0054 %               Example: plist('Built-in', ' ')
0055 %               will show the names of all the existing systems
0056 %
0057 %   'dim'     - Optional parameter to reduce the model to 1, 3, or 6
0058 %               dimension. [Default: empty [] - return full model]
0059 %
0060 % From Repository
0061 % ---------------
0062 %   Construct a statespace model by retrieving it from an LTPDA repository.
0063 %
0064 %   'Hostname' - the repository hostname. Only those objects which
0065 %                are statespace models are returned.
0066 %                [default: 'localhost'];
0067 %
0068 %                Additional parameters:
0069 %
0070 %                'Database'   - The database name [default: 'ltpda']
0071 %                'ID'         - A vector of object IDs. [default: []]
0072 %                'CID'        - Retrieve all SSM objects from a particular
0073 %                               collection.
0074 %
0075 % From a Miir
0076 % ---------------
0077 %   Construct a statespace model out of a MIIR object.
0078 %
0079 %     example :  sys = ssm(themiir);
0080 %
0081 % From PZ model
0082 % ---------------
0083 %   Construct a statespace model by retrieving it from an LTPDA repository.
0084 %
0085 %     example :  sys=ssm(thepzmodel);
0086 %
0087 %
0088 % From Description
0089 % ----------------
0090 % Construct a statespace model from a full description of the system.
0091 %
0092 %     'isADescription' >> special filed to tell the constructor which set to use
0093 %
0094 %     compulsory fields:
0095 %               'name','ssnames', 'outputnames', 'inputnames', 'timestep', 'amats', ...
0096 %               'bmats', 'cmats', 'dmats', 'paramnames', 'paramvalues'
0097 %
0098 %     optionnals fields :
0099 %                'mmats' 'amats_handles' 'bmats_handles' 'cmats_handles' 'dmats_handles'...
0100 %                'inputvarnames'  'ssvarnames' 'outputvarnames'  'paramsigmas'
0101 %
0102 %     example :
0103 %                 name = 'sys';
0104 %                 ssnames = {'ss1' 'ss2' 'ss3'};
0105 %                 ssvarnames = {{'ssvar1'} {'ssvar2'} {'ssvar31' 'ssvar32'}};
0106 %                 inputnames = {'input1' 'input2' 'input3'};
0107 %                 inputvarnames = {{'inputvar1'} {'inputvar2'} {'inputvar31' 'inputvar32'}};
0108 %                 outputnames = {'output1' 'output2' 'output3'};
0109 %                 outputvarnames = {{'outputvar1'} {'outputvar2'} {'outputvar31' 'outputvar32'}};
0110 %                 timestep = 0;
0111 %                 paramnames = {};
0112 %                 paramvalues = [];
0113 %                 amats = cell(3,3);
0114 %                 bmats = cell(3,3);
0115 %                 cmats = cell(3,3);
0116 %                 dmats = cell(3,3);
0117 %                 amats{1,1} = -1;
0118 %                 amats{2,2} = -2;
0119 %                 amats{3,3} = -3*eye(2);
0120 %                 amats{3,1} = [-1;-3];
0121 %                 bmats{1,1} = 1;
0122 %                 bmats{2,2} = 2;
0123 %                 bmats{3,3} = 3*eye(2);
0124 %                 cmats{1,1} = 1;
0125 %                 cmats{2,2} = 1;
0126 %                 cmats{3,3} = eye(2);
0127 %                 dmats{1,3} = [6 6];
0128 %                 dmats{2,1} = 6;
0129 %                 dmats{3,2} = [6;6];
0130 %                 sys = ssm(plist('isADescription', '' ,'name', name , ...
0131 %                   'timestep', timestep  ,    'paramnames', paramnames ,'paramvalues', paramvalues ,...
0132 %                   'inputnames', inputnames , 'outputnames',outputnames  ,'ssnames', ssnames,...
0133 %                   'inputvarnames', inputvarnames , 'outputvarnames',outputvarnames  ,'ssvarnames', ssvarnames,...
0134 %                   'amats', amats ,'bmats', bmats ,'cmats', cmats ,'dmats', dmats ));
0135 %
0136 %
0137 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
0138 classdef ssm < ltpda_uoh
0139 
0140   %-------- Public (read/write) Properties  -------
0141   properties
0142     description = '';
0143   end % End (read/write) Properties
0144 
0145   %-------- Private read-only Properties --------
0146   properties %(SetAccess = protected)
0147     %l inear system matrices
0148     amats           = {};
0149     mmats           = {};
0150     bmats           = {};
0151     cmats           = {};
0152     dmats           = {};
0153     isnumerical     = false;
0154     timestep        = 0;
0155     % nonlinear system function handles
0156     amats_handles   = {};
0157     bmats_handles   = {};
0158     cmats_handles   = {};
0159     dmats_handles   = {};
0160     % input variables data array
0161     inputnames     = {};
0162     inputvarnames  = {};
0163     inputsizes     = [];
0164     Ninputs        = 0;
0165     % state space variables data arrays
0166     ssnames        = {};
0167     ssvarnames     = {};
0168     sssizes        = [];
0169     Nss            = 0;
0170     % output variables data arrays
0171     outputnames    = {};
0172     outputvarnames = {};
0173     outputsizes    = [];
0174     Noutputs       = 0;
0175     % parameter data arrays
0176     paramnames     = {};
0177     paramvalues    = [];
0178     paramsigmas    = [];
0179     Nparams        = 0;
0180   end % End read only properties
0181 
0182 
0183   %-------- Protected Properties ---------
0184   properties (SetAccess = protected)
0185     version = '$Id: ssm.m,v 1.67 2008/09/07 18:16:13 hewitson Exp $';
0186   end
0187 
0188   methods
0189 
0190   end
0191 
0192   %-------- Public Methods ------
0193   methods(Access = public)
0194     %% Class constructor
0195     function s = ssm(varargin)
0196       import utils.const.*
0197       utils.helper.msg(msg.MNAME, 'running %s/%s', mfilename('class'), mfilename);
0198       % Check the supported version
0199       utils.helper.checkMatlabVersion;
0200       %%% Call superclass
0201       s = s@ltpda_uoh(varargin{:}); %to inherit properties
0202       
0203       
0204       % Collect all ssm objects to check for copy constructor
0205       [sss, invars, rest] = utils.helper.collect_objects(varargin(:), 'ssm');
0206 
0207       if isempty(rest) && ~isempty(sss)
0208         % Do copy constructor and return
0209         utils.helper.msg(msg.OPROC1, 'copy constructor');
0210         s = copy(sss, 1);
0211         for kk=1:numel(s)
0212           s(kk).addHistory(ssm.getInfo('ssm', 'None'), [], [], s(kk).hist);
0213         end
0214         return
0215       end
0216       
0217       % Execute appropriate constructor
0218       switch nargin
0219         case 0    % Empty constructor
0220           s.addHistory(ssm.getInfo('ssm', 'None'), plist, {''}, []);
0221         case 1    % Plist, pzmodel, ...
0222           vin = varargin{1};
0223           if isa(vin, 'ssm')  % copy constructor
0224             s = copy(vin,1);
0225             for kk = 1:numel(vin)
0226               utils.helper.msg(msg.PROC1, 'copying %s', vin(kk).name);
0227               s(kk).addHistory(ssm.getInfo('ssm', 'None'), [], [], vin(kk).hist);
0228             end
0229           elseif isstruct(vin) % Struct constructor
0230             fnames = fieldnames(vin);
0231             for jj = 1:length(fnames)
0232               f = fnames{jj};
0233               if isstruct(vin.(f))
0234                 s.(f) = utils.helper.struct2obj(vin.(f));
0235               else
0236                 s.(f) = vin.(f);
0237               end
0238             end
0239           elseif isa(vin, 'plist') % constructor with a plist
0240             if isparam(vin, 'Filename')
0241               % filename constructor
0242               s = ssm.fromFile(vin);
0243             elseif isparam(vin, 'Built-in')
0244               % Construct from built-in
0245               s = ssm.ssmFromBuiltinSystem(vin);
0246             elseif isparam(vin, 'Hostname')
0247               % Retrieve from repository
0248               s = ssm.ssmFromRepository(vin);
0249             elseif isparam(vin, 'amats')
0250               % construct from plist description
0251               s = ssm.ssmFromDescription(vin);
0252             else
0253               display('###          Unknown constructor         ###')
0254               display('### could not find a valid parameter key ###')
0255               display('### these are : ''Filename'', ''Built-in''   ###')
0256               display('### these are : ''amats'', ''Hostname''      ###')
0257               error('See above message ^^');
0258             end
0259           elseif isa(vin, 'pzmodel') % Plist constructor
0260             s = ssm.ssmFromPzmodel(vin);
0261           elseif isa(vin, 'miir') % Plist constructor
0262             s = ssm.ssmFromMiir(vin);
0263           elseif ischar(vin) % from file
0264             filename = varargin{1};
0265             s = fromFile(s, filename);
0266           else
0267             error(['### Error: ssm constructor can''t handle input of type : ',class(vin)]);
0268           end
0269           % Now validate this object
0270           s = s.validate();
0271         case 2
0272           if isa(varargin{1}, 'ssm') && isa(varargin{2}, 'plist') && isempty(varargin{2}.params)
0273             % pass to copy constructor
0274             s = ssm(varargin{1});
0275           else
0276             error('### Unknown two parameter constructor.');
0277           end
0278         otherwise
0279           [ss, invars, rest] = utils.helper.collect_objects(varargin(:), 'ssm');
0280           %%% Do we have a list of SSMs as input
0281           if ~isempty(ss) && isempty(rest)
0282             s = ssm(ss);
0283           else
0284             error('### Unknown number of constructor arguments.');
0285           end
0286       end
0287     end
0288     %% copying one ssm
0289     varargout = copy(varargin)
0290     %% makes an executable string
0291     varargout = string(varargin)
0292     %% change timestep
0293     varargout = modiftimestep(varargin)
0294     %% change and subsitute parameters
0295     varargout = modifparams(varargin)
0296     %% assemble systems
0297     varargout = assemble(varargin)
0298     %% transform into a pzmodel or a iir
0299     varargout = ssm2iirpz(varargin)
0300     %% transform into ABCD doubles/symb
0301     varargout = double(varargin)
0302     %% transform into a matlab ss object
0303     varargout = ssm2ss(varargin)
0304     %% model modification executing a string
0305     varargout = modify(varargin)
0306     %% simulation
0307     varargout = simulate(varargin)
0308     %% kalman filter
0309     varargout = kalman(varargin)
0310     %% model simplification (states)
0311     varargout = reduce(varargin)
0312     %% model simplification (variables)
0313     varargout = reduce_model(varargin)
0314     %% char
0315     varargout = char(varargin)
0316     %% display
0317     varargout = display(varargin)
0318     %% give minimal realization (right now needs control toolbox)
0319     varargout = minreal(varargin)
0320     %% tells if ssm is stable
0321     varargout = isstable(varargin)
0322   end
0323 
0324   %-------- Declaration of private methods --------
0325   methods (Access = private)
0326     %% completion and error check
0327     varargout = validate(varargin)
0328   end
0329 
0330 
0331   %-------- Declaration of Public Static methods --------
0332   methods (Static=true, Access=public)
0333     function ii = getInfo(varargin)
0334       ii = utils.helper.generic_getInfo(varargin{:}, 'ssm');
0335     end
0336 
0337     function out = VEROUT()
0338       out = '$Id: ssm.m,v 1.67 2008/09/07 18:16:13 hewitson Exp $';
0339     end
0340 
0341     function out = SETS()
0342       out = {...
0343         'Default', ...
0344         'From XML File', ...
0345         'From MAT File', ...
0346         'From Built-in Model', ...
0347         'From Description', ...
0348         'From Plist', ...
0349         'From Repository',...
0350         'From Pzmodel',...
0351         'From Miir'};
0352     end
0353 
0354     function pl = getDefaultPlist(set)
0355       sets = ssm.SETS;
0356       % Select parameter set
0357       switch set
0358         case sets{1} % Default
0359           pl = plist();
0360         case sets{2} % XML file
0361           pl = plist('filename', '');
0362         case sets{3} % MAT file
0363           pl = plist('filename', '');
0364         case sets{4} % built-in
0365           pl = plist('Built-in', '', 'dim', 3, 'withParams', true);
0366         case sets{5} % description
0367           plist('isADescription', '' ,'name','me','ssnames',{'my state'} ,...
0368             'outputnames',{'force'}, 'inputnames',{'air','food'} ,'timestep',{0}, ...
0369             'amats',{-0.001}, 'bmats', {0 ,1},'cmats',{1}, 'dmats',{1 , 0}, ...
0370             'paramnames',{'health'}, 'paramvalues',1,...
0371             ... %second part, here facultative fields:
0372             'mmats', {80}, 'amats_handles',cell(1,1), 'bmats_handles',cell(1,2),...
0373             'cmats_handles',cell(1,1), 'dmats_handles',cell(1,2),...
0374             'inputvarnames',{'02','hamburger'}, ...
0375             'ssvarnames', {'energy left'}, ...
0376             'outputvarnames', {'force left to click on the mouse'},...
0377             'paramsigmas', 1);
0378           pl = plist();
0379         case sets{6} % plist
0380           pl = plist('plist', plist());
0381         case sets{7} % repository
0382           pl = plist('hostname', 'localhost', 'database', 'ltpda', 'ID', []);
0383         case sets{8} % pzmodel
0384           pl = plist();
0385         case sets{9} % miir
0386           pl = plist();
0387         otherwise
0388           error('### Unknown parameter set requested.');
0389       end
0390     end
0391 
0392     %% other usefull subroutines
0393     varargout = cellstrfind(c,s,option)
0394     varargout = update_struct(varargin)
0395     %% subroutines for block defined matrix calculus
0396     a_out = cell_recut(a, rowsizes, colsizes)
0397     a_out = cell_fusion(a, rowsizes, colsizes)
0398     c = cell_mult(a,b)
0399     a = cell_add(a,b)
0400     [cell_mat_out, rowsizes_out, colsizes_out]  = cell_select(varargin)
0401   end % End public static methods
0402 
0403 
0404   %-------- Declaration of Private Static methods --------
0405   methods (Static=true, Access=private)
0406     %% ssm constructor + predefined model reduction
0407     varargout = ssm_reduced_builtIn(varargin)
0408     % retrieve from repository
0409     sys = ssmFromRepository( pl)
0410     % load from file
0411     sys = ssmFromFilename( pl)
0412     % create from built-in system
0413     sys = ssmFromBuiltinSystem( pli)
0414     % create from miir
0415     sys = ssmFromMiir(miirsin)
0416     % create from plist
0417     sys = ssmFromDescription(pl)
0418     % create from pzmodel
0419     sys = ssmFromPzmodel(pzmodelsin)
0420   end
0421 
0422 end % End classdef
0423 
0424

Generated on Mon 08-Sep-2008 13:18:47 by m2html © 2003