SDT-nlsim         Contents     Functions              PDF Index

1.8  Data structures for HBM solvers

• Model, superelement
• Opt
• Node
• K{i},Klab{i},DOF
• Elt, Node, il, pl
• TR
• Non-linearity definition NLdata
• NL structure non-linearity representation during HBM solve
• Solver options definition
• Option structure during HBM solve
• Harmonic result structure

1.8.1  Model, superelement

The model structure containing in particular

• model.K list of matrices involved in the computation
• model.Klab list of labels describing each matrix
• model.Opt(2,:) list of labels describing each matrix
• model.NL stack of non-linearities.

This section describes a subset of superelement specifications described in more details in sdtweb('secms'). The structure is a standard OpenFEM model structure with additional fields described below.

Opt

Options characterizing the type of superelement as follows:

Node

Nominal node matrix. Contains the nodes used by the unique superelement. The only restriction in comparison to a standard model Node matrix is that it must be sorted by NodeId so that the last node has the largest NodeId.

K{i},Klab{i},DOF

Superelement matrices. The presence and type of these matrices is declared in the Opt field (see above) and should be associated with a label giving the meaning of each matrix.

All matrices must be consistent with the .DOF field which is given in internal node numbering.

Elt, Node, il, pl

Initial model retrieval for unique superelements. Elt field contains the initial model description matrix which allows the construction of a detailed visualization as well as post-processing operations. .Node contains the nodes used by this model. The .pl and .il fields store material and element properties for the initial model.

Once the matrices built, SE.Elt may be replaced by a display mesh if appropriate.

TR

TR field contains the definition of a possible projection on a reduction basis. This information is stored in a structure array with fields

• .DOF is the model active DOF vector.
• .def is the projection matrix. There is as many columns as DOFs in the reduced basis (stored in the DOF field of the superelement structure array), and as many row as active DOFs (stored in TR.DOF).
• .hdof, when appropriate, gives a list of DOF labels associated with columns of TR.def
• .data, when appropriate, gives a list frequencies associated with columns of TR.def
• .KeptDOF can be used to specify master DOFs not included TR.def but that should still be used for display of the superelement.

1.8.2  Non-linearity definition NLdata

Initialization of non-linear behavior in a cbush element group is performed with the following NLdata formats

Definition with custom functions. The NLdata property must contains the following fields

• type='nl_inout' to let hbm_solve InitHBM build the needed observation matrix
• Fu='@UserFun' references a user function computing the non-linear force with the prototype call described in section ??. Note that in instances of deployed MATLAB generated with the MATLAB compiler, all custom functions must be defined a priori. And only anonymous functions may be created.
• adofi to declare internal states, in coherence with field .MatTyp below. This field can be omitted of left empty if no such feature is used. Internal states are defined independently for each observation line used in the non-linearity. e.g. For a cbush six directions are available relative to the 3 translations and 3 rotations that can be observed. .adofi is then a line cell array of length the number of observations. Each cell defines a number of internal states associated to the corresponding observation index by providing a column vector with as many lines as internal states used each containing the DOF extension .99. The cell is left empty if no internal state is declared for a particular direction. NLdata.adofi={[];[];[];[];[];.99} will add an internal state to the 6^th observation of the non-linearity.
• .MatTyp : declares the time derivative of the signal associated to each internal DOF. This corresponds to matrix definitions in the Jacobian. Thus MatType=1 stiffness corresponds to a displacement DOF, 2 mass an acceleration DOF, 3 viscous damping a velocity DOF.
• .isens may be used to select a partial list of strains normally computed. For example to only keep translations of a cbush use .isens=[1 2 3].

1.8.3  NL structure non-linearity representation during HBM solve

NL structures describing each non-linearity

• NL.c standard observation matrix for the observed motion used to express load. Initially in physical coordinates and transformed to harmonic observation in Build_c_unl_k.
• NL.b command matrix to reapply harmonic loads on the proper DOFs.
• NL.Fu cell array of in-line functions.
• NL.type string containing the non-linearity type
• NL.c0,NL.b0 observation/command of non-linear strain in physical space only.

1.8.4  Solver options definition

out=struct('Method','hbm_solve',...
 'Opt',[0 9 1 .01 .4 0 1],... [adapt Nhmax nu fmin fmax UNU fvar]
 'SaveFreq',[0 .01 1e3 ],... [stra (full/block) fstep nFpoints]
 'RelTol',1e-9,'MaxIter',12,...
 'Rayleigh',[0 0],...
 'NeedUNL',[0 0],...
 'AssembleCall',hbm_solve('AssembleCall'),...
 'JacobianUpdate',pmat(zeros(1)),...
 'iterHBM','@iterHBM',...
 'initHBM','@initHBM',...
 'resHBM','@resHBM',...
 'abscHBM','@abscHBM',...
 'FinalCleanupFcn','hbm_solve(''fe_timeCleanup-cf-1'');',...
 ...'dSOpt',[ 2 1 0 .01 .01 .1  7 .3 1.5 6 12  ]); % [  Ldeg absc step dsfix dsmin dsmax iopt bmin bmax method maxite]
 'dSOpt',[1 .01 .01 .1  7 .3 1.5  2 ]); %step(lin/lagrange) dsfix dsmin dsmax iopt bmin bmax Ldeg

