Improve density and direction calculation in the neutral beam model

[vsnever]

This updates density and direction calculation of the neutral beam model and fixes #414.

1. The beam deviation is now calculated as $$\sigma_x(z) = \sqrt{\sigma^2 + (ztg(\alpha_x))^2}\hspace{0.5cm}\sigma_y(z) = \sqrt{\sigma^2 + (ztg(\alpha_y))^2},$$ which is consistent with the Gaussian beam model, where the beam deviation σ(z) due to both beam divergence and deviation at beam origin is the result of the convolution of the two Gaussian functions as explained here. Previously, the beam deviation was modelled as: $$\sigma_x(z) =\sigma + ztg(\alpha_x)\hspace{0.5cm}\sigma_y(z) = \sigma + ztg(\alpha_y),$$ which is unclear to me.
2. In this case, the (non-normalised) direction of velocity of the beam atoms can be calculated as follows: $$e_x = x\frac{(ztg(\alpha_x))^2}{\sigma^2 + (ztg(\alpha_x))^2},$$ $$e_y = y\frac{(ztg(\alpha_y))^2}{\sigma^2 + (ztg(\alpha_y))^2},$$ $$e_z = z.$$ This gives the following pattern for the beam direction (σ=0.1 m and α=5°):
   

The broadening of the BES line shape is now naturally determined by the beam divergence. Therefore, setting beam temperature to the physically unreasonable values is no longer required. The parameters of the beam in the BES demo are updated.

Although this change does impact user results, I think it is justified by the improved consistency of the beam model.

[Mateasek]

Hi @vsnever,

thanks for the changes. The code itself looks clean and I couldn't find any problems. I would only suggest one improvement regarding the documentation. Since the beam direction became more complex, I think it would be nice to add the equations you use into the documentation. I think it would be enough if you add the equations and plot you posted in the opening post of this PR. It would be explanatory enough and would remove the necessity to go through the cython code for the users, what do you think?

[jacklovell]

Thanks @vsnever. I'm with @Mateasek: the changes are sound but it would be even better to explicitly document what calculation is being used.

I'd also suggest adding some emphasis (** or *) to the line in the changelog highlighting that this will change existing results.

If there aren't already any unit test associated with this, now is also a good time to add them. But don't worry if that's too big an project: I wouldn't want to hold up an otherwise useful change because of the work involved in setting up a mock beam for tests.

[vsnever]

Thanks for the reviews, @Mateasek, @jacklovell.

Since the beam direction became more complex, I think it would be nice to add the equations you use into the documentation. I think it would be enough if you add the equations and plot you posted in the opening post of this PR. It would be explanatory enough and would remove the necessity to go through the cython code for the users, what do you think?

I added equations for the beam density and direction in SIngleRayAttenuator.density() and Beam.direction() docstrings respectively. I noticed that in the docs, the description of the SingleRayAttenuator class was placed under the "CXS models" section, so I moved it to a separate "Beam attenuation" section. The beam direction plot is added to the particle_beams.rst.

I'd also suggest adding some emphasis (** or *) to the line in the changelog highlighting that this will change existing results.

I agree, the line announcing this change in the changelog is now in bold.

If there aren't already any unit test associated with this, now is also a good time to add them. But don't worry if that's too big a project: I wouldn't want to hold up an otherwise useful change because of the work involved in setting up a mock beam for tests.

We already have tests for the beam CX model, so setting up a mock beam and plasma is not a problem. I added the tests for the beam density and direction. They test these values on-axis, off-axis and outside the beam.

[jacklovell]

Looks good. Couple of minor suggestions.

[vsnever]

Looks good. Couple of minor suggestions.

Thanks, @jacklovell. All done.

[Mateasek]

Thanks @vsnever for improving the docstrings, I have no further suggestions.