Improve svFSI documentation on SimVascular website

[CZHU20]

svFSI documentation on http://simvascular.github.io is currently split between two sections: SVFSI GUIDE and SIMCARDIO GUIDE. It might be better to merge all svFSI related contents to SVFSI GUIDE so that users can find everything in one place.

[ktbolt]

The current svFSI documentation is a disorganized mix: mesh creation using MeshMixer, an svFSI Tool example/tutorial, building the solver, etc.

I think it would be good to organize the svFSI documentation like the ROM Simulation Guide.

• Introduction
• svFS Tool
• Theory
• User Guide
• Input File Format
• Examples

Like @vvedula22 mentioned in his email, the documentation should include a comprehensive description of its capabilities including different equations, boundary conditions, linear solvers, etc.

The top-level Clinical Cases menu item can be changed to Applications and a new Cardiac Modeling section added.

Some of the Cardiac Geometric Modeling Tool section should probably be moved under the Modeling Guide I guess.

[ktbolt]

@CZHU20 Let me know how I can help with this.

[CZHU20]

I like the format of ROM Simulation Guide. For svFSI, it might be too crowded to put everything on one page. I would suggest create a main page for general svFSI information and individual page for each major functionality/feature (fluid, structure, fsi, electrophysiology).

The main page will include the following

• Introduction
• Installation
• Input file format
• Major functionalities (each will link to individual pages)
• Simple get-you-started example (e.g. 3D pipe flow with RCR BC)
• Resources (svFSI-Tests, svFSI-Tools, YouTube Channel etc)

For each functionality, we can follow the ROM Simulation Guide and include the following sections

• Introduction
• Theory
• Function-Specific User Guide
• Input File Format
• Example
• Function-Specific Options (e.g. for fluid BC, we have Resistance, RCR, GenBC, cplBC etc. We can also link each option with existing examples in svFSI-Tests.)

I think we need to take full advantage of svFSI-Tests. @vvedula22 curated such a great collection of examples to highlight all the functionalities/options of svFSI. I have built on top of that and improved the documentation (https://github.com/CZHU20/svFSI-Tests) . Now each example contains a README that explains the problem and its unique settings. It would be great to direct users to the corresponding example(s) when they are reading about a functionality/option on SimVascular website.

[ktbolt]

@CZHU20 I'm not sure what you mean by svFSI, it might be too crowded to put everything on one page, do you mean in a single section?

I think things can be organized as sections with appropriate sub-sections, maybe something like

1. Introduction
2. Theory
   1. Fluids
   2. Nonlinear elastodynamics
   3. Coupled momentum method
3. User Guide
   1. Commands
   2. FIle Format
   3. Preparing a mesh for FSI
4. SimVascular svFSI Tool
5. Examples
6. svFSI Tests
7. Appendix
   1. Installing
   2. Building

[CZHU20]

@ktbolt Thanks for the feedback. I was trying to say that if we put everything (or all sections) in one webpage, there might be too much information on that page and readers can get lost. For example, if users only want to learn how to use NS solver, they will need to go through Theory, User Guide and Examples to cherry-pick information only related to NS solver. On the other hand, if we have a main page to document general information of svFSI and separate pages for each feature, it might be easier to find all relevant information quickly. What do you think? Thanks.

[ktbolt]

@CZHU20 Good point about readers getting lost. I say go ahead and organize things the way you feel is best and let's see how it looks.

[CZHU20]

Great. I will get right on it.

[CZHU20]

Hi @ktbolt , I have create a main page for svFSI and it looks like this

The problem is that I don't know how to add a new page and link it to the main page... Can you show me how to do that with the FSI page?

So I already have all the necessary files for svFSI main page at source/documentation/svfsi/main and svFSI FSI page at source/documentation/svfsi/fsi. All the related *erb files are located here with prefix _svfsi_. The goal will be create webpage for FSI function and then reference in the Main features section on the main page.

Thank you.

[ktbolt]

@CZHU20 You can reference other documentation pages like this

<a href="http://simvascular.github.io/docsPythonInterface.html#console"> Python Console </a>

To reference other sections within the current page

http://simvascular.github.io/docsQuickGuide.html#data_manager

Where the #data_manager tag is defined in the section heading like this

<h2 id="data_manager"> Data Manager </h2>

[CZHU20]

Hi @ktbolt , I have made all the changes. You can find them here: https://github.com/CZHU20/simvascular.github.io/tree/source

Here are the new html files generated from source branch above: svFSI-html.zip

Can you please take a look at them? I will submit a pull request if they look okay.

Thanks.

[CZHU20]

Also cleaned up SimCardio page accordingly. It's on a separate branch (source-simcardio) now.

[ktbolt]

@CZHU20 I had a look at the svFSI Guide documentation, much improved from the current version! A few comments

1) You should not lead off the svFSI Guide with a discussion of the human heart and such. This should be a general discussion of multi-physics. Cardiac modeling is a specialize application of svFSI, be careful not to highlight it too much.

