Physics docs update

docs/index.rst

@@ -60,6 +60,7 @@ Mission Statement
     using/components/index
     using/visualization/index
     using/interaction/index
+    using/parallelisation/index
 
 
 .. toctree::

docs/installation.rst

@@ -78,31 +78,6 @@ then install TARDIS, as follows::
     python setup.py install
 
 
-.. _install_openmp:
-
-Enabling parallel execution with OpenMP
----------------------------------------
-
-
-Manually, cloning the repository enables other options such as running the code in parallel (enabling OpenMP).
-In general, we encourage downloading the compilers from `conda` as we then can ensure that they work with TARDIS.
-Within the TARDIS conda environment do::
-
-    conda install -c conda-forge compilers
-
-For macOS::
-
-    conda install -c conda-forge llvm-openmp
-
-For Linux::
-
-    conda install -c conda-forge openmp
-
-To compile TARDIS for parallel execution::
-
-    python setup.py install --with-openmp
-
-
 .. _troubleshooting_inst_label:
 
 Installation Troubles (FAQ)

docs/physics/montecarlo/discretization.rst

@@ -15,10 +15,10 @@ During a Monte Carlo calculation, a large number of packets, all with a certain
 energy :math:`\varepsilon`, are created. In addition, each packet is associated
 with a frequency. These assignments are performed in a manner which ensures
 that the ensemble of packets represents the spectral energy distribution of the
-radiation field (see :doc:`Propagation <propagation>`).
+radiation field (see :ref:`Propagation <propagation>`).
 
 During the simulation, the energy of the packet remains constant in the local
-co-moving frame (see :doc:`Reference Frames <../physics/referenceframes>` for
+co-moving frame (see :ref:`Reference Frames <referenceframes>` for
 details about the lab and co-moving frames). This naturally ensures energy
 conservation and constitutes the main advantage of this discretization scheme.
 There is one side effect of this so-called indivisible packet energy scheme

docs/physics/montecarlo/lineinteraction.rst

@@ -1,3 +1,5 @@
+.. _lineinteraction:
+
 ***************************
 Line Interaction Treatments
 ***************************

docs/physics/montecarlo/randomsampling.rst

@@ -1,3 +1,5 @@
+.. _randomsampling:
+
 **********************
 Random Sampling Basics
 **********************

docs/using/interaction/using_formal_integral.rst

@@ -23,4 +23,6 @@ Note that the integrated spectrum (``simulation.runner.spectrum_integrated``)
 is a lazy property so it will be only generated (and then cached) once it is
 accessed. The spectrum integration routine is Open-MP parallelized, so this
 process may be significantly sped-up if TARDIS is built with the
-``--with-openmp`` option and more then one thread is used.
+``--with-openmp`` option and more then one thread is used. More instructions on
+how to enable parallelisation of the code is given in the :ref:`parallelisation`
+section.

docs/using/parallelisation/index.rst

@@ -0,0 +1,36 @@
+.. _parallelisation:
+
+*****************************************
+Parallel execution with Numba and OpenMP
+*****************************************
+
+Enabling parallel execution with OpenMP
+========================================
+
+Manually, cloning the repository enables other options such as running the code in parallel (enabling OpenMP).
+In general, we encourage downloading the compilers from `conda` as we then can ensure that they work with TARDIS.
+Within the TARDIS conda environment do::
+
+    conda install -c conda-forge compilers
+
+For macOS::
+
+    conda install -c conda-forge llvm-openmp
+
+For Linux::
+
+    conda install -c conda-forge openmp
+
+To compile TARDIS for parallel execution::
+
+    python setup.py install --with-openmp
+
+
+
+Numba Usage Guide
+===========
+
+The ``montecarlo`` section of the Configuration file accepts the parameter ``nthreads`` which sets the number of
+threads to be used for parallelisation. Setting the value of the parameter between 1 and the environment variable
+``NUMBA_NUM_THREADS`` (which is, by default, the number of CPU cores on your system) will automatically invoke Numba
+to parallelise the code. (See :ref:`config-file` section).

setup.py

@@ -88,12 +88,6 @@
                    is_bool=True)
 add_command_option('develop', 'with-openmp', 'compile TARDIS with OpenMP',
                    is_bool=True)
-add_command_option('install', 'with-vpacket-logging', 'compile TARDIS with virtual packet logging',
-                   is_bool=True)
-add_command_option('build', 'with-vpacket-logging', 'compile TARDIS with virtual packet logging',
-                   is_bool=True)
-add_command_option('develop', 'with-vpacket-logging', 'compile TARDIS with virtual packet logging',
-                   is_bool=True)
 
 # Freeze build information in version.py
 generate_version_py(PACKAGENAME, VERSION, RELEASE,

tardis/io/atom_data/base.py

@@ -78,6 +78,11 @@ class AtomData(object):
             index : numerical index;
             columns : atomic_number, ion_number, level_number, nu[Hz], x_sect[cm^2]
 
+    two_photon_data: pandas.DataFrame
+        A DataFrame containing the *two photon decay data* with:
+            index: atomic_number, ion_number, level_number_lower, level_number_upper
+            columns: A_ul[1/s], nu0[Hz], alpha, beta, gamma
+
     Attributes
     ----------
     prepared : bool
@@ -92,6 +97,7 @@ class AtomData(object):
     symbol2atomic_number : OrderedDict
     atomic_number2symbol : OrderedDict
     photoionization_data : pandas.DataFrame
+    two_photon_data: pandas.DataFrame
 
     Methods
     -------
@@ -115,6 +121,8 @@ class AtomData(object):
         "collision_data_temperatures",
         "synpp_refs",
         "photoionization_data",
+        "yg_data",
+        "two_photon_data",
     ]
 
     # List of tuples of the related dataframes.
