Enhance documentation and diagnostics for Gauss's law; refactor field interpolation and update algorithms for improved clarity and performance.

[rogeriojorge]

Now JAX-in-Cell is a full EM PIC code, as it can enforce Gauss' law exactly by choosing the parameter field_solver.

[codecov]

Codecov Report

❌ Patch coverage is 95.77465% with 6 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
jaxincell/_simulation.py	58.33%	4 Missing and 1 partial ⚠️
jaxincell/_plot.py	90.90%	0 Missing and 1 partial ⚠️

Files with missing lines	Coverage Δ
jaxincell/_algorithms.py	99.09% <100.00%> (+0.10%)	⬆️
jaxincell/_diagnostics.py	100.00% <100.00%> (ø)
jaxincell/_fields.py	94.04% <100.00%> (+14.04%)	⬆️
jaxincell/_filters.py	100.00% <100.00%> (ø)
jaxincell/_particles.py	100.00% <100.00%> (ø)
jaxincell/_sources.py	100.00% <100.00%> (ø)
jaxincell/_plot.py	97.48% <90.90%> (-0.57%)	⬇️
jaxincell/_simulation.py	88.83% <58.33%> (-2.17%)	⬇️

[rogeriojorge]

@Longyu975 @aarontran @luisHongkeLu
I added digital filtering as described in the last section of
https://warpx.readthedocs.io/en/latest/theory/models_algorithms/explicit_em_pic.html
@Longyu975, with the digital filtering and with the enforcing of Gauss' law, the Landau damping test appears to be much more robust. Can you test the damping rate now against the known solution? Can you redo your figures with this to see if everything still works?
Then, we should pull request this branch to your merge_exact_conservation_magnetic branch and now we can claim that we have a PIC code that is

• fully electromagnetic (enforcing Gauss' law)
• is both explicit and implicit
• applies digital filtering to smooth energy and currents
• is relativistic and non-relativistic
• handles multispecies

[Longyu975]

Thanks for the updates! The explicit method is working, though I am still unsure about the definition of 'robust' in this context, as the damping rate still deviates when the perturbation amplitude is changed.

Regarding the implicit method, I have actually rewritten several functions in that pull request to achieve exact energy conservation. I found that many standard techniques used to improve explicit/Boris schemes actually break the energy conservation theorem in the implicit framework. For example, using trapezoidal integration to calculate energy in diagnostics, the grid difference between the current and electric field accounts for ghost cells, and even the shape functions for field interpolation and charge deposition can lead to conservation violations.

[rogeriojorge]

I think the bump on tail is not working. Can someone confirm?