Skip to content

Adding first example to svMultiPhysics User Guide #111

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
justran-csuf wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Adding first example to svMultiPhysics User Guide #111

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
dc691b7
Adding first example to svMultiPhysics User Guide
justran-csuf Aug 31, 2026
e9ffa22
Adding second example on unsteady simulations, and moving files to pr…
justran-csuf Sep 9, 2026
0a17f7e
Adding CFD User Guide content to multi_physics.html
justran-csuf Sep 10, 2026
764fed6
Merge branch 'main' into 100-creating-cfd-user-guide
justran-csuf Sep 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 88 additions & 2 deletions documentation/multi_physics.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -251,9 +251,36 @@ <h4 class="skipTo sv-multiphysics-tool"> SimVascular MultiPhysics Tool </h4>
</div>


<!-- ==================== User Guide ====================
<!-- ==================== User Guide ==================== -->
<div>
<h4 class="skipTo user-guide"> User Guide </h4>
<div>
<h4 class="skipTo cfd_ug_introduction">Introduction</h4>
</div>
<div>
<h4 class="skipTo cfd_ug_example_1_intro">Example 1: Steady Rigid Simulation</h4>
<div>
<p class="skipTo cfd_ug_meshing">Loading Mesh and Geometry into svMultiPhysics</p>
<p class="skipTo cfd_ug_equations">Defining Equations and Fluid Properties</p>
<p class="skipTo cfd_ug_boundary_conditions">Assigning Boundary Conditions</p>
<p class="skipTo cfd_ug_output_quantities">Specifying Output Quantities</p>
<p class="skipTo cfd_ug_time_marching">Time Marching Parameters</p>
<p class="skipTo cfd_ug_output_quantities">Specifying Output Quantities</p>
<p class="skipTo cfd_ug_linear_solver">Linear Solver Parameters</p>
<p class="skipTo cfd_ug_file_management_and_miscellaneous">Output Control and File Management</p>
<p class="skipTo cfd_ug_running_svmp">Running svMultiPhysics from Terminal</p>
<p class="skipTo cfd_ug_runtime">Checking Simulation during Runtime</p>
<p class="skipTo cfd_ug_sim_outputs">Checking Simulation Outputs</p>
</div>
<h4 class="skipTo cfd_ug_example_2_intro">Example 2: Unsteady Rigid Simulation with RCR Outlets</h4>
<div>
<p class="skipTo cfd_ug_example_2_unsteady_inflow">Unsteady Inflow Boundary Conditions</p>
<p class="skipTo cfd_ug_example_2_rcr_outlets">RCR Outlet Boundary Conditions</p>
<p class="skipTo cfd_ug_example_2_other">Other Parameters</p>
<p class="skipTo cfd_ug_example_2_run_in_parallel">Running svMultiPhysics in Parallel</p>
<p class="skipTo cfd_ug_example_2_sim_outputs">Simulation Outputs</p>
</div>
</div>
<div>
<p class="skipTo user_guide_cardiac_electrophysiology"> Cardiac electrophysiology </p>
<p class="skipTo user_guide_computational_hemodynamics"> Computational Hemodynamics </p>
Expand All @@ -266,7 +293,9 @@ <h4 class="skipTo user-guide"> User Guide </h4>
<p class="skipTo user_guide_nonlinear_solid_dynamics"> Nonlinear Solid Dynamics </p>
</div>
</div>
-->




<!-- ==================== Developer Guide ==================== -->
<div>
Expand Down Expand Up @@ -470,6 +499,63 @@ <h4 class="skipTo appendix"> Appendix </h4>
<zero-md src="multi_physics/user-guide/readme.md" no-shadow></zero-md>
</span>

<!-- ==================== Computational Fluid Dynamics User Guide ==================== -->

