Interactive Live Python & REPL

Last changes: Documentation changelog

FullMag supports interactive live Python control (fullmag.live) in addition to stage-first batch scripts. Calling fm.connect() attaches an interactive Python REPL, script, or Jupyter notebook directly to a running Docker DEV group so every model edit commits immediately and fm.relax(), fm.run(), and fm.run_until(...) execute as live runtime commands while the Control Room visualizes fields and scalars in real time.

Control Room Start Screen showing an active live Python session ready to open

The Control Room Start Screen detects sessions created by fm.connect() and surfaces them under Active simulations for one-click visual inspection.

Live REPL versus stage-first batch scripts

Use the authoring style that matches how you are working:

Workflow

Entry point

When to use

Execution path

Interactive live Python

fm.connect(url) + fm.relax() / fm.run()

Explorative prototyping, Jupyter notebooks, iterative REPL field sweeps, closing loops on live observables

Executes directly against the attached server session over HTTP + WebSocket

Stage-first batch script

fm.study(...) + study.stages.add_*

Reproducible studies, multi-stage pipelines, automated verification, headless container runs

Lowers to ProblemIR and runs via just docker-dev-script or just fullmag-dev-container

Both modes share the same physical parameter units (SI), discretization contracts, and ProblemIR validation rules. Calling fm.export_script() inside a live session retrieves a canonical, self-contained Python script representing the active model on the server.

Connecting to a running FullMag instance

Install the pure-Python client (pip install fullmag or pip install "fullmag[jupyter]"), ensure a Docker DEV group is running (for example via just docker-dev "$PWD" 3197), and attach from any terminal, IDE interactive window, or notebook:

>>> import fullmag as fm
>>> session = fm.connect("http://127.0.0.1:3197")  # or omit url to read $FULLMAG_URL
>>> fm.engine("fdm")
>>> fm.device("cpu", precision="double")
>>> fm.cell(5e-9, 5e-9, 10e-9)
>>> fm.solver(fix_dt=1e-13)
>>> film = fm.geometry(fm.Box(size=(200e-9, 100e-9, 10e-9), name="film"), name="film")
>>> film.Ms = 800e3
>>> film.Aex = 13e-12
>>> film.alpha = 0.5
>>> film.m = fm.texture.uniform(1, 1, 0)

