def sweep_toroidal(r_m: np.ndarray, z_m: np.ndarray, theta_rad: np.ndarray) -> np.ndarray:
    """Sweep poloidal points through toroidal angles into world points.

    Parameters
    ----------
    r_m : array_like
        Major radius of each poloidal point [m].
    z_m : array_like
        Height of each poloidal point, same shape as *r_m* [m].
    theta_rad : array_like
        Toroidal angles to sweep through [rad].

    Returns
    -------
    np.ndarray
        World points as ``(len(theta) * len(r), 3)``, one row per angle and point
        combination [cm].

    Raises
    ------
    ValueError
        The two poloidal arrays do not have the same shape.

    Convention
    ----------
    ``X = R cos(theta)``, ``Y = R sin(theta)``, ``Z = Z``, then converted from
    metres to centimetres because the packaged calibration is in centimetres.
    Rows vary fastest over the poloidal points and slowest over the angles.

    This is an **outer product**: every point is swept through every angle, giving
    a surface. :func:`trajectory_world_points` pairs them element-wise instead,
    for a single ordered path. Confusing the two produces an array of the wrong
    length rather than an error.

    Applicability
    -------------
    Machine-independent.

    Provenance
    ----------
    .. [1] Reproduces the source notebook's torus sweep; see
       :func:`project_points` for the repository and calibration reference.
    """
    r = np.asarray(r_m, dtype=np.float64).reshape(-1)
    z = np.asarray(z_m, dtype=np.float64).reshape(-1)
    theta = np.asarray(theta_rad, dtype=np.float64).reshape(-1)
    if r.shape != z.shape:
        raise ValueError("r_m and z_m must have the same shape.")

    cos_theta = np.cos(theta)
    sin_theta = np.sin(theta)
    x = np.outer(cos_theta, r).reshape(-1)
    y = np.outer(sin_theta, r).reshape(-1)
    z_tiled = np.tile(z, theta.size)

    return np.stack([x, y, z_tiled], axis=1) * 100.0

def toroidal_ring(r_m: float, z_m: float, theta_rad: np.ndarray) -> np.ndarray:
    """Sweep one poloidal point into a full toroidal ring.

    Parameters
    ----------
    r_m : float
        Major radius of the point [m].
    z_m : float
        Height of the point [m].
    theta_rad : array_like
        Toroidal angles making up the ring [rad].

    Returns
    -------
    np.ndarray
        World points as ``(len(theta), 3)`` [cm].

    Convention
    ----------
    The single-point case of :func:`sweep_toroidal`, with the same axis
    definitions and the same conversion from metres to centimetres.

    Applicability
    -------------
    Machine-independent.

    Provenance
    ----------
    .. [1] :func:`sweep_toroidal`, which this delegates to.
    """
    return sweep_toroidal(np.array([float(r_m)]), np.array([float(z_m)]), theta_rad)

def trajectory_world_points(r_m: np.ndarray, z_m: np.ndarray, phi_rad: np.ndarray) -> np.ndarray:
    """Convert a matched trajectory of cylindrical coordinates into world points.

    Parameters
    ----------
    r_m : array_like
        Major radius along the trajectory [m].
    z_m : array_like
        Height along the trajectory, same shape [m].
    phi_rad : array_like
        Toroidal angle at each point, same shape [rad].

    Returns
    -------
    np.ndarray
        World points as ``(N, 3)``, one row per trajectory point [cm].

    Raises
    ------
    ValueError
        The three arrays do not all have the same shape.

    Convention
    ----------
    **Element-wise pairing**, one angle per point, for an ordered path such as a
    traced field line. :func:`sweep_toroidal` takes the outer product instead and
    gives a surface. Same axis definitions and the same conversion to centimetres.

    Applicability
    -------------
    Machine-independent.

    Provenance
    ----------
    .. [1] The world-frame convention of the source notebook; see
       :func:`project_points`.
    """
    r = np.asarray(r_m, dtype=np.float64).reshape(-1)
    z = np.asarray(z_m, dtype=np.float64).reshape(-1)
    phi = np.asarray(phi_rad, dtype=np.float64).reshape(-1)
    if not (r.shape == z.shape == phi.shape):
        raise ValueError("r_m, z_m, and phi_rad must have the same shape.")

    x = r * np.cos(phi)
    y = r * np.sin(phi)
    return np.stack([x, y, z], axis=1) * 100.0