Creating a new non linearity: nl

SDT-rotor Contents Functions

Creating a new non linearity: nl_fun.m

Purpose

The structure of nl_spring allows creating any new non-linearity through the use of a dedicated function, named nl_fun.m. This function which non-linearity name will be fun, will be automatically called by nl_spring for classical operations.

The function structure has been designed to comply with specific needs. Standard calls have been defined, which are detailed below:

Residue computation, called by mkl_utils (sdtweb mkl_utils), must output the entry force minus the non linear force computed. The call performed is
```
nl_fun(r2,fc,model,u,v,a,opt,Case)
```
This call is low level and must modify fc using sp_util('setinput') as fc-fnl where fnl is the non linear force computed. Note that this is the only possible call for nargin==8. Note that mkl_utils allows a formalism with precomputed observations, using fields unl.
Jacobian computation, must output the tangent stiffness and tangent damping matrices associated to the non linearity. The call performed is
```
[kj2,cj2]=nl_fun(NL,[],model,u,v,[],opt,Case,RunOpt); 
```
This call must output either empty matrices if no tangent nor Jacobian matrix is associated to the non linearity, or matrices expressed on the DOF vector of Case.DOF. The first matrix is the tangent stiffness matrix, the second one is the tangent damping matrix. Typically there are 3 normalized methods to be defined (but not all of them must be defined, and more can be defined) according to the NL.Jacobian value:
- 0 : no Jacobian. (default).
- 1 : tangent matrices.
- 2 : fixed Jacobian (can be max stiffness / damping or mean, ...).
Then computed matrices are then multiplied by NL.alphaJK factor for Jacobian stiffness, and NL.alphaJD factor for Jacobian damping.
Initializations for fe_time, must initialize the model non-linearity for non linear forces computation
The call must generate the non linearity stored in model.NL, it can optionally generate non linear DOF and labels. The call performed is of the type.
```
NL=nl_fun('init',data,mo1);
```
NL is a struct containing at least the field type with the nl_fun handle (e.g. NL.type=@nl_fun). data contains the Stack,pro entry, and mo1 is the model, named mo1 where the call is performed.
ParamEdit returns the ParamEdit string allowing integrated parameters interpretation (for internal SDT use).
The call performed is of the type.
```
st=nl_fun('ParamEdit');
```
db returns default NLdata fields for a non linearity. This allows integrated building of non-linearities in a model. This function can call ParamEdit to allow interactive setup.
This call must return a NLdata field and is of the type
```
NLdata=nl_fun('db data 0');
```
Energy post treatments capability, should return the elastic energy stored in the non-linearity as a vector with as many lines as time steps in the output.
The call performed by nl_solvePost is of the form
```
r2 = nl_fun('PostEnerNL');
```
The non linearity function can access in caller fields RO, out, model, NL, i1 with
- RO a structure with fields EnerP and EnerK respectively containing the potential and kinetic energy.
- out the fe_timeoutput.
- model the model used in the simulation.
- NL the NL containing the data of the non-linearity called.
- i1 the row index of out.Post that is currently generated.
Renumbering capability, must return the non-linearity written for the new renumbered nodes, elements, dof, …
The call performed (by feutilbfor example) is of the type
```
NL=nl_fun('renumber',NL,nind);
```
nind is the renumbering vector.

The designed nl_fun template is given in the non-linear toolbox, sdtweb nl_fun.m#1. It is a functional non linear function, computing a zero non linear force. The definition of a non linearity using nl_fun in a standard SDT model is given in the following.

% A standard SDT model
model=struct('Node',[1  0 0 0  0 0 0; 2  0 0 0  0 0 1],...
             'Elt',[Inf abs('celas') 0 0; 
             1 2 3 -3  0 1 0  10;   % linear celas
            ]);
% Define a non linearity of type nl_fun
model=nl_spring('SetPro ProId 100',model,nl_fun('db data0'));
%Equivalent to
% model=stack_set(model,'pro','nl_fun',...
% struct('il',[100 fe_mat('p_spring','SI',1)],...
%        'type','p_spring',...
%        'NLdata',struct('type','nl_fun','data',[])));

% Define the case
model=fe_case(model,'FixDof','base',1);
model=fe_case(model,'DofLoad','in',struct('DOF',2.03,'def',1));
model=fe_curve(model,'set','input','TestStep t1=0.02');
model=fe_case(model,'setcurve','in','input');
% Define the TimeOpt and compute the solution
opt=nl_solve('TimeOpt'); opt.Opt([4 5])=[1e-3 1e4];opt.NeedUVA=[1 1 0];
def=fe_time(opt,model);