Vector Field Modifications

batch_normalize(vec)

Normalize a batch of vectors along axis 0. Zero-length vectors are left as zeros to avoid division by zero.

Parameters:
  • vec (array_like_type) –

    Array of vectors with shape (D, N), where D is the vector dimension and N is the number of vectors.
Returns:
  • ndarray –

    Array with shape (D, N) where each column has unit norm (or is zero).

add_vectors(vec, add_vec)

Add a vector (field) from vector field.

Parameters:
  • vec (array_like_type) –

    Array of vectors with shape (D, N), where D is the vector dimension and N is the number of vectors.

  • add_vec (array_like_type) –

    Either a single vector with shape (D,) or an array with the same shape (D, N) as vec.
Returns:
  • ndarray –

    Array with shape (D, N).

subtract_vectors(vec, subtract_vec)

Subtract a vector (field) from vector field.

Parameters:
  • vec (array_like_type) –

    Array of vectors with shape (D, N), where D is the vector dimension and N is the number of vectors.

  • subtract_vec (array_like_type) –

    Either a single vector with shape (D,) or an array with the same shape (D, N) as vec.
Returns:
  • ndarray –

    Array with shape (D, N).

rescale_vectors(vec, scale)

Multiply the vector field by a scalar, or scale each vector per-point by the scale array.

Parameters:
  • vec (array_like_type) –

    Array of vectors with shape (D, N), where D is the vector dimension and N is the number of vectors.

  • scale (scalar_like_type | array_like_type) –

    Scalar multiplier applied to every vector, or an array of shape (N,) with a per-point scale factor.
Returns:
  • ndarray –

    Array with shape (D, N).

rotate_vectors_phi(vec, phis)

Rotate each vector by an angle phi about the z-axis.

Parameters:
  • vec (array_like_type) –

    Array of vectors with shape (3, N), where N is the number of vectors.

  • phis (scalar_like_type | array_like_type) –

    Rotation angle in radians. Either a scalar or an array of shape (N,) with a per-point angle.
Returns:
  • ndarray –

    Array with shape (3, N) containing the rotated vectors.

rotate_vectors_theta(vec, thetas)

Rotate each vector by an angle theta about the axis perpendicular to both the vector and the z-axis. This corresponds to tilting each vector out of its own xy-projection direction.

Parameters:
  • vec (array_like_type) –

    Array of vectors with shape (3, N), where N is the number of vectors.

  • thetas (scalar_like_type | array_like_type) –

    Rotation angle in radians. Either a scalar (same rotation for every vector) or an array of shape (N,) with a per-point angle.
Returns:
  • ndarray –

    Array with shape (3, N) containing the rotated vectors.

rotate_vectors_x_axis(vec, alpha)

Rotate each vector by an angle alpha about the x-axis. The x-component is unchanged.

Parameters:
  • vec (array_like_type) –

    Array of vectors with shape (3, N), where N is the number of vectors.

  • alpha (scalar_like_type | array_like_type) –

    Rotation angle in radians. Either a scalar (same rotation for every vector) or an array of shape (N,) with a per-point angle.
Returns:
  • ndarray –

    Array with shape (3, N) containing the rotated vectors.

rotate_vectors_y_axis(vec, alpha)

Rotate each vector by an angle alpha about the y-axis. The y-component is unchanged.

Parameters:
  • vec (array_like_type) –

    Array of vectors with shape (3, N), where N is the number of vectors.

  • alpha (scalar_like_type | array_like_type) –

    Rotation angle in radians. Either a scalar (same rotation for every vector) or an array of shape (N,) with a per-point angle.
Returns:
  • ndarray –

    Array with shape (3, N) containing the rotated vectors.

rotate_vectors_z_axis(vec, alpha)

Rotate each vector by an angle alpha about the z-axis. The z-component is unchanged. Equivalent to rotate_vectors_phi but named for consistency with the x-axis and y-axis rotation functions.

Parameters:
  • vec (array_like_type) –

    Array of vectors with shape (3, N), where N is the number of vectors.

  • alpha (scalar_like_type | array_like_type) –

    Rotation angle in radians. Either a scalar (same rotation for every vector) or an array of shape (N,) with a per-point angle.
Returns:
  • ndarray –

    Array with shape (3, N) containing the rotated vectors.

rotate_vectors_axis(vec, axes, alpha)

Rotate each vector by an angle alpha about an arbitrary axis using the Rodrigues rotation formula.

Parameters:
  • vec (array_like_type) –

    Array of vectors with shape (3, N), where N is the number of vectors.

  • axes (array_like_type) –

    Rotation axis. Either a single unit vector with shape (3,) — same axis for every rotation — or an array of shape (3, N) with a per-point axis.

  • alpha (scalar_like_type | array_like_type) –

    Rotation angle in radians. Either a scalar (same rotation for every vector) or an array of shape (N,) with a per-point angle.
Returns:
  • ndarray –

    Array with shape (3, N) containing the rotated vectors.

revolve_field_x(r, vec)

Revolve a vector field about the x-axis. At each point r, the vector is rotated by the azimuthal angle arctan2(z, y) about the x-axis, so that a field defined on the xy-plane is extended radially around the x-axis.

Parameters:
  • r (array_like_type) –

    Coordinates of points at which the vector field is evaluated. Shape must be (3, N), where N is the number of coordinate points.

  • vec (array_like_type) –

    Array of vectors with shape (3, N) to be revolved.
Returns:
  • ndarray –

    Array with shape (3, N) containing the revolved vector field.

revolve_field_y(r, vec)

Revolve a vector field about the y-axis. At each point r, the vector is rotated by the azimuthal angle arctan2(z, x) about the y-axis, so that a field defined on the xy-plane is extended radially around the y-axis.

Parameters:
  • r (array_like_type) –

    Coordinates of points at which the vector field is evaluated. Shape must be (3, N), where N is the number of coordinate points.

  • vec (array_like_type) –

    Array of vectors with shape (3, N) to be revolved.
Returns:
  • ndarray –

    Array with shape (3, N) containing the revolved vector field.

revolve_field_z(r, vec)

Revolve a vector field about the z-axis. At each point r, the vector is rotated by the azimuthal angle arctan2(y, x) about the z-axis, so that a field defined on the xz-plane is extended radially around the z-axis.

Parameters:
  • r (array_like_type) –

    Coordinates of points at which the vector field is evaluated. Shape must be (3, N), where N is the number of coordinate points.

  • vec (array_like_type) –

    Array of vectors with shape (3, N) to be revolved.
Returns:
  • ndarray –

    Array with shape (3, N) containing the revolved vector field.