Spin tracking

[pots007]

This PR implements spin tracking in FBPIC.

The API is (hopefully) straightforward: the Particle class now has a method activate_spin_tracking, which turns on spin tracking by creating a new instances on SpinTracker. All necessary arrays are stored inside this object. The user can set the average polarisation and have the spins be generated randomly or set to a fixed value.

[RemiLehe]

Thanks a lot for this impressive amount of work!! I love that the code is high-quality, has several automated tests, and is well documented! 🚀 ✨

I added a number of suggestions and comments. Most of them are cosmetic. Some of the more significant comments are the following:

• One of the automated tests did not pass on GPU when I tried. Would you have time to fix it?
• The function that initialized the spin in the case 'random' with a non-zero mean seemed a bit obscure to me. I suggested another function (see corresponding Python code in the inline comments).
• Did anyone test this in the boosted frame? Also: do you have a reference on how spins transform under a Lorentz transform? If yes, we could modify the initialization of the spin, in the case of a boosted-frame simulation, to make it consistent with the fact that the spins are initialized in a different Lorentz frame.

[RemiLehe]

Could you add a brief docstring to this function?
In particular, it might good to say this generates the spins according to the specifications of self.spin_distr, self.sx_m, self.sy_m, self.sz_m.

[pots007]

Turns out this was an oopsie: I implemented the random_point_sphere_gpu method directly in the ionizer. The code is much cleaner now, thanks for pointing this out.

[pots007]

Hey @RemiLehe , thanks a lot for the review and sorry it took me so long to get the changes done! I think I've addressed most of your points:

• the error I cannot reproduce. Could you let me know which fbpic file is the source of the error?
• the random spin generation is now based on your suggestion - that is much, much better
• Updated lots of docstrings
• Removed some weird circular function calls
• removed storing species as you suggested
• improved spin_ionization test
• etc

I have not yet done the boosted frame tests, I need a bit more time to think about that.

If you had time to check over the code again, it'd be great!

[RemiLehe]

Great, thanks implementing these changes!
It looks like we both tried to fix the restart test at the same time ; in the end I pushed a slightly different fix.

Now all the tests are working on GPU on my side too, thanks for the fix!

I will take one last look soon and will then merge.