Draft: New beam architecture

[Mateasek]

This is the work in progress of the new beam architecture (mentioned in #292). There still can be major changes, please use the branch with caution. I wanted to publish it to get it out there so it can be used by pioneers and tested to collect suggestions.

Changes Summary

BeamDistribution
Added BeamDistribution class, with DistributionFunction as baseclass. BeamDistribution handles spatial properties of beam, e.g. geometry, density distribution etc. (these were removed from Beam node). BeamDistribution will allow BeamModels to adress arbitrary level of complexity, from the most complicated 6D integration during observation. Simpler realisation of BeamModels (the currently available ones) can use mehods of the class providing the moments of the distribution: bulk_velocity, temperature, density.

SingleRayAttenuator
Was made more stand-alone. It now has _transform and _transform_inv attributes which are transforms from and to beam frame. This is to allow simple re-using of SingleRayAttenuator for also "MultiRayAttenuator" BeamDistribuions

ThinBeam
is a replacement of the current beam model.

BeamModels and BeamMaterial changed to work with the ThinBeam model and changes brought by the introduction of the BeamDistribution

[vsnever]

Hi @Mateasek,
Thank you very much for this draft PR. I agree that this is a major step in the right direction.

I looked at the output of the FEDASIM code, there neutral density is resolved over excited states. I believe other codes that calculate beam attenuation also output state-resolved neutral density. If only a state-unresolved distribution is supported in Cherab, we run into a data inconsistency problem when the beam attenuation is calculated by the external code with one collisional radiative model (CRM) and the radiation is calculated in Cherab with another CRM.

I'm still thinking how the state-resolved distribution of neutrals can be implemented in the Beam. Perhaps, the beam should have a list of (state, distribution) pairs similar to (species, distribution) pairs in Plasma composition. Having the state-resolved distribution of neutrals should simplify the BeamCXLine and BeamEmissionLine model, but when the beam attenuation is calculated internally in Cherab, the calculation of beam population should be moved from the BeamCXLine to somewhere else.

[Mateasek]

Hi @vsnever , thanks for the feedback. At the beginning I thought that the beam would have only a single particle species needed for the models to work. You are right, that more advanced models would probably need more beam species. In this case I think we should adopt something similar to the plasma composition and apply it to the beam. We should also implement state resolved model into the atomic model of cherab. Sorting this out only within the beam would be I think a bit dirty.

[vsnever]

For the plasma composition, I think we could restrict ourselves to level resolution for hydrogen and H-like ions, and metastable resolution for other species. This would allow to use metastable-resolved PECs and Einstein coefficients for H and H-like ions, when the population density is calculated by an external code, e.g. EIRENE. That would be a huge step forward, but given the amount of change, do we have enough manpower?

[vsnever]

I was thinking about how to add this new beam architecture in 1.5 without breaking user code and I came up with a possible solution.

I think, we should keep the beam properties, now associated with the ThinBeam distribution, until the next release. Beam distribution, if not explicitly set, should default to ThinBeam. So, these deprecated Beam properties should work as follows:

    @property
    def divergence_x(self):
        if isinstance(self._distribution, ThinBeam):
            return self._distribution.divergence_x
        raise TypeError("Unable to get 'divergence_x', not a 'ThinBeam'.")

    @divergence_x.setter
    def divergence_x(self, double value):
        if isinstance(self._distribution, ThinBeam):
            warnings.warn("Setting beam distribution properties directly through a 'Beam' instance is deprecated and will be removed in the next release. Instead, use the 'BeamDistribution' instance properties.", DeprecationWarning)
            self._distribution.divergence_x = value
        else:
            raise TypeError("Unable to set 'divergence_x', not a 'ThinBeam'.")

    @property
    def element(self):
        return self._distribution.element

    @element.setter
    def element(self, Element value not None):
        warnings.warn("Setting beam distribution properties directly through a 'Beam' instance is deprecated and will be removed in the next release. Instead, use the 'BeamDistribution' instance properties.", DeprecationWarning)
        self._distribution.element = value

The deprecated density() and direction() methods should work similar way.

The line warnings.simplefilter('once', DeprecationWarning) can be added at the top of the file to make these warnings appear only once.

[Mateasek]

Hi @vsnever ,

at the end, we will add the new architecture along the old one. The new one will be sitting in particle_beams. This was suggested by @jacklovell during a meeting I had with him when I was visiting JET. I should update this in the issue at least, sorry. We will run the old and new architectures alongside for some time, add deprecation warnings to the old one and when we raise the major version, we will remove the old beam. This is I think the best compromise because we won't have to be introducing some non-optimal aspects into the new architecture.

I'm not in favour of the name "focal length" in this case . It is something the ion lense in the beam source has, but when you look at the generated beam profile the actual beam waist can be in some distance from the focal point of the lense. The difference depends largely on the source properties as beamlet divergences, focal length, etc. In case of a model which is based on the description of the beam itself I would like to use terms "beam waist" and "beam divergence" which is taken from the Gaussian model.

My plan is to add also a model of a beam based on individual bealmlets which will have a focal point into which all the beamlets aim.

[vsnever]

Hi @Mateasek,

at the end, we will add the new architecture along the old one. The new one will be sitting in particle_beams.

I agree it's better, considering that there is also a laser beam in Cherab.

The difference depends largely on the source properties as beamlet divergences, focal length, etc. In case of a model which is based on the description of the beam itself I would like to use terms "beam waist" and "beam divergence" which is taken from the Gaussian model.

Yes, "beam waist" is better, we should avoid ambiguity.