• opt.Method ('hbm_solve') Provides the method used by the solver. The default is hbm_solve for a frequency scan.
• opt.AssembleCall (= hbm_solve('AssembleCall')) Provides the call to perform an assembly performing initialization specific to the HBM module. This field is usually left by default, using the output of command hbm_solveAssembleCall.
• opt.Jacobian (= '') Provides a callback to compute the Jacobian used for the solver resolutions. The default procedures peforms Jacobian computations during residue computation so that this field is empty by default.
• opt.JacobianUpdate (= pmat(ones(1))) A pmat indicator controlling the Jacobian updating procedure. This can be set to 0 to ask not to update the current Jacobian, or to 1 to trigger an update. This value can be modified by the solver if automated Jacobian update schemes are used (see opt.juit).
• opt.initHBM (='@initHBM') Provides a function handle called for data initialization before solve. The internal method initHBM is used by default, this field is thus initialized with the internal handle name of the hbm_solve methods.
• opt.abscHBM (='@abscHBM') Provides a callback to perform curvilinear frequency predictions based on a buffer of response. The internal method abscHBM is used by default (provides linear or Lagrange polynomial interpolation), this field is thus initialized with the internal handle name of the hbm_solve methods.
• opt.iterHBM (='@iterHBM') Provides a callback to perform equilibrium iteration loops at a given point. The internal method iterHBM is used by default, this field is thus initialized with the internal handle name of the hbm_solve methods.
• opt.resHBM (='@resHBM') Provides a callback to compute the equilibrium residue of a given HBM state. The internal method resHBM is used by default (also provides Jacobian computation), this field is thus initialized with the internal handle name of the hbm_solve methods.
• opt.Opt (= [adapt Nhmax nu fmin fmax UNU fvar])
  • adapt (= 0) Unused, must be left to 0.
  • Nhmax (= 9) Defines the maximum number of harmonics considered, drives the transient buffer size.
  • nu (= 1) Defines the harmonic factor ω = k/ν.
  • fstart (= .01) Defines the starting frequency for scanning.
  • fend (= .4) Defines the end frequency for scanning.
  • UNU (= 0) Unused value left to zero for OpenFEM retro-compatibility.
  • fvar (= 1) Declares the frequency representation, either fixed (fvar = 0) or unknown (fvar = 1). If set to 1 the harmonics vector Z is augmented with the pulsation, corresponding to harmonic DOF 1.99,'freq'.
• opt.Rayleigh (= [alpha beta]) Provides Rayleigh damping values applied to system matrices, defining C=α M + β K.
• opt.juit (= -Inf) Defines an automated Jacobian update strategy used in resHBM, the Jacobian is then updated only after juit iterations. The default value set to -Inf asks for an update at each step.
• opt.dSOpt (= [stra dsfix dsmin dsmax iopt bmin bmax Ldeg]) Defines the curvilinear frequency prediction for continuation techniques, used by abscHBM.
  • stra (= 1) defines the increment strategy, either fixed (0) or with Lagrange polynomials (1).
  • fix (= .01 ) defines the fixed pulsation step , used for fixed strategy and to initialize other ones.
  • min (= .01) defines the minimum authorized pulsation step.
  • max (= .1) defines the maximum authorized pulsation step.
  • iopt (= 7) defines an optimal iteration number indicator. Pulsation frequency continuations will be modulated to target iopt iteration for convergence.
  • bmin (= .3) defines the minimal modulation factor applied to reach iopt iterations for convergence.
  • bmax (= 1.5) defines the maximal modulation factor applied to reach iopt iterations for convergence.
  • Ldeg (= 2) defines the degree of the Lagrange polynomial extrapolation.
• opt.RelTol (= 1e-9) defines the tolerance to consider the HBM equilibrium is attained.
• opt.MaxIter (= 12) defines the maximum number of iterations allowed before stopping the loop.
• opt.SaveFreq (= [stra fstep nFpoints]) defines the output storage strategy.
  • stra (= 0) defines the storage strategy. 0 defines a direct output saving, saving as much as nFpoints results every time the module frequency change is greater than fstep since the last save.
  • fstep (= .01) defines the frequency module evolution step triggering a save.
  • nFpoints (= 1e3) defines the total number of results saved in the output.
• opt.NeedUNL (= [0 0]) asks to save unl (if opt.NeedUNL(1)==1) and/or vnl (if NL.NeedUNL(2)==1) observations.
• opt.FinalCleanupFcn Provides the call to perform output cleanup after resolution. This field is usually left by default, calling hbm_solve('fe_timeCleanup'). Token -cf-1 directly stores the result in the GUI.

1.8.5  Option structure during HBM solve

Inside the solver loop, developers may want to access a number of parameters described below. The internal structure during time solves is described in sdtweb('nldata#nlformtime');

• opt.N number of samples for time signal
• opt.A A matrix (??) (this matrix gets overwritten during iterations).
• opt.Hkt unit evolution of a given harmonic.(??)
• opt.dHkt time derivative of unit evolution of a given harmonic.
• opt.hdof two column matrix giving for each DOF the physical DOF and the time variation index.
• opt.harm internal field of retained harmonics.

1.8.6  Harmonic result structure

is the data structure used to store SDT-HBM results. It is a variation of the curve format. With the first dimension containing harmonic DOFs, the second frequencies and the last amplitudes.

sdtweb hbm_solve('outputinithbm')
 out=struct('Y',zeros(r1),...
  'X',{[{hdof}, freq,amp]},...
  'Xlab',{'Hdof','Freq','Amp'},...
  'hdof',{opt.hdof},'DOF',Case.DOF,...
  'harm',opt.harm,'idof',opt.idof,'ihdof',opt.ihdof,'cur',zeros(1,max(3,length(r1)+1)));