ii_mac

ii_mac#

Purpose

User interface function for MAC and other vector correlation criteria.

Syntax

           ii_mac(cpa,cpb)
VC       = ii_mac(cpa,cpb,'PropertyName',PropertyValue, ...)
[VC,ReS] = ii_mac('PropertyName',PropertyValue, ... ,'Command')
           ii_mac(Fig,'PropertyName',PropertyValue, ... ,'Command')
Result =   ii_mac(Fig ,'Command')
VC.PropertyName = PropertyValue

Description

The ii_mac function gives access to vector correlation tools provided by the SDT starting with the Modal Assurance Criterion (MAC) but including many others.

The high level implentation of tools provided by ii_macis interfaced in the dock CoShape. A summary of typical applications is given in section 3.2 and examples in the d_cor demo.

You can also use low level calls to just display a figure or a table, as illustrated by the expamples below.

Vector correlations are SDT objects which contain deformations, see va, typically given at test sensors. For criteria using model mass or stiffness matrices see m. Other details about possible fields of VC objects are given after the listing of supported commands below.

GUI

If you use ii_mac without requesting graphical output, the vector correlation object is deleted upon exit from ii_mac. In other cases, the object is saved in the figure so that you can reuse it.

 [model,sens,ID,FEM]=demosdt('demopairmac'); % Sample data
cf=comgui('guifeplot-reset',2); % force feplot in figure(2);
cf.model=model;  % Display FEM (contains topology correl see fe_case(model,'sens','Test'))
VC=ii_mac(ID,FEM,'sens',sens,'mac plot -cf1'); %Single plot
% See also tutorial in sdtweb d_cor('TutoCoShape');

You can add data to other fields or call new commands from the command line by starting the ii_mac call with a pointer to the figure where the vector correlation is stored (ii_mac(fig,'Command'), ...). An alternate calling form is to set a field of the vector correlation object.

The following commands

 [model,def_fem,res_test]=demosdt('demo GartDataCoshape');
 cf=feplot(model);
 Sens=fe_case(cf.mdl,'sens');
 figure(1); subplot(221); VC=ii_mac(1);% Make figure(1) current so that ii_mac uses it
 ii_mac(VC,res_test,def_fem,'labela','Test','labelb','FEM', ...
           'sens',Sens,'Mac Pair Plot');
 subplot(212);ii_mac(VC,'comac'); % set new axis and display other criterion
 % Assemble to get mass and stiffness for MacM computation
 model2=fe_case('assemble -matdes 2 1 NoT -SE',model); % see sdtweb simul#feass
 subplot(222); ii_mac(VC,'m',model2.K{1},'k',model2.K{2},'MacMPairPlot'); % Add m and k matrices to computed teh condensed mass

illustrate a fairly complex case where one shows the MAC in subplot(221), all three COMAC indicators in subplot(212), then provide mass and a mass-shifted stiffness to allow computation of the mass condensed on sensors and finally show the reduced mass weighted MAC in subplot(222).

The II_MAC menu lets you choose from commands that can be computed based on the data that you have already provided. The context menu associated with plots generated by ii_mac lets you start the cursor, display tabular output, ...

You can link deformations shown in a feplot figure to a MAC plot using

 [model,sens,ID,FEM]=demosdt('demopairmac');
 cf=feplot(model);
 cf.def(1)=ID;  % display test as first def set
 cf.def(2)=FEM; % display FEM as second def set
 % overlay & show interactive MAC in fig 1:
 figure(1);clf;fecom('show2def-mac1')

Main commands

Options ... [Plot,Table,Tex,Thtml]#

By default, the commands plot the result in a figure. Options valid for all commands are

plot generates figure in the current axis. You can use figure and subplot to set the current axis.
Table generates a text output
Tex generates a format suitable for direct inclusion in LaTeX
Thtml creates and open an html file in the MATLAB browser.

Data fields#

Data fields are defined using name, value pairs.

'cpa',dataAsCols sets shapes . But calls with data structures are preferable, see va.
'sens',sens sets sensor observation matrix, see sens.
'labela','name' sets the name of data set A. Typical values are Test, FEM, ...
'inda',ind selects vectors given by ind when computing a criterion. For example, rigid body modes are often not included in correlation. Thus 'indb',7:20 would skip the first 6 modes.
'SubDofInd',ind allows the selection a subset of sensors when computing correlation criteria.

MAC [,M] [ ,PairA,PairB,AutoA, ...] ...#

The Modal Assurance Criterion (MAC) [11] is the most widely used criterion for vector correlation (mainly because of its simplicity).

