svVascularize

svv.simulation.Simulation

Simulation Class v1.0.0

The Simulation class provides a comprehensive framework for generating physics simulation files from synthetic vascular networks. It handles mesh generation, boundary condition specification, and export of simulation-ready files for various solvers.

Quick Example

from svv.simulation.simulation import Simulation
# Assumes `tree` is an existing svv.tree.Tree built as in the Quickstart

# Create simulation from tree
sim = Simulation(tree, name="coronary_sim", directory="./simulations")

# Build meshes with boundary layers
sim.build_meshes(
    fluid=True,
    tissue=True,
    boundary_layer=True,
    layer_thickness_ratio=0.25,
    hausd=0.0001
)

# Extract faces for boundary conditions
sim.extract_faces(crease_angle=60.0)

# Construct 3D fluid simulation
sim.construct_3d_fluid_simulation()

# Write simulation files
sim.write_3d_fluid_simulation()

# Also prepare 1D simulation
sim.construct_1d_fluid_simulation(
    viscosity=0.004,
    density=1060,
    time_step_size=0.001,
    number_time_steps=1000
)

Constructor

Simulation(synthetic_object, name=None, directory=None)

Parameters

Parameter Type Default Description
synthetic_object Tree or Forest required Vascular network to simulate
name str auto-generated Simulation name (uses UUID if not provided)
directory str current directory Output directory for simulation files

Attributes

Core Attributes

Attribute Type Description
synthetic_object Tree/Forest The vascular structure being simulated
file_path str Full path to simulation directory

Mesh Storage

Attribute Type Description
fluid_domain_surface_meshes list Surface meshes for fluid domains
fluid_domain_volume_meshes list Tetrahedral meshes for fluid domains
tissue_domain_surface_meshes list Surface meshes for tissue domains
tissue_domain_volume_meshes list Tetrahedral meshes for tissue domains
fluid_domain_boundary_layers list Boundary layer meshes
fluid_domain_wall_layers list Wall layer meshes for FSI

Simulation Objects

Attribute Type Description
fluid_3d_simulations list 3D CFD simulation configurations
fluid_1d_simulations list 1D ROM simulation configurations
fluid_0d_simulations list 0D lumped parameter models
tissue_simulations list Tissue perfusion simulations

Mesh Generation Methods

build_meshes(fluid=True, tissue=False, hausd=0.0001, hsize=None, minratio=1.1, mindihedral=10.0, order=1, remesh_vol=False, boundary_layer=True, layer_thickness_ratio=0.25, layer_thickness_ratio_adjustment=0.5, boundary_layer_attempts=5, wall_layers=False, wall_thickness=None, upper_num_triangles=1000, lower_num_triangles=100)

Build tetrahedral meshes for fluid and/or tissue domains with optional boundary layers.

Key Parameters

  • fluid (bool): Generate fluid domain mesh
  • tissue (bool): Generate tissue domain mesh
  • hausd (float): Hausdorff distance for remeshing
  • minratio (float): Minimum radius-edge ratio for tetrahedra
  • mindihedral (float): Minimum dihedral angle
  • boundary_layer (bool): Add boundary layers for CFD
  • layer_thickness_ratio (float): Boundary layer thickness relative to mesh size
  • wall_layers (bool): Add wall layers for FSI

Notes

Uses TetGen for tetrahedralization and MMG for remeshing. Boundary layers are critical for accurate wall shear stress calculation in CFD simulations.

extract_faces(crease_angle=60.0, verbose=False)

Extract and classify mesh faces as walls, caps, or interfaces.

Parameters

  • crease_angle (float): Angle threshold for face classification
  • verbose (bool): Print extraction progress

Notes

Automatically identifies inlet/outlet caps and wall surfaces based on geometry.

3D Simulation Methods

construct_3d_fluid_simulation(*args)

Construct a 3D CFD simulation configuration.

Usage

  • sim.construct_3d_fluid_simulation() for single-tree cases
  • sim.construct_3d_fluid_simulation(network_id) for a specific network
  • sim.construct_3d_fluid_simulation(network_id, tree_id) for a specific tree

Creates

XML configuration file compatible with the svFSI solver, including mesh definitions, boundary conditions, and solver parameters.

write_3d_fluid_simulation(*args)

Write 3D simulation files to disk.

Usage

  • sim.write_3d_fluid_simulation() for single-tree cases
  • sim.write_3d_fluid_simulation(network_id) for a specific network
  • sim.write_3d_fluid_simulation(network_id, tree_id) for a specific tree

