def probe_axis(poloidal_angle):
    r"""Direction cosines ``(c_R, c_Z)`` of a poloidal-field probe's sensitive axis.

    $$c_R = \cos\theta, \qquad c_Z = -\sin\theta$$

    ``probe_axis(3*pi/2) == (0, +1)``: VEST's +Bz probes.

    Parameters
    ----------
    poloidal_angle : float or ndarray
        Probe orientation angle in the DD convention; scalar or array [rad].

    Returns
    -------
    tuple of ndarray
        ``(c_R, c_Z)`` direction cosines, each the shape of the input [-].

    References
    ----------
    .. [1] IMAS Data Dictionary, ``magnetics.b_field_pol_probe[:].poloidal_angle``.
    """
    angle = np.asarray(poloidal_angle, dtype=float)
    return np.cos(angle), -np.sin(angle)

def project_poloidal_field(b_r, b_z, poloidal_angle):
    r"""The component of ``(B_R, B_Z)`` a probe oriented at ``poloidal_angle`` reads.

    $$B_{\mathrm{probe}} = B_R \cos\theta - B_Z \sin\theta$$

    ``b_r`` and ``b_z`` may carry any trailing shape (a time series, a response
    row); ``poloidal_angle`` must broadcast against them -- pass a scalar per
    probe, or ``angles[:, None]`` for a stack of rows.

    Parameters
    ----------
    b_r : float or ndarray
        Radial field component [T].
    b_z : float or ndarray
        Vertical field component [T].
    poloidal_angle : float or ndarray
        Probe orientation angle in the DD convention [rad].

    Returns
    -------
    ndarray
        Projected field along the probe axis [T].

    References
    ----------
    .. [1] IMAS Data Dictionary, ``magnetics.b_field_pol_probe[:].poloidal_angle``.
    """
    c_r, c_z = probe_axis(poloidal_angle)
    return np.asarray(b_r, dtype=float) * c_r + np.asarray(b_z, dtype=float) * c_z