pisces.particles.base.ParticleDataset.apply_linear_transformation#

ParticleDataset.apply_linear_transformation(matrix: ndarray, groups: list[str] = None, fields: tuple[str, ...] = None)[source]#

Apply a linear transformation matrix to vector fields in specified particle groups.

This method performs an in-place matrix transformation on each specified vector field (e.g., particle_position, particle_velocity) in one or more particle groups. It is useful for performing operations such as coordinate rotation, scaling, reflection, or shear.

Each particle’s vector field \(\mathbf{x}_i\) is updated according to:

\[\mathbf{x}_i \rightarrow \mathbf{A} \cdot \mathbf{x}_i\]

where \(\mathbf{A}\) is the transformation matrix and \(\mathbf{x}_i\) is the vector value (e.g., position or velocity) of the \(i\)-th particle.

Parameters:

  • matrix (array_like) – A 2D NumPy array of shape \((D, D)\) representing the linear transformation to apply. The dimension \(D\) must match the last axis of each target field.

  • groups (list of str, optional) – List of particle group names to which the transformation will be applied. If None, all groups in the dataset are used.

  • fields (tuple of str, optional) – Tuple of field names (e.g., particle_position, particle_velocity) to transform. Default is ("particle_position", "particle_velocity").

Raises:

  • ValueError – If matrix is not square or its shape does not match the vector dimensionality of the fields being transformed.

  • KeyError – If a specified field is not present in the given group(s).

Notes

  • The transformation is performed in-place and modifies the original field values.

  • Fields that are not present in a group are skipped silently.

  • This operation assumes that vector fields are stored with shape \((N, D)\), where \(N\) is the number of particles and \(D\) is the number of spatial dimensions.