GeneralBlochOperator

class GeneralBlochOperator(name, gamma, time_grid, gradient_waveforms=None, rf_waveforms=None, adc_events=None, submodules=(), device=None)

General bloch-simulation module: accepts RF-Waveforms, Gradient-Waveforms and ADC-events as input and integrates the Bloch-equation (trapezoidal numerical integration). The specified time-grid does not need to be uniform, but must match the definition of the specified waveforms/adc definitions. The required input format matches the common format of a sequence diagram

The integration allows for moving isochromates, as well as the addition of effects defined in the submodules. For more information on how the isochromate motion is incorporated refer to the __call__ method.

Example usage

Instantiation

# time_raster.shape, grad_grid.shape, rf_grid.shape, adc_grid.grid
# >>> (n_reps, t), (n_reps, t, 2), (n_reps, t), (n_reps, t, 2)
gammarad = system_specs.gamma_rad.m_as("rad/mT/ms")
bloch_mod = cmrsim.bloch.GeneralBlochOperator(name="example",
                                               device="GPU:0,
                                               gamma=gammarad,
                                               time_grid=time_raster,
                                               gradient_waveforms=grad_grid,
                                               rf_waveforms=rf_grid,
                                               adc_events=adc_grid)

Parallel call

properties = ...  # From input definition
n_samples = tf.shape(module.gradient_waveforms)[1]
n_repetitions = tf.shape(module.gradient_waveforms)[0]
data_iterator = tf.data.Dataset.from_tensor_slices(properties)
for phantom_batch in tqdm(data_iterator.batch(int(3e5))):
    m, r = bloch_mod(trajectory_module=trajectory_module,
                     run_parallel=True, **phantom_batch)

Sequential call

properties = ...  # From input definition
n_samples = tf.shape(module.gradient_waveforms)[1]
n_repetitions = tf.shape(module.gradient_waveforms)[0]

data_iterator = tf.data.Dataset.from_tensor_slices(properties)
for phantom_batch in tqdm(data_iterator.batch(int(3e5))):
    r = phantom_batch.pop("initial_position")
    m = phantom_batch.pop("magnetization")
    for rep_idx in tqdm(range(n_repetitions)):
        m, r = module(trajectory_module=trajectory_module, initial_position=r,
                      magnetization=m, repetition_index=rep_idx, run_parallel=False,
                      **phantom_batch)

Parameters:

• name (str) – Verbose name of the module (non-functionally relevant)

• gamma (float) – gyromagnetic ratio in rad/ms/m

• time_grid (Tensor) – (n_steps) - tf.float32 - time definition for numerical integration steps

• gradient_waveforms (Tensor) – (#repetitions, #steps, 3) - tf.float32 - Definition of gradients in mT/m

• rf_waveforms (Tensor) – (#repetitions, #steps) - tf.complex64 -

• adc_events (Tensor) – (#repetition, #steps, 2) - tf.float32 - last axis contains the adc-on definitions and the adc-phase

• submodules (Tuple[BaseSubmodule, ...]) – List[tf.Modules] implementing the __call__ function returning the resulting phase increment contribution

• device (str) – str

Methods:

__call__(initial_position, magnetization, ...)	Runs bloch simulation for the specified RF/Gradients and accumulates the signal for the times specified in adc_events.
reset()	Resets the time-signal accumulators, i.e. sets all entries to 0.

Attributes:

adc_events	Sampling events definitions for each time in self.time_grid for R repetitions - shape (R, T, 2), where the two channels have the following meaning: 1.
dt_grid	Grid containing the differences of specified time_grid - shape: (T-1, )
gamma	Gyromagnetic ration in rad/ms/m specified on instantiation
gradient_waveforms	Gradient waveforms at times of self.time_grid in mT/m for R repetitions - shape: (R, T, 3)
n_repetitions	Number of repetitions derived from specified waveforms
rf_waveforms	Complex radio-frequency pulse definition at times of self.time_grid in uT for R repetitions - shape: (R, T)
time_grid	(Non-uniform) temporal raster defining the simulation steps in milliseconds - shape: (T, )
time_signal_acc	Accumulator variables for the signal acquired at specified adc-events.

__call__(initial_position, magnetization, T1, T2, M0, trajectory_module=<cmrsim.trajectory._base.StaticParticlesTrajectory object>, repetition_index=0, run_parallel=False, **kwargs)

Runs bloch simulation for the specified RF/Gradients and accumulates the signal for the times specified in adc_events. For each interval on the time grid, a trapezoidal integration of the flip angle and the gradient phase increment (including the submodules) is performed and subsequently used to rotate the magnetization vectors.

Parameters:

• initial_position (Tensor) – (#batch, 3) - tf.float32 - initial positions of particles

• magnetization (Tensor) – ([repetitions/1], #batch, 3) - tf.complex64 - [Mx+iMy, Mx-iMy, Mz] magnetization per particle. The first optional axis is only used if run_parallel==True.

• T1 (Tensor) – (#batch, ) - tf.float32 - Longitudinal relaxation time in milliseconds per particle

• T2 (Tensor) – (#batch, ) - tf.float32 - Transversal relaxtion time in milliseconds per particle

• M0 (Tensor) – (#batch, ) - tf.float32 - Equilibrium magnetization of each particle (representing a volume)

• trajectory_module (Module) – tf.function accepting the arguments [r[:, 3](tf.float32), dt[,](tf.float32)] and returning the updated position r_new[:, 3](tf.float32) as well as a dictionary of tensors denoting arbitrary look-up values for the new particle positions. Defaults to static particles

• repetition_index (Tensor) – (, ) - tf.int32 - index of the current repetition index to simulate this corresponds to indexing the first dimension of the specified waveforms. Only used if run_parallel==False

• run_parallel (bool) – bool - defaults to False. If True, the repetitions of the specified waveforms are simulated for the same particle trajectories. Otherwise only the waveforms for given repetition_index is simulated.

• kwargs – additional properties of particles, that are required for evaluating the submodules

Returns:

m, r with shapes - [#reps, #particles, 3] if repetitions are run in parallel - [#particles, 3] if run sequential

reset()

Resets the time-signal accumulators, i.e. sets all entries to 0

adc_events: Variable = None

Sampling events definitions for each time in self.time_grid for R repetitions - shape (R, T, 2), where the two channels have the following meaning: 1. ADC On/Off [1/0] at time t and 2. Demodulation phase of the ADC at time t in radians

dt_grid: Variable

Grid containing the differences of specified time_grid - shape: (T-1, )

gamma: float

Gyromagnetic ration in rad/ms/m specified on instantiation

gradient_waveforms: Variable = None

Gradient waveforms at times of self.time_grid in mT/m for R repetitions - shape: (R, T, 3)

n_repetitions: int

Number of repetitions derived from specified waveforms

rf_waveforms: Variable = None

Complex radio-frequency pulse definition at times of self.time_grid in uT for R repetitions - shape: (R, T)

time_grid: Variable = None

(Non-uniform) temporal raster defining the simulation steps in milliseconds - shape: (T, )

time_signal_acc: List[Variable] = None

Accumulator variables for the signal acquired at specified adc-events. This is empty if no ADC==On events where specified. The length of the List is equal to the number of repetitions and the shape of each tf.Variable is (sum(ADC[R]==1), ), which can result different length if the repetitions have different numbers of samples.