Control Room User Guide

Last changes: Documentation changelog

The FullMag Control Room is the interactive browser workspace and authoring companion for the FullMag micromagnetics platform. Running inside your Docker Compose DEV group (typically at http://127.0.0.1:3197), it pairs a live visual interface with the ProblemIR pipeline and runtime APIs so you can build models, inspect 3D/2D fields, analyze scalar and spectral plots, and watch live Python sessions (fm.connect()) update in real time.

Model edits commit typed authoring transactions and re-lower through the study/ProblemIR pipeline; layout, active tabs, and visualization controls remain client-side UI state. Exported scripts preserve supported authored models, while Control Room capability register tracks backend capabilities that do not yet expose a dedicated UI editor.


Start Screen Hub & Multi-Instance Sessions

When no project workspace is active—or when you return via the header Home navigation button—the Start Screen serves as the workspace hub:

FullMag Control Room Start Screen Workspace Hub

The Start Screen launcher exposes empty FDM/FEM problem creation, benchmark templates, file imports (.mif, .mx3, .mph, .fms), recent projects, and active sessions.

From the Start Screen you can:

  • Launch a new study: open an empty FDM simulation (Ctrl+N), an empty FEM simulation (Ctrl+Shift+N), or browse ready-made benchmarks under From template (Ctrl+T, saved as canonical Python .py scripts).

  • Attach to live Python sessions: sessions created by an external script calling fm.connect() appear under Active simulations with their live lifecycle status pill so you can jump straight into the shared 3D/2D workspace.

  • Work across multiple DEV instances: the header Instance Tab Strip lets you switch between multiple running FullMag instances and sessions (/session/<slug>, /instance/<port>) without leaving the workspace shell.

Start Screen Model Templates Browser

Built-in templates (µMAG Standard Problem 4, spin-wave dispersion, FMR, and skyrmion benchmarks) ready to launch into a live session.

Start Screen showing an active live Python session from fm.connect()

Active live Python sessions (fm.connect()) detected on the runtime and surfaced for interactive inspection.

Multi-instance session tab strip in the Control Room header

Multi-instance session switching across running Control Room ports and workspaces.


Workspace Layout & Themes

Inside an open project or active session, the Control Room organizes controls around a single unified workspace shell shared by both FDM and FEM studies:

FullMag Control Room Workspace Overview in Catppuccin Mocha Dark Theme

Control Room workspace overview in the default Catppuccin Mocha (dark) theme.

Region

Component

Primary Purpose

Top Bar

App Menu, Session Indicator & Theme Switcher

Navigate Home, switch multi-instance tabs, open Command Search (Ctrl+Shift+P), monitor session connectivity, control global Run/Pause/Stop transport, and toggle themes.

Top Ribbon

Ribbon Toolbar Strip

Contextual tabs (Workspace, View, Geometry, Materials, Physics, Mesh, Study, Results, plus contextual Analysis when inspecting Results; placeholder preview tabs such as Definitions and Automation stay hidden when they have no active non-preview actions).

Left Dock

Semantic Explorer Panel

Navigate five dedicated explorer tabs (Model, Resources, Results, Jobs, Diagnostics).

Center Stage

3D Viewport / 2D Planar Field Map / Split Plots

WebGL 3D vector & mesh canvas, 2D planar slice inspector, and optional companion analysis viewports.

Right Dock

Contextual Inspector Panel

Property editor for the selected Explorer node with explicit draft-and-apply isolation.

Bottom Dock

Footer Analysis & Telemetry

Tabbed workspace footer hosting Telemetry, Diagnostics, Operations, Engine, Logs, Problems, and Quick Chart.

Footer Bar

Status & Governance Strip

Continuous session connection dot, WebSocket realtime status, status freshness, resolved engine/device lane, mesh state, and simulation method badge.

Use the Theme Switcher in the top-right header (or Command Search) to switch instantaneously between Catppuccin Mocha (dark) and Catppuccin Latte (light):

FullMag Control Room Workspace Overview in Catppuccin Latte Light Theme

The same unified workspace rendered in Catppuccin Latte (light) theme.



Semantic Explorer Panel

The Explorer Panel on the left provides five tabs—Model, Resources, Results, Jobs, and Diagnostics—keeping structural authoring, compute artifacts, and job history strictly separated:

Control Room Semantic Explorer Tree Panel

Hierarchical Model tree displaying geometry objects, material zones, physical interactions, meshing policies, ordered study stages, and monitors.

  1. Model: Hierarchical model tree covering Objects and sub-regions, Materials, Physics terms and couplings, Discretization & Mesh, Study & Ordered Stages, and configured Outputs / Planar Monitors.

  2. Resources: Shared domain manifests, material libraries, field/quantity catalogs, and session assets.

  3. Results: Current run outputs alongside browsable Saved Results history with comparison and playback controls.

  4. Jobs: Active and completed mesh builds, stage commands, and compute queue history.

  5. Diagnostics: Live telemetry, solver profiling summaries, and readiness diagnostics.

Selecting any node in the Explorer updates the Inspector Panel on the right without losing uncommitted edits elsewhere in the model.


Visualization: 3D Viewport, 2D Planar Field Maps, & Analysis Plots

The center canvas switches smoothly between the 3D WebGL scene, the 2D Planar Field Map, and split/companion scientific chart panels.

Interactive 3D WebGL Viewport

Control Room 3D WebGL Viewport Showing Vector Glyphs and Colormaps

The Three.js WebGL 3D viewport displaying normalized magnetization glyphs, surface color projection, orientation cube HUD, and colorbar legend.

  • Vector Glyphs & Field Quantities: Visualize binary-streamed FMVP fields (\(\mathbf{m}\), \(\mathbf{H}_{\text{eff}}\), \(\mathbf{H}_{\text{demag}}\), spin accumulation, or mode profiles) colored by component (\(m_x, m_y, m_z\)) or magnitude using scientific colormaps (viridis, plasma, coolwarm, hsv).

  • Surface Projection Modes: Switch between direct nodal interpolation, boundary surface faces, or depth-averaged projections, and toggle perspective/orthographic projection from the View ribbon.

  • FEM Meshes & Poisson Airbox: Inspect conformal tetrahedral bodies together with surrounding FEM Poisson airbox extents and wireframe boundaries:

Control Room 3D Viewport Displaying FEM Mesh and Poisson Airbox Boundary

Conformal tetrahedral ferromagnet mesh paired with the exterior FEM Poisson airbox wireframe.

2D Planar Field Map

Switch to the Planar 2D view to cut live XY, XZ, or YZ sections across FDM grids or FEM tetrahedral volumes with streamline, contour, vector-glyph, mesh, and line-profile measurement tools:

Control Room 2D Planar Field Map View

2D Planar Field Map showing cross-section controls, layer visibility toggles, vector/contour overlays, and snapshot scrubbing.

Live Charts, Hysteresis Loops, & Spectral Plots

Bottom-docked and companion ECharts views monitor live time-domain dynamics, hysteresis branches, and FEM eigenmode dispersion / driven frequency response:

Control Room Live Time-Series Scalar Plots

Real-time streaming scalar trajectories (\(\langle m_x \rangle, \langle m_y \rangle, \langle m_z \rangle\) and magnetic energies) during an LLG run.

Control Room Hysteresis Loop and Playback Inspector

Interactive hysteresis curve \(M(H)\) with field-step playback and branch inspection.

Control Room Spin-Wave Dispersion and FMR Frequency-Response Plots

FEM modal dispersion \(\omega(k)\) and driven frequency-response susceptibility spectra.


Semantic Inspector & Interactive Stage Re-Execution

The Inspector Panel on the right edits properties of the active Explorer selection using an explicit Draft -> Save / Apply -> Revision lifecycle so edits never silently corrupt an in-flight solve:

Control Room Inspector Panel in Draft Mode

Inspector panel showing draft isolation before committing model mutations to the runtime session.

Control Room Geometry Inspector Panel showing Primitive Geometry controls

Geometry inspector configuring primitive shape dimensions (Kind: box, Size X/Y/Z), Placement, and explicit Revert / Apply draft actions.

  1. Editing fields puts the panel into an explicit Draft state without mutating the running simulation.

  2. Saving/applying submits an atomic transaction to the backend, updates the scene revision, and invalidates dependent mesh or study resources cleanly.

  3. Selecting any stage under Study opens StageInspectorFrame and StageInitialStateSelector:

Control Room Study Stage Inspector with Initial Magnetization and Re-Run Controls

Study stage inspector configuring stopping tolerances, output cadence, initial magnetization seed selection, and interactive stage re-execution.

Within the Execution section of a stage inspector, you can choose how the stage initializes (From the configured Study flow, Study initial texture (m₀), Latest compatible state at start, prepared preview magnetization, or a pinned saved stage result), compare authored recipes against saved results, preview prior magnetization states in the 3D viewport, and re-run that stage without rewriting the entire script.



Control Room crosswalk

Detailed frontend module references live under Control Room, Semantic Inspectors, and Frontend Visualization. Use Control Room capability register to verify whether any Python API parameter has an implemented Control Room editor versus TODO: frontend support.

Python/API crosswalk

The runnable Python authoring API (fm.study(...) and fm.connect()) is authoritative. Consult Interactive Live Python & REPL for live sessions and Python API for complete parameter signatures and unit contracts.

Physics, limitations, and bibliography

Control Room views do not define separate physical equations; all governing equations, boundary conditions, and lane support matrices are owned by Backend.

Source-code index

  • apps/control-room/src/kernel/layout/WorkspaceShellClient.tsx and AppMenuBar.tsx — root workspace shell, Start Screen toggle, theme switcher (Catppuccin Mocha / Latte), Command Search (Ctrl+Shift+P), and header session controls.

  • apps/control-room/src/modules/start/StartScreen.tsx and home/ActiveSessions.tsx — Start Screen workspace hub, template browser, and fm.connect() active simulation list.

  • apps/control-room/src/modules/ribbon/ribbonContributions.tsx — ribbon tab definitions and capability-gated actions.

  • apps/control-room/src/modules/explorer/ExplorerTabBar.tsx — five Explorer tabs (Model, Resources, Results, Jobs, Diagnostics).

  • apps/control-room/src/modules/inspector/panels/GeometryObjectPanel.tsx, StudyStageDraftEditor.tsx, and stages/StageInspectorFrame.tsx — explicit draft-and-apply editors and interactive stage re-execution with StageInitialStateSelector.

  • apps/control-room/src/modules/status-bar/StatusBarModule.tsx — live status strip and footer diagnostics launchers.

  • Control Room capability register — authoritative boundary between implemented UI editors and Python-only features.

Screenshots illustrate the Control Room user interface; they are not runtime, numerical convergence, or scientific qualification evidence.