<span id="cfd_ug_introduction">
<zero-md id="math" src="multi_physics/user-guide/cfd/introduction/readme.md" no-shadow></zero-md>
</span>
<span id="cfd_ug_example_1_intro">
<zero-md src="multi_physics/user-guide/cfd/example_1_steady_rigid_simulation/intro/readme.md" no-shadow></zero-md>
</span>
<span id="cfd_ug_meshing">
<zero-md src="multi_physics/user-guide/cfd/example_1_steady_rigid_simulation/mesh/readme.md" no-shadow></zero-md>
</span>
<span id="cfd_ug_equations">
<zero-md src="multi_physics/user-guide/cfd/example_1_steady_rigid_simulation/equations/readme.md" no-shadow></zero-md>
</span>
<span id="cfd_ug_boundary_conditions">
<zero-md src="multi_physics/user-guide/cfd/example_1_steady_rigid_simulation/boundary_conditions/readme.md" no-shadow></zero-md>
</span>
<span id="cfd_ug_output_quantities">
<zero-md src="multi_physics/user-guide/cfd/example_1_steady_rigid_simulation/outputs/readme.md" no-shadow></zero-md>
</span>
<span id="cfd_ug_time_marching">
<zero-md src="multi_physics/user-guide/cfd/example_1_steady_rigid_simulation/time_marching/readme.md" no-shadow></zero-md>
</span>
<span id="cfd_ug_linear_solver">
<zero-md src="multi_physics/user-guide/cfd/example_1_steady_rigid_simulation/linear_solver/readme.md" no-shadow></zero-md>
</span>
<span id="cfd_ug_file_management_and_miscellaneous">
<zero-md src="multi_physics/user-guide/cfd/example_1_steady_rigid_simulation/file_management_and_miscellaneous/readme.md" no-shadow></zero-md>
</span>
<span id="cfd_ug_running_svmp">
<zero-md src="multi_physics/user-guide/cfd/example_1_steady_rigid_simulation/running_svmp/readme.md" no-shadow></zero-md>
</span>
<span id="cfd_ug_runtime">
<zero-md src="multi_physics/user-guide/cfd/example_1_steady_rigid_simulation/runtime/readme.md" no-shadow></zero-md>
</span>
<span id="cfd_ug_sim_outputs">
<zero-md src="multi_physics/user-guide/cfd/example_1_steady_rigid_simulation/sim_outputs/readme.md" no-shadow></zero-md>
</span>
<span id="cfd_ug_example_2_intro">
<zero-md src="multi_physics/user-guide/cfd/example_2_unsteady_rigid_simulation/intro/readme.md" no-shadow></zero-md>
</span>
<span id="cfd_ug_example_2_unsteady_inflow">
<zero-md src="multi_physics/user-guide/cfd/example_2_unsteady_rigid_simulation/unsteady_inflow/readme.md" no-shadow></zero-md>
</span>
<span id="cfd_ug_example_2_rcr_outlets">
<zero-md src="multi_physics/user-guide/cfd/example_2_unsteady_rigid_simulation/rcr_outlets/readme.md" no-shadow></zero-md>
</span>
<span id="cfd_ug_example_2_other">
<zero-md src="multi_physics/user-guide/cfd/example_2_unsteady_rigid_simulation/other_parameters/readme.md" no-shadow></zero-md>
</span>
<span id="cfd_ug_example_2_run_in_parallel">
<zero-md src="multi_physics/user-guide/cfd/example_2_unsteady_rigid_simulation/running_svmp_in_parallel/readme.md" no-shadow></zero-md>
</span>
<span id="cfd_ug_example_2_sim_outputs">
<zero-md src="multi_physics/user-guide/cfd/example_2_unsteady_rigid_simulation/sim_outputs/readme.md" no-shadow></zero-md>
</span>

<!-- -------------------- Cardiac electrophysiology -------------------- -->

<span id="user_guide_cardiac_electrophysiology">
Expand Down
70 changes: 70 additions & 0 deletions .../user-guide/cfd/example_1_steady_rigid_simulation/boundary_conditions/readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@

### Assigning Boundary Conditions