Output Structure

simulation_name/
├── mesh/
│   ├── fluid_msh_0/
│   │   ├── fluid_msh_0.vtu
│   │   └── mesh-surfaces/
│   │       ├── wall_0.vtp
│   │       ├── cap_0.vtp
│   │       └── cap_1.vtp
│   └── ...
└── fluid_simulation_0-0.xml

1D Simulation Methods

construct_1d_fluid_simulation(*args, viscosity=None, density=None, time_step_size=0.01, number_time_steps=100, olufsen_material_exponent=2)

Construct a 1D reduced-order model simulation.

Usage

  • sim.construct_1d_fluid_simulation() for a single tree
  • sim.construct_1d_fluid_simulation(network_id, tree_id) for forests

Parameters

  • viscosity (float): Dynamic viscosity (Pa·s)
  • density (float): Blood density (kg/m³)
  • time_step_size (float): Time step (s)
  • number_time_steps (int): Total time steps
  • olufsen_material_exponent (float): Material model parameter

Notes

Uses centerlines from the vascular tree to generate 1D network model.

0D Simulation Methods

construct_0d_fluid_simulation(*args)

Construct a 0D lumped parameter model. (To be implemented)

pulsatile_waveform(*args)

Generate pulsatile flow waveforms for inlet boundary conditions. (To be implemented)

Examples

Complete 3D CFD Simulation Setup

from svv.simulation.simulation import Simulation
from svv.tree.tree import Tree
from svv.domain.domain import Domain
import pyvista as pv

# Generate vascular tree
mesh = pv.read('coronary_region.stl')
domain = Domain(mesh)
domain.create()
domain.solve()
domain.build()

tree = Tree()
tree.set_domain(domain)
tree.set_root([0, 0, 0])
tree.n_add(50)

# Create simulation
sim = Simulation(tree, name="coronary_cfd", directory="./cfd_sims")

# Build high-quality mesh with boundary layers
sim.build_meshes(
    fluid=True,
    tissue=False,
    boundary_layer=True,
    layer_thickness_ratio=0.2,  # 20% of mesh size
    boundary_layer_attempts=5,   # Retry if failed
    minratio=1.2,                # Good quality tetrahedra
    mindihedral=15.0,            # Avoid slivers
    remesh_vol=True              # Optimize volume mesh
)

# Extract and classify faces
sim.extract_faces(crease_angle=60.0)

# Setup simulation
sim.construct_3d_fluid_simulation()

# Write files
sim.write_3d_fluid_simulation()

print(f"Simulation files written to: {sim.file_path}")
print(f"Fluid mesh cells: {sim.fluid_domain_volume_meshes[0].n_cells}")
print(f"Boundary layer cells: {sim.fluid_domain_boundary_layers[0].n_cells if sim.fluid_domain_boundary_layers[0] else 0}")

Multi-Scale Simulation (3D + 1D)

# Generate both 3D and 1D models from same tree
sim = Simulation(tree, name="multiscale")

# 3D for proximal vessels
sim.build_meshes(fluid=True)
sim.extract_faces()
sim.construct_3d_fluid_simulation()

# 1D for distal vessels
sim.construct_1d_fluid_simulation(
    viscosity=0.004,      # Pa·s
    density=1060,         # kg/m³
    time_step_size=0.001, # 1ms
    number_time_steps=1000,
    olufsen_material_exponent=2.0
)

# Write both simulations
sim.write_3d_fluid_simulation()
# Note: writing 1-D files is not yet automated.
# Use the returned centerlines/mesh/params to invoke the SimVascular 1-D tools.

# Access centerlines for coupling
centerlines = sim.fluid_1d_simulations[0][0]
print(f"1D model segments: {centerlines.n_cells}")

Typical Workflow

Standard Pipeline:

  1. Create Simulation object from Tree/Forest
  2. Build meshes with desired refinement and layers
  3. Extract faces for boundary condition application
  4. Construct simulation configuration
  5. Write files to disk
  6. Run external solver (svFSI, SimVascular, etc.)

Mesh Quality: Poor quality tetrahedra (low minratio or mindihedral) can cause solver convergence issues. Always check mesh quality metrics before running simulations.

Boundary Layers: Essential for accurate wall shear stress calculation. The first layer thickness should be sized to achieve y+ ≈ 1 for wall-resolved simulations.

File Formats

  • VTU: Unstructured grid volume meshes
  • VTP: PolyData surface meshes
  • XML: svFSI solver configuration
  • JSON: 1D solver parameters

See Also