Execution Debugging

How can I find out why the iterative solution of a nonlinear problem does not converge?

One needs to:

1. find out the equations whose residual does not converge to zero.

   The residual is printed using the statement

       output: residual;
   

   in the problem control block described in Section 4.1.4 of Chapter 4. Each coefficient is preceded by its number and followed by a brief description of which node/element instantiated the equation and what its purpose is, if available; for example, the output

   Eq     1:        0 ModalStructNode(1): linear velocity definition vx
   Eq     2:        0 ModalStructNode(1): linear velocity definition vy
   Eq     3:        0 ModalStructNode(1): linear velocity definition vz
   Eq     4:        0 ModalStructNode(1): angular velocity definition wx
   Eq     5:        0 ModalStructNode(1): angular velocity definition wy
   Eq     6:        0 ModalStructNode(1): angular velocity definition wz
   Eq     7:        0 ModalStructNode(1): force equilibrium Fx
   Eq     8:        0 ModalStructNode(1): force equilibrium Fy
   Eq     9:        0 ModalStructNode(1): force equilibrium Fz
   Eq    10:        0 ModalStructNode(1): moment equilibrium Mx
   Eq    11:        0 ModalStructNode(1): moment equilibrium My
   Eq    12:        0 ModalStructNode(1): moment equilibrium Mz
   

   corresponds to a residual whose first 12 equations refer to a modal node labeled ``1'' (and the residual is exactly zero);

2. find out who instantiated the offending equation or equations.

   If this is not already indicated in the previously mentioned description, one should look up the offending equation index in the output originated by adding the statement

       print: equation description;
   

   in the control data block, as described in Section 5.1.2. In the above example, it would generate

   Structural(1): 12 1->12
           1->3: linear velocity definition [vx,vy,vz]
           4->6: angular velocity definition [wx,wy,wz]
           7->9: force equilibrium [Fx,Fy,Fz]
           10->12: moment equilibrium [Mx,My,Mz]
   

3. find out who could contribute to that equation or equations.

   If the equation was instantiated by a node, one should look at the elements connected to that node. This information is obtained by adding the statement

       print: node connection;
   

   in the control data block, as described in Section 5.1.2. In the above example, it would generate

   Structural(1) connected to
           Joint(1)
           Joint(2)
   

   so one should try to find out which of the connected elements is generating the offending contribution to that equation.

   If the equation was instantiated by an element, usually the element itself is the sole contributor to that equation.