Key connection parameters:

  • fm.connect(url=None, *, new_session=False, backend=None, token=None, timeout=30.0, retry_budget_s=60.0, command_timeout=None, source_path=None, events=True): attaches to the frontend origin ($FULLMAG_URL, defaulting to http://127.0.0.1:3197, with optional bearer auth from $FULLMAG_TOKEN). Pass new_session=True to start a new server session rather than attaching to the active one, and optionally pass backend="fdm" or "fem" when creating a fresh session.

  • Client presence heartbeats: LiveSession runs a background heartbeat thread calling the session heartbeat endpoint every \(10\ \mathrm{s}\) (identifying the client via source_path.name or "python-live"). This keeps the live session active and synchronized with the Control Room Start Screen (Active simulations).

  • fm.disconnect(): cleanly stops the WebSocket listener and presence heartbeat thread without stopping the backend container or discarding the server session.

  • Live-hook conflicts and unsupported operations: Operations that do not apply to interactive command execution—such as relax_stage, run_stage, eigenmode or frequency-response studies, or local file writers (save, save_response, snapshot)—raise fm.LiveModeError. Concurrent conflicting edits between the UI and Python raise StaleRevisionError instead of silently overwriting changes.

Transactions, synchronization, and script export

Outside a transaction, each top-level DSL call (fm.b_ext(...), material assignments, geometry additions) automatically commits an incremental scene update. When applying related parameter edits together—such as updating anisotropy and bias field simultaneously—wrap them in fm.transaction() so the server commits a single atomic revision:

>>> with fm.transaction():
...     film.alpha = 0.02
...     fm.b_ext(0.05, 0.0, 0.0)
>>> rev = fm.sync()  # returns the latest committed server scene revision
>>> canonical_py = fm.export_script()  # retrieve canonical editable Python script
  • fm.sync(reconcile=False): ensures all pending local model state is flushed to the server; pass reconcile=True to synchronize local authoring proxies with changes made in the Control Room.

  • fm.export_script(): downloads the canonical script serialized from the current server model so an interactive session can be saved as a reproducible batch script.

  • fm.execution_context() / fm.ExecutionContext() and fm.reset(): isolate multiple flat-DSL documents inside the same Python process and reset flat authoring state between independent runs.

Control Room File menu showing Save canonical copy as for canonical Python script export

Canonical Python script export via File -> Save canonical copy as… in the Control Room, complementing fm.export_script() in interactive fullmag.live sessions.

Relaxing, continuing magnetization, and predicate loops

Sequential commands preserve magnetization continuity: fm.run() and fm.relax() inherit the exact final magnetization \(\mathbf{m}\) of the previous command whenever the discretization has not changed. In the Control Room, opening any stage in the Study inspector (Initial magnetization selector) lets you inspect saved stage results, preview prior magnetization states, and re-run a stage from a chosen initial state on the shared session.

>>> res1 = fm.relax(dt=1e-13, tolT=1e-4, max_steps=1_000)
>>> res1.status
'completed'
>>> fm.b_ext(-0.04, 0.01, 0.0)
>>> # Step dynamically in 10 ps chunks until mx reverses sign (up to 1 ns)
>>> last = fm.run_until(
...     lambda sess: sess.table("scalars", columns=("mx",)).column("mx")[-1] < 0.0,
...     chunk_time=10e-12,
...     max_time=1.0e-9,
... )

Available execution and transport helpers:

  • fm.relax(...): runs overdamped relaxation (algorithm="llg_overdamped" or lane-supported minimizers, with tol, tolA, tolT, max_steps, dt, max_relaxation_time_s, max_pseudotime_s, max_physical_time_s, relax_alpha, solver, max_error, dt_min, dt_max, field_refresh, stop).

  • fm.run(until) and fm.run_until(predicate, *, chunk_time, max_time=None, max_chunks=None) / fm.run_while(condition, *, chunk_time, max_time=None, max_steps=None, relax=False): advance LLG time integration for a fixed physical duration (s) or until a Python condition triggers.

  • fm.pause(), fm.paused(), fm.resume(), fm.stop(), fm.skip(): runtime transport controls declared on the session. Note the server capability boundary: in Docker accepted mode, mid-command pause, paused(), and skip are explicitly rejected by the server (UnsupportedCapabilityError); apply parameter edits between commands or between run_until chunks instead.

Reading binary fields (FMVP) and scalar tables (FMTB)

Live readback fetches binary vectors and tables directly over the data plane with NumPy (never .numpy()):

>>> field_vec = fm.field("m")  # returns FieldVector or None
>>> m = field_vec.to_numpy()  # NumPy array of shape (point_count, 3)
>>> grid = field_vec.as_grid()  # 4D structured grid array for FDM (nx, ny, nz, 3)
>>> scalars = fm.table("scalars", columns=("t", "mx", "my", "mz"))
>>> t = scalars.column("t")  # 1D NumPy vector in seconds
>>> df = scalars.to_pandas()  # optional pandas DataFrame conversion
  • fm.field(quantity_id, **query) returns a FieldVector with .point_count, .to_numpy(), .as_grid() (for structured FDM grids), and .as_complex() (for complex spectral/response fields). Pass scope_kind="airbox" on FEM sessions when querying demagnetization fields over the airbox domain.

  • fm.table(table_id, *, columns=None, **query) returns a TableRows object exposing .to_numpy(), .column(name), and .to_pandas().

Live events, Jupyter monitoring, and multi-group sweeps

Subscribe to realtime WebSocket events ("scalar.sample", "resource.batch_changed", "hello", "resync.required", or "*"), plot streaming observables inside a Jupyter notebook, or fan out a parameter sweep across multiple independent Docker DEV groups simultaneously:

>>> sub = fm.on("scalar.sample", lambda ev: print(ev.payload))
>>> # Inside a Jupyter notebook (requires fullmag[jupyter]):
>>> from fullmag.live.jupyter import monitor
>>> mon = monitor(("mx", "my", "mz"), min_interval_s=0.25)
>>> fm.run(200e-12)
>>> mon.stop()
>>> sub.cancel()
>>> fm.disconnect()

For parallel parameter studies across separate running DEV groups (for example ports 3197 and 3199), use fm.sweep(...):

>>> def evaluate_field(session, *, hx):
...     session.sync()
...     fm.b_ext(hx, 0.0, 0.0)
...     fm.relax(dt=1e-13, tolT=1e-4, max_steps=1_000)
...     return float(fm.field("m").to_numpy()[:, 0].mean())
>>>
>>> results = fm.sweep(
...     evaluate_field,
...     groups=["http://127.0.0.1:3197", "http://127.0.0.1:3199"],
...     hx=[0.01, 0.02, 0.03, 0.04],
... )

More runnable live scripts live in the repository under examples/live/ (01_fdm_relax_read_m.py through 05_jupyter_monitor.py).

Complete stage-first batch counterpart

When capturing an interactive workflow into a reproducible headless study, convert the commands into an explicit fm.study(...) with study.stages.add_*:

# %% Reproducible stage-first counterpart
import fullmag as fm

nm = 1.0e-9
study = fm.study("interactive_python_counterpart")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")
study.cell(5 * nm, 5 * nm, 10 * nm)
study.solver(fix_dt=1e-13)

film = study.geometry(
    fm.Box(size=(200 * nm, 100 * nm, 10 * nm), name="film"),
    name="film",
)
film.Ms = 800.0e3
film.Aex = 13.0e-12
film.alpha = 0.02
film.m = fm.texture.uniform(1, 1, 0)

study.exchange()
study.demag()
study.b_ext(0.05, 0.0, 0.0)

study.stages.add_relax(
    stage_id="relax",
    algorithm="llg_overdamped",
    dt=1e-13,
    tolT=1e-4,
    max_steps=1_000,
)
study.tableautosave(
    50e-12,
    quantities=["step", "t", "mx", "my", "mz", "E_total"],
)
study.stages.add_run(
    stage_id="dynamics",
    until=1.0e-9,
)

Control Room crosswalk

Live sessions created by fm.connect() appear in Start Screen -> Active simulations, and opening them in the Control Room displays the shared model in Model Explorer, 3D Viewport, Inspector, and Live Charts. See Start Screen & Workspace Hub, Study Authoring, Stages & Interactive Re-Execution, and Control Room capability register for exact panel coverage.

Python/API crosswalk

Exact live transport signatures, event schemas, error hierarchy (LiveModeError, StaleRevisionError, UnsupportedCapabilityError), and HTTP/WebSocket protocol details are maintained in Live Session.

Physics, limitations, and bibliography

Live transport adds no physical equations; governing physics, units, and discretization assumptions are inherited from the active FDM/FEM backend and Relaxation Study, RelaxStop, and add_relax Stage Contract / TimeEvolution Study and add_time Stage Contract.

Source-code index

  • packages/fullmag-py/src/fullmag/live/__init__.py — connect, disconnect, sync, transaction, paused, pause, resume, stop, skip, field, table, on, run_until, sweep, export_script: public live client entry points.

  • packages/fullmag-py/src/fullmag/live/_session.py — LiveSession: HTTP/WebSocket runtime bridge, 10 s presence heartbeat (sessions.heartbeat), chunked predicate execution, and script export.

  • packages/fullmag-py/src/fullmag/live/sweep.py — sweep, SweepResult: parallel multi-group execution across independent DEV group URLs.

  • packages/fullmag-py/src/fullmag/live/jupyter.py — monitor, ScalarMonitor: live Jupyter scalar monitor.

  • packages/fullmag-py/src/fullmag/client/fmvp.py — FieldVector: binary field decoding with .to_numpy(), .as_grid(), and .as_complex().

  • packages/fullmag-py/src/fullmag/client/fmtb.py — TableRows: binary table decoding with .to_numpy(), .column(), and .to_pandas().