Review of the NBI IDS

[imbeauf]

As suggested by @olivhoenen , I am copying here changes suggested by Lynton Appel related to the NBI IDS.
This changes have been initially proposed in various JIRA tickets [IMAS-5435, IMAS-5466, IMAS-5496], but the discussion is transfered here to reach more experts.

[IMAS-5435]
(1) beamlet_group should be a unique structure, (not an array of structures)

(2) Within beamlets_group, make it explicitly clear that there are two methods of defining the beam spatial orientations:

 (a) in terms of width_horzontal, width_vertical, focus, direction, angle, tangency_radius,position,

 (b) in terms of details of individual beamlets (ie current contents oi beamlets).

     Note that divergence_components relates to velocity distribution so is required by both   descriptions.

    (ii) Include in 2(a) above, polynomials to describe the power-fractions in the horizontal and vertical directions.

   (iii) generally change descriptions to  use cartesian coordinates for both spatial positions and unit vectors.    So this means that 

                   (a) beamlets_group.position should use X,Y,Z coords;

                   (b) tangency_radius, angle and direction should be replacede with a unit vector in X,Y,Z coordinates.

                   (c) tilting should be specified as 3-d components of  unit vector in x,y,z coordinates.

                   (d) beamlets.positions.r, beamlets.z, beamlets.phi should be replaced with a positions in x,y,z coordinates.

                  (e) beamlets.tangency-radii , beamlets.angles is missing a diection!!!.  Anyway these should be replaced with  unut vector in x,y,z coordinates.

(3) source. I am not sure why most of this stuff is here. The beamlets have been described in the beamlets-group. The only thing that may be useful to include here is the normal to the beam source. But this can be constructed if required from the beamlets group.

(4) aperture. This description seems to be far to complicated, or at least hard to understand. I suggest to simplify. Create a new structure called "apertures" within which there are three arrays of structures namely:

  outline(.  Has a set of xyz coordinates ordered anticlockwise viewed from the source towards to the plasma,

 (ii) circular(. Has sets of: radii,  xyz coordinates of centre and normal vector pointing towards plasma, 

 (iii) rectangular(.  Has a set of 4 coordinates describing the corners of the rectangles, ordered anticlockwise viewed from the sourced towards the plasma.

[IMAS-5496]
Is it intended that the energy components of the NB particles are E, E/2, E/3? The documentation hints that this is the case, but does not make it explicitly clear. How many energy components are there? I currently use the dimension of unit/beamlet_group/divergence_components to find the answer to this question. Is there a better way?

It turns out that you can actually compute the energy of the beam particle components, and the particle fluxes from the data fields defined in the IDS structure. These are what I would call "basic" parameters. Expressions for these parameters are:

E_i= p_i gamma_0 E_0/ (p_0 gamma_i)

Gamma_i = gamma_i P_Total p_0/ (gamma_0 E_0)

where

(a) the suffices refer to components, i being the i^{th} component and 0 being the fundamental (ie highest energy) component.

(b) E_i is the particle energy (i^th component)

              Gamma_i is the particle flux (i^th component)

              p_i [p_0]is the beam power fraction for the  i^th  [fundamental] component (contained In the IDS)

              gamma_i  [gamma_0] is the beam current (equivalently flux) fraction for the i^th [fundamental] component (contained in the IDS)

             E_0 is the fundamental particle energy  (contained in the IDS)

             P_total is the total power (contained in the IDS)

Please can you provide the above documentation within the IDS description. It would make it much easier for people to compute these basis parameters if they require them.

Nevertheless, I think it would be much better to provide these basic parameters in a more explicit manner. What are the reasons not to?

Finally, as I have shown here the beam particle energy components will not in general be E, E/2 and E/3 as suggested in the documentation. There is a basic incompatibility here. I suggest to remove any references to E,E/2 and E/3 components in the IDS as these are misleading. An alternative possibility is to validate the IDS to ensure that the E, E/2 E/3 condition is maintained. Or even better I think, to remove some of the surplus fields.

[IMAS-5466]
The choice of variables used in the NB IDS means that two basic parameters, namely the particle component energy and the particle component flux are not intuitively clear to extract.

This is partly because the time-dependent fields are defined in terms of fractional (ie relative) components.

In terms of the parameters currently in the IDS, expressions for these parameters are:

---

The i^th component of particle energy:
E_i = E_0 p_i gamma_0/(p_0 gamma_i)

The i^th component of particle flux:

Gamma_i = p_0 P gamma_i/ (gamma_0 E_0)
where in terms of the IDS fields, the parameters on the rhs of these expressions are:

 E_0 <= unit[i1].energy

 p_i <= unit[i1].beam_power_fraction(0,i)

gamma_0 <= unit[i1].beam_current_fraction(0.i)

P <= unit[i1].power_launched

I suggest to redefine the parameters in the IDS, using absolute rather than fractional values.

[imbeauf]

Adding [IMAS-5462] to this discussion
In the NBI IDS, the beam divergence has been specified with "horizontal" and "vertical" components. However, elsewhere in the NBI IDS the beam source orientation has been specified with x1,x2,x3 direction vectors where x1 vector is "labelled as more horizontal than x2 vector". I suggest that the beam divergences should be specified in the directions x1, and x2 rather than horizontally and vertically.

Furthermore, as the beam divergence changes as a function of the focus, you need to specify that the divergence is at the source or somewhere else in the beam trajectory.

I suggest to use this description for "divergence_component(i3)":

"The divergence refers to the divergence (spreading out) of each beamlet at the beam source from the set of point locations as given in beamlet_groups[]/beamlets. The distribution of each beamlet is assumed to be Gaussian with its mean velocity directed at a focal point and an e-folding attenuation referred to as its divergence an angle (specifeid radians).
The divergence components are defined in the (x1,x3) and (x2,x3) planes corresponding approximately to horizontal and vertical planes. For positive ion beams, divergence components should be specified for each energy component (ie E, E/2 and E/3)."

===========================================

Replace "vertical" with "x2_x3_plane" and use the following description:

"The beam divergence in approximately the vertical plane at the beam source grid. This is the divergence in the (x2,x3) plane defined as the angle subtended at the beam source with a line to the beam focal point in the x2-direction (ie. approximately the vertical focus). "

===========================================

Replace "horizontal" with "x1_x3_plane" and use the following description:

"The beam divergence in approximately the horizontal plane at the beam source grid. This is the divergence in the (x1,x3) plane defined as the angle subtended at the beam source with a line to the beam focal point in the x1-direction (ie. approximately the horizontal focus). "

[MireilleSchneider]

I would strongly recommend to not change the name of the variables. Replacing e.g. "vertical" with "x2_x3_plane" is absolutely not intuitive. I understand the need to link the definition to the x1,x2,x3 unit vector definitions, but it can be done in the description of the variables themselves without changing their name. Characterising directions as "vertical" and "horizontal" is much more intuitive for the common users (including me). Variables inside NBI codes themselves use such descriptions. In case of doubts, everyone can check the definitions which, I agree, needed to be improved.