9. Material Model Functions - MatlFun

The material model function module implements an interface between the element formulation modules and the underlying material constitutive model. The material model may be one of two basic types, 1) primitive materials and 2) element materials which contain one or more primitive materials and to which element properties such as shell element thickness are added. An example of the former is a linear elastic isotropic material, an example of the latter is a layered composite which includes primitive materials and element properties such as thickness and offset.

A MatlFun object defines function pointers to the material subsystem. These function pointers are required by each element formulation object to compute quantities such as stress, heat flux, material stiffness and thermal conductivity matrices.

In addition to function pointers to the underlying material subsystem, each material model function object maintains an auxiliary object pointer which is passed as the first argument to each material function. This auxiliary object pointer may be assigned by a module or by the user. The user defined object may be used to hang any information required to implement the material functions for a particular material model. The MatlFun module contains the following functions.

The material model functions are implemented as inline methods using C preprocessor macros. This has been done to reduce procedure call overhead. The macros which implement the following functions appear in the file matlfun.h. The material model functions listed below define the interface to the material subsystem.

9.1. Integration Methodology

The material function interface supports the notions of a continuum material formulation and a preintegrated material formulation. Continuum material models are specialized for continuum element formulations such as solid elements. Preintegrated material formulations are designed to support element types such as shells and beams in which stresses are typically integrated over the thickness or cross section to yield stress resultants.

A continuum material formulation requires the evaluation of stress and material stiffness assuming a 3D stess tensor. The integration over the element volume is done entirely by the element formulation. A continuum material model is specialied to solid element types. The 3D stress components are ordered as (sxx, syy, szz, sxy, syz, szx).

By contrast a preintegrated material formulation requires the evaluation of stress and material stiffness assuming that the stress has been preintegrated through the thickness or over the cross section of the element yielding a so-called stress resultant. A preintegrated material formulation is specialized to a particular element type which dictates the number and type of stress resultant components. For shell elements the stress resultant components are ordered as (Nxx, Nyy, Nxy, Mxx, Myy, Mxy, Qxz, Qyz), for beam elements the stress resultants are ordered as (Nxx, Myy, Mzz, T, Qxy, Qzx).

If the material model includes inelastic or similar effects it may require that a history of computed material quantities be available. The user is responsible for allocating the memory for the history variables and passing pointers to the history variables at the previous and current solution steps. The function vfe_MatlFunNumHist() is used to query for the number of history variables required at an integration point. The function vfe_MatlFunHistPtr() is used to pass the pointers to the history variables to the material model. Linear elastic materials, for example, require no history variables, plastic materials will require several. Use vfe_MatlFunInitHist() to initialize the material history parameters at the initial undeformed configuration.

9.2. Structural Analysis Material Quantities

A number of finctions are used to specifically compute stress and material stiffness and query for material characteristics which relate to structural analysis. The function vfe_MatlFunDInfo() is the general function for querying for material characteristics such as whether a particular material formulation is supported; the zero fill of the material stiffness matrix, etc.

The function vfe_MatlFunDCond() is used to set stress condenstaion flags so the the material model can be configured to handle various plane stress conditions.

The computation functions vfe_MatlFunDMatrix(), vfe_MatlFunStress(), vfe_MatlFunStressDMatrix(), vfe_MatlFunStressStrain(), and vfe_MatlFunModulus() are used to compute stress/resultants, three-dimensional stress and strain at section points, and material stiffness matrices given a small strain or large strain deformation matrix. Again, the function vfe_MatlFunDInfo() is used to query for whether the material model requires small or large strain.

For continuum material formulations the small strain components are ordered (exx, eyy, ezz, gxy, gyz, gzx). and the deformation gradient matrix components are ordered as:

(1.-u,x, u,y,    u,z,
v,x,    1.-v,y, v,z,
w,x,    w,y,    1.-w,z).

For shell formulations the small strain is entered as reference surface strains and curvatures (exx, eyy, gxy, kxx, kyy, kxy, gxz, gyz).

For beam formulations the small strain is entered as reference axis strains, curvatures, a twist and shear strains. (exx, kyy, kzz, twist, gxy, gzx)

9.3. Thermal Analysis Material Quantities

