Add documentation on parameters to control the convergence of the solver

[wilburmao]

Hi Finsberg,

When we study the deformation behavior of the heart with complex material models (such as the Holzapfel model + active strain) on a realistic myocardium geometry, it is easy to encounter the problem of convergence issues, such as pulse.mechanicsproblem.SolverDidNotConverge.

I know there are some parameters in the iterate function to control the convergence behavior, such as max_nr_crash, max_iters, ... Can you give us some suggestions on how to control these parameters to reach convergence? What's the strategy you will use to resolve it if a problem does not converge?

I also wonder if there is a way to print out the progress of the solving process. I find the solver seems stuck when I run it with a medium mesh. It is much slower than I expected and no information is displayed during the solving process. I ran it using python not Jupyter notebook.

Specifications

• Version of pulse: 2022.1.1
• Version of FEniCS: 2019.2.0.dev0
• Platform: WSL

Thanks,
Wilbur

[finsberg]

Hi @wilburmao

Thanks for the issue.

In my experience it is often good to start with a high number of initial steps (initial_number_of_steps). The default value is 5 but if you experience a lot of divergence, setting this to e.g 50 would perhaps avoid having too many unsuccessful steps in the beginning. Also if you set adapt_step=True (which is also True by default) it will try bigger steps if the number og Newton iterations are lower than max_apapt_iter (which is default to 8).

Improving the documentation on this should definitely be done. I will change the title of the issue slightly to reflect that the documentation needs to be improve.

Regarding printing out more information, you can set the log level of the logger in the iterate module in order to get more info

import pulse
import logging

pulse.iterate.logger.setLevel(logging.DEBUG)

You can also get more info about the residuals from the solver by passing solver_parameters={"verbose": True} when creating the MechanicsProblem

[wilburmao]

Thank you for your explanation. It is very useful.