The next step is to establish the boundary conditions. Boundary conditions specify the solution behavior at the exterior surfaces of the model that will be used to drive the solution. Recall from the `<Add_mesh>` section that we labeled each of the exterior surfaces according to the .vtp surface mesh files. We can now use these labels to define the boundary conditions. The figure below shows the boundary conditions we wish to specify for this model:

<figure>
<img class="svImg svImgMd" src="/documentation/multi_physics/user-guide/cfd/img/svmp_ug_ex1_model_and_bc.png">
<figcaption class="svCaption" >Descending Aorta model with inflow and outflow boundary conditions labeled.</figcaption>
</figure>

Boundary conditions are specified further down in the `<Add_equation>` section of the .xml file:

<Add_equation type="fluid">

...

<Add_BC name="cap_aorta">
<Type>Dirichlet</Type>
<Time_dependence>Steady</Time_dependence>
<Value>-100</Value>
<Profile>Parabolic</Profile>
<Zero_out_perimeter>true</Zero_out_perimeter>
<Impose_flux>true</Impose_flux>
</Add_BC>

<Add_BC name="cap_aorta_2">
<Type>Neumann</Type>
<Time_dependence>Resistance</Time_dependence>
<Value>2600</Value>
<Profile>Flat</Profile>
</Add_BC>

<Add_BC name="cap_right_iliac">
<Type>Neumann</Type>
<Time_dependence>Resistance</Time_dependence>
<Value>2600</Value>
<Profile>Flat</Profile>
</Add_BC>

<Add_BC name="wall_aorta">
<Type>Dirichlet</Type>
<Time_dependence>Steady</Time_dependence>
<Value>0</Value>
<Profile>Flat</Profile>
<Zero_out_perimeter>true</Zero_out_perimeter>
</Add_BC>

<Add_BC name="wall_right_iliac">
<Type>Dirichlet</Type>
<Time_dependence>Steady</Time_dependence>
<Value>0</Value>
<Profile>Flat</Profile>
<Zero_out_perimeter>true</Zero_out_perimeter>
</Add_BC>

Notice how there is a separate `<Add_BC>` section for each of the surfaces we defined earlier. The inlet face is `cap_aorta` where we wish to specify an inlet flow rate of $100 \ mL/s$. This value of $100 \ mL/s$ is slightly higher than the typical cardiac output of a healthy individual, but we round up for simplicity. Generally, you want to choose the values of your boundary conditions to match the physiologic data of the patient you are simulating. If you do not have data on specific patients, then using population average values is a reasonable assumption.

Boundary conditions that specify velocity or flow are classified as “Dirichlet” `<Type>` boundary conditions. The flow rate at the inlet is not changing with time, so we specify its `<Time_dependence>` to “Steady”. The `<Value>` for this boundary condition is set to $-100$. We use a negative sign for the value here to specify that the flow is going into the domain. A positive flow value would have the flow exiting the domain. The `<Profile>` setting specifies the spatial profile for the velocity on the face. We set this to “Parabolic” for this case to model the Hagan-Poisuelle solution for flow of a viscous fluid in a pipe. The Hagan-Poisuelle solution has the highest fluid velocity in the center of the vessel and decreases smoothly to a value of zero at the walls. To enforce the no-slip boundary condition at the walls, we set the `<Zero_out_perimeter>` setting to “true”. Finally, to specify that this boundary condition is for the flow (and not velocity), we set the `<Impose_flux>` setting to “true”.

Next, we specify the resistance outlet boundary conditions at the two other caps of the model. Resistance outlet boundary conditions assign a pressure that is proportional to the flowrate of blood passing through the face. Resistance outlet boundary conditions are common for vascular simulations to model the vascular resistance of all smaller vessels downstream. This pressure represents the force needed to push a viscous fluid through the microvasculature:

$$ P = QR $$