The MAC is the correlation coefficient of vector pairs in two vector sets cpa and cpb defined at the same DOFs (see ii_mac va for more details). In general cpa corresponds to measured modeshapes at a number of sensors {cφ_{id j}} while cpb corresponds to the observation of analytical modeshapes [c]{φ_k}. The MAC is given by

(10.32)

For two vectors that are proportional the MAC equals 1 (perfect correlation). Values above 0.9 are generally considered as well correlated. Values below 0.6 should be considered with much caution (they may or may not indicate correlation).

The commands and figure below shows the standard 2-D (obtained using the context menu or view(2)) and 3-D (obtained using the context menu or view(-130,20)) representations of the MAC supported by ii_mac. The color and dimensions of the patches associated to each vector pair are proportional to the MAC value.

 [model,sens,ID,FEM]=demosdt('demopairmac');
if ishandle(1);close(1);end;figure(1);
VC=ii_mac(1,ID,FEM,'sens',sens,'mac paira table')
ii_mac(VC,'mac paira plot');

The basic MAC shows vector pairs for all vectors in the two sets. Specific command options are

MacM should be used when a mass is provided, see MacM
MacPairA command seeks for each vector in cpa (cpb with PairB) the vector in cpb (cpa) that is best correlated. MacPairB pairs against cpb vectors.
MacAutoA Since the objective of the MAC is to estimate the correlation between various vectors, it is poor practice to have vectors known to be different be strongly correlated.
Strong correlation of physically different vectors is an indication of poor test design or poor choice of weighting. MacAutoA (B) compute the correlation of cpa (cpb) with itself. Off diagonal terms should be small (smaller than 0.1 is generally accepted as good practice).
-combineval allows orthogonal linear combinations of vectors whose frequencies are closer than val relatively. This is meant for cases with very closely spaced modes where subspaces rather than individual vectors should be compared.
To be more precise, indices of shapes that are meant to be combined can be provided directly in a structure with two fields GroupA and GroupB. For instance the command
```
 r1=struct('GroupA',{{[8 9] [11 12]}},'GroupB',{{[14 15] [17 18]}});
 VC.Combine=r1;
 ii_mac(VC,'mac plot');
```
will combine first the shapes 8 9 of setA with the shapes 14 15 of setB, and then the shapes 11 12 of setA and the shapes 17 18 of setB.
Error computes the MAC (or MAC-M), does pairing and plots a summary combining the MAC value found for paired modes and the associated error on frequencies ((fb-fa)./fa). Typical calls can be found in gartco example.
By default this command displays a plot similar to the one shown below where the diagonal of the paired MAC and the corresponding relative error on frequencies are shown. For text output see general command options.
This is an example of how to use of the MACError command. In this example, the only significant errors are associated with mode crossing so that the .Combine gives a nearly perfect coerrelation.
```
 [model,sens,ID,FEM]=demosdt('demopairmac');
 if ishandle(1);close(1);end;figure(1);
 VC=ii_mac(1,ID,FEM,'sens',sens)
 ii_mac(1,'SetMAC',struct('Pair','A','MacPlot','do'))
 ii_mac(1,'macerror table',struct('MinMAC',.6,'Df',.2,'Combine',.1));
 ii_mac(1,'SetMAC',struct('MacError','do'))
```

A few things you should know ...

The MAC measures the shape correlation without any reference to scaling of each vector (because of the denominator in (10.32)). This makes the MAC easy to use but also limits its applicability (since the modeshape scaling governs the influence of a given mode on the overall system response, a proper scaling is necessary when comparing the relative influence of different modes). In other terms, the MAC is not a norm (two vectors can be very correlated and yet different), so care must be taken in interpreting results.
As the MAC is insensitive to mode scaling, it can be used with identified normal mode residues. You do not have to determine modal masses (see id_rm) to compute a MAC.
The main weakness of the MAC is linked to scaling of individual components in the correlation. A change in sensor calibration can significantly modify the MAC. If the natures of various sensors are different (velocity, acceleration, deformation, different calibration...) this can induce significant problems in interpretation.
The reference weighting in mechanics is energy. For vectors defined at all DOFs, the MAC is a poor criterion and you should really use its mass weighted counter part. For incomplete measurements, kinetic energy can be approximated using a static condensation of the mass on the chosen sensors which can be computed using the MacM command.
In certain systems where the density of sensors is low on certain parts, cross-correlation levels with the mass weighted MAC can be much lower than for the non weighted MAC. In such cases, you should really prefer the mass weighted MAC for correlation.

MACCo [ ,M] [,ns]#

