[Umbrella] Compose VAFT event/state products into a plasma-evolution timeline and physics-association framework

[HongSik-Yun-Fusion]

Summary

VAFT already has several domain-specific efforts that detect or represent plasma events, states, actuator commands, measured responses, and physics-model outputs. What is still missing is a common composition layer that connects these existing products along one discharge timeline without duplicating their domain logic.

This issue establishes a general plasma-evolution timeline and a physics-association layer for both normal and off-normal operation.

Conceptually:

actuator history
+ diagnostic events
+ plasma states / transitions
+ equilibrium / stability / response quantities
        ↓
common plasma-evolution timeline
        ↓
event / state / physics association
        ↓
shot-level and database-scale analysis

The key rule is:

Keep each domain-specific detector or data product as the source of truth; the common framework composes and references them rather than reimplementing them.

---

Existing VAFT groundwork

This work should build on, not replace, existing issues:

• Plasma onset: H-alpha first with validated fallbacks, robust Ip, explicit provenance — plasma_free_interval currently ends on PF pickup #409 — generic onset primitives and structured plasma-onset provenance
• [Process] Implement literature-defined disruption event detection in VAFT #492 — disruption-event detection and a disruption-specific event timeline
• Gas timing: detect prefill, ionization-associated transitions, and optional later puffs from VEST barometry #614 — gas-timing event taxonomy
• Study VEST gas ionization-associated timing relative to plasma onset #616 — event-to-event timing correlation across a shot population
• Study VEST programmed gas-trigger to measured chamber-response delay #617 — programmed actuator command vs measured response timing
• Map VEST PF/TF/gas/EC shot-program settings into IMAS pulse_schedule #229 — programmed PF/TF/gas/EC settings in pulse_schedule
• Complete GPEC / linear-stability validation for DCON, RDCON and STRIDE #173 — time-dependent DCON/RDCON/STRIDE stability products
• [Umbrella] Establish VEST-native helicity-injection schema and IMAS integration path #511 — startup-state / flux-closure transition semantics
• [Equilibrium] Extend the analytic Solov'ev benchmark with reusable L-/H-mode profile kernels #552 — L-/H-mode represented as physical profile states rather than solver identities
• Reframe VAFT documentation around its scientific-infrastructure role and research use cases #330 — broader VAFT direction toward database-scale transient, stability, and integrated-modeling studies

The new layer should generalize the common patterns already present across these efforts.

---

Scope

1. Minimal common event contract

Define the smallest domain-independent contract needed to compose existing event-like products, for example:

event identity
time
category
source product / diagnostic
method
quality / confidence
flags
provenance

Do not force all domains into a large class hierarchy if their existing result objects can satisfy the common contract through adapters.

2. Distinguish events, states, and transitions

Keep temporal markers and finite-duration physical states semantically separate.

Examples:

plasma_onset      -> event
L_mode            -> state
lh_transition     -> transition
mode_locking      -> transition/event boundary
current_quench    -> state/interval

A transition should be able to relate state_before and state_after where defensible.

3. Preserve actuator-command vs response semantics

Follow the separation already established by #229 and #617:

programmed actuator command
        !=
measured actuator response
        !=
plasma response

The timeline should reference these independently rather than collapsing them into one actuator event.

4. Compose a shot-level plasma timeline

Provide a common composition API that can sort and query events from independent producers, conceptually:

timeline = compose_plasma_timeline(
    plasma_onset=...,
    gas_timing=...,
    disruption_events=...,
    actuator_schedule=...,
    optional_events=...,
)

The timeline must preserve source ownership and provenance.

5. Represent state intervals

Support interval composition from authoritative event/state boundaries so that downstream analysis can query the physical state at a given time, for example:

pre_plasma
plasma_present
beam_heated
L_mode / H_mode
locked
current_quench

The first implementation should use explicit interval composition, not a large automatic state machine.

6. Add generic temporal relations

Generalize patterns already used in #616 and #617:

Δt(gas_response, plasma_onset)
Δt(nbi_on, lh_transition)
Δt(mode_locking, current_quench_start)
Δt(rmp_on, penetration)

Missing and ambiguous associations must remain explicit.

7. Associate events/states with physics products

Equilibrium, stability, and plasma-response quantities remain owned by their existing data products. Do not duplicate them inside the timeline.

Instead support operations such as:

sample metric at event time
summarize metric over state interval
compare metric before/after transition