In a manner analogous to structural analysis, a number of functions are used to specifically compute heat flux and thermal conductivity and query for material characteristics which relate to thermal analysis. The function vfe_MatlFunKInfo() is the general function for querying for material characteristics such as whether a particular material formulation is supported; the zero fill of the thermal conductivity matrix, etc. Density and specific heat are returned using vfe_MatlFunDensity() and vfe_MatlFunSpecHeat() respectively.

The computation functions vfe_MatlFunKMatrix(), vfe_MatlFunHeatFlux() and vfe_MatlFunHeatFluxKMatrix() are used to compute heat flux and thermal conductivity matrices given a temperature gradient vector. The components of the temperature gradient vector are ordered (gtx, gty, gtz).

9.4. Function Descriptions

The currently available MatlFun functions are described in detail in this section.

vfe_MatlFun *vfe_MatlFunBegin(void)

create an instance of a MatlFun object

Create an instance of a MatlFun object. Memory is allocated for the object private data and the pointer to the data is returned. By default all function pointers are NULL.

Destroy an instance of a MatlFun object using 

void vfe_MatlFunEnd (vfe_MatlFun *matlfun)

Return the current value of a MatlFun object error flag using 

Vint vfe_MatlFunError (vfe_MatlFun *matlfun)

Make a copy of a MatlFun object. The private data from the frommatlfun object is copied to the MatlFun object. Any previous private data in MatlFun is lost. 

void vfe_MatlFunCopy (vfe_MatlFun *matlfun,
                      vfe_MatlFun *frommatlfun)

Returns:

The function returns a pointer to the newly created MatlFun object. If the object creation fails, NULL is returned.

void vfe_MatlFunEnd(vfe_MatlFun *p)

destroy an instance of a MatlFun object

See vfe_MatlFunBegin()

Vint vfe_MatlFunError(vfe_MatlFun *p)

return the current value of a MatlFun object error flag

See vfe_MatlFunBegin()

void vfe_MatlFunCopy(vfe_MatlFun *p, vfe_MatlFun *fromp)

make a copy of a MatlFun object

See vfe_MatlFunBegin()

void vfe_MatlFunSet(vfe_MatlFun *p, Vint type, Vfunc *function)

set pointer to material model function

Set pointers to material model functions. Note that the function pointer argument should be cast to match the documented prototype above, for example: 

vfe_MatlFunSet (matlfun,MATLFUN_GETSTRESS,(void(*)())My_GetStress);

Get function as an output argument using 

void vfe_MatlFunGet (vfe_MatlFun *matlfun,
                     Vint type,
                     void (**function)())

Errors

SYS_ERROR_ENUM is generated if an improper type is input.

Parameters:

  • p – Pointer to MatlFun object.

  • type – Function type being set 

    x=MATLFUN_DINFO           Set DInfo function
 =MATLFUN_DMATRIX         Set DMatrix function
 =MATLFUN_STRESS          Set Stress function
 =MATLFUN_STRESSDMATRIX   Set StressDMatrix function
 =MATLFUN_STRESSSTRAIN    Set StressStrain function
 =MATLFUN_DCOND           Set DCond function
 =MATLFUN_MODULUS         Set Modulus function
 =MATLFUN_NUMSTRESSSTRAIN Set NumStressStrain function
 =MATLFUN_DKMATRIXDT      Set dKMatrixdT function
 =MATLFUN_KINFO           Set KInfo function
 =MATLFUN_KMATRIX         Set KMatrix function
 =MATLFUN_HEATFLUX        Set HeatFlux function
 =MATLFUN_HEATFLUXKMATRIX Set HeatFluxKMatrix function
 =MATLFUN_DENSITY         Set Density function
 =MATLFUN_SPECHEAT        Set SpecHeat function
 =MATLFUN_ELEMINTPNT      Set ElemIntPnt function
 =MATLFUN_NUMHIST         Set NumHist function
 =MATLFUN_HISTPTR         Set HistPtr function
 =MATLFUN_INITHIST        Set InitHist function
 =MATLFUN_PROP            Set Prop function

  • function – Pointer to material model function

void vfe_MatlFunSetErrorFunction(vfe_MatlFun *p, VfuncInt *function)

set pointer to error function

Set pointers to error functions.

