DiffusionTaylor#

class DiffusionTaylor(order, time_grid, particle_trajectories, local_basis_over_time, diffusivity, particles_per_node, batch_size=None)[source]#

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)[source]#

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.ops.Tensor, dt: ~tensorflow.python.framework.ops.Tensor, return_eigenbasis: bool = False, **kwargs) -> (<class 'tensorflow.python.framework.ops.Tensor'>, <class 'dict'>)[source]#

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