Sass/spin sampling

[nilssass]

This PR adds two new keys to the config:

• sample_spin
• polarization

which allow to sample and set spin projections on the freezeout surface, given a polarization. If the sampler needs to be tested with spin sampling, make sure to use SMASH-devel until the next release of both codes, as spin will be included in the next SMASH release together with the sampler

Additionally, this PR adds more unit tests for gen.cpp, especially all spin functions

[yukarpenko]

Are the formulas that you're using written down somewhere? I see a lot of boilerplate code, but my feeling is that, given the story with the viscous corrections, I better check what is actually done. So far I don't see anything.

[yukarpenko]

I mean, I am sorry to comment like that but there is a lot of boilerplate stuff and checks in case there's nuclear blast around and CPU starts to misbehave (I guess it's the overall style of SMASH project), but for the essence - what is actually being done, I don't really see anything, and generally the code should correspond to some formulas.

[yukarpenko]

So I am sorry for my comment earlier, but it looks to me that you're missing the essence of what the code should do here. Tests are tests, good that they are there but still. As such, I basically do not know what your update is supposed to do, what formalism are you using, and can't check it. Are you implementing spin-dependent scatterings in SMASH? How?

[nilssass]

Thank you @yukarpenko for sharing your concerns. I understand your points, however, besides having some parts of my code that just ensure that everything is safe and no unwanted internal behavior occurs, the actual sampling procedure is contained in gen.cpp and it is only done if the user enables sample_spin in the config. If this key is not set, the sampler bahavior stays unchanged.

As we neither have a spin-transport code nor a spin MHD code, we have to rely on a phenomenological approach for now, which indeed does not correspond to a specific formula (I am not even aware of some updated Cooper-Frye sampling that incorporates the spin projections). This is to be seen as a first approach to assess the effect of spin dof on polarization observables. SMASH also has been updated to store spins and their projections.

The B03 project of the CRC-TR211 is currently working on a spin MHD code based on BHAC-QGP but they are far from being ready. Once they have a running code, the phenomenological approach of this PR needs to be updated to a more physically rigorous strategy.

I had many discussions with Hannah and the approach of this PR is the starting point we agreed on. Let me quickly summarize the steps of that strategy found in gen.cpp

Spin Sampling

- [`update_vorticity_extrema()`](https://github.com/smash-transport/smash-hadron-sampler/blob/41209cf0c1c46c5cebf7b25da3dccfd12470f3c9/src/gen.cpp#L436) gets the absolute max/min vorticity on the freezeout surface - [`get_vorticity_z_projection_in_cell()`](https://github.com/smash-transport/smash-hadron-sampler/blob/41209cf0c1c46c5cebf7b25da3dccfd12470f3c9/src/gen.cpp#L427) determines the z component of the thermal vorticity $\varpi$ in the cell - We perform a simple mapping of the vorticity in each cell onto the allowed spin projections of the sampled particle with [`get_favored_spin_projection_in_cell()`](https://github.com/smash-transport/smash-hadron-sampler/blob/41209cf0c1c46c5cebf7b25da3dccfd12470f3c9/src/gen.cpp#L451) (see image above) - Based on the vorticity of the cell, this determines the spin state which is most likely (for example, taken a $S=3/2$ particle and a strong negative vorticity, it is more likely to sample $s_z=-3/2$ or $s_z=-1/2$ than $s_z=+3/2$). The actual sampling of the spin projection is done by [`sample_spin_projection()`](https://github.com/smash-transport/smash-hadron-sampler/blob/41209cf0c1c46c5cebf7b25da3dccfd12470f3c9/src/gen.cpp#L475) with a simple "Monte-Carlo" sampling, where the acceptance range for the favored spin projection is increased. - How much the acceptance range is increased, is determined by the new key [`polarization`](https://github.com/smash-transport/smash-hadron-sampler/blob/41209cf0c1c46c5cebf7b25da3dccfd12470f3c9/src/params.cpp#L26). This gives us the possibility to tune the setup to reproduce the $\Lambda$ polarization measurement.

[yukarpenko]

okay, thank you for the explanation. I also had a look at the spin sampling functions and I have even more questions. Are you aware that there is Cooper-Frye extended for spin, established since around 10 years now? E.g. our papers with Francesco (where it was already applied): https://journals.aps.org/prc/abstract/10.1103/PhysRevC.95.054902 or Eqs. 9-13 in https://link.springer.com/article/10.1140/epjc/s10052-017-4765-1 this is what everyone else is using in the field. It isn't Monte Carlo ready, but it could be adapted for. Is there a reason you don't want to use the established formalism? We can discuss it if you like. In get_vorticity_z_projection_in_cell() , I don't really understand what quantity you are computing there. Could you write down a formula?

[nilssass]

After I had a helpful discussion, I will turn this PR into a draft for now. What we discussed was the following:

• The Monte-Carlo can stay as it is, but the weights for the acceptance ranges for each spin projection should not only given by $\varpi$ alone, but should follow eq. 13 of this paper. Eq. 13 gives the average that should be reproduced by the Monte-Carlo sampling when averaging over all spin projections per cell.
• I will discuss with Andrea Palermo whether eq. 13 is applicable for spin states > 1/2 or whether a latest version of the equation with other corrections exist. Once I am ready for a PR, I will let you now in this discussion.