The MACCo criterion is a what if analysis. It takes modes in cpa, cpb and computes the paired MAC or MAC-M with one sensor removed. The sensor removal leading to the best mean MAC for the paired modes is a direct indication of where the poorest correlation is found. The algorithm removes this first sensor then iteratively proceeds to remove ns other sensors (the default is 3). The MACCo command used with command option text prints an output of the form

   Test        1   2   3   4   5   6   7   8
    FEM        7   8  11  10  11  12  13  14
 Sensor Mean                                
    All   87 100  99  60  86  53 100  98 100
  1112z   88 100  99  59  90  62 100  98 100
  1301z   89 100  99  62  90  64 100  98 100
  1303z   90 100  98  66  90  66 100  98 100

where the indices for the vectors used in the pairing are shown first, then followed by the initial mean MAC and MAC associated to each pair. The following lines show the evolution of these quantities when sensors are removed. Here sensor 1112z has a strong negative impact on the MAC of test mode 5.

The sensor labels are replaced by sensor numbers if the sensor configuration sens is not declared.

By default the MACCO command outputs a structure in which field .data contains in its first column the sensor or index removed and the resulting MAC evolution of paired modes in the following columns. The field .xlabel contains the sensor labels or indices.

Command option plot will plot in the ii_mac figure the MAC evolutions as function of the sensors removed. Command option text will output the result as text.

This is an example of how to use of the MACCO command

% To see the result
 [model,sens,ID,FEM]=demosdt('demopairmac');
 figure(1);clf;VC=ii_mac(1);
 ii_mac(VC,ID,FEM,'sens',sens, ...
  'inda',1:8, ... % Select test modes to pair
  'macplot')
% See sensors for each mode
r1=ii_mac(VC,'inda',1:8,'MacCo',struct('Table',1,'ByMode',1,'N',5));
% See sensors improving mean modes
r2=ii_mac(VC,'inda',1:8,'MacCo',struct('Table',1,'N',5));
% Numeric values stored in r1 and r2.

MacM ...#

When cpa and cpb are defined at finite element DOFs, it is much more appropriate to use a mass weighted form of the MAC defined as

(10.33)

called with ii_mac( ... 'm',m,'MacM Plot'). If vectors are defined as sensors, the problem is to define what the mass should be. The standard approach is to use the static condensation of the full order model mass on the sensor set. When importing an external reduced mass matrix, just define the mass as shown above, when using SDT, see the ii_mac mc section below.

If cpa is defined at sensors and cpb at DOFs, ii_mac uses the sensor configuration sens to observe the motion of cpb at sensors. If cpa is defined at DOFs and cpb at sensors, ii_mac calls fe_exp to expand cpb on all DOFs.

The MAC-M can be seen as a scale insensitive version of the Pseudo-Orthogonality check (also called Cross Generalized Mass criterion) described below.

COMAC [ ,M][,A,B][,N][,S][,E] [,sort]#

The COMAC command supports three correlation criteria (N nominal, S scaled and E enhanced) whose objective is to detect sensors that lead to poor correlation. You can compute all or some of these criteria using the n, s, or e options (with no option the command computes all three). Sensors are given in the nominal order or sorted by decreasing COMAC value (sort command option).

These criteria assume the availability of paired sets of sensors. The COMAC commands thus start by pairing modes (it calls MacPair or MacMPair) to pair vectors in cpb to vectors in cpa. The B command option can be used to force pairing against vectors in set B (rather than A which is the default value).

The nominal Coordinate Modal Assurance Criterion (COMAC) measures the correlation of two sets of similarly scaled modeshapes at the same sensors. The definition used for the SDT is

(10.34)

which is 1 minus the definition found in [63] in order to have good correlation correspond to low COMAC values.

The assumption that modes a similarly scaled is sometimes difficult to ensure, so that the scaled COMAC is computed with shapes in set B scaled using the Modal Scale Factor (MSF)

(10.35)

which sets the scaling of vectors in set B to minimize the quadratic norm of the difference between and .

The enhanced COMAC (eCOMAC), introduced in [64], is given by

(10.36)

where the comparison is done using modeshapes that are vector normalized to 1

(10.37)

This is an example of how to use of the COMAC command

 [model,sens,ID,FEM]=demosdt('demopairmac');
figure(1);clf;VC=ii_mac(1);
ii_mac(VC,ID,FEM,'sens',sens,'comac plot')
ii_mac(VC,'comac table');

POC [,Pair[A,B]] ...#

The orthogonality conditions (6.78) lead to a number of standard vector correlation criteria. The pseudo-orthogonality check (POC) (also called Cross Generalized Mass (CGM)) and the less commonly used cross generalized stiffness (CGK) are computed using

(10.38)

where for mass normalized test and analysis modes one expects to have µ_jk≈ δ_jk and κ_jk≈ ω_j²δ_jk.

For matched modes, POC values differing significantly from 1 indicate either poor scaling or poor correlation. To distinguish between the two effects, you can use a MAC-M which corresponds to the square of a POC where each vector would be normalized first (see the MacM command).

