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 results-processing expressions. Such features are currently available in the Solid Mechanics; Membrane; Magnetic Fields; and Magnetic Fields, No Currents interfaces.
•
Using external materials in Solid Mechanics or Membrane 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.
The call syntax is in general not fixed for a given socket. Most sockets allow socket parameters to control certain aspects of the socket behavior, including:
•
Whether to pass arguments as real or complex numbers.
•
Whether to call an initialization function in the external library before the solver is started.
•
Whether to call a cleanup function in the external library.
•
What user-defined state array names to declare and pass to the external function, as well as the size of each array.
•
Whether to add a preallocated string argument of a chosen size to the argument list, to which a detailed error message can be written if the external material function fails in some way.
•
Whether to add a number of string arguments at the end of the argument list.
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 and parameters. 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 may 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. Note that no external material function will be called in this case.
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.
Result Presentation
The external material function may also be called during result presentation. In COMSOL Multiphysics, the stored solution consists of the degrees of freedom plus any possible state variables.
As an example, if you have coded your own elastoplastic material model for solid mechanics, you will typically store the plastic strains as states. If you then during result presentation make a plot of the stresses, the material function is called in order to compute the stresses from the displacements and plastic strains. This will happen at a large number of locations in the mesh.
The states are stored at the integration points, so if you request integration point results of the right order, there will be a call to the external material with a consistent already converged state. If the function is well coded, it will then return the stress state after a single iteration.
Often the material function is called from a location that is not an integration point (for example, a mesh node). In that case, the values of the state variables are taken from the closest integration point, while the total strains are computed from the displacement field gradients at the evaluation location. This combination does in general not provide a converged state, so iterations will be needed inside the material function in order to find the stress state. This can have several negative effects:
•
The iterations will make the evaluation more expensive.
•
The accuracy is decreased, since the state variable values are taken from a neighboring location.
•
In the worst case, evaluation in the material function fails completely. What happens in this case depends on how you handle exceptions.
For these reasons it is advantageous, both from a performance and an accuracy point of view, to evaluate results only at the appropriate integration points. In order to ensure that, you can add the gpeval operator to your expressions. Instead of plotting for example solid.mises, use an expression like gpeval(4,solid.mises).