Process reference: coil_operating_space

Generated from the docstrings of vaft.process.coil_operating_space: 1 public functions. Each entry is what vaft.process.describe("coil_operating_space.<name>") prints. All process categories

Overview

One container, CoilOperatingSpace, carries what a GPEC resonant-field study (#1884), a PENTRC NTV-torque study (#1887) and their plots (#1886) share: the operating points of K coil groups and the metrics evaluated at each. It is a table, not an ODS – mhd_linear has no operating-point, phasor or status axis – and it imports no solver.

samples : one row per operating point   sample_id, role, amplitude_<g>, phase_<g>
values  : one row per (sample, metric)   sample_id, metric, value, unit, status [, m, psi_n_rational, psi_n]
to_frame() ─▶ the two joined, plus amplitude_ratio_<g> and phase_rel_<g> against group 0

The schema was settled on #1886 with the plotting owner; field names change only through that thread.

Excitation. Group g drives its sectors with I_k = A_g cos(n phi_k + delta_g) (vaft.machine_mapping.coils_non_axisymmetric_geometry.CoilExcitation.from_mode), so I_k = Re(c_g exp(+i n phi_k)) with c_g = A_g exp(+i delta_g). Written as I(phi) = C_n exp(+i n phi) + C_{-n} exp(-i n phi), the coefficient of exp(+i n phi) is C_n = c_g / 2; in GPEC’s and DCON’s exp(i(m theta - n phi)) basis the coefficient of exp(-i n phi) is conj(c_g) / 2 – the same excitation, the conjugate number. A_g is the cosine amplitude, not in general the largest sector current. The pattern’s peak sits at n phi = -delta_g: delta_g = 0 puts it at phi = 0 and, for n > 0, increasing delta_g rotates it toward -phi of the frame the result names in convention["frame"]. With N equally spaced sectors the pattern is resolved only when 2 n mod N != 0 (six sectors alias n = 3: the sine part vanishes and delta cannot be recovered); the container cannot see the sector count and does not check it.

Status per (sample, metric). A GPEC metric can be valid where PENTRC failed at the same point, so status lives on the value row. Only a valid row carries a number; every other status carries NaN, so a failed or uncomputed point is never drawn as zero.

Relative coordinates. Against group 0: amplitude_ratio_<g> = A_g / A_0 and phase_rel_<g> = (delta_g - delta_0) mod 2 pi; both NaN where an amplitude involved is zero (a phase there is undefined; the metric is not).

Functions

relative_coil_coordinates(amplitudes, phases)

def relative_coil_coordinates(amplitudes: Sequence, phases: Sequence) -> dict[str, np.ndarray]:
    """Amplitude ratios and relative phases of coil groups against group 0.

    Parameters
    ----------
    amplitudes : array_like
        ``(N, K)`` cosine amplitudes, not negative [A per turn].
    phases : array_like
        ``(N, K)`` phases [rad].

    Returns
    -------
    coordinates : dict
        ``amplitude_ratio`` (``A_g / A_0``) and ``phase_rel``
        (``(delta_g - delta_0) mod 2 pi``, in rad), each ``(N, K)``; column 0
        is 1 and 0 where defined [-, rad].

    Raises
    ------
    ValueError
        Shapes differ, or an amplitude is negative or not finite.

    Processing steps
    ----------------
    1. Ratio against group 0; NaN where ``A_0 = 0``.
    2. Phase difference wrapped to ``[0, 2 pi)``; NaN where ``A_0`` or ``A_g``
       is zero, since a phase of a zero excitation is undefined.

    Convention
    ----------
    Phases follow ``I_k = A cos(n phi_k + delta)``, phasor ``A exp(+i delta)``;
    a relative phase is that of group ``g`` minus group 0.

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

    Provenance
    ----------
    .. [1886] Issue #1886, ``amplitude_ratio`` and ``phase_31`` of the plot contract.
    """
    a = np.atleast_2d(np.asarray(amplitudes, dtype=float))
    delta = np.atleast_2d(np.asarray(phases, dtype=float))
    if a.shape != delta.shape:
        raise ValueError(f"amplitudes {a.shape} and phases {delta.shape} differ")
    if not np.all(np.isfinite(a)) or np.any(a < 0):
        raise ValueError("amplitudes must be finite and not negative")
    reference = a[:, :1]
    with np.errstate(divide="ignore", invalid="ignore"):
        ratio = np.where(reference > 0, a / np.where(reference > 0, reference, 1.0), np.nan)
    defined = (reference > 0) & (a > 0)
    phase_rel = np.where(defined, np.mod(delta - delta[:, :1], 2 * np.pi), np.nan)
    return {"amplitude_ratio": ratio, "phase_rel": phase_rel}