Using External Materials in Physics Interfaces

In order for a physics interface to make use of external materials, it must contain one or more features that provide input quantity definitions and make use of returned output quantities in equations and postprocessing expressions. Such features are currently available in the Solid Mechanics; Magnetic Fields; and Magnetic Fields, No Currents interfaces.

• Using external materials in Solid Mechanics requires a Structural Mechanics Module or MEMS Module license. • AC/DC interfaces supporting external materials are only available with an AC/DC Module license, except for Magnetic Fields in 2D.

External Material Interface Types

Given that a physics feature requires certain output quantities and defines certain input quantities, there are many possible ways to set up a call to an external function, including declarations of material properties and states. The required interface specification, or interface type, is contained in an external material socket, which does a number of different things:

•	It defines the call syntax for the external material functions; that is, it defines the function name, return type, and the number of arguments with their data types and sizes.

•	It defines a mapping between input and output quantity tensor components in the COMSOL Multiphysics variable namespace and positions in external function arguments.

•	It defines a mapping between function argument positions and partial derivatives of outputs with respect to inputs.

•	It decides which input quantities should be evaluated at the last converged step — rather than at the last iteration — and sets up states for these variables.

•	It declares material model state variables and maps them to positions in the function arguments.

•	It declares required material properties and maps them to the function arguments.

•	It specifies error handling procedures, including error messages for various exit conditions.

For an external shared library to be compatible with COMSOL Multiphysics, it must follow the conventions specified by some socket. Conversely, when using an existing external library in a multiphysics model, it is important to choose the right Interface type. Failure to do so will result in the external library being called with unexpected arguments, leading to arbitrary behavior.

It is not necessary for a socket to define all output quantities required by a physics feature. The socket and external library may compute only some quantities, while others are left to be specified by property groups under the External Material feature. For example, the built-in General stress-strain relation socket only returns second Piola-Kirchhoff stress as output, while the physics features using this interface type also may require the material density. The density must instead be specified as an expression in the Basic property group.

It is also possible to set the Interface type to None to select no socket and instead set up the relation between input and output quantities as expressions directly in an external material feature. This behavior is intended mostly for testing and debugging of multiphysics models.

Sockets and associated material property groups are identified by an ID tag that must be unique among all COMSOL installations between which files will be shared. In order to avoid conflicts between built-in sockets and future user-developed sockets, a full Java-style naming convention has been adopted. Therefore, for example, the built-in General H(B) relation socket has the unique ID com.comsol.generalHBRelation and the associated material property group has tag and name comcomsolgeneralHBRelation — that is, a direct concatenation of the ID.

Solver Iterations and State Updates

This section describes quantities as being evaluated either at the current step or at the previous converged step. This is related to the iteration pattern of the solvers. The external material functionality is primarily intended for modeling materials with some kind of memory or path dependence (for example, inelastic solid materials or materials exhibiting electromagnetic hysteresis). This means that simulations must be performed in steps over an interval of time or some parameter (which can often be interpreted as a pseudo-time).

Whether a time-dependent or parametric solver is used, taking a step forward requires solving a nonlinear problem, which is typically an iterative procedure. In order for the convergence to be efficient, the modified Newton solver used needs correct Jacobian information (the Jacobian is sometimes called the tangential stiffness matrix), which must be provided by the external material functions in the form of partial derivatives of output argument components with respect to input argument components. When the nonlinear iteration converges, the solution for that time step or parameter step is stored, and the solver moves on to the next step.

The external material functions are typically called in each iteration in the inner nonlinear loop. Arguments that are evaluated at the current step are reevaluated at each inner iteration, while arguments defined at the previous converged step retain the value they had when the previous nonlinear iteration converged; that is, the value that was last stored. State variable arguments are passed to the external material function with the same previous converged values in each inner nonlinear iteration. The external material function is expected to overwrite this previous value with a new value corresponding to the current iteration, but this value will only be stored and the states updated when the inner nonlinear iteration converges.