Study Authoring, Stages & Interactive Re-Execution

Last changes: Documentation changelog

Selecting Study or any stage node under Stages in the Model Explorer routes the Inspector to StudyInspectorPanel or StudyStageInspectorRouter (apps/control-room/src/modules/inspector/panels/). These panels govern study-wide solver intent (backend, device, precision, demagnetization toggle, execution mode) and stage-by-stage workflow editing, initial-state handoff, and interactive Apply-and-Compute execution.

Study Stage Hysteresis inspector displaying Study pipeline scope, stage identity metadata, completed execution revision, and valid stage authoring card

Study Overview & Execution Profile (StudyInspectorPanel)

At the study root (StudyInspectorPanel.tsx, StudyGlobalAuthoringModel.ts, StudyExecutionProfileSection.tsx), users inspect and author:

  • Requested Intent vs. Resolved Capabilities: Requested backend (auto, fdm, fem), requested device (auto, cpu, gpu), requested precision (double, single), execution strictness mode, and resolved runtime capabilities (active_lane, algorithms_available). Requested intent and resolved provenance remain visibly distinct; forcing GPU never silently degrades to CPU.

  • Stage Pipeline Summary (StudyPipelineSection): Ordered list of stage cards (StudyStageCard) showing validation state, execution status (stageExecution), and quick reordering/removal where permitted by the authoring pipeline.

  • Project Runs, Batches & Checkpoints (ProjectRunsSection, ProjectBatchesSection): Tracks durable SolutionSet run history, parameter sweep batches, and checkpoint restore/export state (PERSISTENCE_CHECKPOINTS_PATH).

Staged Geometry inspector showing STATE modified badge, Revert and highlighted Apply buttons, and Draft ready to apply bar

Stage Draft Editor & Specialized Stage Inspectors

Selecting an individual stage routes through StudyStageInspectorRouter.tsx and StudyStageDraftEditor.tsx, combining editable stage inputs (when not locked to a read-only external script pipeline reference) with stage-specific execution/result inspection under panels/stages/:

Stage kind

Draft & result inspector components

Primary authored / inspected scope

relax

RelaxStageInspector

Relaxation algorithm, torque/energy tolerance, stage initial state, convergence readout

run

RunStageInspector

Integration duration, time step / solver scheme, wall-clock runtime

hysteresis

HysteresisStageInspector, HysteresisStageDraftFields

Field sweep schedule, min/max \(B\), step count, per-branch relaxation threshold, snapshot history

eigenmodes

EigenmodesStageInspector

Requested mode count, solver shift/target, Bloch \(k\)-path parameters, extracted frequencies

frequency_response

FrequencyResponseStageInspector

Driven harmonic frequency sweep bounds, damping/excitation binding, FMR response curve

fft_response

FftResponseStageInspector

Sampling rate, window/detrending, excitation source reference

add_field_drive

AddFieldDriveStageInspector

Dynamic field-drive binding at a specific point in the stage sequence

antenna_field_solve

AntennaFieldSolveStageInspector

Read-only pipeline reference pointing back to the canonical antenna definition

table_autosave / autosave

TableAutosaveStageInspector, AutosaveStageInspector, StageAutosaveSection

Table observable sampling intervals and spatial field snapshot cadence

save_state

SaveStateStageInspector

State checkpoint artifact key

change_device

ChangeDeviceStageInspector

Runtime compute device switch (cpu / gpu) between stages

Each editable stage validates locally via validateStudyStageDraft and across stage sequence rules via validateStudyWorkflow (catching missing dependencies, incompatible lane algorithms, or invalid initial states before submission). stages marked pipelineNodeId lock structural ID edits to protect script provenance while allowing result inspection.

Initial State, Per-Stage Texture Overrides & Interactive Re-Execution

  • Stage Initial-State Selector (StageInitialStateSelector): Lets operators choose default_for_target (inherit prior stage), explicit saved state, or re-seeded initial magnetization without rebuilding upstream geometry.

  • Stage Texture Assignments (StageTextureAssignmentsEditor): Allows per-stage magnetization texture overrides on selected objects or regions.

  • Safe Apply & Run (executeStageAfterApply in studyStageApplyAndRun.ts): Interactive stage re-execution pins (scene_revision, solver_profile, domain) before applying changes, applies the stage draft, fetches fresh sessions/current/status and model/readiness, aborts cleanly if a concurrent Python/UI write mutated scene_revision or changedStudyComputeInput, reports readiness blockers verbatim, and only then dispatches the stage execution command (target = current_stage).

Screenshots illustrate the interface; they are not runtime or physics qualification evidence.

Control Room crosswalk

  • Selection routes: study (StudyInspectorPanel) and study-stage (StudyStageInspectorRouter).

  • Re-execution safety: Controlled solely by executeStageAfterApply and studyComputeDraftBlockedReason; dirty invalid drafts block Study Compute until resolved or reset.

Python/API crosswalk

  • Every editable stage mirrors a study.stages.add_* builder call in packages/fullmag-py.

  • Python-authored workflow stages carrying complex runtime closures render cleanly as UnsupportedStageInspector (inspection-only / TODO: frontend support) rather than corrupting script semantics.

Physics and bibliography scope

This page documents stage authoring, validation UI, and revision-pinned command submission; time integrators, energy minimization schemes, and eigenvalue algorithms are specified in the numerical-methods documentation.

Source-code index

Responsibility

Repository path

Stable symbol

Study overview & execution profile

apps/control-room/src/modules/inspector/panels/StudyInspectorPanel.tsx

StudyInspectorPanel, useStudyInspectorPanelController

Study global backend/device/precision model

apps/control-room/src/modules/inspector/panels/StudyGlobalAuthoringModel.ts

createStudyGlobalDraft, buildStudyGlobalMergePatch

Per-stage inspector router

apps/control-room/src/modules/inspector/panels/StudyStageInspectorRouter.tsx

StudyStageInspectorRouter

Stage form editor & validation

apps/control-room/src/modules/inspector/panels/StudyStageDraftEditor.tsx

StudyStageDraftEditor

Stage Apply & Re-Run transaction pin

apps/control-room/src/modules/inspector/panels/studyStageApplyAndRun.ts

executeStageAfterApply

Initial state & texture overrides

apps/control-room/src/modules/inspector/panels/stages/StageInitialStateSelector.tsx

StageInitialStateSelector