Pulsed repetition protocols (e.g., Zeng et al., 2022) are a major simulation scenario, but how to run heating simulations is currently not very intuitive, partly due to variable naming and their associated comments. Let's see whether we can improve that naming and documentation. First, here is how I set up a continuous burst simulation, with the aim of modeling continuous on-off cycles. In my example, I try to model 80 seconds of a 5Hz protocol with 25% duty cycle (i.e., 50 ms on, 150 ms off within a 200 ms cycle). The implementation of calculations can be found in functions/check_thermal_parameters.m.
thermal:
duty_cycle: 0.25 # share of the stimulation duration during which the stimulation is on
stim_duration: 0.2 # [s] the duration of a complete on-off cycle, not the duration of stimulation on (as determined by the duty cycle) that I would have intuitively expected
iti: 0.2 # interval between trials, from the start of one trial to the start of another [s], in the case of continuous burst stimulation, the ITI is equal to the trial duration [stim_duration above]
on_off_step_duration: 0.2 # duration of one on+off period [s] (200 ms incl. stim on + off)
n_trials: 400 # number of trials to simulate; trial number follows from the total stimulation time (e.g., 80 s) divided by the on_off_step_duration/iti/stim_duration (e.g., 0.2s)
sim_time_steps: 0.005 # [s] internal simulation time steps, basically simulation chunks that have to be chosen such that on and off periods can be simulated
post_stim_time_step_dur: 0.18 # [s] duration of “off” time-step [appears unused]
equal_steps: 0 # on- and off-cycle time steps have unequal duration: if 0, their duration will be calculated based on the specified stim duration * duty cycle
There are currently some checks that could cause problems down the line:
I do not understand what is being computed here. The current calculation of on_off_step_duration makes no sense to me, beacuse sim_time_steps - as I understand it - is merely an internal computation metric to chunk the simulation steps. If on_off_step_duration is explicitly specified, this code is not invoked, but unless there is a clear instruction on how to specify the setup only with a duty cycle, we should probably remove this option.
There are two routes to compute the number and duration of on- and off-steps, the fundamental parameters that k-Wave will use to model heating. In the case that equal_steps for on- and off-stimulation does not apply, the code actually only needs to model a single on- and a single off-step. If I understand this correctly, this should be the default setting however as any protocol not with a 50% duty cycle will have unequal steps for on- and off-stim. Perhaps I still misunderstand what the step refers to here.
This description is misleading, as the duration is NOT the equal step size (parameters.thermal.sim_time_steps) in this scenario.
REFS
Zeng, K. et al. Induction of Human Motor Cortex Plasticity by Theta Burst Transcranial Ultrasound Stimulation. Ann Neurol 91, 238–252 (2022).
Pulsed repetition protocols (e.g., Zeng et al., 2022) are a major simulation scenario, but how to run heating simulations is currently not very intuitive, partly due to variable naming and their associated comments. Let's see whether we can improve that naming and documentation. First, here is how I set up a continuous burst simulation, with the aim of modeling continuous on-off cycles. In my example, I try to model 80 seconds of a 5Hz protocol with 25% duty cycle (i.e., 50 ms on, 150 ms off within a 200 ms cycle). The implementation of calculations can be found in functions/check_thermal_parameters.m.
thermal:
The setup has to fit the following constraints:
There are currently some checks that could cause problems down the line:
on_off_step_durationmakes no sense to me, beacusesim_time_steps- as I understand it - is merely an internal computation metric to chunk the simulation steps. Ifon_off_step_durationis explicitly specified, this code is not invoked, but unless there is a clear instruction on how to specify the setup only with a duty cycle, we should probably remove this option.equal_stepsfor on- and off-stimulation does not apply, the code actually only needs to model a single on- and a single off-step. If I understand this correctly, this should be the default setting however as any protocol not with a 50% duty cycle will have unequal steps for on- and off-stim. Perhaps I still misunderstand what the step refers to here.parameters.thermal.sim_time_steps) in this scenario.REFS
Zeng, K. et al. Induction of Human Motor Cortex Plasticity by Theta Burst Transcranial Ultrasound Stimulation. Ann Neurol 91, 238–252 (2022).