Contents     Functions         Previous Next     PDF Index



User interface function for parameterized superelements.


The upcom interface supports type 3 superelements which handle parameterization by storing element matrix dictionaries and thus allowing reassembly of mass and stiffness matrices computed as weighted sums of element matrices (6.107).

By default, upcom uses a special purpose superelement stored in the global variable Up. You can however use more than one type 3 superelement by providing the appropriate variables as input/output arguments. upcom('info') applies to Up whereas upcom(model,'info') applies to model.

The par commands are used to dynamically relate the element matrix weights to physical parameters thus allowing fairly complex parametric studies on families of models. The main objective for upcom is to enable finite element model updating, but it can also be used for optimization and all problems using with families of models or hysteretic damping modeling as illustrated in section 5.3.2.

The following paragraphs detail calling formats for commands supported by upcom and are followed by an explanation of the signification of the fields of Up (see the commode help for hints on how to build commands and understand the variants discussed in this help).

More details on how these commands are typically sequenced are given in the Tutorial section 6.4 and section 6.5.


Clear, Load File , Save File

upcom('clear') clears the global variable Up and the local and base variables Up if they exist. If these local variables are not cleared then the global variable Up is reset to that value.

upcom('load File') loads the superelement fields from File.mat and creates the file if it does not currently exist. upcom('save File') makes sure that the current values of the various fields are saved in File.mat. Certain commands automatically save the superelement but efficiency mandates not to do it all the time. The working directory field Up.wd lets you work in a directory that differs from the directory where the file is actually located.

Assemble [,m,k] [,coef cur],[,delta i][,NoT][,Point]

[m,k] = upcom('assemble') returns the mass and stiffness parameters associated with the parameters by the last parcoef command. You should look up newer assembly calls in section 4.8.8.

Assemble Coef cur uses the parameter values cur for the assembly. Assemble CoefNone does not use any parameter definitions (all the element matrices are used with a unit weighting coefficient). AssembleMind uses columns 5 and 6 of Up.mind for element matrix coefficients.

Assemble Delta i assembles the derivative of matrices with respect to parameter i. To assemble a derivative with non zero components on more than one parameter, use [dm,dk]=upcom('assemble delta',dirp) where dirp (with Npar rows) characterizes the amplitude of the derivative on each parameter for the current change. dirp can for example be used to describe simultaneous changes in mass and stiffness parameters.

k=upcom('assemble k coef 2 3') only assembles the stiffness with parameter coefficients set to 2 and 3. Similarly, dm=upcom('assemble m delta 2') will assemble the mass derivative with respect to parameter 2.

The NoT option can be used to prevent the default projection of the matrices on the master DOFs defined by the current case.

The Point option can be used return the v_handle object pointing to the non assembled matrix. This matrix can then be used in feutilb('tkt') and feutilb('a*b') out of core operations.

ComputeMode [ ,full,reduced] [,eig_opt]

[mode,freq] = upcom('ComputeMode') assembles the model mass and stiffness based on current model parameters (see the parcoef command) and computes modes. The optional full or reduced can be used to change the current default (see the opt command). The optional eig_opt can be used to call fe_eig with options other than the current defaults (see the opt command).

 upcom('load GartUp');
 def = upcom('computemode full 105 10 1e3');

For reduced model computations, the outputs are [moder,freq,modefull].

ComputeModal [ ,full,reduced]

Given a parameterized model, the command ComputeModal computes the frequency response associated to all the inputs and outputs of the model, taken into account the damping ratio. ComputeModal computes the normal modes and static corrections for inputs of the full or reduced order models based on the full or reduced model. nor2xf is then called to build the responses (for sensor load definitions within the model, see nor2xf).

 Up=upcom('load GartUp');
 upcom(Up,'compute modal full acc iiplot "updated" -po -reset'); 

You may want to compute the direct frequency response associated the inputs on all the DOFs structure. It does not compute modes and is thus faster than ComputeModal for a full order model and a few frequency points. The high level call uses the fe_simul function


Ener [m, k]

ener = upcom('ener k',def) computes the strain energy in each element for the deformations def. ener is a data structure with fields .IndInElt specifying the element associated with each energy row described in the .data field. You can display the kinetic energy in an arbitrary element selection of a structure, using a call of the form

cf.sel={'group6','colordata elt',upcom('ener m','group6',mode)};


upcom('fix0') eliminates DOFs with no stiffness contribution. upcom('fix',adof) only retains DOFs selected by adof.

This command is rather inefficient and you should eliminate DOFs with FixDOF case entries (see fe_case) or assemble directly with the desired DOFs (specify adof in the SetNominal command).


