[spossann]

Model docs (preview): https://struphy-hub.github.io/docs-preview/pr-828/sections/subsections/models-all.html#struphy.models.DriftKineticMaxwell

Follow-up of #823 (DriftKineticMaxwell, merged).

What

Use the total magnetic field in the first term of $\mathbf B^*$:

$$\mathbf B^* = \mathbf B_0 + \tilde{\mathbf B} + \varepsilon v_\parallel \nabla\times\mathbf b_0, \qquad B^*_\parallel = \mathbf b_0\cdot\mathbf B^*. $$

The curvature term keeps the equilibrium $\mathbf b_0$. Guiding centers now stream along the perturbed field lines (the magnetic flutter term $v_\parallel\tilde{\mathbf B}_\perp/B^{*}_\parallel$).

• PushGuidingCenterParallel: with b_tilde, $\hat{\mathbf B}^{*2}$ is built from $\mathbf B_0 + \tilde{\mathbf B}$ (tensor-product 2-form, refreshed together with $B_\parallel$ and $\nabla B_\parallel$). Before, the kernels got the equilibrium b2 only, although the docstring already said $\mathbf B = \mathbf B_0 + \tilde{\mathbf B}$, and CurrentCoupling5DCurlb already used the total field.
  • This changes the results of LinearMHDDriftkineticCC (it passes b_tilde). Models without b_tilde (GuidingCenter, DriftKineticElectrostaticAdiabatic) are unchanged.
• DriftKineticMaxwellCoupling: the parallel response $\mathbf a_p = \hat{\mathbf B}^{*2}/\hat B^{*3}_\parallel$ uses the same total field at $\mathbf b^n$. So the current, the parallel force and the streaming of push_para use the same $\mathbf b^*$.
  • The step remains exactly energy conserving, since $\mathbf a_p$ is frozen in the step.
  • With $\mathbf B^* = \nabla\times\mathbf A^*$, phase-space conservation is now fully consistent.
  • The kernels are unchanged (they take the 2-form as an argument).
• Docs: b_tilde is documented as Hdiv (it was "Hcurl", but all callers pass the 2-form); the DriftKineticMaxwell docs show the new $\mathbf B^*$.

Tests

test_push_guiding_center_full_b.py (1 and 4 ranks), with $\mathbf B_0 = \mathbf e_z$ and the uniform $\tilde{\mathbf B} = 0.1,\mathbf e_x$:

• push_para moves every marker in $x$ by exactly $0.1\times$ its displacement in $z$ (discrete-gradient and explicit algorithms). Before the change: no $x$ motion.
• the stored $\mathbf a_p$ of the coupling step equals $(0.1/L_x, 0, 1/L_z)$.

The existing tests of #823, the verification test (inertial Alfvén wave), and the generic model tests of DriftKineticMaxwell, LinearMHDDriftkineticCC, DriftKineticElectrostaticAdiabatic and GuidingCenter pass.

Review

A separate review agent found no correctness bugs. It checked:

• that all pusher algorithms get the total field, that the buffer is filled before use, and the ghost regions and extraction (also with polar splines);
• that the coupling holds $\mathbf b^n$ during the push, and that exact energy conservation is kept;
• the test expectations and their MPI safety.

Its one nit is fixed: the tests drop previously registered kernels before re-allocating a pusher.

Open points it raised, outside this PR:

• CurrentCoupling5DCurlb adds b_tilde to the tensor-product b2 without the extraction operator E2T, which looks wrong with polar splines.
• With the flutter term, the energy balance of LinearMHDDriftkineticCC should be checked: is the field-side counterpart of the $f v_\parallel \tilde{\mathbf B}$ current present?

🤖 Generated with Claude Code