Where $R$ is the vascular resistance of the vessels downstream of the outlet face. Pressure boundary conditions are considered “Neumann” `<Type>` and do not change with time. We specify a resistance outlet boundary condition by assigning “Resistance” in the `<Time_dependance>` field in the boundary condition. The value of $2600 \ dynes/cm^5$ was chosen to ensure physiologic pressure values within the model. For this example, we assume both outlet resistances are equal. Thus, we can conclude the two outlets will receive roughly equal flow of about $50 \ mL/s$. We assumed an even flow split for simplicity. Later in the User Guide, we will discuss strategies for assigning a more realistic flow split between vessels by adjusting the relative resistances of the outlets. Using the equation above, we can compute the assigned outlet pressure to be:

$$ P=(50 \ mL/s)*(2600 \ dynes/cm^5)=130000 \ dyne/cm^2 \approx 100 \ mmHg $$

$100 \ mmHg$ of pressure is roughly the average blood pressure in a healthy individual. If you have more specific physiologic data on your patient, you will want to choose your boundary condition values to match your patient data.

The last boundary conditions we need to specify are the wall conditions. This simple simulation assumes the walls are **rigid** which means they are fixed in space. For these cases, we apply the **no slip** boundary condition which states that any fluid in direct contact with the wall will have zero velocity. For both the wall surfaces, we assign them as “Dirichlet” type boundary conditions with a value of $0 \ m/s$. We wish to apply this to the velocity directly, thus the `<Impose_flux>` setting, which was present for the inlet face, is missing here.
26 changes: 26 additions & 0 deletions ...ti_physics/user-guide/cfd/example_1_steady_rigid_simulation/equations/readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@

### Defining Equations and Fluid Properties

The next step to running an *svMultiPhysics* simulation is to establish the type of equation that will be solved and to define all material properties needed. This is done in the top part of the `<Add_equation>` section of the .xml file:

<Add_equation type="fluid">

<Coupled>true</Coupled>

<Min_iterations>1</Min_iterations>

<Max_iterations>10</Max_iterations>

<Tolerance>1e-4</Tolerance>

<Backflow_stabilization_coefficient>0.3</Backflow_stabilization_coefficient>

<Density>1</Density>

<Viscosity model="Constant">
<Value>0.04</Value>
</Viscosity>

A pure fluids simulation like this example only requires a solution to the “fluid” equation, which is specified in the `<Add_equation>` XML command. The fluid equation only requires three properties to be defined: (1) fluid density, (2) fluid viscosity, and (3) backflow stabilization coefficient. The fluid density is assumed to be $1 \ g/cm^3$. Note that all numerical parameters in the .xml file are assumed to be consistent with each other, which should be consistent with the unit of measure established in the mesh. Based on the input mesh data for this example, we are using the CGS unit of measure. The fluid viscosity is defined within its own block where users are also able to select the viscosity model. For this simulation, we use a simple constant viscosity model with a value of $0.04 \ Poise$ for simplicity. Blood flow in the large arteries like this model can be safely assumed to be Newtonian with a constant viscosity. Blood is considered to be a non-Newtonian fluid, but the non-Newtonian behavior is typically only observed in the microvasculature where the diameter of the vessel becomes comparable to the size of the blood cells. The backflow stabilization coefficient is a parameter unique to the *svMultiPhysics* flow solver and should be kept at $0.3$.

The other parameters in this section specify settings for the nonlinear solution of the fluids governing equations. `<Min_iterations>` and `<Max_iterations>` specify how many nonlinear iterations you wish the solver to perform in each timestep. Specifying a larger amount of iterations can help the solver converge on a solution at the cost of additional simulation time. `<Tolerance>` defines the threshold for the solution residual needed for the solver to reach convergence. If the solver achieves a solution residual at or below the tolerance, it can move onto the next timestep before reaching the maximum nonlinear iterations. Making the tolerance a smaller number will produce more accurate simulation results at the cost of additional simulation time, and vice-versa for increasing the tolerance.
45 changes: 45 additions & 0 deletions ...d/example_1_steady_rigid_simulation/file_management_and_miscellaneous/readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,45 @@

### Output Control and File Management