Between unmatched modes, POC values should be close to zero. In some industries, off-diagonal cross POC values below 0.1 are required for the test verification of a model.

The PairA, PairB, Plot, Table options are available for POC just as for the MAC.

Rel [,scaled][,m]#

For scaled matched modeshapes, the relative error

(10.39)

is one of the most accurate criteria. In particular, it is only zero if the modeshapes are exactly identical and values below 0.1 denote very good agreement.

The rel command calls MacPair to obtain shape pairs and plots the result of (10.39).

For uncalled matched modeshapes, you may want to seek for each vector in set B a scaling coefficient that will minimize the relative error norm. This coefficient is known as the modal scale factor and defined by

(10.40)

The RelScale command calls MacPair to obtain shape pairs, multiplies shapes in set B by the modal scale factor and plots the result of (10.39).

With the M option, the MacPairM is used to obtain shape pairs, kinetic energy norms are used in equations (10.39)-(10.40).

This is an example of how to use the Rel command

 [model,sens,ID,FEM]=demosdt('demopairmac');
 ii_mac(ID,FEM,'sens',sens,'rel');

VC#

The following sections describe standard fields of VC vector correlation objects and how they can be set.

VC.va	vector set A detailed below
VC.vb	vector set B detailed below.
VC.sens	sensor description array describing the relation between the DOFs of cpb and the sensors on which cpa is defined.
VC.m	full order mass matrix
VC.mc	reduced mass matrix defined at sensors (see definition below)
VC.qi	sensor confidence weighting
VC.k	full order stiffness matrix
VC.kd	factored stiffness or mass shifted stiffness matrix
VC.T	reduced basis used for dynamic expansion

va,vb,sens#

ii_mac uses two data sets referenced in VC.va and VC.vb and extracts shapes at sensors using the get_da_db command shown below. All standard input formats for shape definition are accepted

FEM result with .def and .DOF fields, see section 7.8.
Shapes at IO pairs or pole residue with .res and .po fields (see section 5.6)
Response data with .w and .xf fields
simple matrix with rows giving DOFs and columns shapes. These will be stored in the va.def field, called cpa which stands for [c] {φ_a} since these vectors typically represent the observation of modeshapes at test sensors, see section 5.1. A typical call would thus take the form
```
 FigHandle=figure(1);
 ii_mac(FigHandle,'cpa',shapes_as_col,'labela','Test', ...
     'cpb',shape2, ... % Define vb
     'mac');  % define command
```

sens, when defined (see section 4.7 for the generation of sensor configurations), does not use the results defined in VC.va but their observation given by VC.sens.cta*VC.va.def (same for VC.vb).

The illustration below uses a typical identification result ID, a FEM result FEM and observes on sensors.

 [model,sens,ID,FEM]=demosdt('demopairmac -open')
 figure(1);[r1,VC]=ii_mac(ID,FEM,'sens',sens, ...
  'indb',7:20,'mac plot');
 [da,db]=ii_mac(VC,'get_da_db')

The da.def and db.def fields are always assumed to be observed at the same sensors (correspond to the cpa, cpb fields if these are defined).

To support expansion, cpa is defined at DOFs and cpb at sensors, ii_mac calls fe_exp to expand cpb on all DOFs.

m,k,kd#

For criteria that use vectors defined at DOFs, you may need to declare the mass and stiffness matrices. For large models, the factorization of the stiffness matrix is particularly time consuming. If you have already factored the matrix (when calling fe_eig for example), you should retain the result and declare it in the kd field.

The default value for this field is kd=ofact(k,'de') which is not appropriate for structures with rigid body modes. You should then use a mass-shift (kd = ofact( k + alpha*m,'de'), see section 6.2.4).

mc#

The SDT supports an original method for reducing the mass on the sensor set. Since general test setups can be represented by an observation equation (4.1), the principle of reciprocity tells that [c]^T corresponds to a set of loads at the location and in the direction of the considered sensors. To obtain a static reduction of the model on the sensors, one projects the mass (computes T^TMT) on the subspace

(10.41)

In cases where the model is fixed [K] is non-singular and this definition is strictly equivalent to static/Guyan condensation of the mass [23]. When the structure is free, [K] should be replaced by a mass shifted [K] as discussed under the kd field above.

T#

Reduced basis expansion methods were introduced in [23]. Static expansion can be obtained by using T defined by (10.41).

To work with dynamic or minimum residual expansion methods, T should combine static shapes, low frequency modes of the model, the associated modeshape sensitivities when performing model updating.

Modeshape expansion is used by ii_mac when cpa is full order and cpb is reduced. This capability is not currently finalized and will require user setting of options. Look at the HTML or PDF help for the latest information.