Building from scratch


The models can be built from a plist constructor describing each field. It is possible to give incomplete information on the model and let the constructor auto-complete some fields.

It is still rather lengthy to build a ssm object, and it is advisable to write built-in models to limit the time spent on modeling.

Incomplete description without parameters (params field) and input/state/outputs names

The most retrained set of inputs is

sys = ssm(plist( 'amats',amats, 'bmats',bmats, 'cmats',cmats, 'dmats',dmats, 'timestep',timestep, 'name',name  )

Then a shortcut for the scripts is (note that the input order must be respected)

sys = ssm( amats, bmats, cmats, dmats, timestep, name )

example :

>> name = 'sys';
>> timestep = 0;
>> amats = cell(3,3);
>> bmats = cell(3,3);
>> cmats = cell(3,3);
>> dmats = cell(3,3);
>> amats{1,1} = -(sym('OMEGA'));
>> amats{2,2} = -2;
>> amats{3,3} = [0 1 ; -0.05 -0.01];
>> 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( ...
'amats',amats, 'bmats',bmats, 'cmats',cmats, 'dmats',dmats, ...
'timestep',timestep, 'name',name))
------ ssm/1 -------
      amats: {  [1x1]    []      []     
                 []     [1x1]    []     
                [2x1]    []     [2x2]  }  [3x3]
      mmats: {  [1x1]    []      []     
                 []     [1x1]    []     
                 []      []     [2x2]  }  [3x3]
      bmats: {  [1x1]    []      []     
                 []     [1x1]    []     
                 []      []     [2x2]  }  [3x3]
      cmats: {  [1x1]    []      []     
                 []     [1x1]    []     
                 []      []     [2x2]  }  [3x3]
      dmats: {   []      []     [1x2]   
                [1x1]    []      []     
                 []     [2x1]    []    }  [3x3]
   timestep: 0
     inputs:  [1x3 ssmblock]
         1 : input 1 | input 1 > 1 []
         2 : input 2 | input 2 > 1 []
         3 : input 3 | input 3 > 1 [], input 3 > 2 []
     states:  [1x3 ssmblock]
         1 : state 1 | state 1 > 1 []
         2 : state 2 | state 2 > 1 []
         3 : state 3 | state 3 > 1 [], state 3 > 2 []
    outputs:  [1x3 ssmblock]
         1 : output 1 | output 1 > 1 []
         2 : output 2 | output 2 > 1 []
         3 : output 3 | output 3 > 1 [], output 3 > 2 []
     params: (empty-plist) [1x1 plist]
    version: $Id: ssm_build_description_content.html,v 1.5 2012/01/19 13:28:16 ingo Exp $
    Ninputs: 3
 inputsizes: [1 1 2]
   Noutputs: 3
outputsizes: [1 1 2]
    Nstates: 3
 statesizes: [1 1 2]
    Nparams: 0
isnumerical: false
       hist: ssm.hist [1x1 history]
   procinfo: (empty-plist) [1x1 plist]
   plotinfo: (empty-plist) [1x1 plist]
       name: sys
description: 
    mdlfile: 
       UUID: 61f33fcc-f06a-4d71-944f-3ea094c80458
--------------------

Then the field “params” must be user set using the syntax “sys.setParams(<parameter plist>)”. Otherwise the toolbox will simply assume there are no parameters in the system and the matrices should be exclusively numerical in this case..

The content of „params“ is a plist with parameters whose:

>>sys.setParams(plist({'OMEGA', 'system frequency'}, 2))
------ ssm/1 -------
      amats: {  [1x1]    []      []     
                 []     [1x1]    []     
                [2x1]    []     [2x2]  }  [3x3]
      mmats: {  [1x1]    []      []     
                 []     [1x1]    []     
                 []      []     [2x2]  }  [3x3]
      bmats: {  [1x1]    []      []     
                 []     [1x1]    []     
                 []      []     [2x2]  }  [3x3]
      cmats: {  [1x1]    []      []     
                 []     [1x1]    []     
                 []      []     [2x2]  }  [3x3]
      dmats: {   []      []     [1x2]   
                [1x1]    []      []     
                 []     [2x1]    []    }  [3x3]
   timestep: 0
     inputs:  [1x3 ssmblock]
         1 : input 1 | input 1 > 1 []
         2 : input 2 | input 2 > 1 []
         3 : input 3 | input 3 > 1 [], input 3 > 2 []
     states:  [1x3 ssmblock]
         1 : state 1 | state 1 > 1 []
         2 : state 2 | state 2 > 1 []
         3 : state 3 | state 3 > 1 [], state 3 > 2 []
    outputs:  [1x3 ssmblock]
         1 : output 1 | output 1 > 1 []
         2 : output 2 | output 2 > 1 []
         3 : output 3 | output 3 > 1 [], output 3 > 2 []
     params: (OMEGA=2) [1x1 plist]
    version: $Id: ssm_build_description_content.html,v 1.5 2012/01/19 13:28:16 ingo Exp $
    Ninputs: 3
 inputsizes: [1 1 2]
   Noutputs: 3
