There are currently six different built-in external material function interface types, or sockets, which have many traits in common:

These built-in material function interfaces expect the external library to contain at least an evaluation function called eval, with a signature following the following pattern:

The user is required to specify an array of material model parameters, called par. The number of parameters nPar is specified implicitly as the length of the material property array, which must be defined as a property in a property group under the calling External Material feature or set in the Material Contents table in the External Material node’s settings. The material property expression list specified in this way is interpreted as a list of model expressions which are evaluated at the points for which external material outputs are requested.

The user may also specify a list of state arrays to be defined at each integration point, as well as the length of each array. The array lengths and values are passed to the external function in consecutive pairs of arguments, here formally called nStates1, states1, nStates2, states2, and so on. Note that the state arrays are both input and output: when the function is called, they contain the previous step converged values of the states; on return, they must contain the state values to be stored if the solver decides to proceed to the next step.

The optional errMsg argument allows returning a detailed error message if the evaluation must be terminated abnormally, or to pass a warning or log message to be displayed in the solver log. It is a preallocated string of specified size.

The property group which stores the par array may also specify another array of extra function library string arguments, arg, which are passed unevaluated as separate string arguments to the external material function. Note that the number of string arguments passed in this way is not checked.

In addition to the eval function, the external library may contain functions called init and cleanup. The initialization function has the following signature:

The first five arguments are always passed. The remaining may or may not be present, depending on settings in the External Material node from which the external library is called. If errMsg is not present, the errMsgSize argument will be negative. The number of extra char* arguments at the end of the argument list is given by the nStringArgs argument.

The initialization function is called every time a new native representation of the Multiphysics problem is created. In a solver sequence, this point corresponds to the Compile Equations node. But native representations may also be created at other times, for example when showing a default solver. You can rely on the init method being called at least once before the solver is started, but it may be called multiple times.

The cleanup function is called when the native representation is discarded. This typically happens when a solution object is overwritten or otherwise discarded, at the latest at program exit. The function has the following signature:

The arguments passed are the same as the last arguments to the init function, with the same sizes and values.

The functions must return an integer values. For the eval function, the following return values are defined:

For the init function, the following return values are defined:

For the cleanup function, any nonzero return value is reported as “External material cleanup error”.

When the return value signals an error, it is also possible to supply an error details string in the optional output argument, errMsg. The error message argument, if present, is a preallocated string of a specified size.

You can also use the errMsg argument to return a warning or a log message. If the return value is -1, the contents of errMsg are displayed as a warning in the solver log and in a Warnings node under the solver node; when the return value is -2, the message is only displayed in the log.

The General stress–strain relation socket implements a stress–strain relation computing a second Piola–Kirchhoff stress tensor given the current Green–Lagrange strain together with a material property vector and a vector of stored states. The expected external material function signature is:

The e and s tensors are given in Voigt order; that is, the components in e are {exx, eyy, ezz, eyz, exz, exy} and similarly for s. The Jacobian Jac is a 6-by-6 matrix of partial derivatives of components of s (rows) with respect to components of e (columns); the matrix is stored in row-major order. All components refer to the local material coordinate system. Note that Jac in general is nonsymmetric since the three last components of e represent strain tensor components, rather than engineering shear (γij = 2eij). For an explanation of remaining arguments, see General Arguments for the Built-In Material Functions.

The General stress–deformation relation socket implements a stress-deformation relation computing a second Piola–Kirchhoff stress tensor given the current and previous deformation gradient, the current and previous local temperature, the local material coordinate system, a material property vector, plus standard optional arguments. The expected external material function signature is:

The FlOld and Fl tensors are given as 3-by-3 matrices expanded in row-major order, where the row index refers to global (displacement) directions, and the column index refers to directions in the local material coordinate system. The coordinate system itself, sysT, is passed as a 1-by-9 concatenation of the local system’s three covariant base vectors expressed in global material coordinates. The argument delta is a scalar reserved for future use.

The output stress tensor, Sl, is given in Voigt order; that is, the components in Sl are {Slxx, Slyy, Slzz, Slyz, Slxz, Slxy}, where the indices refer to the local material coordinate system. The Jacobian Jac is a 6-by-9 matrix of partial derivatives of components of Sl (rows) with respect to components of Fl (columns); the matrix is stored in row-major order. For an explanation of remaining arguments, see General Arguments for the Built-In Material Functions.

The Inelastic Residual Strain socket implements an update procedure for an additive inelastic contribution to the total Green–Lagrange strain. Total stress and strain at the previous converged step, current total strain, current temperature, a reference temperature, a material property vector, and a vector of stored states are passed as inputs.

The sOld, eOld, e, and eInel tensors are given in Voigt order (that is, the components in e are {exx, eyy, ezz, eyz, exz, exy}) and similarly for the other tensors. The Jacobian Jac is a 6-by-6 matrix of partial derivatives of components of eInel (rows) with respect to components of e (columns); the matrix is stored in row-major order. Note that the primary output quantity eInel is declared as states, meaning that the argument on entry contains the previous converged step values. The temperature arguments T and Tref are standard model inputs, which are specified in the physics feature calling the external material where the Inelastic residual strain socket is selected. For an explanation of remaining arguments, see General Arguments for the Built-In Material Functions.

The Inelastic Residual Deformation socket implements an update procedure for an inelastic contribution to the deformation gradient. Total stress and deformation at the previous converged step, current total deformation, current temperature, a reference temperature, plus standard optional arguments are passed as inputs.

The sOld, tensor is given in Voigt order (that is, the components in s are {sxx, syy, szz, syz, sxz, sxy}). The deformation gradient arguments FlOld, Fl, and FlInel are passed as 3-by-3 matrices expanded in row-major order, where the row index refers to global (displacement) directions, and the column index refers to directions in the local material coordinate system. The Jacobian Jac is a 9-by-9 matrix of partial derivatives of components of FlInel (rows) with respect to components of Fl (columns); the matrix is stored in row-major order. Note that the primary output quantity FlInel is declared as states, meaning that the argument on entry contains the previous converged step values. The temperature arguments T and Tref are standard model inputs, which are specified in the physics feature calling the external material where the Inelastic residual strain socket is selected. For an explanation of remaining arguments, see General Arguments for the Built-In Material Functions.

The General B(H) relation and General H(B) relation sockets implement generalizations of B-H and H-B curves, respectively. The General B(H) relation socket computes an updated magnetic flux density corresponding to an updated magnetic field, given the magnetic field and magnetic flux density at the previous converged step. A material property vector and a vector of stored states are passed as additional input. Typical implementations will use extra states to model hysteresis.

The magnetic fields oldH and H and the magnetic flux density B are passed as arrays of length 3. The Jacobian Jac is 3-by-3 matrix of partial derivatives of components of B (rows) with respect to components of H (columns); the matrix is stored in row-major order. Note that the primary output quantity B is declared as states, meaning that the argument on entry contains the previous converged step values. For an explanation of remaining arguments, see General Arguments for the Built-In Material Functions.