Parameters:

  • p – Pointer to MatlFun object.

  • function – Pointer to error function

void vfe_MatlFunGet(vfe_MatlFun *p, Vint type, Vfunc **function)

get pointer to material model function

See vfe_MatlFunSet()

void vfe_MatlFunSetObj(vfe_MatlFun *p, Vobject *obj)

set pointer to auxiliary object

Set pointer to material model function auxiliary object.

Get obj as an output argument using 

void vfe_MatlFunGetObj (vfe_MatlFun *matlfun,
                        Vobject **obj)

Parameters:

  • p – Pointer to MatlFun object.

  • obj – Pointer to auxiliary object

void vfe_MatlFunGetObj(vfe_MatlFun *p, Vobject **obj)

get pointer to auxiliary object

See vfe_MatlFunSetObj()

void vfe_MatlFunAPI(vfe_MatlFun *p, Vint api)

set built-in functions

Set built in material functions. The MATLFUN_APIRETURN drawing functions simply return.

Errors

SYS_ERROR_ENUM is generated if an improper api is input.

Parameters:

  • p – Pointer to MatlFun object.

  • api – Type of built-in material function to return. 

    x=MATLFUN_APIRETURN      Set return material functions

void vfe_MatlFunDMatrix(vfe_MatlFun *p, Vdouble dm[])

compute material stiffness matrix

Return a material stiffness matrix, dm, for an element. The material stiffness matrix returned by this function is evaluated at zero strain. Use vfe_MatlFunStressDMatrix() to return tangent material stiffness matrices at a given strain. For continuum material formulations the material stiffness is assumed to have 6 rows. Shell element material stiffness matrices have 8 rows and beam element material stiffness matrices have 6 rows.

For beams and shells the resultant tangent matrix is returned by this function. Otherwise, the three dimensional tangent matrix is returned.

Parameters:

  • p – Pointer to MatlFun object.

  • dm – [out] Lower triangle of material stiffness matrix

void vfe_MatlFunDInfo(vfe_MatlFun *p, Vint type, Vint *info)

get material stiffness matrix information

Return an integer constant which reflects an attribute or parameter of the underlying material model.

VFE_MATLELEM queries the material model for specific support for an element type. If the underlying material model is a primitive material, then the element type will be SYS_ELEM_UNDEFINED. Element materials specific to shells or beams return SYS_ELEM_SHELL or SYS_ELEM_BEAM respectively.

VFE_MATLFULL queries the non-zero pattern of the material stiffness matrix. This value is used to avoid zero arithmetic by the element formulation modules. A return value of SYS_ON indicates that the matrix is full, ie. has all possible non-zero entries. A value of SYS_OFF indicates a certain degree of sparsity.

For 6 by 6 continuum material stiffnesses, full and sparse matrices have the following fill patterns: 

Full                  Sparse

x x x x x x           x x x 0 0 0
x x x x x x           x x x 0 0 0
x x x x x x           x x x 0 0 0
x x x x x x           0 0 0 x 0 0
x x x x x x           0 0 0 0 x 0
x x x x x x           0 0 0 0 0 x
For 8 by 8 shell material stiffnesses, full and sparse matrices have the following fill patterns:

Full                  Sparse

x x x x x x 0 0       x x x 0 0 0 0 0
x x x x x x 0 0       x x x 0 0 0 0 0
x x x x x x 0 0       x x x 0 0 0 0 0
x x x x x x 0 0       0 0 0 x x x 0 0
x x x x x x 0 0       0 0 0 x x x 0 0
x x x x x x 0 0       0 0 0 x x x 0 0
0 0 0 0 0 0 x x       0 0 0 0 0 0 x x
0 0 0 0 0 0 x x       0 0 0 0 0 0 x x

For 6 by 6 beam material stiffnesses, full and sparse matrices have the following fill patterns: 

Full                  Sparse

x x x 0 0 0           x 0 0 0 0 0
x x x 0 0 0           0 x 0 0 0 0
x x x 0 0 0           0 0 x 0 0 0
0 0 0 x x x           0 0 0 x 0 0
0 0 0 x x x           0 0 0 0 x 0
0 0 0 x x x           0 0 0 0 0 x

