umat

Uncertain matrix

Description

Use the umat object to represent matrices whose entries have uncertain values. Uncertain matrices are useful for worst-case gain analysis and for building uncertain state-space (uss) models.

Creation

Create uncertain matrices by creating uncertain elements of type ureal, ucomplex, or ucomplexm and combining them using arithmetic and matrix operations. For example, the following code creates a umat object representing a 2-by-2 matrix with the uncertain parameter p.

 p = ureal('p',1);
 M = [0 p; 1 p^2]

Uncertain matrix with 2 rows and 2 columns.
The uncertainty consists of the following blocks:
  p: Uncertain real, nominal = 1, variability = [-1,1], 3 occurrences
Model Properties

Type "M.NominalValue" to see the nominal value and "M.Uncertainty" to interact with the 
uncertain elements.

The syntax M = umat(A) converts the double array A to a umat object with no uncertainty.

Properties

NominalValue — Nominal value of uncertain model

ss model object

Nominal value of the uncertain model, specified as a state-space (ss) model object. The state-space model is obtained by setting all the uncertain control design blocks of the uncertain model to their nominal values.

If M is a umat, then M.NominalValue is the result obtained by replacing each uncertain element in M with its own nominal value.

Uncertainty — Uncertain elements

structure

Uncertain elements of the matrix, specified as a structure whose fields are the names of the uncertain blocks and whose values are the control design blocks themselves. Thus, the values stored in the structure can be ureal, ucomplex, or ucomplexm objects.

You can access or examine each uncertain parameter individually using dot notation. For example, consider an umat matrix A with real uncertain parameters p1 and p2. Use dot notation to examine p2.

A.Uncertainty.p2

Uncertain real parameter "p2" with nominal value 3 and variability [-15,15]%.

Name — Model name

'' (default) | character vector | string

Model name, stored as a character vector or string. If you specify Name using a string, such as "DCmotor", the string is stored as a character vector, 'DCmotor'.

Example: 'system_1'

SamplingGrid — Sampling grid for model arrays

structure with no fields (default) | structure

Sampling grid for model arrays, specified as a structure. For model arrays that are derived by sampling one or more independent variables, this property tracks the variable values associated with each model in the array. This information appears when you display or plot the model array. Use this information to trace results back to the independent variables.

Set the field names of the data structure to the names of the sampling variables. Set the field values to the sampled variable values associated with each model in the array. All sampling variables should be numeric and scalar valued, and all arrays of sampled values should match the dimensions of the model array.

For example, suppose you create a 11-by-1 array of linear models, sysarr, by taking snapshots of a linear time-varying system at times t = 0:10. The following code stores the time samples with the linear models.

 sysarr.SamplingGrid = struct('time',0:10)

Similarly, suppose you create a 6-by-9 model array, M, by independently sampling two variables, zeta and w. The following code attaches the (zeta,w) values to M.

[zeta,w] = ndgrid(<6 values of zeta>,<9 values of w>)
M.SamplingGrid = struct('zeta',zeta,'w',w)

When you display M, each entry in the array includes the corresponding zeta and w values.

M

M(:,:,1,1) [zeta=0.3, w=5] =
 
        25
  --------------
  s^2 + 3 s + 25
 

M(:,:,2,1) [zeta=0.35, w=5] =
 
         25
  ----------------
  s^2 + 3.5 s + 25
 
...

For model arrays generated by linearizing a Simulink^® model at multiple parameter values or operating points, the software populates SamplingGrid automatically with the variable values that correspond to each entry in the array. For example, the Simulink Control Design™ commands linearize (Simulink Control Design) and slLinearizer (Simulink Control Design) populate SamplingGrid in this way.

Object Functions

Most standard matrix manipulations are valid on uncertain matrices, including addition, multiplication, inverse, and horizontal and vertical concatenation. You can index, reference, and assign specific rows, columns, or entries of an uncertain matrix the same as you would any matrix.

The following list contains a representative subset of some of the other functions you can use with umat matrices.

blkdiag	Block-diagonal concatenation of models
connect	Block diagram interconnections of dynamic systems
getBlockValue	Get current value of Control Design Block in Generalized Model
getNominal	Nominal value of uncertain model
isuncertain	Check whether argument is uncertain class type
ss	State-space model
usample	Generate random samples of uncertain model or element
usubs	Substitute given values for uncertain elements of uncertain objects