Information about the superelement is stored in fields of the global variable Up. The easiest way to access those fields is to make the variable local to your workspace (use global Up) and to access the fields directly. The superelement also has pseudo-fields mi,me,ki,ke which are always stored in Up.file. Commands of the form load(Up.file,'ke') are used to get them.


upcom femesh copies Up.Elt to FEelt and Up.Node to FEnode so that femesh commands can be applied to the model.


upcom('IndInElt') returns a vector giving the row position in Up.Elt of each row in Up.mind. This is in particular used for color coded energy plots which should now take the form


Although it is typically easier to use high level calls of the form

 upcom('load GartUp');upcom('plotelt');
 cf=feplot;cf.def=fe_eig(Up,[5 10 1e3]);fecom('ch7');
 cf.sel={'groupall','colordata enerk'};

Info [ ,par,elt]

upcom('info') prints information about the current content of Up: size of full and reduced model, values of parameters currently declared, types, etc.

InfoPar details currently defined parameters. InfoElt details the model.


upcom('opt Name Value ') sets the option Name to a given Value. Thus upcom ('opt gPrint 11') sets the general printout level to 11 (maximum). Accepted names and values are detailed in the Up.copt field description below.

Par [add type values,reset]

These commands allow the creation of a parameter definition stack. Each parameter is given a type (k for stiffness, m for mass, t for thickness) optional current, min and max values, a name, and an element selection command.

 Up=upcom('load GartUp');  % Load sample model
 Up=fe_case(Up,'ParReset') % Reset parameters
 Up=fe_case(Up,'ParAdd k 1.0 0.5 2.0','Tail','group3');
 Up=fe_case(Up,'ParAdd t 1.0 0.9 1.1','Constrained Layer','group6');
 Up=fe_case(Up,'parcoef',[1.2 1.3]);
 upcom(Up,'info par');

Parameters are stored in the case stack and can be selected with


des is a cell array where each row has the form {'par','name',data} with data containing fields

.selstring or cell array allowing selection of elements affected by the parameter
.coefvector of parameter coefficients (see format description under upcom ParCoef).
.pdirBoolean vector giving the positions of affected elements in Up.mind (for upcom models)
.nameParameter name
.zCoefoptional string definition of the zcoef associated to the parameter.


The value of each physical parameter declared using upcom Par or fe_case par commands is described by a row of coefficients following the format

    [type cur min max vtype]


upcom(Up,'parcoef',cur) is used to set current values (cur must be a vector of length the number of declared parameters), while upcom(Up,'parcoef',par) also sets min, max and vtype values. You can also use [cur,par]=upcom(Up,'parcoef') or par=upcom(Up,'parcoefpar') to obtain current values or the parameter value matrix.

An example of parameter setting is thus

Up=demosdt('gartup'); % see sdtweb demosdt('gartup')
%      MatType cur min max vtype
par = [ 1      1.0 0.1 3.0  1 ; ... % Linear
        3      0.0  -1 2.0  2 ];    % Log variation
upcom(Up,'info par');

Note that to prevent user errors, upcom does not allow parameter overlap for the same type of matrix (modification of the modulus and/or the thickness of the same element by two distinct parameters).


upcom('par red',T) projects the current full order model with the currently declared parameters on the basis T. Typical reduction bases are discussed in section 6.2.7 and an example is shown in the gartup demo. Matrices to be projected are selected based on the currently declared variable parameters in such a way that projected reduced model is able to make predictions for new values of the parameters.


tt=upcom('partable') returns a cell array of string describing the parameters currently declared. This cell array is useful to generate formatted outputs for inclusion in various reports using comstr(tt,-17,'excel') for example.


upcom plotelt initializes a feplot figure displaying the model in upcom. If Up has deformations defined in a .def field, these are shown using cf=feplot;cf.def=Up.

Profile [,fix]

Renumbers DOFs and pseudo-fields mi,me,ki,ke using symrcm to minimize matrix bandwidth. ProfileFix eliminates DOFs with no stiffness on the diagonal at the same time. upcom('ProfileFix',fdof) profiles and eliminates DOFs in fdof and DOFs with no stiffness on the diagonal.

Support for case entries (see fe_case) makes this command obsolete.

SensMode [,reduced]

[fsen,mdsen,mode,freq] = upcom('SensMode',dirp,indm,T) returns frequency and modeshape sensitivities of modes with indices given in indm for modifications described by dirp.

For a model with NP parameters (declared with the Par commands), dirp is a matrix with Npar rows where each column describe a case of parameter changes of the form par = dirp(:,j). The default for dirp the identity matrix (unit change in the direction of each parameter).