VFE_STRAINTYPE queries whether large strain, VFE_LARGESTRAIN, or small strain, VFE_SMALLSTRAIN, is supported. Large strains require a deformation gradient matrix to be passed to the vfe_MatlFunStress(), vfe_MatlFunStressStrain(), and vfe_MatlFunStressDMatrix() functions. Small strains require a small strain tensor to be passed to the vfe_MatlFunStress(), vfe_MatlFunStressStrain(), and vfe_MatlFunStressDMatrix() functions.

Parameters:

  • p – Pointer to MatlFun object.

  • type – Type of material stiffness matrix information to return 

    x=VFE_MATLELEM             Specific element type supported
 =VFE_MATLFULL             Zero fill of matrix
 =VFE_STRAINTYPE           Strain capability

  • info – [out] Material stiffness matrix information 

    x=SYS_ON                   True
 =SYS_OFF                  False
 =SYS_ELEM_UNDEFINED       Not element type specific
 =SYS_ELEM_SHELL           Shell element material
 =SYS_ELEM_BEAM            Beam element material
 =VFE_LARGESTRAIN          Large strain capability
 =VFE_SMALLSTRAIN          Small strain capability

void vfe_MatlFunStress(vfe_MatlFun *p, Vdouble dfrm[], Vdouble strs[])

compute stress/resultant given strain/curvature

Compute the Cauchy stresses, strs, for an element given a small strain or deformation gradient matrix, dfrm. The underlying material model must be queried using vfe_MatlFunDInfo() for support of small strain or large strain. If the material model supports small strain then dfrm contains a small strain tensor, if the material model supports large strain then dfrm contains a deformation gradient matrix.

For shells and beams the resultant stresses are returned by this function. Otherwise, the 6 stress components are returned.

Parameters:

  • p – Pointer to MatlFun object.

  • dfrm – Given small strain tensor or deformation gradient matrix

  • strs – [out] Computed Cauchy stresses

void vfe_MatlFunStressDMatrix(vfe_MatlFun *p, Vdouble dfrm[], Vint dflag, Vdouble strs[], Vdouble dm[])

compute stress and material stiffness matrix

Compute the Cauchy stresses, strs, and optional material stiffness matrix, dm, for an element given a small strain or deformation gradient matrix, dfrm. This function is specifically designed for use in nonlinear analysis to allow stress and tangent material stiffness to be computed together for computational efficiency. The underlying material model must be queried using vfe_MatlFunDInfo() for support of small strain or large strain. If the material model supports small strain then dfrm contains a small strain tensor, if the material model supports large strain then dfrm contains a deformation gradient matrix.

For shells and beams the resultant stresses and tangent matrix are returned by this function. Otherwise, the three dimensional stress components and the resulting tangent are returned.

Parameters:

  • p – Pointer to MatlFun object.

  • dfrm – Given small strain tensor or deformation gradient matrix

  • dflag – Optional computation of material stiffness matrix

  • strs – [out] Computed Cauchy stresses

  • dm – [out] Lower triangle of material stiffness matrix

void vfe_MatlFunModulus(vfe_MatlFun *p, Vdouble modulus[])

compute characteristic elastic modulus

Return characteristic elastic modulus or preintegrated elastic modulus. For continuum material formulations the elastic modulus is returned as a single characteristic value for Young’s modulus, E. For shell elements the elastic moduli is E*Thk**3/12 and for beam elements the elastic modulus is G*J.

Parameters:

  • p – Pointer to MatlFun object.

  • modulus – [out] Elastic modulus

void vfe_MatlFunNumHist(vfe_MatlFun *p, Vint *numhist)

return number of material history variables

Return the number of history variables, numhist, used in the underlying element or primitive material model at an integration point. This number should be used to allocate memory to hold history variables to be passed to the underlying material model. A history variable is of type Vdouble. For example a linear material model does not require history variables and should return numhist = 0, whereas a path dependent plasticity model requires a stress history of some sort and would return a numhist > 0.

Parameters:

  • p – Pointer to MatlFun object.

  • numhist – [out] Number of material history variables.

void vfe_MatlFunHistPtr(vfe_MatlFun *p, Vdouble *oldhistptr, Vdouble *newhistptr)

set pointers to material history

Set pointers to the material history at the previous step and the current step. The amount of allocated memory pointed to by each of the pointers, oldhistptr and newhistptr must be equal to: 

sizeof(Vdouble) * numhist
where numhist is returned by vfe_MatlFunNumHist().

Parameters:

  • p – Pointer to MatlFun object.

  • oldhistptr – Pointer to history at previous step

  • newhistptr – Pointer to history at current step

void vfe_MatlFunInitHist(vfe_MatlFun *p)

initialize entries in material history

Initialize the values of the history variables used in the underlying element or primitive material model at an integration point. This operation should be performed to initialize the old history variables to reflect the condition of the initial configuration. This function needs to be called exactly once per integration point and only if the number of history variable returned by vfe_MatlFunNumHist() is non-zero. The pointers to the history variables must have been previously set using vfe_MatlFunHistPtr().

Parameters:

p – Pointer to MatlFun object.

void vfe_MatlFunElemIntPnt(vfe_MatlFun *p, Vint elemintpnt, Vdouble r[3], Vdouble w, Vdouble dj)

specify element integration point

This function is strictly used to communicate element integration point information to the material model for the calculation of user defined output quantities which are not supported directly by the material function interface. For example the element volume can be easily computed by accumulating the product of the weight, w, and the determinant of the Jacobian, dj, for each integration point in an element.

Parameters:

  • p – Pointer to MatlFun object.

  • elemintpnt – Element integration point number 1 <= elemintpnt

  • r – Natural coordinates of integration point

  • w – Weight of integration point

  • dj – Determinant of the Jacobian matrix at the integration point

void vfe_MatlFunKMatrix(vfe_MatlFun *p, Vdouble km[])

compute thermal conductivity matrix

Return a thermal conductivity matrix, km, for an element. The thermal conductivity matrix is assumed to have 3 rows.

Parameters:

  • p – Pointer to MatlFun object.

  • km – [out] Lower triangle of thermal conductivity matrix

void vfe_MatlFunKInfo(vfe_MatlFun *p, Vint type, Vint *info)

get thermal conductivity matrix information

Return an integer constant which reflects an attribute or parameter of the underlying material model.

VFE_MATLELEM queries the material model for specific support for an element type. If the underlying material model is a primitive material, then the element type will be SYS_ELEM_UNDEFINED. This is currently the only option for thermal analysis.

VFE_MATLFULL queries the non-zero pattern of the thermal conductivity matrix. This value is used to avoid zero arithmetic by the element formulation modules. A return value of SYS_ON indicates that the matrix is full, ie. has all possible non-zero entries. A value of SYS_OFF indicates a certain degree of sparsity. 

Full            Sparse

x x x           x 0 0
x x x           0 x 0
x x x           0 0 x

VFE_TEMPDEP queries for temperature-dependent thermal conductivity. This value is used to determine whether vfe_MatlFundKMatrixdT() should be called to add this dependency to a non-symmetric thermal conductivity matrix.

Parameters:

  • p – Pointer to MatlFun object.

  • type – Type of thermal conductivity matrix information to return 

    x=VFE_MATLELEM             Specific element type supported
 =VFE_MATLFULL             Zero fill of matrix
 =VFE_TEMPDEP              Temperature-dependent conductivity

  • info – [out] Thermal conductivity matrix information 

    x=SYS_ON                   True
 =SYS_OFF                  False
 =SYS_ELEM_UNDEFINED       Not element type specific

void vfe_MatlFunHeatFlux(vfe_MatlFun *p, Vdouble grad[], Vdouble flux[])

compute heat flux given temperature gradient

Compute the heat flux, flux, for an element given a temperature gradient vector, grad.

Parameters:

  • p – Pointer to MatlFun object.

  • grad – Given temperature gradient vector

  • flux – [out] Computed heat flux vector

void vfe_MatlFunHeatFluxKMatrix(vfe_MatlFun *p, Vdouble tgrad[], Vint kflag, Vdouble flux[], Vdouble kl[])

compute flux and conductivity matrix

Compute the heat flux, flux, and option thermal conductivity matrix, kl, for an element given a temperature gradient vector, tgrad. This function is specifically designed for use in nonlinear analysis to allow heat flux and tangent thermal conductivity to be computed together for computational efficiency.