outputsizes: [1 1 2]
    Nstates: 3
 statesizes: [1 1 2]
    Nparams: 1
isnumerical: false
       hist: ssm.hist [1x1 history]
   procinfo: (empty-plist) [1x1 plist]
   plotinfo: (empty-plist) [1x1 plist]
       name: sys
description: 
    mdlfile: 
       UUID: 7bccc440-fcc3-4d71-bf9c-057bbc08d318
--------------------

The method “setParams” should not be confused with “setParameters” which only allows to modify the property VALUE in the “params” field.

Input blocks and input variables will be automatically maned after their index number in this case, and the description field will be empty.

Incomplete description whithout input/state/outputs names

In case the user has a plist describing the parameters, he may use the following either of the syntaxes:

>> sys = ssm(plist( 'amats',amats, 'bmats',bmats, 'cmats',cmats, 'dmats',dmats, 'timestep',timestep, 'name',name, 'params',params ));
>> sys = ssm( amats, bmats, cmats, dmats, timestep, name, params )

>> name = 'sys';
>> timestep = 0;
>> params = plist({'OMEGA', 'system frequency'}, 2);
>> amats = cell(3,3);
>> bmats = cell(3,3);
>> cmats = cell(3,3);
>> dmats = cell(3,3);
>> amats{1,1} = -(sym('OMEGA'));
>> amats{2,2} = -2;
>> amats{3,3} = [0 1 ; -0.05 -0.01];
>> 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( ...
'amats',amats, 'bmats',bmats, 'cmats',cmats, 'dmats',dmats, ...
'timestep',timestep, 'name',name, 'params',params ));

Then the inputs, states and outputs name fields are still automatically set.

They can be modified by using the “setBlock*” and “setPort*” setter methods. Blocks are vectors of ports which will be matched when assembling two system. Setting their name correctly is important as the names are used to identify automatically which output will be fed to which input. Ports are independent variables and have properties like the name, the description and the unit which the user may want to set to keep track of the systems data. Note that there is no unit check implemented when assembling two systems.

The setter functions are respectively “setBlockNames”, “setBlockDescription”, “setPortNames”, “setPortDescriptions”, “setPortUnits”.

>> sys.setBlockNames(plist('field', 'inputs', 'blocks', [1 2 3], 'names', {'myinput1','myinput2','myinput3'} ));
>> sys.setBlockDescriptions(plist('field', 'inputs', 'blocks', {'myinput1'}, 'descriptions',{'myinput1 description'} ));
>> sys.setPortNames(plist('field', 'inputs', 'block', {'myinput3'}, 'ports', [1 2], 'names',{'my port 3-1' 'my port 3-2'} ));
>> sys.setPortDescriptions(plist('field', 'inputs', 'block', {'myinput3'}, 'ports', [1 2], 'descriptions',{'first description' 'second description'} ));
>> sys.setPortUnits(plist('field', 'inputs', 'block', {'myinput3'}, 'ports', [1 2], 'units', [unit('kg m^-2') unit('m')] ));
>> sys.inputs

------ ssmblock/1 -------
       name: myinput1
      ports: input 1 > 1 [] [1x1 ssmport]
description: myinput1 description
    version: $Id: ssm_build_description_content.html,v 1.5 2012/01/19 13:28:16 ingo Exp $
-------------------------
------ ssmblock/2 -------
       name: myinput2
      ports: input 2 > 1 [] [1x1 ssmport]
description: 
    version: $Id: ssm_build_description_content.html,v 1.5 2012/01/19 13:28:16 ingo Exp $
-------------------------
------ ssmblock/3 -------
       name: myinput3
      ports: my port 3-1 [kg m^(-2)], my port 3-2 [m] [1x2 ssmport]
