First FEM Simulation

Last changes: Documentation changelog

This page runs the finite-element counterpart of the FDM onboarding example. The same film relaxes from a uniform magnetization, but the domain is an unstructured tetrahedral mesh and the magnetostatic field is solved with a Poisson airbox formulation instead of an FFT convolution.

What the example computes

A universe of \(160 \times 160 \times 24\ \mathrm{nm}\) surrounds a \(80 \times 120 \times 8\ \mathrm{nm}\) ferromagnetic film. The film is resolved with \(4\ \mathrm{nm}\) elements while the surrounding air region is coarsened, so the airbox supports the magnetostatic Poisson solve without paying four-nanometer resolution far from the magnet. The demagnetization linear system is solved with a conjugate-gradient method and an algebraic multigrid preconditioner.

Author the study

# %% Author the study
import fullmag as fm

nm = 1.0e-9
study = fm.study("first_fem_simulation")
study.engine("fem")
study.device("cpu", precision="double")
study.mode("strict")

study.universe(mode="manual", size=(160 * nm, 160 * nm, 24 * nm))
study.universe.mesh(maximum_element_size=40 * nm, maximum_element_growth_rate=1.7)

film = study.geometry(
    fm.Box(size=(80 * nm, 120 * nm, 8 * nm), name="film"),
    name="film",
)
film.Ms = 800.0e3
film.Aex = 13.0e-12
film.alpha = 0.1
film.m = fm.init.UniformMagnetization((1.0, 0.0, 0.0))
film.mesh(maximum_element_size=4 * nm, order=1)

study.exchange()
study.demag(realization="poisson_robin")
study.fem_demag_solver(solver="CG", preconditioner="AMG", rtol=1.0e-10, max_iterations=500)
study.build_domain_mesh()

study.stages.add_relax(
    stage_id="relax",
    algorithm="projected_gradient_bb",
    max_steps=2000,
    tolT=5.0e-9,
).tableautosave(
    every_steps=10,
    quantities=["step", "mx", "my", "mz", "e_ex", "e_demag", "e_total", "max_torque_T"],
)

What each part does

  • study.engine("fem") selects the finite-element backend.

  • study.universe.mesh(...) sizes the airbox elements with a growth-rate bound so the magnet is resolved finely while air elements grow away from it.

  • film.mesh(maximum_element_size=4 * nm, order=1) overrides the local element size on the magnetic body.

  • study.demag(realization="poisson_robin") chooses the scalar-potential Poisson demagnetization formulation; the alternative public FEM strategy is the boundary-element method documented on the demagnetization pages.

  • study.fem_demag_solver(...) configures the linear solver for the Poisson system.

  • study.build_domain_mesh() realizes the domain mesh from the universe plus body before lowering.

  • study.stages.add_relax(algorithm="projected_gradient_bb", tolT=5.0e-9, ...) relaxes with the projected Barzilai-Borwein gradient method until the torque magnitude in tesla falls to the requested tolerance or the step budget is spent. This projected-gradient method does not need an LLG timestep, unlike the overdamped stage used on the FDM page.

Run in the Docker DEV group

Save the block inside your checkout (for example as first_fem_simulation.py) after ensuring the container toolchain image is prepared (just docker-dev-toolchain), then run through the Docker Compose DEV group:

just fullmag-dev-container first_fem_simulation.py

If your group is already running with an empty workspace (just docker-dev "$PWD"), activate the script directly with just docker-dev-script first_fem_simulation.py, or attach interactively with fm.connect() (Interactive Live Python & REPL).

The runtime records the resolved backend, device, and precision in the result provenance. To request the FEM GPU lane instead, change the script to study.device("gpu", precision="double"), start the DEV group with GPU access (--gpu-access auto or gpu), and verify the device identity in the produced provenance. Dedicated release/qualification FEM gates preserve their own managed justfile recipes (fem-managed-headless).

Reading the result

max_torque_T is the maximum torque magnitude reported in tesla and is the relaxation stop signal, while e_ex, e_demag and e_total are the exchange, demagnetization and total energies. Autosave tables are scalar time series; mesh and field snapshots are separate artifacts.

Control Room 3D Viewport rendering conformal FEM mesh body and Poisson airbox boundary

Conformal tetrahedral ferromagnet mesh and surrounding Poisson airbox wireframe visualized in the Control Room 3D viewport.

Limits of this example

The finite Robin airbox approximates the exterior magnetostatic problem. This small onboarding domain is not an airbox-convergence study and is not numerically identical to open-boundary FDM convolution. Compare results only after separate mesh and airbox-size convergence checks.

Unstructured-mesh relaxation has stricter tolerance and meshing regimes than the small onboarding grid shown here. μMAG Standard Problem 4 and the analytical validation pages provide the qualification evidence for those regimes. FEM GPU execution requires a managed CUDA runtime and is not claimed by this snippet.

Control Room crosswalk

Use the authoring path stated in this guide, normally Model Explorer -> Objects followed by the relevant Geometry, Material, Physics, Mesh, or Stage panel. Any parameter shown in Python but not shown in that path is TODO: frontend support; do not describe it as configurable in the UI. See Control Room capability register.

Python/API crosswalk

The runnable Python example and exact argument contract are authoritative. If this guide is conceptual or does not contain a runnable example, it explicitly defers to the linked Python API page rather than duplicating an unverified signature.

Physics, limitations, and bibliography

Use the linked physics or numerical-methods page for governing equations and assumptions. This onboarding page does not add a new physical model. Bibliography: see the linked terminal API or physics page; no additional source is claimed here.

Source-code index

  • packages/fullmag-py/src/fullmag/world.py — StudyBuilder, StudyStagesBuilder: stage-first authoring and capture.

  • packages/fullmag-py/src/fullmag/model/problem.py — Problem.to_ir: canonical serialization and validation.

  • justfile — docker-dev-toolchain, docker-dev, docker-dev-script, fullmag-dev-container, fem-managed-headless: container launch and managed FEM execution recipes.

Authoring and IR validation do not establish mesh convergence, solver execution, or GPU parity.