DiffusionTaylor

class DiffusionTaylor(order, time_grid, particle_trajectories, local_basis_over_time, diffusivity, particles_per_node, batch_size=None)

Combines gaussian diffusional motion with bulk-motion defined as reference-particle trajectories. The diffusion motion is implemented by sampling random-walk steps from a gaussian distribution and adding them to the reference particle motions, where the number of diffusion particles per reference position can be specified on instantiation. The random-walk displacements are translated and rotated in space according to a temporal evolution of a local basis per reference particle, which must be specified on instantiation.

Example Usage

t, r = ...   # (steps, )  (particles, steps, 3)
diff_eigenbasis = ...  # (particles, steps, 9)
diffusivity = Quantity(np.repeat([[0.18, 0.12, 0.07],], r.shape[0], axis=0), "mm^2/s")

mod = cmrsim.trajectory.DiffusionTaylor(order=5, time_grid=t,
                                        particle_trajectories=r,
                                        local_basis_over_time=diff_eigenbasis,
                                        diffusivity=diffusivity,
                                        particles_per_node=100)

Parameters:

• time_grid (Quantity) – (T, ) time-points corresponding to the snapshots of motion states

• particle_trajectories (Quantity) – (N, T, 3) trajectory snapshots describing the motion state of the reference nodes

• local_basis_over_time (ndarray) – (N, T, 9) Eigen-basis of diffusion tensors per snapshot of reference particle motion state

• diffusivity (Quantity) – (N, 3) diffusion constant in the direction of the eigen-basis of diffusion tensors per reference node

• particles_per_node (int) – Number of additional particles per reference node used as random walkers

• order (Variable) –

• batch_size (Variable) –

Methods:

__call__(timing, dt_max[, return_eigenbasis])	Repeatedly evaluates the increment_particle method to obtain positions at specified times.
increment_particles(particle_positions, dt)	Evaluates the internally stored taylor-series to obtain the deterministic reference positions and diffusion tensor eigen-basis.

Attributes:

diffusivity_per_particle

Diffusion constants per

__call__(timing, dt_max, return_eigenbasis=False, **kwargs)

Repeatedly evaluates the increment_particle method to obtain positions at specified times. The resulting trajectories consist of the deterministic part and a random-walk according to local diffusion tensor definitions:

Parameters:

• timing (Tensor) – Sequence of time-points at which the particle positions shall be return.

• dt_max (Tensor) – maximal temporal step-length used to evaluated the increment particles method

• return_eigenbasis (bool) – if true the rotated eigen-basis is returned as entry in the additional field dictionary

Return type:

(Tensor, List[dict])

Returns:

particle trajectory (#steps, #ref_pos, #subparts, #3), additional-field dictionary

increment_particles(particle_positions: ~tensorflow.python.framework.tensor.Tensor, dt: ~tensorflow.python.framework.tensor.Tensor, return_eigenbasis: bool = False, **kwargs) -> (<class 'tensorflow.python.framework.tensor.Tensor'>, <class 'dict'>)

Evaluates the internally stored taylor-series to obtain the deterministic reference positions and diffusion tensor eigen-basis. Additionally, a new random-walk step according to the stored diffusivity is sampled and then transformed (rotated) according to the orientation change of the eigen-basis.

Note: increments the variable self.current_time

Parameters:

• dt (Tensor) –

• return_eigenbasis (bool) – if True, the eigen-basis at the new position is returned as entries off the additional_fields dictionary

• particle_positions (Tensor) –

Return type:

(Tensor, dict)

Returns:

(#ref, #subparts, 3), additional_fields

batch_size: Variable

Together with self.current_batch_size determines the subset of particle trajectories that is evaluated on call and increment_particles

current_batch_idx: Variable

Allows to only evaluate the position for a batch of stored particle trajectories

current_time_ms: Variable

Keeps track of the current timing when increment_particles is called.

diffusivity_per_particle: Variable

Diffusion constants per

is_periodic: constant

Is periodic

optimal_parameters: Variable

Stores the result of fitting the TaylorPolynomial for all particle trajectories

order: Variable

Stores the order of the TaylorPolynomial, defined on instantiation