Parameters:

  • p – Pointer to MatlFun object.

  • tgrad – Given temperature gradient vector

  • kflag – Optional computation of thermal conductivity matrix

  • flux – [out] Computed heat flux vector

  • kl – [out] Lower triangle of thermal conductivity matrix

void vfe_MatlFunDensity(vfe_MatlFun *p, Vdouble density[])

compute density

Return density or preintegrated densities. For continuum material formulations the density is returned as a single value. Shell element densities have 3 values; the density per unit area followed by the first and second moments of the density with respect to the thickness coordinate of the shell. Beam element densities have 6 values; the density per unit length followed by the first and second moments of the density with respect to the beam section y coordinates followed by the first and second moments of the density with respect to the beam section z coordinates followed by the yz moment. If the density or densities are not defined they are returned as zero.

Parameters:

  • p – Pointer to MatlFun object.

  • density – [out] Density

void vfe_MatlFunSpecHeat(vfe_MatlFun *p, Vdouble specheat[])

compute specific heat

Return specific heat. If the specific heat is not defined it is returned as zero.

Parameters:

  • p – Pointer to MatlFun object.

  • specheat – [out] Specific heat

void vfe_MatlFunProp(vfe_MatlFun *p, Vint ptype, Vdouble prop)

set value of interpolated element property

Set the value of an interpolated element property at an element integration point. This value will be in effect until changed by this function. Note that not all properties are supported by the underlying material properties.

Parameters:

  • p – Pointer to MatlFun object.

  • ptype – Property type to set 

    x=VFE_PROP_TEMPERATURE     Temperature
 =VFE_PROP_THICKNESS       Thickness
 =VFE_PROP_OFFSET          Offset

  • prop – [out] Element property.

void vfe_MatlFunDCond(vfe_MatlFun *p, Vint cond[])

set material matrix condensation rule

Set the condensation flags for each component (row) of stress. A non-zero flag in cond specifies that the associated stress component is zero. If the stress component is a shear stress then the associated shear strain is also assumed to be zero. For example a 2D plane stress solid element which requires a continuum material model would set cond[] = {0,0,1,0,1,1} . By default all condensation flags are assumed to be zero.

Parameters:

  • p – Pointer to MatlFun object.

  • cond – Vector of condensation flags

void vfe_MatlFunNumStressStrain(vfe_MatlFun *p, Vint *numstressstrain)

get number of section output points

Return the number of section points in the underlying shell or beam cross section formulation.

Parameters:

  • p – Pointer to MatlFun object.

  • numstressstrain – [out] Number of section output points

void vfe_MatlFunStressStrain(vfe_MatlFun *p, Vdouble dfrm[], Vdouble strs[], Vdouble stress[], Vdouble strains[])

compute 3D stress and strain given strain/curvature

Compute the stress resultants, strs, for an element given a small strain or deformation gradient matrix, dfrm. Also compute the three-dimensional stress and strain components, stress and strain at selected section points - if sections are available as in beams and shells. The underlying material model must be queried using vfe_MatlFunDInfo() for support of small strain or large strain. If the material model supports small strain then dfrm contains a small strain tensor, if the material model supports large strain then dfrm contains a deformation gradient matrix.

For shells and beams the resultant stresses are returned by this function. This function is not available for elements other than shells and beams. The order for stress and strain data is all element nodal stresses and strains for the first section point, followed by all element nodal data for the second section point, etc.

Parameters:

  • p – Pointer to MatlFun object.

  • dfrm – Given small strain tensor or deformation gradient matrix

  • strs – [out] Computed stress resultants

  • stress – [out] Computed Cauchy stresses at section points

  • strains – [out] Computed strains at section points

void vfe_MatlFundKMatrixdT(vfe_MatlFun *p, Vdouble dkmdt[])

compute d(conductivity matrix)/dT

Compute the derivative of the thermal conductivity matrix, dkmdt with respect to temperature This function is specifically designed for use in nonlinear analysis to allow non-symmetric dependencies in the thermal conductivity element matrix for computational efficiency.

Parameters:

  • p – Pointer to MatlFun object.

  • dkmdt – [out] Computed derivative of Lower triangle of thermal conductivity matrix w.r.t. temperature