Configuration

Architecture

AortaCFD uses a three-layer configuration system that merges settings from three sources in order of increasing priority:

Base defaults -- Built-in OpenFOAM 12 settings covering all solver parameters
Numerics profile -- Pre-calibrated discretisation scheme and solver tolerance sets (robust, standard, or precise)
Case configuration -- The user's config.json file, which overrides any base or profile setting

This architecture minimises the number of parameters that must be specified in a typical case while preserving full control over every OpenFOAM dictionary entry. The fully resolved configuration is written to reports/merged_config.json in each run directory for reproducibility.

Minimal Configuration

The smallest working configuration requires only the essential case parameters. All other settings are filled from base defaults and the selected profile:

{
  "case_info": {
    "patient_id": "MY_CASE"
  },
  "physics": {
    "model": "laminar",
    "transport_properties": {
      "rho": 1060,
      "nu": 3.7736e-6
    }
  },
  "numerics": {
    "profile": "standard"
  },
  "mesh": {
    "cells_per_diameter": 15
  },
  "geometry": {
    "inlet_keywords_ordered": "inlet",
    "outlet_keywords_ordered": ["outlet1", "outlet2"],
    "wall_keywords_ordered": "wall_aorta",
    "scale_factor": 0.001
  },
  "boundary_conditions": {
    "inlet": {
      "type": "CONSTANT",
      "cardiac_output": 5.0,
      "profile": "parabolic"
    },
    "outlets": {
      "type": "3EWINDKESSEL",
      "windkessel_settings": {
        "systolic_pressure": 120,
        "diastolic_pressure": 80
      }
    },
    "walls": {
      "type": "no_slip"
    }
  },
  "simulation_control": {
    "end_time": 1.0,
    "writeInterval": 0.1
  },
  "run_settings": {
    "solution_type": "parallel",
    "subdomains": 8
  }
}

Example configurations are provided in the examples/ directory:

config_minimal.json -- Smallest working config (above)
config_standard.json -- Pulsatile Windkessel workflow with hemodynamics
config_full.json -- Complete parameter reference with documentation

Configuration Sections

case_info

Parameter	Type	Description
`patient_id`	string	Case identifier
`description`	string	Optional case description

physics

Parameter	Type	Default	Description
`model`	string	`"laminar"`	Physics model: `laminar`, `rans`, or `les`
`transport_properties.rho`	float	1060	Blood density (kg/m\(^3\))
`transport_properties.nu`	float	3.7736e-6	Kinematic viscosity (m\(^2\)/s)

numerics

Parameter	Type	Default	Description
`profile`	string	`"standard"`	Numerics profile: `robust`, `standard`, or `precise`

mesh

Parameter	Type	Default	Description
`cells_per_diameter`	int	15	Cells across reference vessel diameter
`boundary_layers.enabled`	bool	true	Enable prismatic boundary layers
`boundary_layers.num_layers`	int	5	Number of prismatic layers
`boundary_layers.expansion_ratio`	float	1.2	Layer growth ratio
`boundary_layers.final_layer_thickness`	float	0.3	Final layer as fraction of surface cell
`SNAPPY_SETTINGS.parallel`	bool	true	Parallel mesh generation
`SNAPPY_SETTINGS.nProcessors`	int	8	Number of meshing processors

geometry

Parameter	Type	Description
`inlet_keywords_ordered`	string or list	STL filename stem(s) for inlet patches
`outlet_keywords_ordered`	list	STL filename stems for outlet patches
`wall_keywords_ordered`	string or list	STL filename stem(s) for wall patches
`scale_factor`	float	Unit conversion factor (typically 0.001 for mm to m)

boundary_conditions

See Boundary Conditions for detailed documentation.

Inlet types:

Type	Description	Required Fields
`CONSTANT`	Steady flow	`cardiac_output` (L/min), `flowrate` (m\(^3\)/s), or `velocity` (m/s)
`TIMEVARYING`	Pulsatile from CSV	`csv_file`, `data_type` (`flowrate` or `velocity`)
`WOMERSLEY`	Analytical pulsatile	Derived from flow waveform
`MRI`	Patient-specific 4D flow	Pre-processed OpenFOAM boundary data

Velocity profiles: plug, parabolic, womersley, wall_distance

Outlet types:

Type	Description
`3EWINDKESSEL`	3-element Windkessel with Murray's law auto-distribution
`ZEROGRADIENT`	Simple zero-gradient outlets for testing

