Ferromagnet¶

Contract¶

Ferromagnet binds one geometry, one magnetic material, an initial state, optional object-local mesh/region data, and object-scoped constraints. The stage-first study.geometry(...) facade is the normal user workflow; the constructor remains the canonical class API and serialization owner.

Governing equations¶

This object introduces no independent field equation. It defines ownership and identity for the magnetic domain consumed by interactions and dynamics.

Symbols and SI units¶

Geometry lengths use metres. Material parameters retain their interaction-specific SI units. Magnetization textures and region/constraint identities are dimensionless semantic data.

Assumptions and validity¶

Names and optional object_id values are non-empty. A supplied Region must refer to the same geometry. When m0 is omitted, the constructor installs uniform \(+x\) magnetization. Planner validation owns mesh, region, material-field, and constraint realization.

Python API¶

# %% Ferromagnet authoring
import fullmag as fm

nm = 1.0e-9
study = fm.study("ferromagnet_api_example")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")
study.objects.mesh.defaults(cell_size=(2 * nm, 2 * nm, 5 * nm))
film = study.geometry(fm.Box(100 * nm, 20 * nm, 5 * nm), name="film")
film.Ms = 800.0e3
film.Aex = 13.0e-12
film.alpha = 0.02
film.m = fm.texture.uniform(1.0, 0.0, 0.0)
study.exchange()
study.stages.add_run(stage_id="run", until=1.0e-12)

ProblemIR¶

The magnet record preserves object identity, material binding, region, initial magnetization, mesh recipe, and absorbing-boundary data. Object regions, fields, and constraints retain separate typed ownership rather than being flattened into the magnet name.

Round-trip and failure semantics¶

Requested intent preserves object IDs, region ownership, material bindings, texture versions, mesh recipes, and constraint identities. Resolved execution adds concrete cell/element ownership, normalized data, masks, solver, device, and precision without replacing authored intent. Validation errors reject unknown references, duplicate identities, mismatched region geometry, and malformed data. Unsupported combinations fail closed and are not silently omitted or converted.

Discrete realization¶

FDM realizes the object as active cells; FEM realizes it as marked magnetic elements/nodes. The constructor does not prove either mesh or device lane executable.

Implementation mapping¶

packages/fullmag-py/src/fullmag/model/structure.py, class Ferromagnet, owns construction, default state, object identity, constraint accumulation, and magnet-record lowering.

Validation¶

Tests compare this complete parameter inventory with inspect.signature(Ferromagnet) and validate the adjacent source map.

Limitations¶

The underscore-prefixed accumulator is exposed by the dataclass signature but is not the preferred user API. Use typed constraint helpers and stage/problem authoring rather than mutating it directly.

Scientific bibliography¶

No new physical model is introduced; references belong to the interactions consuming the magnet.

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).

Source-code index¶