%% Create and Manipulate Uncertain Matrices
% You create uncertain matrices (umat objects) by creating uncertain parameters and using them to build matrices. You can then use uncertain matrices to build uncertain state-space models. This example shows how to create an uncertain matrix, access and change its uncertain parameters, extract elements, and perform matrix arithmetic.
% For example, create two uncertain real parameters, and use them to create a 3-by-2 uncertain matrix.

a = ureal('a',3); 
b = ureal('b',10,'Percentage',20); 
M = [-a, 1/b; b, a+1/b; 1, 3]

%
%% Examine and Modify umat Properties
% M is a umat object. Examine its properties using get.

get(M)

%
% The nominal value of M is the matrix obtained by replacing all the uncertain elements with their nominal values.

M.NominalValue

%
% The Uncertainty property is a structure containing the uncertain elements (the Control Design Blocks) of M.

M.Uncertainty

%

M.Uncertainty.a

%
% Use the Uncertainty property for direct access to the uncertain elements. For example, check the Range of the uncertain element a within M.

M.Uncertainty.a.Range

% The range is [2,4] because you created the ureal parameter a with a nominal value 3 and the default uncertainty of +/- 1. Change the range to [2.5,5].
%

M.Uncertainty.a.Range = [2.5,5]

%
% This change to a only takes place within M. Verify that the variable a in the MATLAB workspace still has the original range.

a.Range

% You cannot combine elements that have a common internal name, but different properties. So, for example, entering M.Uncertainty.a - a would generate an error, because the realp parameter a in the workspace has different properties from the element a in M.
%
%% Row and Column Referencing
% You can use standard row-column referencing to extract elements from a umat. For example, extract a 2-by-2 selection from M consisting of its second and third rows.

Msub = M(2:3,:)

%
% You can use single indexing only if the umat is a single column or row. Make a single-column selection from M and use single-index references to access elements of it.

Msing = M([2 1 2 3],2);
Msing(2)

%
% You can use indexing to change the value of any element of a umat. For example, set the (3,2) entry of M to an uncertain parameter c.

c = ureal('c',3,'Percentage',40);
M(3,2) = c

% M now has three uncertain blocks.
%
%% Matrix Operations on umat Objects
% You can perform many matrix operations on a umat object, such as matrix-multiply, transpose, and inverse. You can also combine uncertain matrices with numeric matrices that do not have uncertainty.
% For example, premultiply M by a 1-by-3 numeric matrix, resulting in a 1-by-2 umat.

M1 = [2 3 1]*M;

%
% Verify that the first entry of M1 is as expected, -2*a + 3*b + 1.

d = M1(1) - (-2*M.Uncertainty.a + 3*M.Uncertainty.b + 1)

%
% Transpose M, form a product, and invert it. As expected, the product of a matrix and its inverse is the identity matrix. You can verify this by sampling the result.

H = M.'*M; 
K = inv(H); 
usample(K*H,3)

%
%% Lifting a Double Matrix to umat
% You can convert a numeric matrix to a umat object with no uncertain elements. Use the umat command to lift a double matrix to the umat class. For example:

Md = [1 2 3;4 5 6]; 
M = umat(Md)

%
% You can also convert higher-dimension numeric matrices to umat. When you do so, the software interprets the third dimension and beyond as array dimensions. For example, convert a random three-dimensional numeric array to umat.

Md = randn(4,5,6); 
M = umat(Md)

%
% The result is a one-dimensional array of uncertain matrices, rather than a three-dimensional uncertain array. Similarly, a four-dimensional numeric array converts to a two-dimensional array of umat objects.

Md = randn(4,5,6,7); 
M = umat(Md)

% See Array Management for Uncertain Objects for more information about multidimensional arrays of uncertain objects.
% Copyright 2012 The MathWorks, Inc.