hemodynamics

Parameter	Type	Default	Description
`runtime_functions.wallShearStress`	bool	false	Enable WSS computation
`runtime_functions.fieldAverage`	bool	false	Enable field averaging
`runtime_functions.pressureMonitoring`	bool	false	Enable pressure monitoring
`tawss_settings.skip_cycles`	int	2	Cardiac cycles to skip before averaging
`tawss_settings.periodicRestart`	bool	true	Restart averaging each cycle

simulation_control

Parameter	Type	Default	Description
`end_time`	float	1.0	Simulation end time (s)
`number_of_cycles`	int	--	Alternative: specify number of cardiac cycles
`writeInterval`	float	0.1	Solution write interval (s)

run_settings

Parameter	Type	Default	Description
`solution_type`	string	`"parallel"`	`serial` or `parallel`
`subdomains`	int	8	Number of parallel subdomains
`decomposition_method`	string	`"scotch"`	Domain decomposition method

Numerics Profiles

Three pre-calibrated profiles control the discretisation scheme selection, solver tolerances, and relaxation factors. These are defined in src/config/profiles/numerics/.

robust -- Maximum Stability

Setting	Value
Time integration	Euler (1st order implicit)
Convection	Gauss upwind (1st order, bounded, monotone)
Gradients	Gauss linear
Laplacian	Gauss linear corrected
Relaxation	U=0.7, p=0.3, pFinal=1.0, UFinal=1.0
Residual tolerance	1e-3
nOuterCorrectors	25

Use for: Initial geometry testing, poor mesh quality, divergence debugging, coarse meshes.

standard -- Production (Recommended Default)

Setting	Value
Time integration	backward (2nd order implicit)
Convection	Gauss limitedLinearV 1 (2nd order TVD bounded) Jasak 1996
Gradients	cellLimited Gauss linear 0.5
Laplacian	Gauss linear limited corrected 0.5
Relaxation	U=0.7, p=0.3, pFinal=1.0, UFinal=1.0
Residual tolerance	1e-6
nOuterCorrectors	50 (convergence-based exit)

Use for: All production simulations. The TVD-bounded limitedLinearV scheme prevents oscillations at outlet boundaries while maintaining second-order accuracy in smooth flow regions Jasak 1996; OpenFOAM 2024.

precise -- Minimal Numerical Diffusion

Setting	Value
Time integration	CrankNicolson 0.9 (2nd order, nearly centred)
Convection	LUST (Linear-Upwind Stabilised Transport)
Gradients	Gauss linear
Laplacian	Gauss linear limited corrected 0.777
Relaxation	U=0.7, p=0.3, pFinal=1.0, UFinal=1.0
Residual tolerance	1e-6
nOuterCorrectors	50

Use for: LES simulations, validation studies, mesh convergence analysis. Requires excellent mesh quality (orthogonality > 70 deg, skewness < 2).

Mesh Quality Requirement

The precise profile requires excellent mesh quality. Run checkMesh and resolve all warnings before using this profile. If the mesh does not meet the requirements, use standard instead.

Physics Model Selection

Model	Reynolds Number	Mesh Requirements	Guidance
`laminar`	Re < 4000	Standard quality	Recommended default for most aortic cases Steinman 2002; Taylor & Figueroa 2009
`rans`	Re > 5000	Non-ortho < 65 deg, skewness < 4	Severe stenosis, mechanical valves, high cardiac output
`les`	Any (time-resolved)	Non-ortho < 55 deg, skewness < 2, y+ < 1, CFL < 0.5	Jet breakdown, vortex dynamics

Aortic Reynolds numbers are typically 500--4000, falling in the transitional regime. Published aortic CFD increasingly employs laminar simulations for this range Steinman 2002; Taylor & Figueroa 2009. AortaCFD issues automatic warnings when RANS or LES is selected but conditions are unfavourable (low Re, poor mesh quality).

Mesh Resolution

The cells_per_diameter parameter is the primary control for mesh resolution:

Category	cells/D	Typical Cell Count	Use Case
Coarse	10--12	200k--500k	Geometry checks, initial exploration
Standard	15--20	500k--2M	Production simulations
Fine	25--30	2M--5M	Mesh independence studies

Cell counts vary with geometry volume and anatomical complexity. The same cells_per_diameter value produces different cell counts for different patient anatomies.

References

Full bibliography on the References page.

Found an issue or have a suggestion for this page?

Open a GitHub issue