User-Defined Structural Material

The MATUSR Bulk Data Entry, in combination with the LOADLIB I/O Option Entry, allows for the definition of structural material through user-defined external functions.

The external functions may be written in Fortran, C or C++. The resulting libraries and files should be accessible by OptiStruct regardless of the coding language, provided that consistent function prototyping is respected, and adequate compiling and linking options are used.

Write External Functions

Two Fortran subroutines are required to define user material in OptiStruct. First, a Nonlinear subroutine for the nonlinear large displacement solution, and another subroutine for the linear and nonlinear small displacement solution. Both subroutines are mandatory, and the same argument order should be followed as:

Nonlinear subroutine (LGDISP):

      subroutine usermaterial(idu,stress,
     $     strain,dstrain,dfgrOld,dfgrNew,
     $     stater,state,nstate,
     $     drot,
     $     props,nprops,ndi,nshear,ntens,temp,dtemp,
     $     ieuid,
     $     kinc,dt,t_step,t_total,
     $     cdev,cbulk)

integer idu, nstate, nprops, kinc, ieuid, ndi, nshear, ntens, ierr
double precision stress(6),stater(*),state(*),
     $     cdev(6,6),cbulk, drot(3,3), temp, dtemp, dt, 
     $     t_step, t_total,
     $     strain(6), dstrain(6), props(nprops)
     $     dfgrOld(3,3),dfgrNew(3,3)
character*32000 userdata

Linear subroutine (Linear and SMDISP):

subroutine smatusr(idu, nprop, prop, ndi, nshear, ntens, smat, userdata,  ierr)
integer idu, nprop, ndi, nshear, ntens, ierr
double precision prop(nprop), smat(*)
character*32000 userdata

initusr subroutine:

subroutine initusr(idu,nstate,cstate)
      implicit none
      integer idu,nstate
      character*64 cstate(nstate)

The strings in the initusr subroutine should always be declared as follows:

      character*64 cstate(nstate)

The declaration should always use 64-character size.

After declaration, the cstate variable can be assigned the label to print in the user-defined results with 1 being the index for the first variable in the example below:

	cstate(1) = “Variable Name for State(1)”

Note: Subroutine names should not be changed.

Subroutine Arguments

The following table briefly describes the arguments which are passed among OptiStruct and the external subroutines. OptiStruct calls these two subroutines for every integration point of every element in the model. Therefore, the values listed below are calculated at each integration point.


Argument	Type	Input / Output	Description
`idu`	integer	Input	This is defined via the `USUBID` parameter on the MATUSR Bulk Data Entry. This argument can be used to define and choose between different types of materials within the same user subroutine. optional use
`stress`	double (table)	Input/Output	This is the Stress tensor. The initial stress is considered to be input and the stress, tensor calculated during the nonlinear solution are output from the user subroutine to OptiStruct.
`strain`	double (table)	Input	Strain tensor. The initial strain is considered to be input.
`dstrain`	double (table)	Input	Incremental strain table. The incremental strain is input from OptiStruct to the user subroutine.
`dfgrOld`	double (table)	Input	Deformation gradient tensor of the previous increment. This argument is currently supported for solid elements (PSOLID) or continuum shells (PCOMPLS).
`dfgrNew`	double (table)	Input	Deformation gradient tensor of the current increment. This argument is currently supported for solid elements (PSOLID) or continuum shells (PCOMPLS).
`stater`	double (table)	Input/Output	Table of State variables at the previous increment.
`state`	double (table)	Input/Output	Table of State variables at the current increment. See `stater` for more information. State variables are variables that can be requested as output in the H3D file. Any variable (for example, plastic strain, equivalent plastic strain, and so on) calculated within the solution process in the subroutine can be output by defining it as a state variable. The number of state variables can be specified via `nstate`.
`nstate`	integer	Input/Output	Number of State Variables that the user requires in the subroutine. These state variables are output in the H3D file. See `stater` for more information. This is specified via the `NDEPVAR` field of the MATUSR Bulk Data Entry.
`cstate`	string	Output	Output in the form of a string from `initusr` subroutine to OptiStruct. In the `usermaterial` or `smatusr` subroutines the state variable outputs any variable in the H3D file. The `cstate` variable provides the name of the state variable declared in that subroutine to display in the H3D file.
`props`	double (table)	Input	This table contains all the user-defined material property information from the `PROPERTY` continuation line of the MATUSR entry.
`nprops`	Integer	Input	This is the total number of material properties defined on the `PROPERTY` continuation line of the MATUSR entry.
`ndi`	Integer	Input	The number of normal stress components (3 for solid elements, 2 for shell elements).
`nshear`	Integer	Input	The number of shear stress components (3 for solid elements, 1 for shell elements).
`ntens`	Integer	Input	The number of tensor components (`ntens` = `ndi` + `nshear`).
`temp`	double	Input	This is the temperature at the previous converged increment.
`dtemp`	double	Input	This is the temperature increment.
`ieuid`	integer	Input	Element ID. This subroutine is called for every integration point for every element.
`kinc`	integer	Input	Current increment.
`dt`	double	Input	Current Time increment
`t_step`	double	Input	Subcase time.
`t_total`	double	Input	Total time (if CNTNLSUB is used)
`cdev`	double (table)	Output	Full material modulus matrix of size (6x6). These are calculated during the solution and are output to OptiStruct to form the stiffness matrix.
`cbulk`	double (table)	Output	(Optional) Bulk material modulus Matrix.
`smat`	Double (table)	Output	1D array (21 terms). This is the symmetric part of `cdev`. These are calculated during the solution and are output to OptiStruct to form the stiffness matrix.
`userdata`	Character	Output	User-defined message that is output based on the value of `ierr` argument.
`ierr`	Integer	Input/Output	Flag that activates/deactivates Output message for an OptiStruct run from the user subroutine. 0 (Default) No action. 1 The OptiStruct run errors out and an ERROR message is printed based on the message defined in `userdata` argument. -1 The information message defined in `userdata` argument is printed and the OptiStruct run continues.

Build External Libraries for User-defined Materials

Allows building shared libraries on Windows or Linux.

Refer to Build External Libraries for more information.