---
title: Zeeman interaction
status: partial
doc_kind: reference
audience: user
owner: fullmag-public-docs
---

(public-docs-physics-interactions-zeeman)=
# Zeeman interaction

The Zeeman interaction couples magnetization to a prescribed external magnetic field. Fullmag
authors the public field as magnetic flux density $\mathbf B_{\mathrm{ext}}$ in tesla and
converts it once to $\mathbf H_{\mathrm{ext}}$ in amperes per metre.

(physics-zeeman-problem-statement)=
## Physical problem

The prescribed field is external input and is not solved self-consistently. This page separates
authored semantics, planner resolution, executable backend lanes, and scientific qualification.

(physics-zeeman-governing-equations)=
## Governing equations

```{math}
:label: eq-public-zeeman-zeeman-conversion
\mathbf H_{\mathrm{ext}}=\frac{\mathbf B_{\mathrm{ext}}}{\mu_0}.
```

```{math}
:label: eq-public-zeeman-zeeman-energy
E_{\mathrm Z}
=
-\mu_0\int_{\Omega_m}\mathbf M\cdot\mathbf H_{\mathrm{ext}}\,\mathrm dV
=
-\int_{\Omega_m}\mathbf M\cdot\mathbf B_{\mathrm{ext}}\,\mathrm dV .
```

The corresponding effective field is exactly the prescribed field:

```{math}
:label: eq-public-zeeman-zeeman-field
\mathbf H_{\mathrm Z}=\mathbf H_{\mathrm{ext}}.
```

A positive field lowers the energy of magnetization aligned with it. Reversing
$\mathbf B_{\mathrm{ext}}$ reverses the field and the signed energy.

(physics-zeeman-symbols-and-si-units)=
## Symbols and SI units

| Symbol | Meaning | SI unit |
|---|---|---:|
| $\mathbf B_{\mathrm{ext}}$ | authored external flux density | $\mathrm T$ |
| $\mathbf H_{\mathrm{ext}}$ | external magnetic field | $\mathrm{A\,m^{-1}}$ |
| $\mathbf M$ | magnetization | $\mathrm{A\,m^{-1}}$ |
| $\mathbf m$ | reduced magnetization | $1$ |
| $E_{\mathrm Z}$ | Zeeman energy | $\mathrm J$ |
| $\mu_0$ | vacuum permeability | $\mathrm{N\,A^{-2}}$ |
| $\Omega_m$ | magnetic domain | not applicable |
| $\mathrm dV$ | volume measure | $\mathrm{m^3}$ |

(physics-zeeman-assumptions-and-validity)=
## Assumptions and validity

`Zeeman` is a prescribed-field interaction. It does not solve Maxwell equations, inductive
coupling, eddy currents, or the field generated by transport current. A zero field is legal.
Spatial maps and antenna/RF drives are separate field-source contracts and must not be
silently represented as a constant vector.

(physics-zeeman-discrete-realization)=
## Backend capability matrix

| Solver | Device | Authoring / IR | Executable realization | Scientific qualification | Exact boundary |
|---|---|---|---|---|---|
| FDM | CPU | `Zeeman(B)` / `study.b_ext(...)` | implemented | analytic sign and scaling tests | uniform field sampled on active cells |
| FDM | GPU | same canonical intent | implemented | device parity is precision-specific | field upload/residency must be recorded |
| FEM | CPU | same canonical intent | implemented | mesh-independent uniform-field oracle | resolved on magnetic nodes/elements |
| FEM | GPU | same canonical intent | implemented | executed-device parity required | no host fallback under strict GPU request |

(physics-zeeman-python-api)=
## Python API and stage-first example

