Encoding Modules

Summary

cmrsim.analytic.encoding.BaseSampling(...[, ...])

Base Module for implementing a time-dependent sampling in k-space.

cmrsim.analytic.encoding.InternalAccumulator(...)

Wraps a BaseSampling object to enable internal k-space accumulation

cmrsim.analytic.encoding.BlochOperatorInput(...)

Wraps a BaseSampling object to deal with the difference in input shape for bloch operators and solution operators

cmrsim.analytic.encoding.EPI(field_of_view, ...)

Encoding Module implementing a single shot echo planar imaging trajectory.

cmrsim.analytic.encoding.SingleLinePerShot(...)

Encoding Module that assumes the handed in signal tensor in images space to be calculated according to one process per k-space line.

cmrsim.analytic.encoding.GenericEncoding(...)

" Interface to use cmr-seq definitions of k-space samples as encoder

Modules

class BaseSampling(absolute_noise_std, name=None, k_space_segments=1, device=None, orientation_matrix=None)

Base Module for implementing a time-dependent sampling in k-space. Is meant to be inherited from when specifying standard trajectories.

Parameters:

• absolute_noise_std (Union[float, Iterable[float]]) – if < 0, add_noise() will leave signal unchanged

• name (Optional[str]) – (str) defining the module name-scope

• k_space_segments (int) – int

• device (Optional[str]) – str e.g. ‘GPU:0’

• orientation_matrix (ndarray) –

Methods:

__call__(transverse_magnetization, r_vectors)	Calculates fourier phases for given object-representation at r-vectors.
add_noise(s_of_k, **kwargs)	Adds noise to k-space-samples, expands the number of axis by one and appends the different noise instantiations as second last axis.
get_sampling_times()	Getter for sampling times.
set_orientation_matrix(slice_position, ...)	type slice_position: Quantity
update()	Assigns values to trajectory vectors.

Attributes:

acq_position	Spatial acquisition offset (corresponds to frequency offset)
device	Name of the device that the module is executed on (defaults to: GPU:0 - CPU:0)
k_space_segments	Number of segments used to subdivide the simulation memory load
number_of_samples	Number of k-space samples that are defined by the _calculate trajectory method
ori_matrix	Orientation matrix (3, 4) performing the transformation from slice to global coordinates

__call__(transverse_magnetization, r_vectors, segment_index=0, **kwargs)

Calculates fourier phases for given object-representation at r-vectors. For multiple different contrasts #repetitions is the representing axis.

Motion during encoding is captured in the r_vectors input axis #k-space-samples. If this axis has size=1, this position is reused for all sampling ADC events. If #repetitions = 1 in r_vectors, the same trajectory/constant position is reused for all contrasts.

Parameters:

• transverse_magnetization (Tensor) – (#voxel, #repetitions, #k-space-samples) of type tf.complex; #repetitions, #k-space-samples can be 1

• r_vectors (Tensor) – (#voxel, #repetitions, #k-space-samples, 3), axis #repetitions and #k-space-samples can be 1 to broadcast for coordinate reuse.

• segment_index (Union[int, Tensor]) – int

• kwargs –

  • noise_seed: if not None, sets seed for sampling the noise vector.

Returns:

tf.Tensor

add_noise(s_of_k, **kwargs)

Adds noise to k-space-samples, expands the number of axis by one and appends the different noise instantiations as second last axis.

Parameters:

s_of_k (Tensor) – Tensor containing all encoded k-space samples

Returns:

tf.Tensor

get_sampling_times()

Getter for sampling times. Defines format that should be used for all Signal modules that need the timing of the sampling events.

Returns:

• tf.RaggedTensor or numpy.ndarray

• sampling times as numpy.ndarray in case the trajectory is not segmented.

set_orientation_matrix(slice_position, slice_normal, readout_direction)

Parameters:

• slice_position (Quantity) – (3, )

• slice_normal (ndarray) –

• readout_direction (ndarray) –

update()

Assigns values to trajectory vectors. Should be used after modifying the parameters of the encoding module. :return:

acq_position: Variable = <tf.Variable 'Variable:0' shape=(3,) dtype=float32, numpy=array([0., 0., 0.], dtype=float32)>

Spatial acquisition offset (corresponds to frequency offset)

device: str

Name of the device that the module is executed on (defaults to: GPU:0 - CPU:0)

k_space_segments: Variable

Number of segments used to subdivide the simulation memory load

number_of_samples: Tensor

Number of k-space samples that are defined by the _calculate trajectory method

ori_matrix: Variable

Orientation matrix (3, 4) performing the transformation from slice to global coordinates

class InternalAccumulator(encoding_module, n_repetitions)

Wraps a BaseSampling object to enable internal k-space accumulation

Methods:

__call__(transverse_magnetization, r_vectors)	Call self as a function.
get_kspace()	Returns k-space data in shape (1, -1, #samples)
reset()	Sets all k-space-line accumulators to zero

Attributes:

wrapped_module

Encoding module that is wrapped

Parameters:

• encoding_module (BaseSampling) –

• n_repetitions (int) –

__call__(transverse_magnetization, r_vectors, segment_index=0, **kwargs)

Call self as a function.

Parameters:

• transverse_magnetization (Tensor) –

• r_vectors (Tensor) –

• segment_index (int | Tensor) –

get_kspace()

Returns k-space data in shape (1, -1, #samples)

reset()

Sets all k-space-line accumulators to zero

wrapped_module: BaseSampling

Encoding module that is wrapped

class BlochOperatorInput(encoding_module)

Wraps a BaseSampling object to deal with the difference in input shape for bloch operators and solution operators

Methods:

__call__(magnetization, trajectories[, ...])

type magnetization: Tensor

Parameters:

encoding_module (BaseSampling | InternalAccumulator) –

__call__(magnetization, trajectories, segment_index=0, **kwargs)

Parameters:

• magnetization (Tensor) – (#batch, 3)

• trajectories (Tensor) – (#batch, #k-space-points, 3)

• segment_index (int | Tensor) –

class EPI(field_of_view, sampling_matrix_size, absolute_noise_std, read_out_duration=None, bandwidth_per_pixel=None, blip_duration=0.0, acquisition_start=0.0, **kwargs)

Encoding Module implementing a single shot echo planar imaging trajectory. The subdivision into segments is solely used to manage memory limitation during simulation.

class SingleLinePerShot(field_of_view, sampling_matrix_size, absolute_noise_std, read_out_duration=None, repetition_time=0.0, acquisition_start=0.0, orientation=<tf.Tensor: shape=(3, 3), dtype=float32, numpy= array([[1., 0., 0.],        [0., 1., 0.],        [0., 0., 1.]], dtype=float32)>, **kwargs)

Encoding Module that assumes the handed in signal tensor in images space to be calculated according to one process per k-space line. Number of segments in this implementation corresponds to number of acquired k-space lines

Parameters:

• field_of_view (Tuple[float, float] | List[float]) –

• sampling_matrix_size (Tuple[int, int] | List[int] | numpy.ndarray) –

• absolute_noise_std (Variable) –

• read_out_duration (float) –

• repetition_time (float) –

• acquisition_start (float | None) –

• orientation (Tensor) –

class GenericEncoding(name, sequence, absolute_noise_std, device=None)

“ Interface to use cmr-seq definitions of k-space samples as encoder

Parameters:

• name (str) –

• sequence (Sequence | Iterable[Sequence]) –

• absolute_noise_std (Variable) –

• device (str) –