def phased_sector_currents(phi_rad, n: int, phase_rad: float, amplitude_a: float) -> np.ndarray:
    """Per-sector currents of one toroidal harmonic.

    Parameters
    ----------
    phi_rad : array_like
        Toroidal angle of each sector, IMAS ``phi``, shape ``(K,)`` [rad].
    n : int
        Toroidal mode number [-].
    phase_rad : float
        Phase ``delta`` of the pattern at ``phi = 0`` [rad].
    amplitude_a : float
        Peak sector current ``A`` [A].

    Returns
    -------
    np.ndarray
        ``I_k`` for each sector, shape ``(K,)`` [A].

    Raises
    ------
    ValueError
        ``phi_rad`` is not one-dimensional or is empty.

    Convention
    ----------
    ``I_k = A cos(n phi_k + delta)``: the pattern whose
    :func:`toroidal_mode_decomposition` coefficient is
    ``C_n = (A/2) exp(+i delta)`` when the sectors resolve ``n``, so the two
    functions are inverse to each other.  Positive current flows along the
    filament vertex order, as :func:`biot_savart_filaments` takes it.

    Assumptions
    -----------
    A single harmonic with no ``n = 0`` offset; the sectors are driven in
    phase with each other up to the stated pattern.

    Applicability
    -------------
    Machine-independent.  Any toroidal row of discrete coils phased as one
    harmonic: RMP and error-field correction coils.
    """
    phi = np.asarray(phi_rad, dtype=float)
    if phi.ndim != 1 or phi.size == 0:
        raise ValueError(f"phi_rad must be a non-empty one-dimensional array, got shape {phi.shape}")
    return float(amplitude_a) * np.cos(int(n) * phi + float(phase_rad))

def toroidal_mode_decomposition(
    phi_rad, values, modes: Iterable[int]
) -> Mapping[int, complex]:
    """Complex toroidal Fourier coefficient of a per-sector quantity.

    Parameters
    ----------
    phi_rad : array_like
        Toroidal angle of each sector sample, any order, shape ``(K,)`` [rad].
    values : array_like
        The quantity at each sector, real or complex, shape ``(K,)``; coil
        currents are the usual case [any].
    modes : iterable of int
        Toroidal mode numbers ``n`` to evaluate [-].

    Returns
    -------
    dict[int, complex]
        ``C_n`` for each requested ``n``, in the units of ``values`` [any].

    Raises
    ------
    ValueError
        ``phi_rad`` and ``values`` differ in length, are not one-dimensional,
        or are empty.

    Convention
    ----------
    ``C_n = (1/K) sum_k v_k exp(-i n phi_k)``, the plain sample mean, so a
    pattern ``v_k = A cos(n phi_k + delta)`` returns ``C_n = (A/2) exp(+i delta)``
    when the sectors resolve ``n`` without aliasing: the peak amplitude is
    ``2 |C_n|`` and the phase of ``C_n`` is the pattern's phase ``delta`` at
    ``phi = 0``.  The ``exp(-i n phi)`` kernel is the one GPEC's ``coil.in``
    documentation and the legacy ``fourier_mode_coefficient`` use; a ``exp(+i n phi)`` convention conjugates every coefficient.  No
    normalisation by ``2/K`` is applied, so ``C_0`` is the mean.

    Assumptions
    -----------
    Uniform weighting of the sectors.  With ``K`` equally spaced sectors the
    coefficients are exact for ``|n| < K/2``; with fewer or unevenly spaced
    sectors they are the least-squares-free sample projection and alias.

    Applicability
    -------------
    Machine-independent.  Any toroidal array of discrete elements: RMP coil
    rows, error-field correction coils, saddle loops.

    Provenance
    ----------
    .. [GPEC] GPEC ``coil.in`` documentation: per-coil currents are
       combined per toroidal harmonic with ``exp(-i n phi)``.
    .. [legacy] The legacy implementation's ``gpec_input_processor.py``
       ``fourier_mode_coefficient`` (same kernel), ported unchanged.
    """
    phi = np.asarray(phi_rad, dtype=float)
    v = np.asarray(values)
    if phi.ndim != 1 or v.ndim != 1 or phi.shape != v.shape:
        raise ValueError(
            f"phi_rad and values must be one-dimensional and equal in length, got {phi.shape} and {v.shape}"
        )
    if phi.size == 0:
        raise ValueError("at least one sector sample is required")
    return {int(n): complex(np.mean(v * np.exp(-1j * int(n) * phi))) for n in modes}