The final batch of settings that need to be set for a CFD simulation have to do with file management and control. *svMultiPhysics* simulations can produce a lot of output files, so it is important to specify the type and number of output files produced. These settings are located in the `<GeneralSimulationParameters>` section at the top of the .xml file:

<GeneralSimulationParameters>

...

<Restart_file_name>results</Restart_file_name>
<Increment_in_saving_restart_files>10</Increment_in_saving_restart_files>
<Start_saving_after_time_step>1</Start_saving_after_time_step>

<Continue_previous_simulation>false</Continue_previous_simulation>

<Save_averaged_results>true</Save_averaged_results>

<Save_results_to_VTK_format>true</Save_results_to_VTK_format>

<Name_prefix_of_saved_VTK_files>results</Name_prefix_of_saved_VTK_files>

<Increment_in_saving_VTK_files>10</Increment_in_saving_VTK_files>

<Spectral_radius_of_infinite_time_step>0.2</Spectral_radius_of_infinite_time_step>

<Searched_file_name_to_trigger_stop>STOP_SIM</Searched_file_name_to_trigger_stop>

<Simulation_requires_remeshing>false</Simulation_requires_remeshing>

<Verbose>true</Verbose>

<Warning>true</Warning>

<Debug>false</Debug>

</GeneralSimulationParameters>

Because of the amount and variety of settings in this section, the most useful and important settings for a general user will be listed below:

1. `<Increment_in_saving_restart_files>` - This specifies how often you want to save simulation outputs in terms of number of timesteps. Usually, you do not want to save results too often otherwise it will take up too much space and overwhelm a file system. But you also want to have enough time resolution to adequately analyze your results. This setting is more relevant for unsteady cases since for a steady case like this, we only need the results at the final timestep.
2. `<Start_saving_after_time_step>` - Allows the simulation to skip saving results for the first few timesteps. Usually, the first few timesteps only contain initial conditions or transient results so you can skip some to save a bit of space.
3. `<Save_averaged_results>` - This flag will tell *svMultiPhysics* to save one file that contains time-averaged results. This can be convenient if you wish to perform time averaging across all timesteps in an unsteady simulation.
4. `<Save_results_to_VTK_format>` - This flag will tell *svMultiPhysics* to automatically convert simulation results to VTK format which is convenient for viewing in Paraview.

The other settings in this section can be adjusted for more niche cases, but these are the most useful to know for a general *svMultiPhysics* simulation.
9 changes: 9 additions & 0 deletions .../multi_physics/user-guide/cfd/example_1_steady_rigid_simulation/intro/readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@

## Example 1: Steady Fluids Simulation on Descending Aorta with Rigid Walls

This first example will go through the steps needed to set up a steady fluids simulation on a patient-specific geometry with rigid walls and connect these with the associated commands and settings in the svMultiPhysics .xml file. All conditions in this example are assumed to be steady, meaning that the flowrate of blood coming into the model will be constant as well as all other boundary conditions. Rigid walls mean that the vessel walls are assumed to be fixed with time and thus have zero velocity for the entire simulation. Both of these assumptions are not physiologically consistent with blood flow in a real patient. Flowrates and pressures fluctuate with time due to the pulsatility of cardiac contraction and blood vessel walls are flexible that inflate and deflate along with the oscillating pressures. But we choose to start with the simplest example possible to introduce the process and format of using *svMultiPhysics*. These assumptions will be relaxed in future examples. Even if your goal is to run a more complex simulation, running a steady rigid wall simulation is still useful to help debug other issues with the model or simulation setup. The subject for this example is the following patient-specific model of the descending aorta and iliac arteries. The figure below also includes the names of the exterior surfaces that we will use when assigning boundary conditions:

<figure>
<img class="svImg svImgMd" src="/documentation/multi_physics/user-guide/cfd/img/svmp_ug_ex1_model_and_surfaces.png">
<figcaption class="svCaption" >Descending Aorta model with mesh surfaces labeled.</figcaption>
</figure>
Loading