Hysteresis¶

Contract¶

This page records the public Python authoring contract and canonical lowering for the field-sweep hysteresis study type; magnetization dynamics and settle semantics are owned by the dynamics and relaxation pages.

Governing equations¶

Hysteresis sweeps an external field and settles the system between field points; it introduces no independent governing equation. Field-to-H mapping and settle physics are owned by Zeeman and relaxation/dynamics contracts.

Symbols and SI units¶

Field values are authored and displayed in millitesla and stored canonically with a field_unit_provenance record that maps mu0_h / mT to canonical h_ext in \(\mathrm{A\,m^{-1}}\). \(1\) denotes dimensionless data.

Assumptions and validity¶

Constructor checks run immediately. Lowering and planning additionally check sweep monotonicity, expected-branch scheduling, settle-step consistency, mesh cardinality, capability, and backend legality.

Python API¶

The canonical stage entrypoint add_hysteresis_sweep exposes these fields by keyword; the sweep is not constructed as a standalone Hysteresis(...) object in a user script.

# %% Major hysteresis loop with per-point relaxation
import fullmag as fm

nm = 1.0e-9

# %% Study and execution lane
study = fm.study("hysteresis_api_example")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")

# %% Geometry, material, initial state, and interactions
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 = 1.0
film.m = fm.init.UniformMagnetization((1.0, 0.0, 0.0))
study.exchange()

# %% Hysteresis stage over a swept external field
study.stages.add_hysteresis_sweep(
    field_min_mT=-50.0,
    field_max_mT=50.0,
    field_step_mT=2.0,
    direction=(0.0, 0.0, 1.0),
    initial_protocol="positive_saturation",
    branch_mode="major_loop",
)

ProblemIR¶

Hysteresis.to_ir() emits {"kind": "hysteresis", ...} including field_unit_provenance, measurement_axis, initial_protocol, branch_mode, sampling, and the optional sweep/settle extensions. The final column above gives each destination.

Round-trip and failure semantics¶

Requested intent (field schedule, protocol, branch mode, storage) is preserved in Python and IR; resolved execution and the actual settle algorithm are selected by the planner. Validation errors reject zero field steps, non-monotonic schedules, invalid protocols/axes, and inconsistent settle pipelines. Unsupported combinations fail capability checks without silent fallback.

Discrete realization¶

This page owns authoring and lowering only. Settle and dynamics realizations are documented in the relaxation and dynamics numerical pages.

Implementation mapping¶

The adjacent map anchors claims to packages/fullmag-py/src/fullmag/model/study.py (class Hysteresis and its settle/storage helpers) and packages/fullmag-py/src/fullmag/world.py (StudyStagesBuilder.add_hysteresis_sweep).

Validation¶

Ownership tests compare this inventory with live signatures and validate the adjacent source map.

Limitations¶

Settle and storage policies are authoring contracts; executed qualification is backend-dependent and must be reported per lane.

Scientific bibliography¶

Physical model references belong to the Zeeman and dynamics pages; no independent model is introduced here.

Control Room crosswalk¶

Status: Stage authoring and inspection are partial; the stage editor exposes only its advertised fields.

not implemented: frontend support for study parameters not rendered by the stage editor. See Control Room capability register for the support matrix and not implemented policy. Frontend source owner: apps/control-room/src/modules/inspector/panels/StudyStageDraftEditor.tsx (StudyStageDraftEditor).

Source-code index¶