@@ -194,6 +202,8 @@ def __init__(
         collision_data_temperatures=None,
         synpp_refs=None,
         photoionization_data=None,
+        yg_data=None,
+        two_photon_data=None,
     ):
 
         self.prepared = False
@@ -244,6 +254,10 @@ def __init__(
 
         self.photoionization_data = photoionization_data
 
+        self.yg_data = yg_data
+
+        self.two_photon_data = two_photon_data
+
         self._check_related()
 
         self.symbol2atomic_number = OrderedDict(
@@ -448,6 +462,9 @@ def prepare_atom_data(
                 # are not used in downbranch calculations
                 self.macro_atom_data.loc[:, "destination_level_idx"] = -1
 
+            if self.yg_data is not None:
+                self.yg_data = self.yg_data.loc[self.selected_atomic_numbers]
+
         self.nlte_data = NLTEData(self, nlte_species)
 
     def _check_selected_atomic_numbers(self):

tardis/io/schemas/plasma.yml

@@ -86,6 +86,14 @@ properties:
         description: Species that are requested to be treated with continuum
             interactios (radiative/collisional ionization and recombination)
             in the format ['Si II', 'Ca I', etc.]
+      enable_adiabatic_cooling:
+        type: boolean
+        default: false
+        description: enables adiabatic cooling of the electron gas
+      enable_two_photon_decay:
+        type: boolean
+        default: false
+        description: enables two photon decay processes
   helium_treatment:
     type: string
     default: none

tardis/io/util.py

@@ -285,7 +285,6 @@ def get_properties(self):
 
     @property
     def full_hdf_properties(self):
-        # If tardis was compiled --with-vpacket-logging, add vpacket properties
         if hasattr(self, "virt_logging") and self.virt_logging:
             self.hdf_properties.extend(self.vpacket_hdf_properties)
 

tardis/montecarlo/base.py

@@ -334,8 +334,9 @@ def virtual_packet_nu(self):
         except AttributeError:
             warnings.warn(
                 "MontecarloRunner.virtual_packet_nu:"
-                "compile with --with-vpacket-logging"
-                "to access this property",
+                "Set 'virtual_packet_logging: True' in the configuration file"
+                "to access this property"
+                "It should be added under 'virtual' property of 'spectrum' property",
                 UserWarning,
             )
             return None
@@ -347,8 +348,9 @@ def virtual_packet_energy(self):
         except AttributeError:
             warnings.warn(
                 "MontecarloRunner.virtual_packet_energy:"
-                "compile with --with-vpacket-logging"
-                "to access this property",
+                "Set 'virtual_packet_logging: True' in the configuration file"
+                "to access this property"
+                "It should be added under 'virtual' property of 'spectrum' property",
                 UserWarning,
             )
             return None
@@ -360,8 +362,9 @@ def virtual_packet_luminosity(self):
         except TypeError:
             warnings.warn(
                 "MontecarloRunner.virtual_packet_luminosity:"
-                "compile with --with-vpacket-logging"
-                "to access this property",
+                "Set 'virtual_packet_logging: True' in the configuration file"
+                "to access this property"
+                "It should be added under 'virtual' property of 'spectrum' property",
                 UserWarning,
             )
             return None

tardis/montecarlo/setup_package.py

@@ -26,15 +26,6 @@
     define_macros = []
 
 
-if (
-    get_distutils_option(
-        "with_vpacket_logging", ["build", "install", "develop"]
-    )
-    is not None
-):
-    define_macros.append(("WITH_VPACKET_LOGGING", None))
-
-
 def get_extensions():
     sources = ["tardis/montecarlo/montecarlo.pyx"]
     sources += [

tardis/plasma/base.py

@@ -183,6 +183,55 @@ def update(self, **kwargs):
         for module_name in self._resolve_update_list(kwargs.keys()):
             self.plasma_properties_dict[module_name].update()
 
+    def freeze(self, *args):
+        """
+        Freeze plama properties.
+
+        This method freezes plasma properties to prevent them from being
+        updated: the values of a frozen property are fixed in the plasma
+        calculation. This is useful for example for setting up test cases.
+
+        Parameters
+        ----------
+        args : iterable of str
+            Names of plasma properties to freeze.
+
+        Examples
+        --------
+        >>> plasma.freeze('t_electrons')
+        """
+        for key in args:
+            if key not in self.outputs_dict:
+                raise PlasmaMissingModule(
+                    "Trying to freeze property {0}"
+                    " that is unavailable".format(key)
+                )
+            self.outputs_dict[key].frozen = True
+
+    def thaw(self, *args):
+        """
+        Thaw plama properties.
+
+        This method thaws (unfreezes) plasma properties allowing them to be
+        updated again.
+
+        Parameters
+        ----------
+        args : iterable of str
+            Names of plasma properties to unfreeze.
+
+        Examples
+        --------
+        >>> plasma.thaw('t_electrons')
+        """
+        for key in args:
+            if key not in self.outputs_dict:
+                raise PlasmaMissingModule(
+                    "Trying to thaw property {0}"
+                    " that is unavailable".format(key)
+                )
+            self.outputs_dict[key].frozen = False
+
     def _update_module_type_str(self):
         for node in self.graph:
             self.outputs_dict[node]._update_type_str()

tardis/plasma/properties/__init__.py

@@ -8,3 +8,4 @@
 from tardis.plasma.properties.nlte import *
 from tardis.plasma.properties.j_blues import *
 from tardis.plasma.properties.continuum_processes import *
+from tardis.plasma.properties.transition_probabilities import *