|
| 1 | +### Input File Format |
| 2 | + |
| 3 | +svZeroDSolver is configured using either a JSON file or a Python dictionary. JSON is a convenient file format to represent a dictionary-like object. More details can be found [here](https://stackoverflow.blog/2022/06/02/a-beginners-guide-to-json-the-data-format-for-the-internet/). |
| 4 | + |
| 5 | +The top-level structure of both is: |
| 6 | + |
| 7 | +```python |
| 8 | +{ |
| 9 | + "simulation_parameters": {...}, |
| 10 | + "vessels": [...], |
| 11 | + "junctions": [...], |
| 12 | + "boundary_conditions": [...] |
| 13 | +} |
| 14 | +``` |
| 15 | + |
| 16 | +In the following sections, the individual categories are described in more |
| 17 | +detail. |
| 18 | + |
| 19 | +#### Simulation parameters |
| 20 | + |
| 21 | +The svZeroDSolver can be configured with the following options in the |
| 22 | +`simulation_parameters` section of the input file. Parameters without a |
| 23 | +default value must be specified. |
| 24 | + |
| 25 | +|Parameter key | Description | Default value | |
| 26 | +|-----------------------------------------------|------------------------------------------------------------ | --------------| |
| 27 | +|`number_of_cardiac_cycles`   | Number of cardiac cycles to simulate   | - | |
| 28 | +|`number_of_time_pts_per_cardiac_cycle`   | Number of time steps per cardiac cycle   | - | |
| 29 | +|`absolute_tolerance`   | Absolute tolerance for time integration   | $10^{-8}$ | |
| 30 | +|`maximum_nonlinear_iterations`   | Maximum number of nonlinear iterations for time integration   | $30$ | |
| 31 | +|`steady_initial`   | Toggle whether to use the steady solution as the initial condition for the simulation   | true | |
| 32 | +|`output_variable_based`   | Output solution based on variables (i.e. flow and pressure at nodes and internal variables)   | false | |
| 33 | +|`output_interval`   | The frequency of writing timesteps to the output (1 means every timestep is written)   | $1$ | |
| 34 | +|`output_mean_only`   | Write only the mean values over every timestep to output file   | false | |
| 35 | +|`output_derivative`   | Write time derivatives to output file   | false | |
| 36 | +|`output_all_cycles`   | Write all cardiac cycles to output file   | false | |
| 37 | +|`use_cycle_to_cycle_error`   | Use cycle-to-cycle error to determine number of cycles for convergence   | false | |
| 38 | +|`sim_cycle_to_cycle_percent_error`   | Percentage error threshold for cycle-to-cycle pressure and flow difference   | 1.0 | |
| 39 | + |
| 40 | +The option `use_cycle_to_cycle_error` allows the solver to change the number of cardiac cycles it runs depending on the cycle-to-cycle convergence of the simulation. For simulations with no RCR boundary conditions, the simulation will add extra cardiac cycles until the difference between the mean pressure and flow in consecutive cycles is below the threshold set by `sim_cycle_to_cycle_percent_error` at all inlets and outlets of the model. If there is at least one RCR boundary condition, the number of cycles is determined based on equation 21 of <a href="#0d-Pfaller2021">Pfaller et al. (2021)</a>, using the RCR boundary condition with the largest time constant. |
| 41 | + |
| 42 | + |
| 43 | +<style> |
| 44 | +table{ |
| 45 | + border-collapse: collapse; |
| 46 | + border-spacing: 100000px; |
| 47 | + border:1px solid #000000; |
| 48 | +} |
| 49 | + |
| 50 | +th{ |
| 51 | + border:0.1px dotted #000000; |
| 52 | + padding: 15px; |
| 53 | +} |
| 54 | + |
| 55 | +td{ |
| 56 | + border:0.1px dotted #000000; |
| 57 | + padding: 5px; |
| 58 | +} |
| 59 | +</style> |
| 60 | + |
| 61 | +#### Vessels |
| 62 | + |
| 63 | +More information about the vessels can be found in their respective class references. Below is a template vessel block with boundary conditions, `INFLOW` and `OUT`, at its inlet and outlet respectively. |
| 64 | + |
| 65 | +```python |
| 66 | +{ |
| 67 | + "boundary_conditions": { |
| 68 | + "inlet": "INFLOW", # Optional: Name of inlet boundary condition |
| 69 | + "outlet": "OUT", # Optional: Name of outlet boundary condition |
| 70 | + }, |
| 71 | + "vessel_id": 0, # ID of the vessel |
| 72 | + "vessel_name": "branch0_seg0", # Name of vessel |
| 73 | + "zero_d_element_type": "BloodVessel", # Type of vessel |
| 74 | + "zero_d_element_values": {...} # Values for configuration parameters |
| 75 | +} |
| 76 | +``` |
| 77 | + |
| 78 | +| Description | Class | `zero_d_element_type`   | `zero_d_element_values`   | |
| 79 | +| ---------------------------------------- | --------------------------- | --------------------- | ------------------------| |
| 80 | +| Blood vessel with optional stenosis   | BloodVessel   | `BloodVessel`   | `C`: Capacitance <br> `L`: Inductance <br> `R_poiseuille`: Poiseuille resistance <br> `stenosis_coefficient`: Stenosis coefficient   | |
| 81 | + |
| 82 | + |
| 83 | +#### Junctions |
| 84 | + |
| 85 | +More information about the junctions can be found in their respective class references. Below is a template junction block that connects vessel ID 0 with vessel IDs 1 and 2. |
| 86 | + |
| 87 | +```python |
| 88 | +{ |
| 89 | + "junction_name": "J0", # Name of the junction |
| 90 | + "junction_type": "BloodVesselJunction", # Type of the junction |
| 91 | + "inlet_vessels": [0], # List of vessel IDs connected to the inlet |
| 92 | + "outlet_vessels": [1, 2], # List of vessel IDs connected to the inlet |
| 93 | + "junction_values": {...} # Values for configuration parameters |
| 94 | +} |
| 95 | +``` |
| 96 | + |
| 97 | +Description   | Class   | `junction_type`   | `junction_values`   |
| 98 | +------------------------------------- | ---------------------| --------------------- | ----------- |
| 99 | +Purely mass conserving junction   | Junction   | `NORMAL_JUNCTION`   | -   |
| 100 | +Resistive junction   | ResistiveJunction   | `resistive_junction`   | `R`: Ordered list of resistances for all inlets and outlets   |
| 101 | +Blood vessel junction   | BloodVesselJunction   | `BloodVesselJunction`   | Same as for `BloodVessel` element but as ordered list for each inlet and outlet   |
| 102 | + |
| 103 | +#### Boundary conditions |
| 104 | + |
| 105 | +More information about the boundary conditions can be found in their respective class references. Below is a template `FLOW` boundary condition. |
| 106 | + |
| 107 | +```python |
| 108 | +{ |
| 109 | + "bc_name": "INFLOW", # Name of the boundary condition |
| 110 | + "bc_type": "FLOW", # Type of the boundary condition |
| 111 | + "bc_values": {...} # Values for configuration parameters |
| 112 | +}, |
| 113 | +``` |
| 114 | + |
| 115 | +Description   | Class   | `bc_type`   | `bc_values`   |
| 116 | +------------------------------------- | ---------------------- | --------------------- | ---------- |
| 117 | +Prescribed (transient) flow   | FlowReferenceBC   | `FLOW`   | `Q`: Time-dependent flow values <br> `t`: Time steps   |
| 118 | +Prescribed (transient) pressure   | PressureReferenceBC   | `PRESSURE`   | `P`: Time-dependent pressure values <br> `t`: Time steps   |
| 119 | +Resistance   | ResistanceBC   | `RESISTANCE`   | `R`: Resistance <br> `Pd`: Time-dependent distal pressure <br> `t`: Time stamps   |
| 120 | +Windkessel or RCR   | WindkesselBC   | `RCR`   | `Rp`: Proximal resistance <br> `C`: Capacitance <br> `Rd`: Distal resistance <br> `Pd`: Distal pressure   |
| 121 | +Coronary outlet   | OpenLoopCoronaryBC   | `CORONARY`   | `Ra`: Proximal resistance <br> `Ram`: Microvascular resistance <br> `Rv`: Venous resistance <br> `Ca`: Small artery capacitance <br> `Cim`: Intramyocardial capacitance <br> `Pim`: Intramyocardial pressure <br> `Pv`: Venous pressure   |
| 122 | + |
| 123 | +The above table describes the most commonly used boundary conditions. In addition, svZeroDSolver includes various closed-loop boundary conditions. See <a href="#0d-Menon2023">Menon et al. (2023)</a> for details of a closed-loop 0D model. Examples can also be found in `svZeroDSolver/tests/cases`. |
| 124 | + |
| 125 | +Values of the boundary condition can be specified as a function of time as follow: |
| 126 | +```python |
| 127 | +{ |
| 128 | + "bc_name": "INFLOW", # Name of the boundary condition |
| 129 | + "bc_type": "FLOW", # Type of the boundary condition |
| 130 | + "bc_values": { |
| 131 | + "Q": [ ..., ..., ... ], # Comma-separated list of values |
| 132 | + "t": [ ..., ..., ... ] # Comma-separated list of corresponding time stamps |
| 133 | + } |
| 134 | +}, |
| 135 | +``` |
| 136 | +See `svZeroDSolver/tests/cases/pulsatileFlow_R_RCR.json` for an example. |
0 commit comments