From 33557fdf6a041a696cbbf5447724c6ae75d0ed58 Mon Sep 17 00:00:00 2001 From: Rogerio Jorge Date: Wed, 7 Oct 2026 15:14:40 -0500 Subject: [PATCH] PointDipoleField: point dipoles (permanent magnets) with the moments as dofs B(x) = mu0 / (4 pi) sum_j [3 (m_j . r_j) r_j / |r_j|^5 - m_j / |r_j|^3] for dipoles at fixed positions; the moments are the optimization dofs, so the field adds to coils (coils + dipoles) and differentiates with respect to the moments. Named apart from the permanent-magnet DipoleField of #32, which optimizes scalar strengths of fixed orientations through an interaction matrix. The pytree unflattens without __init__, since transforms put non-array leaves in its slots. --- README.md | 2 +- essos/fields.py | 36 ++++++++++++++++++++++++++++++++++++ tests/test_fields.py | 20 ++++++++++++++++++++ 3 files changed, 57 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 740f658e..1c39c232 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ pip install essos `|B|` spectrum and flux functions `iota`, `G` and `I`, with optional collisions. - **Field-line tracing.** Adaptive, arclength and toroidal-angle models, with Poincare sections. -- **Fields.** Biot-Savart from coils, VMEC equilibria (analytic derivatives, +- **Fields.** Biot-Savart from coils, point dipoles (permanent magnets), VMEC equilibria (analytic derivatives, optional `mode_tolerance` truncation) and near-axis expansions. Fields combine as vectors (`coils + other`, `2.0 * field`), and `field.compare(other, points)` measures two fields at the same physical diff --git a/essos/fields.py b/essos/fields.py index 2269c431..adb07e73 100644 --- a/essos/fields.py +++ b/essos/fields.py @@ -687,6 +687,42 @@ def series(c, s): # sum c cos + s sin, and its first two theta derivatives (R, dR, d2R), (Z, dZ, d2Z) = series(rc, rs), series(zc, zs) return R, Z, dR, dZ, d2R, d2Z +class PointDipoleField(MagneticField): + """Point dipoles, such as permanent magnets, in Cartesian coordinates. + + B(x) = mu0 / (4 pi) sum_j [3 (m_j . r_j) r_j / |r_j|^5 - m_j / |r_j|^3], + r_j = x - x_j, for dipoles at ``positions`` (n, 3) [m] with ``moments`` + (n, 3) [A m^2]. The moments are the optimization ``dofs``. + """ + + def __init__(self, positions, moments): + self.positions, self.moments = jnp.asarray(positions), jnp.asarray(moments) + + @property + def dofs(self): + return self.moments + + @dofs.setter + def dofs(self, moments): + self.moments = jnp.asarray(moments) + + @jit + def B(self, points): + r = points - self.positions + r2 = jnp.sum(r * r, axis=1, keepdims=True) + mr = jnp.sum(self.moments * r, axis=1, keepdims=True) + return 1e-7 * jnp.sum((3 * mr * r - r2 * self.moments) / r2**2.5, axis=0) + + +def _unflatten_dipoles(_, children): # without __init__: transforms put non-array leaves here + field = PointDipoleField.__new__(PointDipoleField) + field.positions, field.moments = children + return field + + +tree_util.register_pytree_node(PointDipoleField, lambda f: ((f.positions, f.moments), None), _unflatten_dipoles) + + class near_axis: def __init__(self, *args, **kwargs): raise ImportError( diff --git a/tests/test_fields.py b/tests/test_fields.py index 810d61c1..318b10d1 100644 --- a/tests/test_fields.py +++ b/tests/test_fields.py @@ -573,3 +573,23 @@ def test_field_algebra_and_comparison(): assert jnp.allclose(jax.jit(vmap((0.5 * total).B))(p), 1.5 * B) # weights survive the pytree round trip assert jnp.allclose(coils.compare(coils, p), 0.) assert jnp.allclose(total.compare(coils, p), 2. / 3.) # |3B - B| / |3B| + + +def test_dipole_field_matches_the_axis_formula_and_is_curl_and_divergence_free(): + from essos.fields import PointDipoleField + m = 2.0e3 + field = PointDipoleField(jnp.zeros((1, 3)), jnp.array([[0., 0., m]])) + assert jnp.allclose(field.B(jnp.array([0., 0., 0.5])), jnp.array([0., 0., 1e-7 * 2 * m / 0.5**3])) + J = field.dB_by_dX(jnp.array([0.3, -0.2, 0.4])) + assert jnp.abs(jnp.trace(J)) < 1e-12 * jnp.abs(J).max() and jnp.allclose(J, J.T, atol=1e-12 * jnp.abs(J).max()) + assert jnp.allclose(jax.grad(lambda d: field.__class__(field.positions, d).B(jnp.array([0., 0., 0.5]))[2])(field.dofs), + jnp.array([[0., 0., 1e-7 * 2 / 0.5**3]])) + + +def test_sum_of_coils_and_dipoles_traces_field_lines(): + from essos.dynamics import Tracing + from essos.fields import PointDipoleField + field = _coil_field() + PointDipoleField(jnp.array([[2.0, 0., 0.]]), jnp.array([[0., 0., 1e2]])) + tracing = Tracing(field=field, model="FieldLineAdaptative", initial_conditions=jnp.array([[1.0, 0., 0.]]), + maxtime=1e-6, times_to_trace=5) + assert jnp.all(jnp.isfinite(tracing.trajectories))