def magnetics_sensor_centre(r, z):
    """Geometric centre of a magnetic sensor layout.

    Parameters
    ----------
    r : array_like
        Major radius of each sensor [m].
    z : array_like
        Height of each sensor [m].

    Returns
    -------
    tuple of float
        The centre as major radius and height [m].

    Convention
    ----------
    A layout counts as **two clusters** -- an inboard and an outboard array --
    when the widest gap in major radius spans at least a set fraction of the
    radial extent; a ring of sensors around the plasma has gaps far smaller than
    that. The two cases need different centres: a ring's centre is the median of
    its sensors, while two clusters take the midpoint between them, because the
    median of a two-cluster layout lands inside whichever cluster has more
    sensors rather than between them.

    The median is used rather than the mean so that an unevenly populated ring
    does not drag the centre toward its dense side.

    Defaults
    --------
    The cluster gap fraction is a numerical convenience separating the two
    layouts; a real ring and a real two-cluster array sit far either side of it.

    Applicability
    -------------
    Machine-independent.  The VEST case is an example: an inboard array against a
    wall array further out is the two-cluster geometry this distinguishes.

    Limitations
    -----------
    Two cases only. Three or more clusters, or a layout that is neither, gets
    whichever branch its widest gap selects.

    Provenance
    ----------
    .. [1] Issue #486, which established this definition of the layout centre.
    """
    from vaft.plot.selection import classify_regions, radial_divider

    r = np.asarray(r, dtype=float).ravel()
    z = np.asarray(z, dtype=float).ravel()
    finite = np.isfinite(r) & np.isfinite(z)
    if not np.any(finite):
        raise ValueError("a sensor centre needs at least one finite (r, z) position")
    r, z = r[finite], z[finite]
    r0 = float(np.mean(r))
    split = radial_divider(r)
    extent = float(r.max() - r.min())
    if split and extent > 0.0:
        regions = np.asarray(classify_regions(r, split=split))
        inboard = r[regions == "inboard"]
        outboard = r[regions == "outboard"]
        if inboard.size and outboard.size:
            gap = float(outboard.min() - inboard.max())
            if gap >= MAGNETICS_CLUSTER_GAP_FRACTION * extent:
                r0 = 0.5 * (float(np.median(inboard)) + float(np.median(outboard)))
    return r0, float(np.median(z))

def magnetics_sensor_poloidal_angle(r, z, centre=None):
    """Poloidal angle of each sensor about the layout centre.

    Parameters
    ----------
    r : array_like
        Major radius of each sensor [m].
    z : array_like
        Height of each sensor [m].
    centre : tuple of float, optional
        The centre to measure about; computed from the layout when omitted [m].

    Returns
    -------
    np.ndarray
        Poloidal angle of each sensor, on the interval from zero to a full turn
        [rad].

    Convention
    ----------
    Measured from the layout centre, counter-clockwise from the outboard
    midplane, and wrapped to a single positive turn rather than centred on zero.

    **This is not the IMAS poloidal angle of a probe**, which describes the
    orientation of the probe's sensitive axis rather than its position; on VEST
    every vertical-field probe has the same IMAS angle wherever it sits. Confusing
    the two puts every probe at the same place.

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

    Limitations
    -----------
    Inherits the two-case centre rule of :func:`magnetics_sensor_centre` when the
    centre is not supplied, so a layout that fits neither case gets angles about a
    centre that may not be where the caller expects.

    Provenance
    ----------
    .. [1] The IMAS data dictionary's own poloidal-angle definition, which this
       deliberately differs from.
    """
    r = np.asarray(r, dtype=float)
    z = np.asarray(z, dtype=float)
    if centre is None:
        centre = magnetics_sensor_centre(r, z)
    r0, z0 = float(centre[0]), float(centre[1])
    angle = np.mod(np.arctan2(z - z0, r - r0), 2.0 * np.pi)
    # A sensor on the outboard midplane a rounding error below Z = 0 wraps to
    # 2*pi; it belongs at 0.
    return np.where(np.isclose(angle, 2.0 * np.pi), 0.0, angle)