description: 
    version: $Id: ssm_build_description_content.html,v 1.5 2012/01/19 13:28:16 ingo Exp $
-------------------------

>>sys.inputs(3).ports

------ ssmport/1 -------
       name: my port 3-1
      units: [kg m^(-2)] [1x1 unit]
description: first description
    version: $Id: ssm_build_description_content.html,v 1.5 2012/01/19 13:28:16 ingo Exp $
------------------------
------ ssmport/2 -------
       name: my port 3-2
      units: [m] [1x1 unit]
description: second description
    version: $Id: ssm_build_description_content.html,v 1.5 2012/01/19 13:28:16 ingo Exp $
------------------------

So far there is no special display function for ssmblocks so the description of the ports is not displayed. This may change in the future

Description whith input/state/outputs names

Then a more extensive set of inputs is :
>>sys = ssm(plist( 'amats',amats, 'bmats',bmats, 'cmats',cmats, 'dmats',dmats, 'timestep',timestep, 'name',name, 'params',params, 'statenames',statenames, 'inputnames',inputnames, 'outputnames',outputnames ));
>> sys = ssm( amats, bmats, cmats, dmats, timestep, name, params, statenames, inputnames, outputnames );

Still here, the port names are set automatically without any description or unit.

Complete description

example :

>> name = 'sys';
>> statenames = {'ss1' 'ss2' 'ss3'};
>> inputnames = {'input1' 'input2' 'input3'};
>> outputnames = {'output1' 'output2' 'output3'};
>> timestep = 0;
>> params = plist({'OMEGA', 'system frequency'}, 2);
>> amats = cell(3,3);
>> bmats = cell(3,3);
>> cmats = cell(3,3);
>> dmats = cell(3,3);
>> amats{1,1} = -(sym('OMEGA'));
>> amats{2,2} = -2;
>> amats{3,3} = [0 1 -0.05 -0.01];
>> 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( ...
 'amats',amats, 'bmats',bmats, 'cmats',cmats, 'dmats',dmats, ...
 'timestep',timestep, 'name',name, 'params',params, ...
 'statenames',statenames, 'inputnames',inputnames, 'outputnames',outputnames ));
>> sys
------ ssm/1 -------
      amats: {  [1x1]    []      []     
                 []     [1x1]    []     
                [2x1]    []     [2x2]  }  [3x3]
      mmats: {  [1x1]    []      []     
                 []     [1x1]    []     
                 []      []     [2x2]  }  [3x3]
      bmats: {  [1x1]    []      []     
                 []     [1x1]    []     
                 []      []     [2x2]  }  [3x3]
      cmats: {  [1x1]    []      []     
                 []     [1x1]    []     
                 []      []     [2x2]  }  [3x3]
      dmats: {   []      []     [1x2]   
                [1x1]    []      []     
                 []     [2x1]    []    }  [3x3]
   timestep: 0
     inputs:  [1x3 ssmblock]
         1 : input1 | input1 > 1 []
         2 : input2 | input2 > 1 []
         3 : input3 | input3 > 1 [], input3 > 2 []
     states:  [1x3 ssmblock]
         1 : ss1 | ss1 > 1 []
         2 : ss2 | ss2 > 1 []
         3 : ss3 | ss3 > 1 [], ss3 > 2 []
    outputs:  [1x3 ssmblock]
         1 : output1 | output1 > 1 []
         2 : output2 | output2 > 1 []
         3 : output3 | output3 > 1 [], output3 > 2 []
     params: (OMEGA=2) [1x1 plist]
    version: $Id: ssm_build_description_content.html,v 1.5 2012/01/19 13:28:16 ingo Exp $
    Ninputs: 3
 inputsizes: [1 1 2]
   Noutputs: 3
outputsizes: [1 1 2]
    Nstates: 3
 statesizes: [1 1 2]
    Nparams: 1
isnumerical: false
       hist: ssm.hist [1x1 history]
   procinfo: (empty-plist) [1x1 plist]
   plotinfo: (empty-plist) [1x1 plist]
       name: sys
description: 
    mdlfile: UUID: b30c0d1d-9d09-4fd5-8dc1-8185f8b1c165


This constructor still does not set ports properties (except automatic name) nor the block description.
These may be set by the user later on using the setter functions above.



©LTP Team