Examples:

Δ'(t_lock)
q95(t_transition)
βN over H-mode interval
response metric before/after penetration

This creates the bridge between event characterization and physics/stability calculations without coupling detectors to individual solvers.

---

Intended applications

The same framework should eventually support trajectories such as:

prefill
→ plasma onset
→ current ramp-up
→ equilibrium formation
→ auxiliary heating
→ L-H transition
→ flat-top

RMP on
→ plasma response evolution
→ penetration / locking
→ suppression or recovery

MHD precursor
→ thermal collapse
→ current-quench sequence
→ plasma-wall interaction

Disruption analysis therefore remains one specialization of the more general plasma-evolution representation.

---

Implementation phases

Phase 1 — inventory and composition contract

• inventory current event/state-like result objects;
• define the minimal common event contract;
• implement shot-level chronological composition;
• preserve source/provenance;
• add generic event-to-event timing utilities.

Phase 2 — connect existing products

Connect at least:

• Plasma onset: H-alpha first with validated fallbacks, robust Ip, explicit provenance — plasma_free_interval currently ends on PF pickup #409 plasma onset;
• [Process] Implement literature-defined disruption event detection in VAFT #492 disruption events;
• Gas timing: detect prefill, ionization-associated transitions, and optional later puffs from VEST barometry #614 gas timing;
• Map VEST PF/TF/gas/EC shot-program settings into IMAS pulse_schedule #229 programmed actuator timing.

Phase 3 — state intervals

Add minimal interval composition for existing states such as pre-plasma, plasma-present, and current-quench intervals, with actuator-derived states where semantics are unambiguous.

Phase 4 — physics association

Add generic APIs to:

• sample a physics quantity at an event;
• summarize it over a state interval;
• compare it before and after a transition.

Phase 5 — extend to additional physics domains

Candidates include:

• L-H / H-L transition;
• NBI / EC heating states;
• mode locking / unlocking;
• RMP penetration / recovery;
• flux closure / equilibrium formation;
• additional disruption precursor chains.

---

Provenance principles

Every composed event or relation must retain enough information to trace:

source product / diagnostic
algorithm or definition
parameter set
software version where available
time convention
quality / ambiguity flags
literature provenance where applicable

For literature-defined detectors, keep the relationship explicit:

published scientific definition
    ↓
independent VAFT implementation
    ↓
reproducible validation

The framework does not target software or algorithmic parity with any external event-analysis system.

---

Acceptance criteria

• Inventory existing VAFT event/state/actuator products and their ownership.
• Define a minimal common event contract without duplicating domain semantics.
• Compose events from multiple domains into a chronological shot-level timeline.
• Preserve source, method, quality flags, and provenance after composition.
• Distinguish events from finite-duration states and transitions.
• Keep programmed actuator commands distinct from measured and plasma responses.
• Provide generic event-to-event timing utilities.
• Connect Plasma onset: H-alpha first with validated fallbacks, robust Ip, explicit provenance — plasma_free_interval currently ends on PF pickup #409, [Process] Implement literature-defined disruption event detection in VAFT #492, Gas timing: detect prefill, ionization-associated transitions, and optional later puffs from VEST barometry #614, and Map VEST PF/TF/gas/EC shot-program settings into IMAS pulse_schedule #229 as initial producers.
• Represent at least minimal plasma-state intervals.
• Reference physics quantities without copying them into the timeline product.
• Sample a physics quantity at an event time.
• Summarize a physics quantity over a state interval.
• Compare a physics quantity before/after a transition.
• Keep detector ownership separate from composition and analysis ownership.

---

Non-goals

• reimplementing existing Plasma onset: H-alpha first with validated fallbacks, robust Ip, explicit provenance — plasma_free_interval currently ends on PF pickup #409 / [Process] Implement literature-defined disruption event detection in VAFT #492 / Gas timing: detect prefill, ionization-associated transitions, and optional later puffs from VEST barometry #614 detectors;
• defining one universal disruption_time;
• implementing every plasma-event detector in this issue;
• immediately building a universal plasma-state classifier;
• ML forecasting or causal inference;
• duplicating equilibrium/stability/response quantities in a new persistence layer;
• redefining pulse_schedule semantics;
• introducing a new IMAS IDS;
• building a full ontology or knowledge graph before the composition contract is validated.

The initial responsibility of this framework is temporal alignment, semantic composition, provenance, and physics association.