SDT-nlsim         Contents     Functions              PDF Index

1.6  Data structures for non-linearities in time

• NLdata non-linearity definition (model declaration)
• Additional fields in model
• NL structure : non-linearity representation during time integration

1.6.1  NLdata non-linearity definition (model declaration)

A non linearity has the following input form when stored as NLdata of an element group property.

• .type a MATLAB function handle which is used for initialization phases. The most commonly used non-linearity is nl_inout. For transient simulations observation matrices are built in nl_spring('init') while for HBM solutions this is done in hbm_solve InitHBM.
• .Fu can be done through generic anonymous functions see section 1.3.7, user defined anonymous functions see section 1.3.6, tabular definitions section 1.3.2.
• .Fv can be used for tabular definitions section 1.3.2 of laws on velocity.
• .adof optional definition of DOF specific to the non linearity that will be propagated to model.FNLDOF. For vectorized non-linearities, this gives the decimal part describing fields associated with .snl. To associate other DOF to .unl, you can set a .udof field.
• .isens optional : 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].
• .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. For the cell array format, rows correspond to each observed strain, and multiple columns can be given when multiple Gauss points differ. More details are given under DOF representation of internal states.
• .keepLin set to zero to avoid assembly of linear behavior in the base matrices
• .MatTyp : declares the time derivative of the signal associated to each internal DOF. When using explicit definitions of internal DOF, as in HBM or time integration with explicit internal states, this is used to specify how to compute the Jacobian (see nl_spring NLJacobianUpdate). Thus MatType=1 stiffness corresponds to a displacement DOF, 2 mass an acceleration DOF, 3 viscous damping a velocity DOF.
• .Jacobian can be a function computing the tangent matrix or a number as described for nl_spring nl_inout.
• .obs Optional command to fill in out.FNL.NL, see below. This can either be a logical, evaluating nl_fun('obs'), or a cell-array giving non linear data fields to propagate to the output from model.NL, or a string which will be evaluated.
• .snl as a empty field will force the initialization of a NL.snl buffer during time integration.
• .StoreType can be used to specify the StoreType strategy.
• .MexCb is a cell array giving callback function and options (for an example see d_fetime K_t) . .MexCb{1}=fun should be a function handle within a function that also contains
  • funtoOpt the method checking init of the non-linearity, called in nlutil('genToOpt')
  • funcheckFu post buildBC checks
  • funJacobian implements Jacobian computation.
• .unl(:,:,2)=unl0 Optional. Define an offset in observation (before applying Fu) as unl=c*u+unl0. It can be a vector giving direct offset (as many lines as c). It can also be a string defining what offset to apply : the only strategy implemented at this time is unl0='q0' to remove observation of the static from observation at each time step. It can also be the name of a curve stored in model stack.
  

1.6.2  Additional fields in model

Base on model stack entries of the pro type where as NLdata field is present as described in the previous section, nl_spring support additional model fields.

• .NL This is a stack containing all non linearity data built using nl_spring NL. The stack has as many lines as existing non-linearities and three columns, the first being the non linearity type (the non linear function name most of the time), the second the non linearity name, and the non linearity data described in section 1.6.3.
• .FNL This is a transfer vector containing non linear data to output. Each non-linearity can store output data based on .Find.
• .FNLDOF This is a DOF vector corresponding to vector FNL. These FNLDOF are defined freely and not critical for base functionality. They are however convenient to keep track of internal states or non-linearity output, so that its building should be taken care of.
• .FNLlab This is a cell array of labels corresponding to non linear data to output. This is used by iiplot when non-linear responses are displayed during cleanup operations.

Output from simulations with non-linearities, from nl_solve, or fe_timehave additional data stored in a .FNL field. This is a deformation structure with fields

• .def Stored content of model.FNL at saving times.
• .DOF Stored content of model.FNLDOF.
• .data Copied data of out.data (saved times)
• .lab Stored content of model.FNLlab.
• .NL This is a cell array of the same format than model.NL. The third column contains structures containing non linear data relevant for result display. By default it contains field .iNL, the index vector of the current non linearity in the full FNLDOF. This field can be modified using the .obs callback of the non linearities. This field is based on NL.FInd, if .FInd is missing, iNL will be empty. iNL is then generated using the length of NL.adof, or by default using the length of NL.unl.

1.6.3  NL structure : non-linearity representation during time integration

