TimeVaryingVelocityField#

class TimeVaryingVelocityField(time_grid, velocity_field, map_dimensions, additional_dimension_mapping=None, **kwargs)[source]#

Implements a the the path integration for particles in a temporally varying velocity field and also lookups for temporally varying fields. The internal representation of the field is of shape (T, X, Y, Z, 3+n). By keeping track of the current time in an internal variable, the current interval of the zeroth axis is determined. Temporal linear interpolation of the looked up values is used.

Example usage
Instantiation#
const_velocities = Quantity(np.zeros([21, 21, 200, 3], dtype=np.float32), "m/s")
const_velocities[..., 2] = Quantity(10, "cm/s")
linear_increasing_v = np.tile(const_velocities.m_as("cm/s")[np.newaxis],
                              [11, 1, 1, 1, 1])
linear_increasing_v = Quantity(lin_inc_velocities *
                                np.linspace(0, 1, 11).reshape(11, 1, 1, 1, 1), "cm/s")
time_grid = Quantity(np.arange(0, 51, 5), "ms")
map_dimension = Quantity([[-4, 4], [-4, 4], [-10, 30]], "cm").to("m")
field_list = []
trajectory_module = TimeVaryingVelocityField(
                        time_grid.m_as("ms"),
                        np.array(lin_inc_velocities.m_as("m/ms"), dtype=np.float32),
                        np.array(map_dimension.m_as("m"), dtype=np.float32), field_list)
Parameters:

  • time_grid (array) – (T, ) time in milliseconds defining the grid points of the varying velocity_fields

  • velocity_field (ndarray) – (T, X, Y, Z, 3+n) 3D map storing gridded velocities in m/s at positions X, Y, Z. Unit should be m/ms. Additional dimensions past 3 are treated as additional data fields.

  • map_dimensions (ndarray) – (3, 2) -> [(xlow, xhigh), (ylow, yhigh), (zlow, zhigh)] Physical extend of the gridded velocity fields.

  • additional_dimension_mapping (List[Tuple[str, int]]) – List of name/len pairs to unstack the looked up values. If not None this mapping must explain all ‘n’ additional dimension in the parameter velocity-field e.g. (‘off_res’, 1) meaning that the 1 index (starting from 3) in velocity field describes the off-resonance at all time points.

  • kwargs –

    • device: str defaults to CPU:0

Methods:

__call__(initial_positions, timing, dt_max)

Evaluates the increment particle function for multiple steps, and for the times matching the argument values, stores the position.

increment_particles(particle_positions, dt)

For given particle positions and specified time-interval returns the values of all additional fields at the initial particle position and moves the particles according to:

reset_time()

Sets the internal time-tracker to the first value of time grid
__call__(initial_positions, timing, dt_max, verbose=True, return_velocities=False)[source]#

Evaluates the increment particle function for multiple steps, and for the times matching the argument values, stores the position.

Parameters:

  • initial_positions (Tensor) – (#particles, 3)

  • timing (Tensor) – float - in seconds

  • dt_max (float) – Maximal temporal step width in milliseconds

  • verbose (bool) – bool

  • return_velocities (bool) – if True, the velocities for each time-step is saved and returned as entry of the additional fields dictionary

Return type:

(Tensor, dict)

Returns:

(#particles, n_steps, 3) - tf.Tensors, Trajectory, dict(field-name: tf.Tensor with shape (#particles, n_steps, n_components)) field values at trajectory locations

increment_particles(particle_positions: ~tensorflow.python.framework.ops.Tensor, dt: ~tensorflow.python.framework.ops.Tensor, return_velocities: bool = False) -> (<class 'tensorflow.python.framework.ops.Tensor'>, <class 'dict'>)[source]#

For given particle positions and specified time-interval returns the values of all additional fields at the initial particle position and moves the particles according to:

\[r_{t+1} = r_{t} + \delta t v(r_{t}, t)\]

where \(v(r_{t}, t)\) is assumed to be specified in m/ms and \(\delta t\) in ms. The temporal dependency for \(v(r_{t}, t)\) is evaluated by linear interpolation of lookups at the reference times given as zeroth dimension of the look-up map. The current interval is determined by the variable self._current_time.

Parameters:

  • particle_positions (Tensor) – (-1, 3) batch of 3D particle coordinates

  • dt (Tensor) – scalar value in ms

  • return_velocities (bool) – if True the additional field lookup contains the field “velocity”

Return type:

(Tensor, dict)

Returns:

new particle positions (-1, 3), dict(**aditional_fields[-1, c])

reset_time()[source]#

Sets the internal time-tracker to the first value of time grid