The optional argument T can be used to give an estimate of modeshapes at the current design point. If T is given the modes are not computed which saves time but decreases accuracy if the modes are not exact.

fsen gives, for modes indm, the sensitivities of modal frequencies squared to all parameters (one column of fsen per parameter). mdsen stores the modeshape sensitivities sequentially (sensitivities of modes in indm to parameter 1, parameter 2, ...).

When modeshape sensitivities are not desired (output is [fsen] or [fsen, mode, freq]), they are not computed which takes much less computational time.

By default SensMode uses the full order model. The first order correction to the modal method discussed in Ref. [42] is used. You can access the reduced order model sensitivities using SensModeReduced but should be aware that accuracy will then strongly depend on the basis you used for model reduction (ParRed command).

SetNominal [ , t groups]

To generate a new model, you should first clear any Up variable in the workspace, specify the file that where you will want the element matrices to be saved, then perform the assembly. For example

 % delete(fullfile(Up.wd,[Up.file,'.mat'])) % to remove the result

Case information (boundary conditions, ... see fe_case) in model is saved in Up.Stack and will be used in assembly unless the NoT option is included in the Assemble command.

If the parameter that will be declared using the Par commands include thickness variations of some plate/shell elements, the model will use element sub-matrices. You thus need to declare which element groups need to have a separation in element submatrices (doing this separation takes time and requires more final storage memory so that it is not performed automatically). This declaration is done with a command of the form SetNominal T groups which gives a list of the groups that need separation.

Obsolete calling formats upcom('setnominal',FEnode,FEelt,pl,il) and upcom( 'setnominal',FEnode,FEelt,pl,il,[],adof) ( where the empty argument [] is used for coherence with calls to fe_mk) are still supported but you should switch to using FEM model structures.

Fields of Up

Up is a generic superelement (see description under fe_super) with additional fields described below. The Up.Opt(1,4) value specifies whether the element matrices are symmetric or not.


The computational options field contains the following information

 (1,1:7) = [oMethod gPrint Units Wmin Wmax Model Step]

oMethodoptimization algorithm used for FE updates

1: fmins of MATLAB (default)

2: fminu of the Optimization Toolbox

3: up_min

gPrintprintout level (0 none to 11 maximum)
Unitsfor the frequency/time data vector w and the poles

01: w in Hertz 02: w in rad/s 03: w time seconds

10: po in Hertz 20: po in rad/s

example: Up.copt(1,3) = 12 gives w in rad/sec and po in Hz

Wminindex of the first frequency to be used for update
Wmaxindex of the last frequency to be used for update
Modelflag for model selection (0 full Up, 1 reduced UpR)
Stepstep size for optimization algorithms (foptions(18))
 (2,1:5) = [eMethod nm Shift ePrint Thres MaxIte]

are options used for full order eigenvalue computations (see fe_eig for details).

 (3,1)     = [exMethod ]

exMethod expansion method (0: static, 1: dynamic, 2: reduced basis dynamic, 3: modal, 4: reduced basis minimum residual)

Up.mind, Up.file, Up.wd, mi, me, ki, ke

Up stores element submatrices in pseudo-fields mi,me,ki,ke which are loaded from Up.file when needed and cleared immediately afterwards to optimize memory usage. The working directory Up.wd field is used to keep tract of the file location even if the user changes the current directory. The upcom save command saves all Up fields and pseudo-fields in the file which allows restarts using upcom load.

ki,mi are vectors of indices giving the position of element matrix values stored in ke,me. The indices use the column oriented numbering from 1 to N2 where N is the assembled matrix size.

Up.mind is a NElt x6 matrix. The first two columns give element (sub-)matrix start and end indices for the mass matrix (positions in mi and me). Columns 3:4 give element (sub-)matrix start and end indices for the stiffness matrix (positions in ki and ke). Column 5 (6) give the coefficient associated to each element mass (stiffness) matrix. If columns 5:6 do not exist the coefficients are assumed equal to 1. The objective of these vectors is to optimize model reassembly with scalar weights on element matrices.

Up.Node, Up.Elt,,, Up.DOF, Up.Stack

Model nodes (see section 7.1), elements (see section 7.2), material (see section 7.3) and element (see section 7.4) property matrices, full order model DOFs. These values are set during the assembly with the setnominal command.

Up.Stack contains additional information. In particular parameter information (see upcom par commands) are stored in a case (see section 7.7) saved in this field.


Sensor configuration array built using fe_sens. This is used for automatic test / analysis correlation during finite element update phases.

See also

fesuper, up_freq, up_ixf

©1991-2016 by SDTools
Previous Up Next