Mumax3 Texture Compatibility¶

Physical problem¶

Fullmag exposes the analytic initial-magnetization configurations listed in the pinned Mumax3 submodule revision f656494b29516bead825b444b1f0b38c6e6c7dbf, subject to the explicit exceptions below. The names refer to the public Python factories and the version-2 canonical Rust sampler used by both FEM and FDM planning. The canonical physics contract is docs/physics/0531-versioned-magnetic-preset-textures.md.

Fullmag additionally provides antiskyrmion, skyrmionium, bimeron, domain_wall, and a stereographic hopfion initializer. These are Fullmag extensions rather than named Mumax3 Config constructors.

Governing equations¶

Mumax3-compatible vortex wall¶

The complete stage-first Python scenario below constructs fm.texture.vortex_wall(wall_half_width=25e-9, left_mx=1, right_mx=-1, circulation=1, core_polarity=1, core_radius=2e-9).

For local coordinate \(u\), Fullmag returns the normalized left domain for \(u<-w\), the normalized right domain for \(u>w\), and its version-2 vortex profile in the central interval. Mumax3 derives \(w\) from half the simulation width; Fullmag makes that physical scale explicit so the same texture is reproducible for FEM and FDM meshes. When circulation is omitted, Fullmag derives its sign from left_mx * right_mx, matching the domain orientation; an explicit -1 or 1 overrides that compatibility default. Upstream VortexWall returns raw vectors (mleft, 0, 0) and (mright, 0, 0), after which magnetization.SetArray normalizes the field. Therefore every finite nonzero authored magnitude reduces to its sign; preserving 0.5 as a final x component would not match Mumax3. Fullmag rejects zero explicitly because its canonical reduced-magnetization field must be unit length.

Compact-support hopfion¶

The same executable scenario constructs fm.texture.hopfion_compact_support(major_radius=20e-9, minor_radius=8e-9).

For \(\psi=\operatorname{atan2}(y,x)\), the toroidal radial coordinate is \(a_H=x\cos\psi+y\sin\psi-R\) and \(\rho=\sqrt{z^2+a_H^2}\); the interior profile is

The implemented toroidal profile is exactly uniform \(+\hat{\mathbf z}\) for \(\rho\geq r\), including the support boundary. At the torus centreline, the magnetization is \(-\hat{\mathbf z}\). The profile is three-dimensional and therefore requires mapping.projection="object_local".

Symbols and SI units¶

Assumptions and validity¶

Both profiles define reduced initial magnetization, not an energy term, equilibrium solution, or time integrator. Lengths are authored in SI metres and must remain independent of mesh resolution. The vortex-wall exterior uses only the sign of each nonzero authored domain component because the resolved magnetization is normalized. The compact-hopfion denominator is evaluated only for \(\rho<r\); the support boundary belongs to the exact uniform exterior.

Python API and parameters¶

# %%
import fullmag as fm

# %%
wall = fm.texture.vortex_wall(
    wall_half_width=25e-9,
    left_mx=1.0,
    right_mx=-1.0,
    circulation=1,
    core_polarity=1,
    core_radius=2e-9,
)
compact_hopfion = fm.texture.hopfion_compact_support(
    major_radius=20e-9,
    minor_radius=8e-9,
)

study = fm.study("mumax3_texture_compatibility")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")
study.universe(mode="manual", size=(200e-9, 100e-9, 10e-9))
study.objects.mesh.defaults(cell_size=(4e-9, 4e-9, 5e-9))
film = study.geometry(
    fm.Box(size=(160e-9, 80e-9, 5e-9), name="film"),
    name="film",
)
film.Ms = 8.0e5
film.Aex = 1.3e-11
film.m = wall
# To initialize a three-dimensional object instead, assign compact_hopfion.
study.demag(realization="auto")
study.stages.add_save_state(
    artifact_name="initial-m.zarr",
    format="zarr",
    dataset="m",
)

ProblemIR lowering¶

Both factories lower to kind="preset_texture", preset_version=2, the listed preset_params, a versioned mapping descriptor, and a texture transform. The Python factory names are authoring helpers; the canonical serialized names are vortex_wall and hopfion_compact_support. Browser authoring lowers to the same descriptors. Its Python export uses the generic fm.PresetTexture(...) form so ui_label, mapping, transform, preview metadata, and every authored parameter round-trip unchanged; a factory-authored texture without extra metadata may use the shorter factory call.

