mkl_utils
Purpose
For detailed callback information see sdtweb('nlspring_timeopt').
Residual
Residual command is used to compute standard residue.
mkl_utils('residual',r,model,u,v,a,opt,Case); call modifies variable r in memory according to following standard residue computation (implicit Newmark).
r = model.K{1}*a + model.K{2}*v + model.K{3}*u + b*(snl_fun) + fnl_int -fc;
In this formula, b*(snl_fun) refers to the legacy m file implementations (non chandle) which expect the nl_ function to fill a unl vector multiplying b (.snl field support was not activated). This was incorrectly noted -fnl in earlier documentation the minus sign coming from the convention of considering non-linear forces as external rather than internal (the convention used from now on). fnl_int refers to chandle implementations that match classical conventions : traction leading to positive stress in continuous mechanics, positive over-closure (negative gap) leading to positive pressures in contact mechanics.
Typically in fe_time computations one has
opt.Residual='r=-full(fc);mkl_utils(''residual'',r,model,u,v,a,opt,Case);';
with fc the time load (resulting from DofLoad entries in model Case) and fnl is the sum of the non linear efforts (if any) computed directly by mkl_utils (rotcenter, mocirc2), in the non linear functions (see sdtweb nl_fun) or in nl_spring. mkl_utils then calls the adequate nl_fun function (nl_spring by default) automatically.
Such call stored in opt.Residual is filled by nl_spring('TimeOpt') for default simulations.
Model information specifically supported by the residual command are
-
opt.Rayleigh if the field exists defines a global Rayleigh damping and
opt.Rayleigh(1)*model.K{1}*v+opt.Rayleigh(2)*model.K{3}*v is added to the residual.
- model.K{2} can be a data structure describing modal damping with following fields:
-
.def : vectors as columns.
- .data : modal damping coefficients as a vector. . A second column has to be set to zero for transient applications.
- .type : @nl_modaldmp handling function for callbacks. The following callbacks must be handled
-
matrix projection : tkt=feval(K.type,'getTKT',K,T,Tt,typ)
with K the implicit matrix, T the right projection matrix, Tt the left projection matrix (can be empty or skipped if , typ the output type, either imp to keep the implicit format (by default), or full to recover a full numeric matrix (to be reserved for small output sizes).
- vector application : f=feval(K.type,'getForce',K,q)
with K the implicit matrix, q a deformation vector.
- .UseDiag : to be set to one if one wants the output of getTKT to be diagonal (as for a standard dtkt call).
- .K : optional additional damping matrix. This matrix must be in a mkl transposed v_handle format (use v_handle('mklst',K) to convert a matlab matrix to this format). Note that model.K{2}.K is taken in account for the Jacobian computation whereas modal damping is not.
- .defT : the resitution matrix (left side ), that can occur mainly in the case where a non-symmetric projection has been carried out. E.g., the implicit representation of will use field .def to store and .defT to store .
Corresponding additional residue term is
. - model.NL can be a stack of non linearities. Column 3 provides a structure with the following standard fields, see nldata.
Typically, fnl is computed by non linearity functions, see nl_fun for details on these functions. The non linear functions are called by mkl_utils to provide the value of fnl at a given state. Two implementations are supported
-
An optimized input-output formulation, using observation and command matrices c and b documented in nldata. The computation of the observation is possible either on the displacement, the velocity or both, and the command is added to the residual using r = r + b*unl. With unl a vector depending on the observation (c*u, c_v v).
- A used defined addition (older format, that should be only used when the generic b,c format fails to be relevant. In this mode the non linear function must add fnl by itself, choosing the sign convention, using a call of type of_time(-1,fc,fc-fnl);. One will note that the residue vector is named fc in the non linear functions.
chandle
chandle objects are used to streamline communication between mex and MATLAB in iterative processes. They are used in various nl_solve calls and in particular for ModalNemwark and ExpNewmark.
©1991-2023 by SDTools