Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 14 additions & 1 deletion essos/dynamics.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
from pyexpat import model
import copy
import os
import jax
jax.config.update("jax_enable_x64", True)
Expand All @@ -22,7 +23,7 @@
import diffrax
import optimistix as optx
from essos.coils import Coils
from essos.fields import BiotSavart, ExternalField, MagneticField, is_toroidal
from essos.fields import BiotSavart, ExternalField, MagneticField, NearAxisField, is_toroidal
from essos.surfaces import SurfaceClassifier
from essos.electric_field import Electric_field_flux, Electric_field_zero
from essos.constants import ALPHA_PARTICLE_MASS, ALPHA_PARTICLE_CHARGE, FUSION_ALPHA_PARTICLE_ENERGY,ELEMENTARY_CHARGE,SPEED_OF_LIGHT
Expand Down Expand Up @@ -943,6 +944,18 @@ def __init__(self, trajectories_input=None, initial_conditions=None, times_to_tr
else:
self.electric_field=electric_field

full_orbit = model is not None and model.startswith('FullOrbit')
if full_orbit and isinstance(getattr(field, "fields", (field,))[0], NearAxisField):
raise ValueError("full orbits need B at Cartesian points, which a near-axis field does not invert to")
if full_orbit and is_toroidal(field):
# Full orbits move in Cartesian space: trace them in the Cartesian view of the field, from the
# Cartesian position of each guiding center given in (s, theta, phi), up to the boundary s = 1.
toroidal, particles = field, copy.copy(particles)
particles.initial_xyz = vmap(field.to_xyz)(particles.initial_xyz)
field = field.cartesian()
particles.to_full_orbit(field)
if condition is None and stopping_criteria is None:
condition = lambda t, y, args, **kwargs: 1.0 - toroidal.flux_coordinates(y[:3])[0][0]
if isinstance(field, Coils):
self.field = BiotSavart(field)
else:
Expand Down
190 changes: 185 additions & 5 deletions essos/fields.py
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,10 @@ def difference(point):
return jnp.linalg.norm(B - other.B_xyz(self.to_xyz(point))) / jnp.linalg.norm(B)
return vmap(difference)(points)

def cartesian(self):
"""This field in Cartesian coordinates, B(x) = :meth:`B_xyz`: the field full orbits move in."""
return ExternalField(lambda xyz: vmap(self.B_xyz)(xyz))

def __add__(self, other):
return CombinedField(self, other)

Expand Down Expand Up @@ -389,6 +393,13 @@ def d(f):
values = vmap(lambda t: jnp.stack([rz(t), d(rz)(t), d(d(rz))(t)]))(jnp.ravel(theta))
return tuple(values[:, i, j].reshape(jnp.shape(theta)) for i in range(3) for j in range(2))

def _minor_radius(self):
"""Radius of the circle with the mean area of the boundary cross-sections of one field period."""
theta = jnp.linspace(0, 2 * jnp.pi, 128, endpoint=False)
R, Z, dR, dZ = vmap(lambda phi: jnp.stack(self._boundary_rz(theta, phi)[:4]), out_axes=1)(
jnp.linspace(0, 2 * jnp.pi / self.nfp, 8, endpoint=False))
return jnp.sqrt(jnp.abs(jnp.mean(R * dZ - Z * dR)))

@jit
def boundary_distance(self, xyz):
"""Signed distance [m] from a Cartesian point to the LCFS, in its phi = const plane.
Expand Down Expand Up @@ -718,11 +729,8 @@ class MRXField(ToroidalField):

def __init__(self, raw, basis, Phi, nfp, Aminor_p=None):
self.raw, self.basis, self.Phi, self.nfp, self.Aminor_p = raw, basis, Phi, int(nfp), Aminor_p
if Aminor_p is None: # radius of the circle with the mean boundary cross-section area
theta = jnp.linspace(0, 2 * jnp.pi, 128, endpoint=False)
R, Z, dR, dZ = vmap(lambda phi: jnp.stack(self._boundary_rz(theta, phi)[:4]), out_axes=1)(
jnp.linspace(0, 2 * jnp.pi / self.nfp, 8, endpoint=False))
self.Aminor_p = jnp.sqrt(jnp.abs(jnp.mean(R * dZ - Z * dR)))
if Aminor_p is None:
self.Aminor_p = self._minor_radius()

@classmethod
def from_mrx(cls, geometry, checkpoint=None, resolution=(12, 16, 16), degree=3):
Expand Down Expand Up @@ -810,6 +818,123 @@ def _tree_unflatten(cls, aux_data, children):
tree_util.register_pytree_node(MRXField, MRXField._tree_flatten, MRXField._tree_unflatten)


def _hermite(x, values):
"""Cubic Hermite interpolation of ``values`` given on a uniform grid of [0, 1], with centred-difference slopes."""
n = len(values) - 1
slope = jnp.gradient(values)
i = jnp.clip(jnp.floor(x * n).astype(int), 0, n - 1)
t = x * n - i
return ((1 + 2 * t) * (1 - t)**2 * values[i] + t * (1 - t)**2 * slope[i]
+ t * t * (3 - 2 * t) * values[i + 1] + t * t * (t - 1) * slope[i + 1])


def _fourier_zernike(c, modes, rho, theta, zeta, nfp):
"""sum_k c_k R_k(rho) F(m_k theta) F(n_k nfp zeta) of a DESC Fourier-Zernike series with modes (l, m, n).

R_k = (-1)^j rho^|m| P_j^(|m|, 0)(1 - 2 rho^2), j = (l - |m|) / 2, with the
Jacobi polynomial from its three-term recurrence (stable at high l), and
F(k x) = cos(k x) for k >= 0, sin(|k| x) for k < 0, as in DESC.
"""
l, m, n = (np.asarray(modes)[:, i] for i in range(3))
a, j = np.abs(m), (l - np.abs(m)) // 2
x = 1 - 2 * rho**2
P_prev, P = 0. * a, 1. + 0. * a
radial = jnp.where(j == 0, P, 0.)
for k in range(int(j.max(initial=0))):
if k == 0:
P_prev, P = P, (a + 1) + (a + 2) * (x - 1) / 2
else:
b = 2 * k + a
P_prev, P = P, ((b + 1) * (b * (b + 2) * x + a**2) * P - 2 * k * (k + a) * (b + 2) * P_prev) / (
2 * (k + 1) * (k + a + 1) * b)
radial = jnp.where(j == k + 1, P, radial)
angle = lambda k, x: jnp.where(k >= 0, jnp.cos(np.abs(k) * x), jnp.sin(np.abs(k) * x))
return jnp.sum(c * (-1.)**j * rho**a * radial * angle(m, theta) * angle(n, nfp * zeta))


@tree_util.register_static
class DescField(ToroidalField):
"""A DESC equilibrium (https://github.com/PlasmaControl/DESC) in the coordinates of :class:`ToroidalField`.

DESC writes R, Z and the stream function lambda as Fourier-Zernike
series in (rho, theta, zeta), with zeta the cylindrical angle. Here
(s, theta, phi) = (rho^2, theta, zeta). With the toroidal flux ``Psi`` and
sqrt(g) the Jacobian of ``to_xyz`` in (s, theta, phi),

B^s = 0, B^theta = Psi (iota - d_phi lambda) / (2 pi sqrt(g)),
B^phi = Psi (1 + d_theta lambda) / (2 pi sqrt(g)).

The series are evaluated as DESC writes them, so the field is exact on
the axis. ``iota`` holds the rotational transform on a uniform grid in rho
from 0 to 1, interpolated by cubic Hermite polynomials (continuous
derivative, as guiding centers need). :meth:`from_desc` builds the field from a DESC
equilibrium or file, or from the ``.npz`` that :meth:`save` writes, which
needs no DESC install.
"""

def __init__(self, R_lmn, Z_lmn, L_lmn, R_modes, Z_modes, L_modes, Psi, nfp, iota):
self.coefficients = tuple(jnp.asarray(c) for c in (R_lmn, Z_lmn, L_lmn))
self.modes = tuple(np.asarray(m, dtype=int) for m in (R_modes, Z_modes, L_modes))
self.Psi, self.nfp, self.iota = float(Psi), int(nfp), jnp.asarray(iota)
self.Aminor_p = self._minor_radius()

@classmethod
def from_desc(cls, source):
"""The field of a DESC ``Equilibrium``, of a DESC output file (both need DESC), or of an ``.npz`` from :meth:`save`."""
if isinstance(source, str) and source.endswith(".npz"):
data = np.load(source)
return cls(*(data[k] for k in ("R_lmn", "Z_lmn", "L_lmn", "R_modes", "Z_modes", "L_modes", "Psi", "nfp", "iota")))
if isinstance(source, str):
import desc.io
source = desc.io.load(source)
source = source[-1] if hasattr(source, "__len__") else source # the last of a solve sequence
from desc.grid import LinearGrid
grid = LinearGrid(rho=np.linspace(0, 1, 1025), M=source.M_grid, N=source.N_grid, NFP=source.NFP)
iota = grid.compress(source.compute("iota", grid=grid)["iota"])
return cls(source.R_lmn, source.Z_lmn, source.L_lmn, source.R_basis.modes, source.Z_basis.modes,
source.L_basis.modes, source.Psi, source.NFP, iota)

def save(self, path):
"""Write the field to an ``.npz`` that :meth:`from_desc` reads without DESC."""
np.savez(path, **dict(zip(("R_lmn", "Z_lmn", "L_lmn"), self.coefficients)),
**dict(zip(("R_modes", "Z_modes", "L_modes"), self.modes)), Psi=self.Psi, nfp=self.nfp, iota=self.iota)

def _series(self, i, points):
s, theta, phi = points
return _fourier_zernike(self.coefficients[i], self.modes[i], jnp.sqrt(s), theta, phi, self.nfp)

@jit
def to_xyz(self, points):
R, Z = self._series(0, points), self._series(1, points)
return jnp.array([R * jnp.cos(points[2]), R * jnp.sin(points[2]), Z])

def _frame(self, points):
e = jacfwd(self.to_xyz)(points)
sqrtg = jnp.linalg.det(e)
dlambda = jax.grad(lambda p: self._series(2, p))(points)
iota = _hermite(jnp.sqrt(points[0]), self.iota)
B_con = self.Psi / (2 * jnp.pi * sqrtg) * jnp.array([0., iota - dlambda[2], 1 + dlambda[1]])
return e, sqrtg, B_con

@jit
def sqrtg(self, points):
return self._frame(points)[1]

@jit
def B_contravariant(self, points):
return self._frame(points)[2]

@jit
def B(self, points):
e, _, B_con = self._frame(points)
return e @ B_con

@jit
def B_covariant(self, points):
e, _, B_con = self._frame(points)
return e.T @ (e @ B_con)


class PointDipoleField(MagneticField):
"""Point dipoles, such as permanent magnets, in Cartesian coordinates.

Expand Down Expand Up @@ -846,6 +971,61 @@ def _unflatten_dipoles(_, children): # without __init__: transforms put non-arr
tree_util.register_pytree_node(PointDipoleField, lambda f: ((f.positions, f.moments), None), _unflatten_dipoles)


@tree_util.register_static
class NearAxisField(MagneticField):
"""A first-order near-axis field from pyQSC_JAX, in its Boozer coordinates (r, theta, varphi).

``qsc`` is a ``pyqsc_jax.near_axis.near_axis``. Its covariant and
contravariant components, |B| and Jacobian are used as they are, so
guiding centers and field lines follow the expansion exactly. ``to_xyz``
places a point at r X n + r Y b off the axis in its Frenet frame at the
axis angle phi0(varphi); it is first order in r like the field, so the
Cartesian ``B`` agrees with the components to O(r). (r, theta) is
singular on the axis, so orbits must stay off it, and full orbits, which
need B at Cartesian points, are not available.
"""

def __init__(self, qsc):
self.qsc, self.nfp = qsc, int(qsc.nfp)

@jit
def B_covariant(self, points):
return self.qsc.B_covariant(points)

@jit
def B_contravariant(self, points):
return self.qsc.B_contravariant(points)

@jit
def AbsB(self, points):
return self.qsc.AbsB(points)

@jit
def sqrtg(self, points):
return self.qsc.jacobian(points)

@jit
def to_xyz(self, points):
r, theta, varphi = points
q, period = self.qsc, 2 * jnp.pi / self.nfp

def at(a, x): # periodic linear interpolation of a quantity on the axis grid
return jnp.interp(x, jnp.append(q.phi, period), jnp.append(a, a[0]), period=period)
shift = period * jnp.floor(varphi / period) # phi0 - varphi is periodic, phi0 itself is not
phi0 = shift + jnp.interp(varphi - shift, jnp.append(q.varphi, period), jnp.append(q.phi, period))
X, Y = (r * (at(c1, phi0) * jnp.cos(theta) + at(s1, phi0) * jnp.sin(theta))
for c1, s1 in ((q.X1c_untwisted, q.X1s_untwisted), (q.Y1c_untwisted, q.Y1s_untwisted)))
R = at(q.R0, phi0) + X * at(q.normal_R, phi0) + Y * at(q.binormal_R, phi0)
P = X * at(q.normal_phi, phi0) + Y * at(q.binormal_phi, phi0) # displacement along phi-hat
Z = at(q.Z0, phi0) + X * at(q.normal_z, phi0) + Y * at(q.binormal_z, phi0)
c, s = jnp.cos(phi0), jnp.sin(phi0)
return jnp.array([R * c - P * s, R * s + P * c, Z])

@jit
def B(self, points):
return jacfwd(self.to_xyz)(points) @ self.B_contravariant(points)


class near_axis:
def __init__(self, *args, **kwargs):
raise ImportError(
Expand Down
62 changes: 62 additions & 0 deletions tests/test_fields.py
Original file line number Diff line number Diff line change
Expand Up @@ -631,3 +631,65 @@ def test_sum_of_coils_and_dipoles_traces_field_lines():
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))


def test_fourier_zernike_radial_polynomials_match_closed_forms():
from essos.fields import _fourier_zernike
rho = jnp.linspace(0.05, 1.0, 7)
for l, m, closed in ((4, 2, lambda r: 4 * r**4 - 3 * r**2), (5, -1, lambda r: 10 * r**5 - 12 * r**3 + 3 * r),
(6, 0, lambda r: 20 * r**6 - 30 * r**4 + 12 * r**2 - 1)):
value = vmap(lambda r: _fourier_zernike(jnp.ones(1), [[l, m, 0]], r, 0.3, 0.0, 1))(rho)
angle = jnp.cos(abs(m) * 0.3) if m >= 0 else jnp.sin(abs(m) * 0.3)
assert jnp.allclose(value, closed(rho) * angle, rtol=1e-12)


def _synthetic_desc(tmp_path=None):
from essos.fields import DescField
R_modes, R = [[0, 0, 0], [1, 1, 0], [2, 2, 1]], [1.0, 0.2, 0.02]
Z_modes, Z = [[1, -1, 0], [2, -2, -1]], [0.25, 0.02]
L_modes, L = [[2, 2, 1], [3, -1, -1]], [0.01, -0.005]
iota = 0.4 + 0.1 * jnp.linspace(0, 1, 65)**2
return DescField(R, Z, L, R_modes, Z_modes, L_modes, Psi=0.1, nfp=3, iota=iota)


def test_desc_field_components_are_consistent_and_divergence_free(tmp_path):
from essos.fields import DescField, _hermite, is_toroidal
field = _synthetic_desc()
p = jnp.array([[0.3, 0.4, 0.2], [0.7, 2.0, 1.5], [0.05, 5.0, 4.0]])
e = vmap(jax.jacfwd(field.to_xyz))(p)
B = vmap(field.B)(p)
assert jnp.allclose(jnp.einsum("nij,nj->ni", e, vmap(field.B_contravariant)(p)), B, rtol=1e-12)
assert jnp.allclose(jnp.einsum("nij,ni->nj", e, B), vmap(field.B_covariant)(p), rtol=1e-12)
divergence = vmap(lambda q: jnp.trace(jax.jacfwd(lambda x: field.sqrtg(x) * field.B_contravariant(x))(q)))(p)
assert jnp.max(jnp.abs(divergence)) < 1e-12 * jnp.max(jnp.abs(vmap(field.sqrtg)(p) * B[:, 0]))
assert jnp.isclose(_hermite(jnp.sqrt(0.49), field.iota), 0.4 + 0.1 * 0.49, rtol=1e-6)
assert is_toroidal(field) and jnp.isclose(field.Aminor_p, 0.25 * jnp.sqrt(0.2 / 0.25), rtol=0.1)
field.save(tmp_path / "desc.npz")
again = DescField.from_desc(str(tmp_path / "desc.npz"))
assert jnp.allclose(vmap(again.B)(p), B)


def test_full_orbits_in_toroidal_fields_trace_in_the_cartesian_view():
from essos.dynamics import Tracing, Particles
vmec = Vmec(WOUT_FILE)
x0 = jnp.array([[0.3, 0.2, 0.1], [0.5, 1.0, 0.4]])
particles = Particles(initial_xyz=x0, field=vmec)
tracing = Tracing(field=vmec, model="FullOrbit_Boris", particles=particles, maxtime=1e-7, timestep=1e-10,
times_to_trace=10)
xyz = tracing.trajectories[:, :, :3]
# The orbits start one gyroradius off their guiding centers, given in (s, theta, phi), and stay near them.
assert jnp.all(jnp.linalg.norm(xyz[:, 0] - vmap(vmec.to_xyz)(x0), axis=1) < 0.2)
energy = tracing.energy()
assert jnp.allclose(energy[:, -1], energy[:, 0], rtol=1e-6)


def test_near_axis_field_is_consistent_to_first_order():
pytest.importorskip("pyqsc_jax")
from pyqsc_jax.near_axis import near_axis
from essos.fields import NearAxisField
field = NearAxisField(near_axis(rc=[1, 0.155, 0.0102], zs=[0, 0.154, 0.0111], etabar=0.64, nfp=2, nphi=61))
errors = []
for r in (0.02, 0.08):
p = jnp.stack([jnp.full(32, r), jnp.linspace(0, 6.28, 32), jnp.linspace(0, 6.28, 32)], 1)
errors.append(jnp.max(jnp.abs(jnp.linalg.norm(vmap(field.B)(p), axis=1) / vmap(field.AbsB)(p) - 1)))
assert errors[1] < 0.1 and errors[1] > errors[0] # first order: the mismatch grows with r
Loading