How to Debug an External Material

Problem Description

I have a implemented an external material for use with Structural Mechanics, but my model is not solving.

Solution

External materials are coded in C, and then compiled into a shared library that COMSOL Multiphysics uses at runtime. If you are having problems compiling the external material code, please consult the section in the How to Compile and Link an External Material Model in the COMSOL Multiphysics Reference Manual.

The purpose of the external material is twofold:

• To compute mechanical stresses that will be used to determine if equilibrium has been reached between internal and external forces.
• To compute the derivative of stress with respect to strain (the Jacobian) so that the equation solver can iterate to establish force equilibrium.

When COMSOL Multiphysics uses an external material, parameters and states (internal variables) are passed between the program and the external material function, and this has to be done in a consistent manner. For example, the number of states defined in COMSOL Multiphysics has to match the number of states that you use inside the external material. See the section Working with External Materials in the COMSOL Multiphysics Reference Manual. Also, consult the examples provided in the links at the further down on this page. Try compiling one of the example external materials and use it in a simple case to make sure that your model definition is sound.

If the model does not solve or converge, try to understand if it is the stress computation or the Jacobian computation that is problematic. To make it easier to test your external material code do the following:

• Make a model that is as small as possible, preferably using a single mesh element.
• Subject the model to displacement-controlled loading. This way, you have exact control over the strains that enter into the external material code. Moreover, if the material model that you are implementing includes softening, a displacement-controlled model is necessary.
• Use simple cases of deformation, such as uniaxial tension and pure shear.

Stress Computation

There are a couple of things to check that have to do with the computation of stresses:

• If the external material works well under uniaxial loading, but either fails or produces incorrect results in other modes of deformation, make sure that you use the correct definitions and ordering of shear strain components in the external material code.
• Are there any risks of division by zero in your code? In the beginning of an analysis, the external material can be called for a zero displacement field (zero strains), and you need to safeguard your code to identify problems that may arise.
• Many inelastic material models require local iterations to compute stresses. This is often called the stress update algorithm. COMSOL Multiphysics has no control over these local iterations, so it is useful to pay close attention to the robustness of the iterative method that you have implemented. Are there any risks of numerical overflow? In creep models, the stress is typically raised to a power (greater than one). During the local iterations, the non-converged stresses can be high enough to cause an overflow when raised to a power. It is useful to place safeguards in your code to identify these types of problems.
• If you believe that the stress update algorithm is problematic, you can print information from the local iterations to a separate file using the fprintf statement in C. Be careful, however, as this can generate large volumes of output.

Jacobian Computation

A sign that the Jacobian is incorrect is that the model runs without problem for a portion of the analysis, and then experiences convergence problems. This behavior suggests that the inelastic portion of the Jacobian is incorrect. There are a few ways to identify and remedy problems that pertain to the Jacobian computation:

• First, it must be pointed out that in many situations, an approximate Jacobian, that deviates slightly from the correct Jacobian is often good enough to reach convergence. Only the rate of convergence is affected, and not the accuracy of the solution.
• The most common cause of convergence problems is that the Jacobian is not correctly defined. Formally, the Jacobian is the derivative of 2nd Piola-Kirchhoff stress with respect Green-Lagrange strain (or with respect to the deformation gradient). The derivative has to be computed so that it is consistent with the stress update algorithm used to compute stresses.
• Just like with the stress update algorithm, pay close attention to the definition and ordering of shear strains.
• A common pitfall when differentiating quantities such as the equivalent stress is to omit the symmetry of the stress tensor. Problems can arise when a compact vector format is used for stresses and strains.
• The differentiation of stress with respect to strain can be quite involved (and error prone). You can try making controlled simplifications to the Jacobian expression.
• If the expressions for the Jacobian terms are very involved, you can use the fprintf statement to print values to a separate file and then compare to manually computed values. However, be careful, as this can generate large volumes of output.

Cross-Platform Use of External Materials

Sometimes you want to solve your model on a different computer from the one being used to build the model and process results. If these computers are using different operating systems (e.g. one being a Linux computer, and the other being a Windows computer), you will need to:

• Compile the External Material for both platforms.
• Perform Update Solution before you try to process the results. This ensures that the correct compiled External Material library is being used.

General Advice

Sometimes it is difficult to pinpoint if the external material code fails because of problems in the stress computation or in the Jacobian computation. It may be useful to implement a Jacobian based on numerical perturbations to the strain field. Miehe (1996) has suggested a perturbation technique that replaces the computation of the Jacobian by six additional stress computations. This technique is potentially computationally expensive, but very useful during external material development.

Also, note that a library of utility functions is provided for many of the tensor and vector operations that frequently appear in constitutive modeling. These can help you reduce the time that you otherwise spend on coding the corresponding functions yourself. See the section Using External Materials in the Structural Mechanics Module User's Guide.

There are several sources to consult that demonstrate implementations of external materials in COMSOL Multiphysics. See, for example:

External Material Examples, Structural Mechanics

How to Implement Elastoplasticity in a Model Using External Materials

With each version of COMSOL Multiphysics, more built-in material models are added to the already large collection of material models in the software. It is possible that the material behavior that you are coding as an external material now exists inside COMSOL Multiphysics.

References

Miehe, C., “Numerical computation of algorithmic (consistent) tangent moduli in large-strain computational inelasticity”, Comp. Meth. Appl. Mech. Engng., Vol 134, No. 3-4, pp. 223-240, Aug 1996.

Browse by Category