Overview

This page provides general guidelines that can be followed to troubleshoot when a knee model is not running as expected in FEBio. It is often difficult to know what is causing a problem with the model, but we provide here some examples of methods to help determine the cause of the issues.

When the first time step won't converge

Sometimes a model will not succeed in converging even at the first step. This is often a sign that there is some underlying issue with a tie or contact in the model. These are suggested steps to take to discover where the issue lies.

We recommend beginning with a very simple model, and adding complexities one at a time. Here is an example workflow for a full knee model that is not running for 90 degree flexion.

Begin by commenting all contacts in the model, and the MCL-MNS-M tie. (Ligament-Bone ties on their own generally do not cause issues - more likely it is a contact or some combination of contacts that is causing the issues.) Add the contacts back in the order specified below. At each step, run the model. It does not need to run to fully converge, if the first time step converges it is usually a sign that there is no issue with the contact, and you can interrupt the run and move on.

Cartilage to Cartilage contacts (if this fails break them down one at a time ex: first only FMC to TBC-L, then add FMC to TBC-M...)
Meniscus to cartilage contacts (if this fails break them down one at a time ex: first add MNS-M to FMC, then MNS-M to TBC-M...)
MCL to bone contacts
MCL to MNS-M tie
QAT to bone contacts

If the first time step does not converge when a contact is added, some things to investigate are:

penetrating tissues (in this case, edit the geometry to reduce penetration)
contact surfaces that intersect with tie surfaces (check the MED files in salome)
if you get a segmentation fault error when a bone-to-ligament contact is added, try changing the contact type from "sliding-elastic" to "sliding-node-on facet".
try commenting all other contacts, and leaving ONLY the problematic contact on, to see if it is a stand-alone problem, or if there is some combination of contacts that is causing an issue. This may provide additional clues to what the issue is.

Once the above contacts are all running, run the model as far as it will converge. Looking at results in postview will indicate if any other ligament-bone or ligament-ligament contacts are necessary to add. For example, if there is penetration between the ACL and PCL, add the ACL-PCL contact.

General convergence issues

Convergence issues are often very difficult to diagnose as there can be many factors involved in the non-convergence of a model. Here we list some tools that may help to identify issues:

in the terminal window/log file of a model, FEBio will indicate if negative jacobians were detected at any element. In postview, you can search for this element using the edit>find tool.
use postview to view stresses, strains, contact pressure to look for stress concentrations. Strange patterns can sometimes be an indication that the geometry needs further smoothing, or it too coarse/fine.

Below is a workflow that was useful to get oks003 model to converge in simulations representative of experimental loading:

PLOT_MUST_POINTS should only be requested for time points where output is necessary for post-processing. These requests may result in small increments in time step during the solution, which may be problematic when loading/displacement increment is small. This results in very low displacement norms to satisfy (set by dtol) while there may be no loading acting on the system, i.e., trying to solve 0 flexion with small loads from reference state. Increasing min_res parameter, e.g. to 0.01 (from 0.001) can be helpful to force convergence, i.e., when dtol is not satisfied but residual norm becomes lower than 0.01.
Troubleshooting should start with the analysis of log file. Workflow can be in following:
- Make sure the element IDs for elements with negative jacobian are printed. Starting with FEBio version 2.9, this is optional. It can be enforced by adding the following line to FEBio configuration file (febio.xml):
  - <output_negative_jacobians>1</output_negative_jacobians>
- Start at the end of the log file to troubleshoot.
- The reason for early termination is always "Max. nr of retries reached." First, identify why this is the case by moving up in the log life.
- One possibility for error is "Max nr of reformations reached." This indicates that full newton step has slow convergence. It may help increasing max_refs parameter, e.g. to 50 (from 25). if required displacement norm is very small, e.g. less than 1e-5, this may be triggered due to small increments in time step during solution where loading/displacement change is small (see comment on PLOT_MUST_POINTS). If that is the case, you may want to increase min_res parameter, e.g. to 0.01.
  - Another possibility for error is "Negative jacobian was detected". The error message should also print element ID. Checking dt (at the AUTO STEPPER line) above can help evaluate if the retried time incrementation was small, e.g. 0.001. If higher, it may be beneficial to increase max_retries parameter, e.g. to 10 (from 5), to let the simulation take smaller time steps. Alternatively, or in addition, the elements with negative jacobians can be visualized in Postview. In Edit -> Find -> Select Elements, in the Item box type element ID with the negative jacobian. Usually these elements are located at the ligament insertions with some nodes in tie definitions (plotting contact pressures will help to identify boundary between tie regions and contact regions). Record the nodes of the elements that are tied "Select Nodes" in Postview). These nodes can be commented in the geometry file where the tie constraints are defined. Sometimes elements with negative jacobian can be in the middle of tissue, in unloaded regions, e.g. cartilage. This indicates that the original mesh may have some elements with low volume and bad aspect rations. A quick solution is to comment the element in the geometry file.
Previously, while trying to get simulations converge, many other strategies were tried with mixed outcomes.
- Set dtol to 0 and etol to 0.0001. Essentially, stop checking displacement norm for convergence and tighten energy norm tolerance for convergence. Sometimes this is helpful for convergence.
- Set lstol to 0.1 or 0.01. Sometimes this helps to reach a solution with the cost of increased stiffness reformations.
- Simplify model, remove unnecessary components, contact definitions. Possibly convert cartilage to rigid bodies, etc.
- Change linear tet meshes to quadratic tet meshes.
It will be helpful to compare solutions, e.g. joint kinematics-kinetics response, for models with original and updated parameters for convergence. This will help document the potential impact of these changes on relative accuracy of the solution.

Checking tissue geometries

When a model is not converging, the geometry itself can sometimes be the cause of the problem. To test a tissue individually for convergence issues, it is recommended to create "reduced models", where only the tissue of interest is being tested. Edit the geometry as needed.

Ligaments

A bone-ligament-bone model can be created, with the ligament tied to the bones. one bone can be fixed, and the other bone can be translated using a rigid body translation approximately along the long axis of the ligament. ex: Checking the ACL. Create a model with TBB, ACL, FMB. Fix the TBB, translate the FMB in the z direction ~ 4 mm so that the ACL is "stretched" . If this converges, view the results in postview and check that there are no stress concentrations caused by element-locking, etc.

Cartilage

A bone and cartilage model can be created, and a simple compression of cartilage against cartilage can be tested by fixing one bone, and translating the other bone towards it so that the cartilage is compressed between the bones. Check in postview the stress/pressure distributions in the cartilage. Sometimes if a cartilage geometry was not smoothed enough, there can be 'ridges' in the cartilage which create a striped stress distribution. In this case the cartilage needs to be smoothed further.