Round-trip, provenance, and failure semantics¶

The requested intent preserves the preset kind, version, authored SI parameters, mapping, and transform. Resolved execution records the selected solver, device, precision, and materialization path without rewriting those semantics. Validation errors reject invalid scales, signs, planes, mappings, or versions before sampling. Unsupported combinations, including a three-dimensional hopfion without object_local projection, fail explicitly instead of falling back to another preset or uniform magnetization. Python, UI, ProblemIR, session state, and exported Python must round-trip every authored parameter unchanged.

Discrete realization and backend semantics¶

The planner samples the same version-2 descriptor at FDM cell centres or FEM magnetic mesh points. CPU and GPU lanes consume that materialized vector field; there is no backend-specific reinterpretation of either profile. The preset descriptor, requested version, mapping, transform, resolved solver, device, and precision remain part of the ProblemIR and execution provenance. These initial conditions do not claim an equilibrium state or qualify later LLG dynamics.

Invalid scales, signs, planes, mappings, or versions fail before materialization. There is no fallback to a different preset or to a uniform state. CurrentMag remains runtime state transfer rather than an analytic preset because its value depends on a resolved mesh and session state.

Implementation mapping¶

• Rust evaluator: crates/fullmag-plan/src/magnetization_textures_v2.rs, symbols vortex_wall and hopfion_compact_support.

• Python factories and reference evaluator: packages/fullmag-py/src/fullmag/init/textures.py and preset_eval_v2.py.

• Rust/Python parity: the shared 1000-point fixture crates/fullmag-plan/tests/fixtures/magnetization_textures_v2_parity.json, consumed by crates/fullmag-plan/tests/magnetization_textures_v2_parity.rs and packages/fullmag-py/tests/test_preset_texture_v2_parity.py.

• Browser registry and round-trip: apps/control-room/src/shared/domain/magnetization-texture/texturePresets.ts and ObjectMagneticTexturePanelModel.mumax3.test.ts.

The compatibility equations are mapped directly to the immutable upstream Mumax3 submodule file external_solvers/3/engine/config.go at f656494b29516bead825b444b1f0b38c6e6c7dbf and compared by the shared Rust/Python fixture named above. Fullmag replaces Mumax3’s mesh-derived vortex core and world-derived wall half-width with explicit SI parameters; this is a deliberate reproducibility adaptation, not bitwise sampling parity.

Validation¶

Rust contract tests check both uniform wall domains, the central vortex core, exact compact-support boundary values, exterior values, and unit norm. Python tests check factory validation and component parity. Control Room tests check registry completeness, default hydration, serialization, and version preservation. Public examples and the scientific source-map validator run in CI. GPU runtime qualification remains separate because the planner materializes the shared field before device execution.

Limitations and deferred qualification¶

“Mumax3-compatible” means matching the analytic family and parameter signs while making mesh-derived lengths explicit. It does not promise bitwise equality with Mumax3’s grid-dependent vortex core, automatic world-size lookup, random-number stream, or later solver trajectory. The profiles are initial conditions and require an independent relaxation or dynamics qualification for a scientific study.

Scientific bibliography¶

1. Mumax3, engine/config.go, VortexWall and HopfionCompactSupport, https://github.com/mumax/3/blob/f656494b29516bead825b444b1f0b38c6e6c7dbf/engine/config.go.

2. A. Vansteenkiste et al., The design and verification of MuMax3, AIP Advances 4, 107133 (2014), https://doi.org/10.1063/1.4899186.

Current magnetization¶

Mumax3 CurrentMag() snapshots the current mesh magnetization and exposes it as another configuration. Fullmag represents the same operation through explicit runtime state: stage-to-stage continuation, interactive-session state, and checkpoint restore. It is intentionally not presented as an analytic texture preset because its value depends on a specific resolved mesh and simulation state.

Control Room crosswalk¶

Status: The exposed texture families are partial; unlisted presets remain Python-only.

frontend support is not implemented for texture presets and arguments not exposed by ObjectMagneticTexturePanel. See Control Room capability register for the support matrix and not implemented policy. Frontend source owner: apps/control-room/src/modules/inspector/panels/ObjectMagneticTexturePanel.tsx (ObjectMagneticTexturePanel).

Python API¶

The complete runnable example is in the numbered example section below; the exact callable fields and arguments are in the numbered API section. These values are copied from the current Python contract, not inferred from the UI.

Source-code index¶