```python
# %% Study, execution lane, and magnetic body
import fullmag as fm

nm = 1.0e-9
study = fm.study("zeeman_reference")
study.engine("fdm")
study.device("cpu", precision="double")
study.mode("strict")
study.objects.mesh.defaults(cell_size=(2 * nm, 2 * nm, 2 * nm))
body = study.geometry(fm.Box(40 * nm, 20 * nm, 4 * nm), name="film")
body.Ms = 8.0e5
body.Aex = 13.0e-12
body.alpha = 0.02
body.m = fm.texture.uniform(1.0, 0.0, 0.0)

study.exchange()
study.b_ext(0.0, 0.0, 0.1)  # tesla
study.stages.add_run(stage_id="precession", until=1.0e-12)
```

(physics-zeeman-validation)=
## Validation boundary

At the audited revision, `Zeeman.__init__` uses `as_vector3`: it validates length and float
conversion, but it does **not** itself reject `NaN` or infinity. Finite-value rejection must
therefore be documented at the `ProblemIR`/planner boundary unless the constructor is hardened.
The recommended code change is to use a finite-vector validator so malformed input fails at the
earliest public boundary.

(physics-zeeman-problem-ir)=
## ProblemIR and observables

```json
{"kind": "zeeman", "B": [0.0, 0.0, 0.08]}
```

Expected observables are `B_ext` in tesla, `H_ext` in $\mathrm{A\,m^{-1}}$, and
`E_ext` in joules. Quantity naming must not obscure the one-time
$\mathbf B/\mu_0$ conversion.

## Required numerical validation

- exact vector conversion $\mathbf H=\mathbf B/\mu_0$;
- uniform macrospin energy for parallel, perpendicular, and antiparallel states;
- odd symmetry under field reversal;
- zero-field exact zero contribution;
- time-dependent precession frequency against the selected LLG $\gamma$ convention;
- matched CPU/GPU field and energy comparisons.

(physics-zeeman-limitations)=
## Limitations and recommended extensions

Add a first-class spatial field-map page and a field-schedule page rather than expanding
`Zeeman(B)` with unrelated payloads. Every extension must state whether its source is sampled at
stage start, every accepted step, or every RHS evaluation.

(physics-zeeman-scientific-bibliography)=
## Scientific bibliography

1. W. F. Brown, *Micromagnetics*, Wiley, 1963.
2. G. Bertotti, *Hysteresis in Magnetism*, Academic Press, 1998.

(physics-zeeman-source-code-index)=

## Control Room crosswalk

This is a navigation page; the selected interaction or foundation is configured by its linked Python API and object/stage editor. The category itself has no standalone control. 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.

## Round-trip and failure semantics

Requested intent preserves the authored model, coefficients, orientations, targets, and execution request. Resolved execution records the selected solver, device, precision, discretization, and capability decision. Validation errors reject malformed or contradictory data before runtime. Unsupported combinations fail closed and are not silently omitted or converted to another interaction.

(physics-zeeman-implementation-mapping)=
## Implementation mapping

Python owns authoring and serialization, ProblemIR owns canonical intent, planners own legality and realization selection, and backend kernels own numerical evaluation.

## Source-code index

| Repository path | Stable symbol / area | Responsibility |
|---|---|---|
| `packages/fullmag-py/src/fullmag/model/energy.py` | `Zeeman` | public constructor and IR |
| `packages/fullmag-py/src/fullmag/_validation.py` | `as_vector3` | current constructor-level vector validation |
| `packages/fullmag-py/src/fullmag/world.py` | `b_ext` | stage-first field authoring |
| `crates/fullmag-plan/src/fdm.rs` | `Zeeman planning` | FDM resolution |
| `crates/fullmag-plan/src/fem.rs` | `Zeeman planning` | FEM resolution |
| `crates/fullmag-engine/src/fdm/cpu/fields.rs` | `Zeeman field` | FDM CPU reference |
| `backends/fdm/gpu/cuda/interactions` | `Zeeman kernels` | FDM GPU |
| `backends/fem/cpu/mfem/interactions` | `Zeeman field` | FEM CPU |
| `backends/fem/gpu/cuda/interactions` | `Zeeman kernels` | FEM GPU |

(physics-zeeman-round-trip-and-failure-semantics)=