Solver documentation needs a working tutorial, updates, and corrections

[ryanspilker]

Description

No working tutorial is currently available in this documentation that leads to a completed simulation with the supported solver, svMultiPhysics. The Simulations Tool lacks a tutorial and has documentation that needs updates and corrections. The MultiPhysics Tool has a tutorial that is incomplete, currently not working, and written twice. Both tools' documentation pages are marked as beta versions.

Reproduction

A new user following the Getting Started Guide and continuing through the tutorial sections of the other guides in the documentation currently fails to complete a hemodynamic simulation.

Expected behavior

A new user should find a straightforward path starting with the Getting Started Guide to complete a first simulation with the Simulations Tool or the MultiPhysics Tool.

Additional context

The MultiPhysics Tool's tutorial with corrections should enable a new user to complete a simulation, but it is missing final steps and fails due to another issue, SimVascular/SimVascular#1182.

Code of Conduct

• I agree to follow this project's Code of Conduct and Contributing Guidelines

[ryanspilker]

Thanks to progress by @ktbolt on SimVascular/SimVascular#1182, a new user can now use the MultiPhysics Tool's tutorial to complete a first simulation with a few educated guesses.

[alisonmarsden]

It would be a good idea to have @sujaldave check the linear solver / preconditioner choice and tolerances in the input file for this cylinder example (and the others we use). Many users have been thrown off by too tight tolerances used in test cases and therefore ended up with simulations taking forever unnecessarily.

[ryanspilker]

@alisonmarsden That sounds like an important update to the solver tutorial.
@sujaldave I would be happy to have your recommendations on parameter values.

[sujaldave]

@ryanspilker The current version of the tutorial Cylinder Project does in fact have too tight tolerances on the linear solver. The following section in the solver.xml file (CylinderProject/Simulations/steady/solver.xml)

   <LS type="NS">
        <Linear_algebra type="fsils">
            <Preconditioner>fsils</Preconditioner>
        </Linear_algebra>
        <Max_iterations>15</Max_iterations>
        <Tolerance>1e-4</Tolerance>
        <Krylov_space_dimension>200</Krylov_space_dimension>
        <NS_GM_max_iterations>10</NS_GM_max_iterations>
        <NS_GM_tolerance>1e-3</NS_GM_tolerance>
        <NS_CG_max_iterations>300</NS_CG_max_iterations>
        <NS_CG_tolerance>1e-3</NS_CG_tolerance>
   </LS>

should be replaced to be

    <LS type="NS">
        <Linear_algebra type="fsils">
            <Preconditioner> fsils </Preconditioner>
        </Linear_algebra>
        <Max_iterations> 15 </Max_iterations>
        <Tolerance> 0.4 </Tolerance>
        <Krylov_space_dimension> 200 </Krylov_space_dimension>
        <NS_GM_max_iterations> 100 </NS_GM_max_iterations>
        <NS_GM_tolerance> 1e-2 </NS_GM_tolerance>
        <NS_CG_max_iterations> 200 </NS_CG_max_iterations>
        <NS_CG_tolerance> 0.2 </NS_CG_tolerance>
   </LS>

[alisonmarsden]

Glad we're getting this sorted out. I think this may be (partly) why so many users are getting thrown off. They are using this input file as an example, when it was originally intended as an automated test case for the solver. @ryanspilker please verify that the case runs for you as expected with this change and then let's update the file.

[ktbolt]

@ryanspilker The linear solver parameters while not optimal are conservative; it is not clear if the very large tolerances, like NS_CG_tolerance=0.2, for NS are applicable to all simulations with different boundary conditions and such.

From what I've seen on the SV Forum and interacting with other uses like Daniele it is the test cases that are causing problems because people are using them as simulation templates.

[alisonmarsden]

Quite sure our recent experience running a variety of CFD simulations in the lab confirms that these tolerances are generally applicable and match (according to @wgyang ) with what we were using historically. @sujaldave can also weigh in here since he has run a bunch of tests. These values are not comparable to typical tolerances because they are used in an iterative loop with calls to both GMRES and CG.

[sujaldave]

@ryanspilker @ktbolt @alisonmarsden If we compare two simulations, one with "GMRES+fsils+fsils" combination (Classic GMRES solver with diagonal preconditioner) with fine tolerance (1e-4) and the other with "NS+fsils+fsils" combination (Bipartition LS method with Resistance-based preconditioner) with coarse tolerance (0.4), both will produce similar flow fields for a particular CFD test case. This relaxation in the tolerance for bipartition method is a result of its design to solve the tangent matrices concerning momentum and continuity portions separately with calls to different LS solvers (2 GMRES and 1 CG) within one bipartition LS iteration.

From my experience of running various tests for different LS and preconditioner combinations, I believe the bipartition solver, resistance-base preconditioner and coarse tolerance combination could be a good starting point for first-time users and for those limited to running CFD simulations. However, once they need to move to more complex tests involving CMM, FSI etc. they might need to be more careful with the choice of LS employed. Although it would be the easiest for users to start with "NS+fsils+fsils" combination with coarse tolerance and if that doesn't work, shift to "GMRES+fsils+fsils" combination with tighter tolerances.

[ryanspilker]

Thanks, @sujaldave. I will use these recommendations as a goal for guiding new users in the documentation. This should help to clear up the current situation.

Users have a variety of sources to guide their simulation setups. My current understanding is that the obvious sources are the following for a new user trying to run the cylinder example:

• solver.xml file for the Simulations tool (CylinderProject/Simulations/steady/solver.xml) in the SimTK examples and cases project
• solver.xml file produced by the Simulations tool with the default parameter values which differ from above in the nonlinear solver's max. iterations and tolerance
• solver section for the Simulations tool in the CFD Simulations User Guide
• defaults for the MultiPhysics tool
• Creating a Solver Input File section of the MultiPhysics User Guide
• test cases that you're mentioning, @ktbolt, which might be somehow marked as not recommended as examples for users

It seems worthwhile to provide consistent recommendations for a "NS+fsils+fsils" combination to get new users started and then make sure that the documentation has an example for CMM or something else that would require a "GMRES+fsils+fsils" combination.

[ktbolt]

@ryanspilker You will need to add a section about svSolver compatibility; this is important for users that want to simulate a model from the VMR.

The new CFD Simulation Tool will read in most of the current .sjb GUI parameters and set them correctly except for the number of time steps and time step.

[alisonmarsden]

I agree - I also think at some point we will need to rerun all the VMR models with svMultiPhysics so everything is compatible.