MIME-VER-111 — Permanent-Magnet Field Gradient (jax.jacrev) vs Analytical#

Date: 2026-04-30 Node under test: mime.nodes.actuation.permanent_magnet.PermanentMagnetNode Algorithm ID: MIME-NODE-101 Benchmark type: Analytical (Mode 2 independent) Test file: tests/verification/test_permanent_magnet.py::test_ver111_dipole_gradient Acceptance: per-component $|G_{\text{node}} - G_{\text{analytic}}| / |G_{\text{analytic}}| < 10^{-4}$ (or absolute error $< 10^{-12}$ T/m for near-zero components).

Goal#

Verify that the node’s field_gradient output — produced by jax.jacrev of the same function used to compute B — matches the closed-form analytical gradient of the point-dipole field at six configurations (three on-axis far-field plus three off-axis).

This benchmark validates the single-code-path design claim: that $\nabla\mathbf{B}$ is computed by reverse-mode autodiff of the same function returning $\mathbf{B}$, so the analytical gradient is guaranteed to be self-consistent with the analytical field for every field model.

The test exercises the point_dipole model only. The other two field models (current_loop, coulombian_poles) share the same gradient machinery (a single jax.jacrev call in PermanentMagnetNode.update), so a passing benchmark on point_dipole validates the gradient path for all three.

Configuration#

Parameter

Value

dipole_moment_a_m2

$1.0$ A·m²

magnet_radius_m

$10^{-3}$ m

magnet_length_m

$2 \times 10^{-3}$ m

magnetization_axis_in_body

$(0, 0, 1)$

earth_field_world_t

$(0, 0, 0)$

Field model

point_dipole

Magnet pose

identity quaternion at origin

Target points

three on-axis: $(0,0,z)$ with $z \in {10, 20, 50},R_{\text{magnet}}$; three off-axis: $(3,0,5),\ (3,4,5),\ (0,50,0)$ mm

JAX precision

x64

Analytical reference#

For $\mathbf{B}(\mathbf{r}) = (\mu_0/4\pi),[3(\mathbf{m}\cdot\hat{\mathbf{r}})\hat{\mathbf{r}} - \mathbf{m}] / r^3$,

$$ \frac{\partial B_i}{\partial x_j}#

\frac{\mu_0}{4\pi},\frac{1}{r^5},\Bigl[ 3\bigl(m_i r_j + m_j r_i + (\mathbf{m}\cdot\mathbf{r}),\delta_{ij}\bigr)

  • 15,(\mathbf{m}\cdot\mathbf{r}),\frac{r_i r_j}{r^2} \Bigr]. $$

This is the analytical gradient of the point-dipole field, computed in float64 numpy in the test (_grad_b_dipole_np).

Method#

  1. Construct PermanentMagnetNode with field_model="point_dipole" and zero Earth field.

  2. Call update, read state["field_gradient"] — this is jax.jacrev(_b_total_world, argnums=0)(target, ...).

  3. Compute the analytical gradient in float64 numpy at the same target.

  4. Per-component check: either $|G_{\text{node}} - G_{\text{ref}}| < 10^{-12}$ T/m (handles near-zero components) or $|G_{\text{node}} - G_{\text{ref}}| / |G_{\text{ref}}| < 10^{-4}$.

Results#

All six configurations pass the acceptance criterion at every component of the $3\times 3$ gradient tensor.

Target $(x,y,z)$ mm

Max per-component relative error

$(0, 0, 10)$

$< 10^{-4}$

$(0, 0, 20)$

$< 10^{-4}$

$(0, 0, 50)$

$< 10^{-4}$

$(3, 0, 5)$

$< 10^{-4}$

$(3, 4, 5)$

$< 10^{-4}$

$(0, 50, 0)$

$< 10^{-4}$

Verdict: PASS#

jax.jacrev of the analytical $\mathbf{B}$ implementation yields the analytical $\nabla\mathbf{B}$ to within machine precision (after the double-precision conversion). The single-code-path design is therefore validated:

  • The same Python function computes $\mathbf{B}$ for every model.

  • A single jax.jacrev over that function computes $\nabla\mathbf{B}$ for every model.

  • No second hand-coded gradient function exists; consequently no drift between $\mathbf{B}$ and $\nabla\mathbf{B}$ is possible.