During time integration, non-linearities are stored in the model.NL cell array. Each non-linearity is a data structure with the following standard fields for optimized computation (see mkl_utils

• .type a MATLAB function handle which is then called through
  NL.type(NL,fc,model,u,v,q,opt,Case). Some older NL use a string giving the type name.
• .c observation matrix (1.3) for non linear displacements and velocities. During solves this is stored in row format obtained with NL.c=v_handle('mklst',sparse(NL.c)) to optimize product speed.
• .unl pre-allocated memory for the result of NL.c*u. Must be consistent with the number of rows in NL.c. The computation is handled by mkl_utils. New implementations support a third dimension to store .unl0 in .unl(:,:,2) and .unlj1, the value at the previous time step, in .unl(:,:,3).
• .vnl if exists pre-allocated memory for the result of NL.c*v. Must be consistent with the number of rows in NL.c. The computation is handled by mkl_utils.
• .snl preallocated buffer of length size(b,2) to store the non-linear stresses (1.6).
• .b command matrix for non linear loads. At the end of the NL.type call it is expected that NL.snl (which may point to NL.unl if buffer overwrite is acceptable) contains the non linear component loads such that the residual becomes r=r+NL.b*NL.snl.
  During solves, sparse matrix operations must be optimized. This the product bs_nl is computed, it is interesting to store the transpose of the b matrix. The matrix is expected to be in transposed form NL.b=v_handle('mklst',b);. This conventions allow reuse of a .c matrix for command.
  Note that the sign conventions when using unl to return a non linear force are opposite to what is done when the result is added to fc, see sdtweb nl_fun to compare conventions.
• .FInd C++ start index in model.FNL to store the current non linearity data.
• .adof FNLDOF specific to the non linearity.
• .obs Optional command to fill in out.FNL.NL, see below. This can either be a logical, evaluating nl_fun('obs'), or a cell-array giving non linear data fields to propagate to the output from model.NL, or a string which will be evaluated.
• .opt data vector containing double values to be used in C++ implementation of non-linearities. Default values would be FuCode(1) tc(2) dt0(3) val1 ...
  • val1, ... is a FuCode dependent storage
  • for tables the standard, see sdtweb('d_fetime','stdFuToOpt')) is to use iopt[6:3:.] to point to start of table in .opt stored, give M as [(double)jcur,Val/Type,s, table]
• .iopt int32 data vector containing non-linearity specific integers. (1)FInd C start of model.FNL, (2)iu C staring position of internal states in global displacement vector, (3)Nstrain number of observed strains for each Gauss point. (4)Nistate number of internal states per Gauss point. (5)Ngauss number of Gauss points in a vectorized non-linearity. Later format may be dependent on non-linearity, a few variants are documented below to improve standardization
  
  • FuTable no internal state iopt(6)=xStartC,(7)yStartC, (8)size(y,1), (9)size(y,2) C style start in .opt of table with unl as first column and F(u_NL) values in second followed by cur (3 values). When combined with FvTable iopt(10)=xStartC,(11)yStartC, (12)size(FvY,1), (13)size(FvY,2).
  • constitutive laws with internal states will use iopt(6)StoreType update strategy in residual call, iopt(7:9) formulation dependent choices. iopt(10)=tstartC (11)size(y,1), (12)size(y,2) may be used for tabular definitions (hyperelasticity for example) where table starts by 3 values cur,val,s followed by the x vector and y matrix.
• .MexCb is a cell array giving callback function and options, when calling MATLAB from the mex, . For optimized operation without fieldname checks, the option structure is assumed to have ordered fields :
  • .unlg at a single Gauss point,
  • .opt copy of NL.opt,
  • .jg int32 vector allowing passing of current Gauss point index,
  • .vnlg optional copy of velocities at gauss point or empty.
  • The .mID identifier can be used for C callbacks. See section 1.3.5.
• in the C implementations the N field gives [0]numel(unl(:,:,1)) [1]size(c,1) size(c,2) isTrans(c) [4]size(b,1) size(b,2) [6]isTrans(b) [8]length(opt) length(iopt) [10]size(unl,3)
• obsolete
• .extDOF obsolete see iopt, double vector containing Matlab indices [iu,Nstrain,Nistate]
• Obsolete .unl0 offset to apply to .unl, so that the content of .unl becomes NL.c*u+unl0. Current implementations should store in .unl(:,:,2).
• Obsolete .vnl0 offset to apply to .vnl, so that the content of .vnl becomes NL.c*v+vnl0. Current implementations should store in .vnl(:,:,2).