def vest_equilibrium_magnetics_signals(
    shot: int,
    channels: Sequence[dict],
    loader: Callable[[int, int], tuple[np.ndarray, np.ndarray] | None],
    *,
    indices: Sequence[int] | None = None,
    config: VestMagneticsProcessingConfig | None = None,
    allow_missing: bool = False,
    allow_zero_fallback: bool | None = None,
) -> tuple[np.ndarray, list[np.ndarray], list[np.ndarray]]:
    """The processed magnetics of one VEST shot, as the three-array legacy view.

    Parameters
    ----------
    shot : int
        Shot number [-].
    channels : sequence
        The channels to process [-].
    loader : callable
        Returns the raw record and its time base for a channel [-].
    indices : sequence of int, optional
        Which channels to process [-].
    config : VestMagneticsProcessingConfig, optional
        Processing settings [-].
    allow_missing : bool, optional
        Whether an unavailable channel is tolerated [-].
    allow_zero_fallback : bool, optional
        Whether to fall back to zero baseline with a warning when a channel encounters
        a degenerate baseline window. Defaults to config.allow_zero_fallback [-].

    Returns
    -------
    tuple of np.ndarray
        The output window in seconds, the fluxes in weber per radian and the
        fields in tesla [-].

    Convention
    ----------
    A backward-compatible view of :func:`vest_equilibrium_magnetics_detailed`,
    returning the three arrays the older callers expect and discarding the native-
    rate voltages. New code should call the detailed form, which keeps them.

    Applicability
    -------------
    VEST-specific.  The same chain and eras as the function it wraps.

    Limitations
    -----------
    Inherits everything from that function, and additionally discards the
    native-rate voltages, which cannot then be recovered.

    Provenance
    ----------
    .. [1] :func:`vest_equilibrium_magnetics_detailed`, which does the work.
    """
    result = vest_equilibrium_magnetics_detailed(
        shot,
        channels,
        loader,
        indices=indices,
        config=config,
        allow_missing=allow_missing,
        allow_zero_fallback=allow_zero_fallback,
    )
    return result.time, result.flux_loops, result.probes

def vest_flux_loop_legacy(
    time: np.ndarray,
    raw: np.ndarray,
    calibration: float,
    *,
    flux_loop_number: int,
    config: VestMagneticsProcessingConfig | None = None,
    allow_zero_fallback: bool | None = None,
    shot: int | None = None,
    channel: str | int | None = None,
) -> np.ndarray:
    """Poloidal flux through a VEST flux loop, from its raw record.

    Parameters
    ----------
    time : array_like
        Time base [s].
    raw : array_like
        Raw digitizer record [V].
    calibration : float
        Calibration factor for the loop [-].
    flux_loop_number : int
        Which loop [-].
    config : VestMagneticsProcessingConfig, optional
        Processing settings [-].
    allow_zero_fallback : bool, optional
        Whether to fall back to zero baseline with a warning when the baseline window
        is degenerate (fewer than 2 valid samples). Defaults to config.allow_zero_fallback [-].
    shot : int, optional
        Shot number for diagnostic error reporting [-].
    channel : str or int, optional
        Channel identifier for diagnostic error reporting [-].

    Returns
    -------
    np.ndarray
        Flux through the loop, per radian [Wb/rad].

    Processing steps
    ----------------
    1. Calibrate the raw record into a terminal voltage.
    2. Integrate, normalize per radian and subtract the era's baseline.

    Convention
    ----------
    The composition of :func:`vest_flux_loop_voltage` and
    :func:`vest_flux_loop_flux_from_voltage`, kept as a single call because the
    donor workflow had one. Same per-radian output and same era policy as those.

    Applicability
    -------------
    VEST-specific.  Inherits the calibration convention and the acquisition eras
    of the two functions it composes.

    Limitations
    -----------
    Inherits both. Raises `DegenerateBaselineWindowError` on degenerate baseline
    windows (issue #639) unless `allow_zero_fallback=True`.

    Provenance
    ----------
    .. [1] The legacy VEST magnetics workflow; see the two functions this
       composes for the donor indices.
    """
    time = np.asarray(time, dtype=float)
    raw = np.asarray(raw, dtype=float)
    if time.size <= 1 or raw.size <= 1:
        raise ValueError("VEST flux-loop processing requires at least two samples")

    voltage = vest_flux_loop_voltage(raw, calibration, config=config)
    return vest_flux_loop_flux_from_voltage(
        time,
        voltage,
        flux_loop_number=flux_loop_number,
        config=config,
        allow_zero_fallback=allow_zero_fallback,
        shot=shot,
        channel=channel,
    )