2) The Main features section is nicely organized but the documentation links don't work. Note that these links should be tags within the current page.

3) Software installation and build should go at the end of the documentation.

4) Remove the Plugin installation section. I think the plugin was used before svFSI became an SV core plugin.

5) You cannot explain the solver input file format using an example. You might could organize it like http://simvascular.github.io/docsROMSimulation.html#1d-solver-input-file, not exactly sure how though.

[CZHU20]

@ktbolt Thanks for the feedback! I will revise the documentation based on your comments 1, 3, 4 and 5.

Regarding 2, all of those broken links direct readers to newly created webpages (docssvFSI-CEP.html, docssvFSI-FSI.html etc.). BTW, the main features section is on webpage docssvFSI.html.

By Note that these links should be tags within the current page, do you mean I cannot reference another webpage from the current page? My understanding of web-design with Ruby is extremely rudimentary.

Here is my unsuccessful workflow.

1. In source branch, ran bundle exec middleman build. This successfully generated all the html files, including those created by me.
2. Copied those html files and pasted them to the main branch.
3. Ran bundle exec middleman server to check the website on web browser. Unfortunately, links are broken.

The table is implemented here: https://github.com/CZHU20/simvascular.github.io/edit/source/source/documentation/svfsi/main/_feature.md

The hyperlink is achieved through the following code.

<a href="http://simvascular.github.io/docssvFSI-Fluid.html" target="_blank" rel="noopener noreferrer">Webpage</a>

Note that docssvFSI-Fluid.html is a newly created webpage. Maybe the issue is http://simvascular.github.io/docssvFSI-Fluid.html does not exist yet?

[CZHU20]

All comments except 2 are addressed here.

[ktbolt]

@CZHU20 Looks good!

[CZHU20]

@ktbolt Great! I have submitted a pull request. Let me know if there is any issue. Thank you.

[vvedula22]

@CZHU20 It looks good but the links to the newly created webpages (fluids, structure, FSI) didn't work for me. Another minor comment is that the figures look very large on my computer compared to the text. Also, in the main equations, do you want to add other equations as well (diffusion, linear elasticity, stokes, etc.)?

[CZHU20]

@vvedula22 Thanks for the feedback.

I think the link issue is that there is no corresponding html in the main branch of SimVascular/simvascular.github.io at the moment, since the link points to http://simvascular.github.io/docssvFSI-Fluid.html etc. Once everything is in place, it should work. @ktbolt Can you please confirm?

The image size has been adjusted.

In term of equations, I think it's best to focus on the main features at the moment, as those are the focus of the JOSS paper.

[ktbolt]

@CZHU20 I'm not sure about the html links, this should work with the source branch but it doesn't. Like I mentioned before, these sections should be contained in the svFSI document using tagged headers. As it is now the user cannot scroll within the svFSI document to find these sections.

[CZHU20]

Hi @ktbolt , Thanks. I have also submitted a pull request for the main branch.

Regarding the html links, the linked file/section may not be required to be in the svFSI document. I searched the existing documentation and found a working example where the link directs to another html page and no header information is provided in the link: https://github.com/SimVascular/simvascular.github.io/blob/ee76b7310596d1f80326c08c6ffc8782dcdf6b3a/source/documentation/quickguide/tutorial/_create_solid_model.md?plain=1#L32

[ktbolt]

@CZHU20 I've merge the master branch and now see the html links.

I fell that some of the sections are too focused on applications (e.g. fsi for cardiovascular mechanics) but that is OK for now, definitely and improvement over the old documentation!

[CZHU20]

@ktbolt Thanks for the help!

One more thing, I just submitted a new pull request. Currently some figures cannot be displayed.

There are definitely still room for improvement. Now that the overall framework is in place, group members can contribute to different sections at the same time.

Lastly, since structure and electrophysiology modeling sections have been moved to new pages, we may need to revise the SimCardio page to remove the redundant information. I have opened a new issue #115. Please let me know what you think.

Thanks again.

[ktbolt]

@CZHU20 I think this is good for now, thank you for all of your work!

After the C++ svFSI conversion is done I will spend some time improving the documentation, will allow me to better understand functionality.

[CZHU20]

@ktbolt @vvedula22 Thank you so much for the help. I will close this issue for now.