Periodic Demagnetization¶

Physical problem¶

Periodic axes identify corresponding degrees of freedom or image cells. The treatment of the zero-wave-number mode and the remaining open axes determines whether a scalar potential is unique. The periodic request therefore has three independent parts: the periodic equivalence relation, the finite image or reduced-space realization, and the zero-mode/gauge policy. Changing one of these changes the discrete magnetostatic problem.

Governing equations¶

Symbols and SI units¶

Assumptions and validity¶

Periodic FEM currently requires at least one open axis and a declared zero-mode policy. FDM truncated_images is a finite approximation to an infinite image sum. Fully periodic 3-D FEM and FDM periodic_airbox_k0 are not interchangeable.

Python API¶

The complete stage-first scenario below requests an FDM film that is periodic in-plane and uses four translated demagnetization images on each periodic axis. The relaxation stage records both the demagnetization energy and field so that increasing images can be treated as a convergence study rather than as an undocumented solver setting.

# %% Imports and units
import fullmag as fm

nm = 1.0e-9

# %% Study, execution lane, and periodic grid
study = fm.study("periodic_demag_convergence")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")
study.objects.mesh.defaults(cell_size=(3 * nm, 3 * nm, 4 * nm))
study.pbc(
    x=True,
    y=True,
    z=False,
    demag="truncated_images",
    images=(4, 4, 0),
)

# %% Geometry, material, initial state, and interactions
film = study.geometry(
    fm.Box(size=(96 * nm, 48 * nm, 4 * nm), name="film"),
    name="film",
)
film.Ms = 8.0e5
film.Aex = 1.3e-11
film.alpha = 0.02
film.m = fm.init.UniformMagnetization((1.0, 0.1, 0.0))
study.exchange()
study.demag()

# %% Ordered relaxation stage and reproducible observables
study.stages.add_relax(
    stage_id="relax",
    algorithm="projected_gradient_bb",
    max_steps=500,
    tolT=1.0e-6,
).autosave(
    fm.StageAutosave(
        table=fm.TableAutosave(
            every_steps=10,
            quantities=[
                "step",
                "mx",
                "my",
                "mz",
                "e_demag",
                "e_total",
                "max_torque_T",
            ],
        ),
        fields=[fm.FieldAutosave("H_demag", every_steps=20)],
    )
)

ProblemIR¶

FdmPbc.to_ir() writes periodic/open axis names and the selected demag policy. The planner rejects periodic_airbox_k0 for FDM and validates the FEM periodic reduction separately.

Round-trip and failure semantics¶

Requested intent is preserved even when unsupported. Resolved execution is recorded separately. Periodic axes with an incompatible open policy, fully periodic FEM, and invalid image counts are validation errors; unsupported combinations are never silently changed to open boundaries.

For a fully periodic direction, the mean potential is not determined by the gradient field. The planner must either remove the constant null mode or apply an explicitly recorded gauge. A finite FDM image count is not a gauge choice: it controls truncation of the image sum. For FEM, periodic representative identification changes the matrix topology and the right-hand side before the linear solve.

Discrete realization¶

FDM sums a finite set of translated kernels. FEM identifies mesh classes, reduces the operator and right-hand side, solves the reduced problem, and lifts the potential to the full mesh.

Zero mode and convergence evidence¶

For FDM, report the image truncation sequence and the observable convergence of both field and energy. For FEM, report the reduced-system residual, the gauge/null-space policy, open-axis solvability, and continuity of the lifted field. A periodic result without a zero-mode policy is not reproducible even when the final energy is finite.

Implementation mapping¶

FdmPbc owns Python validation. FDM periodic spectra are computed separately from open spectra; FEM periodic reduction is implemented by solve_demag_periodic_poisson_reduced.

Validation¶

Increase image counts for FDM and compare against a larger reference. For FEM test representative identification, open-axis solvability, residuals, lifted-field continuity, and field-energy parity.

Limitations¶

Finite FDM images are not an exact Ewald or infinite periodic sum. The FEM periodic production gate must be reported independently of historical artifact validation.

Scientific bibliography¶

• FullMag internal references: docs/physics/0800-fem-static-pbc-demag.md and docs/physics/0823-native-fem-cpu-pbc-reduced-warm-start.md.

Control Room crosswalk¶

Use Model Explorer -> Objects -> <object> -> Physics when PhysicsInteractionPanel exposes the interaction. Status: partial. frontend support is not implemented applies to physical parameters without a matching control. See {doc}/frontend/capability-register; do not infer UI support from backend or Python availability.

Python/API crosswalk¶

The linked Python API page is authoritative for exact functions, arguments, units, and failure semantics. If this page is a foundation or category overview, runnable Python is ot applicable here and must be taken from the terminal API page.

Bibliography and source scope¶

Use the scientific bibliography and source-code index on the linked terminal page. This block adds no new equation or unverified implementation claim.

Source-code index¶