Troubleshoot FreeCAD FEM Solver Convergence Errors

Solver convergence errors in FreeCAD FEM typically occur when the underlying solver (most commonly CalculiX) cannot find a stable equilibrium state within the allocated iterations. This guide provides a direct, structured approach to diagnosing and resolving these failures by methodically checking boundary conditions, refining mesh quality, managing non-linear solver settings, and interpreting solver log files to pinpoint the exact source of numerical instability.

1. Eliminate Rigid Body Motion

The most common cause of non-convergence, particularly when the solver reports zero or negative pivots, is an under-constrained model.

  • Check Degrees of Freedom (DOF): Ensure your model is constrained against all three translational and three rotational degrees of freedom. A part free to translate or rotate along any axis will trigger an immediate numerical singularity.
  • Inspect Symmetry Conditions: If using symmetry boundary conditions to cut model size, verify that faces are properly constrained along the normal direction of the symmetry plane.
  • Verify Multi-Part Constraints: In multi-body assemblies, ensure each body is either independently anchored or tied to an anchored body via constraints or contact pairs.

2. Inspect and Refine the Mesh

Poor mesh quality frequently produces distorted elements that generate singular stiffness matrices.

  • Check for Distorted Elements: High aspect ratio tetrahedrons, inverted elements, and elements with sharp interior angles struggle to converge. Use the Netgen or Gmsh controls within FreeCAD to set maximum element size limits.
  • Refine at Stress Concentrations: Coarse meshes around sharp internal radii, holes, or contact zones fail to capture high strain gradients. Apply local mesh refinement meshes to these critical regions.
  • Switch Element Orders: Second-order (quadratic) elements (e.g., C3D10) provide higher accuracy, but in complex contact or plasticity scenarios, first-order (linear) elements with reduced integration can sometimes overcome stubborn geometric convergence blocks.

3. Tune Non-Linear Time Stepping

When running non-linear analyses involving large deformations, non-linear materials, or contacts, default step sizes are often too aggressive.

  • Enable Non-linear Geometry: Set the GeometricNonlinearity (NLGEOM) property to True if deformations affect the load path, as linear assumptions under large displacement cause divergence.
  • Reduce Initial and Minimum Time Steps: Access the solver properties in FreeCAD. Decrease the initial time increment (e.g., from 0.1 to 0.01 or 0.001) and lower the minimum allowed increment (1e-5 or lower). This gives the solver room to cut back the step size when iterations diverge.
  • Increase Iteration Limits: Increase the maximum number of iterations allowed per increment before the solver declares a cutback.

4. Adjust Contact Formulations

Contact non-linearities are notoriously sensitive and prone to chattering or penetration errors.

  • Initial Clearances: Ensure contacting surfaces either perfectly touch or have a well-defined initial gap. Penetrating geometries at step zero will destabilize the solver.
  • Contact Stiffness: If using penalty contact, excessively high contact stiffness leads to numerical ill-conditioning, while low stiffness allows excessive penetration. Adjust the penalty parameter incrementally.
  • Simplify to Tie Constraints: For troubleshooting, temporarily replace contact pairs with fixed tie constraints. If the simulation converges with tied interfaces, the issue resides entirely in your contact parameters rather than the overall setup.

5. Validate Material Definitions

Inconsistent or unphysical material models directly cause convergence breakdown.

  • Poisson's Ratio: Ensure Poisson's ratio for linear elastic materials does not approach 0.5 (incompressibility), which causes volumetric locking in standard displacement-based elements. Keep it below 0.49 for metals and plastics.
  • Plasticity Curves: When defining non-linear stress-strain curves, confirm the data is strictly monotonic (yield stress must not drop unless explicitly modeling softening mechanics) and that true stress/true strain values are supplied rather than engineering values.

6. Read the Solver Log File

Instead of guessing, use the output text generated by the solver during the run to identify the failure point.

  • Locate the .dat and .sta Files: Open the working directory specified in the solver object to inspect CalculiX’s native text outputs.
  • Look for Cutbacks: Frequent cutbacks indicate contact chattering or sharp yielding. The log indicates which node or element is generating the largest residual force.
  • Search for "Negative Pivot": A negative pivot warning lists the exact node number causing the instability. Use FreeCAD's selection tools or inspect the mesh to find that node's physical location, which will show you the exact point of inadequate constraint or extreme distortion.