Encoding Modules

Summary

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

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

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(...)

"Encoding module that allowing to directly define the k-space sampling events

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 (str) – (str) defining the module name-scope

• k_space_segments (int) – Number of segments in k-space. Total number of samples divided by the number of segments must be an integer value

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

• orientation_matrix (ndarray) –

Methods:

__call__(m_transverse, r_vectors)	Fourier transforms the handed batch of object points / isochromates,
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.
call_single_segment(...[, segment_index])	Calculates fourier phases for given object-representation at r-vectors.
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__(m_transverse: Tensor, r_vectors: Tensor)

Fourier transforms the handed batch of object points / isochromates,

Parameters:

• m_transverse (Tensor) –

• r_vectors (Tensor) –

Returns:

tf.Tensor of shape (#repetitions, #k-space-samples)

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

call_single_segment(transverse_magnetization: Tensor, r_vectors: Tensor, segment_index: int | Tensor = 0, **kwargs) → Tensor

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

Return type:

Tensor

Returns:

tf.Tensor (…, k-space-points in segment)

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 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.

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) –

• bandwidth_per_pixel (float) –

• blip_duration (float | None) –

• acquisition_start (float | None) –

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, k_space_vectors, sampling_times, absolute_noise_std, k_space_segments=None, device=None)

“Encoding module that allowing to directly define the k-space sampling events

Parameters:

• name (str) – Name of the module

• k_space_vectors (Iterable[ndarray]) – List or single instance of a numpy array containing the all sampled k-space vectors, each with shape (N_i, 3)

• sampling_times (Iterable[ndarray]) – List or single instance of numpy array containing corresponding sampling times, each with shape (N_i, ).

• absolute_noise_std (Union[float, Iterable[float]]) – Noise standard deviation

• k_space_segments (int) – If not specified, the number of sequences is used.

• device (str) – Name of device that the operation is placed on

Methods:

from_cmrseq(name, sequence, absolute_noise_std)

Creates an analytic encoding module from a list of CMRseq sequence objects

classmethod from_cmrseq(name, sequence, absolute_noise_std, k_space_segments=None, device=None)

Creates an analytic encoding module from a list of CMRseq sequence objects

Parameters:

• name (str) – Name of the module

• sequence (Union[cmrseq.Sequence, Iterable[cmrseq.Sequence]]) – List or single instance of cmrseq.Sequence that implements the calculate_kspace() function

• absolute_noise_std (Union[float, Iterable[float]]) – Noise standard deviation

• k_space_segments (int) – If not specified, the number of sequences is used.

• device (str) – Name of device that the operation is placed on

Returns: