Merge branch 'development' into enhancement/stark_zeeman_doppler_line…

…shape

CHANGELOG.md

@@ -24,10 +24,15 @@ New:
 * Improved beam direction calculation to allow for natural broadening of the BES line shape due to beam divergence. (#414)
 * Add kwargs to invert_regularised_nnls to pass them to scipy.optimize.nnls. (#438)
 * StarkBroadenedLine now supports Doppler broadening and Zeeman splitting. (#393)
+* Add thermal charge-exchange emission model. (#57)
+* PECs for C VI spectral lines for n <= 5 are now included in populate(). Rerun populate() after upgrading to 1.5 to update the atomic data repository.
+* All interpolated atomic rates now return 0 if plasma parameters <= 0, which matches the behaviour of emission models. (#450)
 
 Bug fixes:
 * Fix deprecated transforms being cached in LaserMaterial after laser.transform update (#420)
 * Fix IRVB calculate sensitivity method.
+* Fix missing donor_metastable attribute in the core BeamCXPEC class (#411).
+* **Fix the receiver ion density being passed to the BeamCXPEC instead of the total ion density in the BeamCXLine. Also fix incorrect BeamCXPEC dosctrings. Attention!!! The results of CX spectroscopy are affected by this change. (#441)**
 
 Release 1.4.0 (3 Feb 2023)
 -------------------

cherab/core/atomic/interface.pxd

@@ -45,6 +45,8 @@ cdef class AtomicData:
 
     cpdef RecombinationPEC recombination_pec(self, Element ion, int charge, tuple transition)
 
+    cpdef ThermalCXPEC thermal_cx_pec(self, Element donor_ion, int donor_charge, Element receiver_ion, int receiver_charge, tuple transition)
+
     cpdef TotalRadiatedPower total_radiated_power(self, Element element)
 
     cpdef LineRadiationPower line_radiated_power_rate(self, Element element, int charge)

cherab/core/atomic/interface.pyx

@@ -1,6 +1,6 @@
-# Copyright 2016-2023 Euratom
-# Copyright 2016-2023 United Kingdom Atomic Energy Authority
-# Copyright 2016-2023 Centro de Investigaciones Energéticas, Medioambientales y Tecnológicas
+# Copyright 2016-2024 Euratom
+# Copyright 2016-2024 United Kingdom Atomic Energy Authority
+# Copyright 2016-2024 Centro de Investigaciones Energéticas, Medioambientales y Tecnológicas
 #
 # Licensed under the EUPL, Version 1.1 or – as soon they will be approved by the
 # European Commission - subsequent versions of the EUPL (the "Licence");
@@ -31,70 +31,124 @@ cdef class AtomicData:
 
     cpdef double wavelength(self, Element ion, int charge, tuple transition):
         """
-        Returns the natural wavelength of the specified transition in nm.
+        The natural wavelength of the specified transition in nm.
         """
 
         raise NotImplementedError("The wavelength() virtual method is not implemented for this atomic data source.")
 
     cpdef IonisationRate ionisation_rate(self, Element ion, int charge):
+        """
+        Electron impact ionisation rate for a given species in m^3/s.
+        """
+
         raise NotImplementedError("The ionisation_rate() virtual method is not implemented for this atomic data source.")
 
     cpdef RecombinationRate recombination_rate(self, Element ion, int charge):
+        """
+        Recombination rate for a given species in m^3/s.
+        """
+
         raise NotImplementedError("The recombination_rate() virtual method is not implemented for this atomic data source.")
 
     cpdef ThermalCXRate thermal_cx_rate(self, Element donor_ion, int donor_charge, Element receiver_ion, int receiver_charge):
+        """
+        Thermal charge exchange effective rate coefficient for a given donor and receiver species in m^3/s.
+        """
+
         raise NotImplementedError("The thermal_cx_rate() virtual method is not implemented for this atomic data source.")
 
     cpdef list beam_cx_pec(self, Element donor_ion, Element receiver_ion, int receiver_charge, tuple transition):
         """
-        Returns a list of applicable charge exchange emission rates in W.m^3.
+        A list of Effective charge exchange photon emission coefficient for a given donor (beam) in W.m^3.
         """
 
         raise NotImplementedError("The cxs_rates() virtual method is not implemented for this atomic data source.")
 
     cpdef BeamStoppingRate beam_stopping_rate(self, Element beam_ion, Element plasma_ion, int charge):
         """
-        Returns a list of applicable beam stopping coefficients in m^3/s.
+        Beam stopping coefficient for a given beam and target species in m^3/s.
         """
 
         raise NotImplementedError("The beam_stopping() virtual method is not implemented for this atomic data source.")
 
     cpdef BeamPopulationRate beam_population_rate(self, Element beam_ion, int metastable, Element plasma_ion, int charge):
         """
-        Returns a list of applicable dimensionless beam population coefficients.
+        Dimensionless Beam population coefficient for a given beam and target species.
         """
 
         raise NotImplementedError("The beam_population() virtual method is not implemented for this atomic data source.")
 
     cpdef BeamEmissionPEC beam_emission_pec(self, Element beam_ion, Element plasma_ion, int charge, tuple transition):
         """
-        Returns a list of applicable beam emission coefficients in W.m^3.
+        The beam photon emission coefficient for a given beam and target species
+        and a given transition in W.m^3.
         """
 
         raise NotImplementedError("The beam_emission() virtual method is not implemented for this atomic data source.")
 
     cpdef ImpactExcitationPEC impact_excitation_pec(self, Element ion, int charge, tuple transition):
+        """
+        Electron impact excitation photon emission coefficient for a given species in W.m^3.
+        """
+
         raise NotImplementedError("The impact_excitation() virtual method is not implemented for this atomic data source.")
 
     cpdef RecombinationPEC recombination_pec(self, Element ion, int charge, tuple transition):
+        """
+        Recombination photon emission coefficient for a given species in W.m^3.
+        """
+
         raise NotImplementedError("The recombination() virtual method is not implemented for this atomic data source.")
 
+    cpdef ThermalCXPEC thermal_cx_pec(self, Element donor_ion, int donor_charge, Element receiver_ion, int receiver_charge, tuple transition):
+        """
+        Thermal charge exchange photon emission coefficient for given donor and receiver species in W.m^3.
+        """
+
+        raise NotImplementedError("The thermal_cx_pec() virtual method is not implemented for this atomic data source.")
+
     cpdef TotalRadiatedPower total_radiated_power(self, Element element):
+        """
+        The total (summed over all charge states) radiated power
+        in equilibrium conditions for a given species in W.m^3.
+        """
+
         raise NotImplementedError("The total_radiated_power() virtual method is not implemented for this atomic data source.")
 
     cpdef LineRadiationPower line_radiated_power_rate(self, Element element, int charge):
+        """
+        Line radiated power coefficient for a given species in W.m^3.
+        """
+
         raise NotImplementedError("The line_radiated_power_rate() virtual method is not implemented for this atomic data source.")
 
     cpdef ContinuumPower continuum_radiated_power_rate(self, Element element, int charge):
+        """
+        Continuum radiated power coefficient for a given species in W.m^3.
+        """
+
         raise NotImplementedError("The continuum_radiated_power_rate() virtual method is not implemented for this atomic data source.")
 
     cpdef CXRadiationPower cx_radiated_power_rate(self, Element element, int charge):
+        """
+        Charge exchange radiated power coefficient for a given species in W.m^3.
+        """
+
         raise NotImplementedError("The cx_radiated_power_rate() virtual method is not implemented for this atomic data source.")
 
     cpdef FractionalAbundance fractional_abundance(self, Element ion, int charge):
+        """
+        Fractional abundance of a given species in thermodynamic equilibrium.
+        """
+
         raise NotImplementedError("The fractional_abundance() virtual method is not implemented for this atomic data source.")
 
     cpdef ZeemanStructure zeeman_structure(self, Line line, object b_field=None):
+        r"""
+        Wavelengths and ratios of :math:`\pi`-/:math:`\sigma`-polarised Zeeman components
+        for any given value of magnetic field strength.
+        """
+
         raise NotImplementedError("The zeeman_structure() virtual method is not implemented for this atomic data source.")
 
     cpdef tuple zeeman_triplet_parameters(self, Line line):

cherab/core/atomic/rates.pxd

@@ -46,11 +46,13 @@ cdef class RecombinationPEC(_PECRate):
     pass
 
 
-cdef class ThermalCXPEC(_PECRate):
-    pass
+cdef class ThermalCXPEC:
+    cpdef double evaluate(self, double electron_density, double electron_temperature, double donor_temperature) except? -1e999
 
 
 cdef class BeamCXPEC:
+    cdef readonly int donor_metastable
+
     cpdef double evaluate(self, double energy, double temperature, double density, double z_effective, double b_field) except? -1e999
 
 

cherab/core/atomic/rates.pyx

@@ -130,11 +130,27 @@ cdef class RecombinationPEC(_PECRate):
     pass
 
 
-cdef class ThermalCXPEC(_PECRate):
+cdef class ThermalCXPEC:
     """
     Thermal charge exchange rate coefficient.
     """
-    pass
+
+    def __call__(self, double electron_density, double electron_temperature, donor_temperature):
+        """Returns a CX photon emissivity coefficient at the specified plasma conditions.
+
+        This function just wraps the cython evaluate() method.
+        """
+        return self.evaluate(electron_density, electron_temperature, donor_temperature)
+
+    cpdef double evaluate(self, double electron_density, double electron_temperature, double donor_temperature) except? -1e999:
+        """Returns a CX photon emissivity coefficient at given conditions.
+
+        :param electron_density: Electron density in m^-3.
+        :param electron_temperature: Electron temperature in eV.
+        :param donor_temperature: Donor temperature in eV.
+        :return: The effective CX PEC rate in W/m^3.
+        """
+        raise NotImplementedError("The evaluate() virtual method must be implemented.")
 
 
 cdef class BeamCXPEC:
@@ -144,8 +160,13 @@ cdef class BeamCXPEC:
     transition :math:`n\rightarrow n'` of ion :math:`Z^{(\alpha+1)+}` with electron donor
     :math:`H^0` in metastable state :math:`m_{i}`. Equivalent to
     :math:`q^{eff}_{n\rightarrow n'}` in `adf12 <http://open.adas.ac.uk/adf12>_`.
+
+    :param donor_metastable: The metastable state of the donor species for which the rate data applies.
     """
 
+    def __init__(self, int donor_metastable):
+        self.donor_metastable = donor_metastable
+
     def __call__(self, double energy, double temperature, double density, double z_effective, double b_field):
         """Evaluates the Beam CX rate at the given plasma conditions.
 
@@ -158,7 +179,7 @@ cdef class BeamCXPEC:
 
         :param float energy: Interaction energy in eV/amu.
         :param float temperature: Receiver ion temperature in eV.
-        :param float density: Receiver ion density in m^-3
+        :param float density: Plasma total ion density in m^-3
         :param float z_effective: Plasma Z-effective.
         :param float b_field: Magnetic field magnitude in Tesla.
         :return: The effective rate

cherab/core/model/beam/charge_exchange.pxd

@@ -36,7 +36,7 @@ cdef class BeamCXLine(BeamModel):
         object _lineshape_class, _lineshape_args, _lineshape_kwargs
 
     cdef double _composite_cx_rate(self, double x, double y, double z, double interaction_energy,
-                                          Vector3D donor_velocity, double receiver_temperature, double receiver_density) except? -1e999
+                                          Vector3D donor_velocity, double receiver_temperature) except? -1e999
 
     cdef double _beam_population(self, double x, double y, double z, Vector3D beam_velocity, list population_data) except? -1e999
 

cherab/core/model/beam/charge_exchange.pyx

@@ -61,6 +61,7 @@ cdef class BeamCXLine(BeamModel):
     :ivar Line line: The emission line object.
 
     .. code-block:: pycon
+
         >>> from cherab.core.model import BeamCXLine
         >>> from cherab.core.atomic import carbon
         >>> from cherab.core.model import ParametrisedZeemanTriplet
@@ -158,7 +159,7 @@ cdef class BeamCXLine(BeamModel):
         interaction_energy = ms_to_evamu(interaction_speed)
 
         # calculate the composite charge-exchange emission coefficient
-        emission_rate = self._composite_cx_rate(x, y, z, interaction_energy, donor_velocity, receiver_temperature, receiver_density)
+        emission_rate = self._composite_cx_rate(x, y, z, interaction_energy, donor_velocity, receiver_temperature)
 
         # spectral line emission in W/m^3/str
         radiance = RECIP_4_PI * donor_density * receiver_density * emission_rate
@@ -169,7 +170,7 @@ cdef class BeamCXLine(BeamModel):
     @cython.wraparound(False)
     @cython.cdivision(True)
     cdef double _composite_cx_rate(self, double x, double y, double z, double interaction_energy,
-                                   Vector3D donor_velocity, double receiver_temperature, double receiver_density) except? -1e999:
+                                   Vector3D donor_velocity, double receiver_temperature) except? -1e999:
         """
         Performs a beam population weighted average of the effective cx rates.
 
@@ -188,23 +189,26 @@ cdef class BeamCXLine(BeamModel):
         :param interaction_energy: The donor-receiver interaction energy in eV/amu.
         :param donor_velocity: A Vector defining the donor particle velocity in m/s.
         :param receiver_temperature: The receiver species temperature in eV.
-        :param receiver_density: The receiver species density in m^-3
         :return: The composite charge exchange rate in W.m^3.
         """
 
         cdef:
-            double z_effective, b_field, rate, total_population, population, effective_rate
+            double ion_density, z_effective
+            double b_field
+            double rate, effective_rate
+            double population, total_population
             BeamCXPEC cx_rate
             list population_data
 
-        # calculate z_effective and the B-field magnitude
+        # calculate ion density, z_effective and the B-field magnitude
+        ion_density = self._plasma.ion_density(x, y, z)
         z_effective = self._plasma.z_effective(x, y, z)
         b_field = self._plasma.get_b_field().evaluate(x, y, z).get_length()
 
         # rate for the ground state (metastable = 1)
         rate = self._ground_beam_rate.evaluate(interaction_energy,
                                                receiver_temperature,
-                                               receiver_density,
+                                               ion_density,
                                                z_effective,
                                                b_field)
 
@@ -219,7 +223,7 @@ cdef class BeamCXLine(BeamModel):
 
             effective_rate = cx_rate.evaluate(interaction_energy,
                                               receiver_temperature,
-                                              receiver_density,
+                                              ion_density,
                                               z_effective,
                                               b_field)
 

cherab/core/model/plasma/__init__.pxd

@@ -20,4 +20,5 @@
 from cherab.core.model.plasma.bremsstrahlung cimport Bremsstrahlung
 from cherab.core.model.plasma.impact_excitation cimport ExcitationLine
 from cherab.core.model.plasma.recombination cimport RecombinationLine
+from cherab.core.model.plasma.thermal_cx cimport ThermalCXLine
 from cherab.core.model.plasma.total_radiated_power cimport TotalRadiatedPower

cherab/core/model/plasma/__init__.py

@@ -20,4 +20,5 @@
 from .bremsstrahlung import Bremsstrahlung
 from .impact_excitation import ExcitationLine
 from .recombination import RecombinationLine
+from .thermal_cx import ThermalCXLine
 from .total_radiated_power import TotalRadiatedPower

cherab/core/model/plasma/thermal_cx.pxd

@@ -0,0 +1,35 @@
+# Copyright 2016-2018 Euratom
+# Copyright 2016-2018 United Kingdom Atomic Energy Authority
+# Copyright 2016-2018 Centro de Investigaciones Energéticas, Medioambientales y Tecnológicas
+#
+# Licensed under the EUPL, Version 1.1 or – as soon they will be approved by the
+# European Commission - subsequent versions of the EUPL (the "Licence");
+# You may not use this work except in compliance with the Licence.
+# You may obtain a copy of the Licence at:
+#
+# https://joinup.ec.europa.eu/software/page/eupl5
+#
+# Unless required by applicable law or agreed to in writing, software distributed
+# under the Licence is distributed on an "AS IS" basis, WITHOUT WARRANTIES OR
+# CONDITIONS OF ANY KIND, either express or implied.
+#
+# See the Licence for the specific language governing permissions and limitations
+# under the Licence.
+
+from cherab.core.atomic cimport Line
+from cherab.core.plasma cimport PlasmaModel
+from cherab.core.species cimport Species
+from cherab.core.model.lineshape cimport LineShapeModel
+
+
+cdef class ThermalCXLine(PlasmaModel):
+
+    cdef:
+        Line _line
+        double _wavelength
+        Species _target_species
+        list _rates
+        LineShapeModel _lineshape
+        object _lineshape_class, _lineshape_args, _lineshape_kwargs
+
+    cdef int _populate_cache(self) except -1