def vest_flux_loop_voltage(
    raw: np.ndarray,
    calibration: float,
    *,
    config: VestMagneticsProcessingConfig | None = None,
) -> np.ndarray:
    """Calibrated flux-loop terminal voltage, before integration.

    Parameters
    ----------
    raw : array_like
        Raw digitizer record [V].
    calibration : float
        Calibration factor for the loop [-].
    config : VestMagneticsProcessingConfig, optional
        Processing settings; the shipped defaults when omitted [-].

    Returns
    -------
    np.ndarray
        The calibrated terminal voltage [V].

    Convention
    ----------
    Calibration divides by default rather than multiplying, which is the donor's
    convention and the opposite of what a gain usually means; the mode is
    configurable and any other value is refused.

    This is the single definition of a calibrated flux-loop voltage, shared by
    :func:`vest_flux_loop_legacy` and the voltage the ODS mapper stores, so the
    two cannot drift apart.

    Applicability
    -------------
    VEST-specific.  The calibration convention is that of the VEST flux-loop
    digitizer chain.

    Limitations
    -----------
    Voltage only. Nothing is integrated and no baseline is removed here.

    Provenance
    ----------
    .. [1] Issue #209, which established this as the single definition shared with
       the ODS mapping.
    """
    cfg = config or DEFAULT_VEST_MAGNETICS_PROCESSING
    return _calibrated_signal(raw, float(calibration), cfg.calibration_mode)

def vest_magnetics_time_window(shot: int, config: VestMagneticsProcessingConfig | None = None) -> np.ndarray:
    """The output time window a VEST shot's magnetics are resampled onto.

    Parameters
    ----------
    shot : int
        Shot number, which selects the acquisition era [-].
    config : VestMagneticsProcessingConfig, optional
        Processing settings; the shipped defaults when omitted [-].

    Returns
    -------
    np.ndarray
        The sample times of the output window [s].

    Convention
    ----------
    A slice of the shot's own timebase, chosen by era rather than by inspecting
    the record. The window and baseline indices are legacy acquisition-era policy, not a
        signal-quality decision: which samples apply depends on the shot number,
        and the eras are recorded in ``vest.yaml`` rather than inferred from the
        data.

    Defaults
    --------
    Every index is an acquisition-era value. Two eras exist: a transient block of
    six shots and everything from a later shot onward share one window, and
    earlier shots take another. A configured override from ``vest.yaml``
    supersedes both; a directly constructed record keeps the historical thresholds
    so old behaviour is reproducible.

    Applicability
    -------------
    VEST-specific.  The windows are VEST acquisition policy, tied to that
    machine's digitizer timebase and its shot-numbering eras.

    Limitations
    -----------
    Selects by shot number alone. A shot whose acquisition differed from its era's
    policy gets that era's window regardless.

    Provenance
    ----------
    .. [1] ``vest.yaml`` ``magnetics.equilibrium_magnetics.processing.window``
       (issue #195), which carries the era table and supersedes the hard-coded
       thresholds.
    """
    cfg = config or DEFAULT_VEST_MAGNETICS_PROCESSING
    index_start, index_end, _ = cfg.window_for_shot(int(shot))
    return cfg.timebase()[index_start : index_end + 1]