Examples

Matrix with Uncertain Entries

Create three uncertain elements a, b, and c, and use them to build a 3-by-2 uncertain matrix,

$\mathit{M}=\left[\begin{array}{cc}\mathit{a}& \mathit{b}\\ \mathit{ba}& 7\\ \mathit{c}-\mathit{a}& {\mathit{b}}^2\end{array}\right]$.

a = ureal('a',5,'Range',[2 6]); 
b = ucomplex('b',1+j,'Radius',0.5); 
c = ureal('c',3,'Plusminus',0.4); 
M = [a b;b*a 7;c-a b^2] 

Uncertain matrix with 3 rows and 2 columns.
The uncertainty consists of the following blocks:
  a: Uncertain real, nominal = 5, range = [2,6], 1 occurrences
  b: Uncertain complex, nominal = 1+1i, radius = 0.5, 4 occurrences
  c: Uncertain real, nominal = 3, variability = [-0.4,0.4], 1 occurrences
Model Properties

Type "M.NominalValue" to see the nominal value and "M.Uncertainty" to interact with the uncertain elements.

The nominal value of M is the matrix value with all uncertain elements set to their nominal values.

M.NominalValue 

ans = 3×2 complex

   5.0000 + 0.0000i   1.0000 + 1.0000i
   5.0000 + 5.0000i   7.0000 + 0.0000i
  -2.0000 + 0.0000i   0.0000 + 2.0000i

If you change the nominal value of one of the uncertain elements in M, the nominal value of M reflects the change.

M.Uncertainty.a.NominalValue = 4; 
M.NominalValue 

ans = 3×2 complex

   4.0000 + 0.0000i   1.0000 + 1.0000i
   4.0000 + 4.0000i   7.0000 + 0.0000i
  -1.0000 + 0.0000i   0.0000 + 2.0000i

You can obtain a random sample of M using usample. This function takes a random sample of each uncertain element of M.

usample(M) 

ans = 3×2 complex

   5.2589 + 0.0000i   1.3012 + 0.6290i
   6.8428 + 3.3079i   7.0000 + 0.0000i
  -2.1530 + 0.0000i   1.2974 + 1.6369i

You can index into M as you would an ordinary matrix. For instance, select the first and third rows and the second column of M.

Ms = M([1 3],2)  

Uncertain matrix with 2 rows and 1 columns.
The uncertainty consists of the following blocks:
  b: Uncertain complex, nominal = 1+1i, radius = 0.5, 3 occurrences
Model Properties

Type "Ms.NominalValue" to see the nominal value and "Ms.Uncertainty" to interact with the uncertain elements.

The resulting 2-by-1 umat contains only the uncertain element b, because the selected entries of M do not depend on a or c.

State-Space Model with Uncertain Matrices

To create a state-space model with matrices having uncertain elements, you first use uncertain parameters such as ureal and ucomplex. Then use these elements to specify the state-space matrices of the system. For instance, create three uncertain real parameters and build state-spaces matrices from them.

p1 = ureal('p1',10,'Percentage',50); 
p2 = ureal('p2',3,'PlusMinus',[-.5 1.2]); 
p3 = ureal('p3',0); 

A = [-p1 p2; 0 -p1]; 
B = [-p2; p2+p3]; 
C = [1 0; 1 1-p3]; 
D = [0; 0];

The matrices constructed with uncertain parameters, A, B, and C, are uncertain matrix (umat) objects. Using them as inputs to ss results in a 2-output, 1-input, 2-state uncertain system.

sys = ss(A,B,C,D)

Uncertain continuous-time state-space model with 2 outputs, 1 inputs, 2 states.
The model uncertainty consists of the following blocks:
  p1: Uncertain real, nominal = 10, variability = [-50,50]%, 2 occurrences
  p2: Uncertain real, nominal = 3, variability = [-0.5,1.2], 2 occurrences
  p3: Uncertain real, nominal = 0, variability = [-1,1], 2 occurrences
Model Properties

Type "sys.NominalValue" to see the nominal value and "sys.Uncertainty" to interact with the uncertain elements.

The display shows that the system includes the three uncertain parameters.

Version History

Introduced before R2006a