code review updates

_sources/example.rst.txt

@@ -53,7 +53,7 @@ This adds three more lines:
 
 :literal:`nuclear_model: FERMI2`: This sets the nucleus to be modelled not as a point charge, but as a Fermi 2-term charge distribution, which is far more accurate to reality. The program contains parameters for this distribution for all isotopes of interest in the periodic table. This will account for the finite size of the nucleus, and the overlap of the muon orbitals with it.
 
-:literal:`uehling_correction: T`: This accounts for the Uehling correction, a quantum field effect relevant to electrostatics at these high energies. It can be undestood as accounting for the vacuum itself acting as a polarizable medium; because virtual electron-positron pairs can be generated in quantum field theory, these partially shield the charges and lower the traditional Coulomb force. This is an important term especially for very massive nuclei like Au or Pb and orbitals close to the nucleus.
+:literal:`uehling_correction: T`: This accounts for the Uehling correction, a quantum field effect relevant to electrostatics at these high energies. It can be understood as accounting for the vacuum itself acting as a polarizable medium; because virtual electron-positron pairs can be generated in quantum field theory, these partially shield the charges and lower the traditional Coulomb force. This is an important term especially for very massive nuclei like Au or Pb and orbitals close to the nucleus.
 
 :literal:`electronic_config: Au`: This term includes approximatively the effect of the other electrons orbiting the nucleus. It does not solve the equations for them, rather it just places them in fixed idealised orbitals and builds a negative charge background from them. The result is an additional correction to the energy, that is however tiny compared to the previous two terms, and often easily ignored.
 

_sources/index.rst.txt

@@ -12,14 +12,9 @@ Welcome to MuDirac's documentation
    keywords.rst
    example.rst
 
-MuDirac is a simulation software that integrates the Dirac equation for muonic atoms to compute their X-Ray transition energies; it is written in C++ and can be found on `GitHub <https://github.com/muon-spectroscopy-computational-project/mudirac>`_. The use and functioning of MuDirac 1.0 is extensively documented in the paper `S. Sturniolo, A. Hillier, "Mudirac: A Dirac equation solver for elemental analysiswith muonic X-rays", X-Ray Spectrom. 2020;1–17 <https://onlinelibrary.wiley.com/doi/full/10.1002/xrs.3212>`_, which should be cited by any work using it. Here we will give a quick tutorial on how to start using it for simple cases.
+MuDirac is a simulation software that integrates the Dirac equation for muonic atoms to compute their X-Ray transition energies; it is written in C++ and can be found on `GitHub <https://github.com/muon-spectroscopy-computational-project/mudirac>`_. The use and functioning of MuDirac 1.0 is extensively documented in the paper `S. Sturniolo, A. Hillier, "Mudirac: A Dirac equation solver for elemental analysis with muonic X-rays", X-Ray Spectrom. 2020;1–17 <https://onlinelibrary.wiley.com/doi/full/10.1002/xrs.3212>`_, which should be cited by any work using it. Here we will give a quick tutorial on how to start using it for simple cases.
 
-Installation
--------------
-Details for how to install and use MuDirac is given :doc:`here <installation>`.
-
-
-Citing mudirac
+Citing MuDirac
 ---------------
 For the theoretical background on the software and examples of its applications, see the published paper:
 

_sources/installation.rst.txt

@@ -1,16 +1,17 @@
 Installation of MuDirac
 ========================
-MuDirac used CMake as a build system, and requires a C++ compiler. In order to compile it and prepare it to be executed on a Linux, Unix, or MacOS system with a working C++ compiler installes, follow these steps:
-1. download and unpack (or :literal:`git clone`) the repository on your local system;
-2. within the main folder of the repository (the one containing the :literal:`READ.md` file), create a subfolder called :literal:`build`;
-3. within the :literal:`build` folder, run the following commands:
+MuDirac uses CMake as a build system, and requires a C++ compiler. In order to compile it and prepare it to be executed on a Linux, Unix, or MacOS system with a working C++ compiler installed, follow these steps:
+
+#. Download and unpack (or :literal:`git clone`) the repository on your local system.
+#. Within the main folder of the repository (the one containing the :literal:`READ.md` file), create a subfolder called :literal:`build`.
+#. Within the :literal:`build` folder, run the following commands:
 
 .. code-block:: bash
 
    cmake ..
    make mudirac
 
-In order to run the test suite. within the same directory, run
+In order to run the test suite, within the same directory run:
 
 .. code-block:: bash
 

_sources/keywords.rst.txt

@@ -20,20 +20,22 @@ These keywords take a string as value; invalid strings (e.g. a chemical symbol t
 * :literal:`ideal_atom_minshell`: for this shell, and all above it, treat the atom as a simple hydrogen-like point charge Dirac atom, using the known analytical solution and discarding all corrections. Mostly useful for debugging, or when very high shell states have difficulty to converge. The shell must use IUPAC notation (:math:`K \Rightarrow n=1`, :math:`L \Rightarrow n=2`, etc.). Default is the empty string (no ideal solutions used).
 * :literal:`xr_lines`: the transition or transitions for which energy and rates are desired. Each line must be expressed using the conventional IUPAC notation [Jenkins et al., 1991]. Multiple lines can be separated by commas. For example:
 
-::
+  ::
       
       xr_lines: K1-L2,K1-L3
 	
-In addition, colons can be used to indicate ranges of lines. The notation :literal:`K1:L3-M1` would compute the lines K1-M1, L1-M1, L2-M1 and L3-M1. Note that if some of these lines are forbidden by selection rules, they will simply be skipped. A double colon, like :literal:`K1:L3-K1:L3` would loop on both sides, and not count all repeated lines. 
+  In addition, colons can be used to indicate ranges of lines. The notation :literal:`K1:L3-M1` would compute the lines K1-M1, L1-M1, L2-M1 and L3-M1. Note that if some of these lines are forbidden by selection rules, they will simply be skipped. A double colon, like :literal:`K1:L3-K1:L3` would loop on both sides, and not count all repeated lines. 
 
 Boolean keywords
 ~~~~~~~~~~~~~~~~~
 These keywords can only have a value of TRUE or FALSE. In order to set them true, either the word 'TRUE' or the letter 'T' (regardless of case) work.
 
-* :literal:`uehling_correction`: whether to turn on or not the Uehling correction. Default is FALSE.
-* :literal:`write~_spec`:  if true, write a spectrum file using the transition lines found broadened with Gaussian functions. Other parameters can be specified with different keywords. Default is FALSE.
+* :literal:`uehling_correction`: whether to turn on the Uehling correction or not. Default is FALSE.
+* :literal:`write_spec`:  if true, write a spectrum file using the transition lines found broadened with Gaussian functions. Other :ref:`floating_point_keywords` starting with :literal:`spec_` can then be specified. Default is FALSE.
 * :literal:`sort_byE`: if true, print out the transitions sorted by energy instead than by shell. Default is FALSE.
 
+.. _floating_point_keywords:
+
 Floating point keywords
 ~~~~~~~~~~~~~~~~~~~~~~~~
 These keywords accept a non-integer number. It can be written normally (e.g. 105.3) or in scientific notation (e.g. 1.053E2).

_sources/theory.rst.txt

@@ -6,7 +6,7 @@ X-Ray Spectroscopy with negative muons
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 While positive muons can be used as magnetic probes acting as if they were light protons, negative muons have wholly different uses due to behaving in matter more as if they were heavy electrons. Negative muons possess the same charge and spin as electrons, and so will form bound states with nuclei that are known as muonic atoms. These atoms possess peculiar properties due to the heavier mass of the muon:
 
-1. the muon orbitals around the nucleus are much smaller and denser than the electronic ones, meaning that the muon tends to be rather insensitive to the presence of electrons - as it is closer to the nucleus than any of them (See figure 1);
+1. the muon orbitals around the nucleus are much smaller and denser than the electronic ones, meaning that the muon tends to be rather insensitive to the presence of electrons - as it is closer to the nucleus than any of them (See Figure 1);
 
 2. for the same reason, the muon orbitals can overlap significantly with the atomic nucleus, and their energy is affected by the shape of its charge distribution;
 
@@ -16,7 +16,7 @@ While positive muons can be used as magnetic probes acting as if they were light
 .. figure:: _static/Figure-MuDirac.jpg
    :alt: Schematic drawing of the muon cascade process and the electron configuration evolution in a muonic iron atom within Fe metal. 
 
-   Schematic drawing of the muon cascade process and the electron configuration evolution in a muonic iron atom within Fe metal. Side feeding and electron refilling, via radiative decay or electronic Auger decay, fill the electron holes. It is assumed that the number of 4s electrons is a constant during the cascade because of rapid N-shell side feeding. Figure taken from T. Okumura et. al. PHYSICAL REVIEW LETTERS 127, 053001 (2021). 
+Figure 1: Schematic drawing of the muon cascade process and the electron configuration evolution in a muonic iron atom within Fe metal. Side feeding and electron refilling, via radiative decay or electronic Auger decay, fill the electron holes. It is assumed that the number of 4s electrons is a constant during the cascade because of rapid N-shell side feeding. Figure taken from T. Okumura et. al. PHYSICAL REVIEW LETTERS 127, 053001 (2021). 
 
 
 The consequence of these facts is that when cascading on a nucleus to form a muonic atom, muons will shed their energy in the form of highly energetic X-Ray photons, and the specific energies of these photons will be tied to the transitions between levels that are unique for each element. For this reason, `muons can be an excellent probe for non-destructive elemental analysis <https://www.sciencedirect.com/science/article/abs/pii/S0026265X1500301X?via%3Dihub>`_. The exact characteristic energies for each element can be tabulated by experimental calibration, but they can also be modelled from first principles, by solving the quantum equations to find the orbitals and their energies. However, this is not as simple as applying the usual Schrödinger equation, because the muons orbit the nucleus at relativistic energies and the Dirac equation is necessary; plus, at these energies, the electrostatic potential itself stops being perfectly Coulombic. For these reasons, we have provided a software that easily allows one to perform these calculations by including all necessary details to achieve precision sufficient for the interpretation of experiments.

example.html

@@ -117,7 +117,7 @@ <h1>Example of MuDirac Usage<a class="headerlink" href="#example-of-mudirac-usag
 </div>
 <p>This adds three more lines:</p>
 <p><code class="docutils literal notranslate"><span class="pre">nuclear_model:</span> <span class="pre">FERMI2</span></code>: This sets the nucleus to be modelled not as a point charge, but as a Fermi 2-term charge distribution, which is far more accurate to reality. The program contains parameters for this distribution for all isotopes of interest in the periodic table. This will account for the finite size of the nucleus, and the overlap of the muon orbitals with it.</p>
-<p><code class="docutils literal notranslate"><span class="pre">uehling_correction:</span> <span class="pre">T</span></code>: This accounts for the Uehling correction, a quantum field effect relevant to electrostatics at these high energies. It can be undestood as accounting for the vacuum itself acting as a polarizable medium; because virtual electron-positron pairs can be generated in quantum field theory, these partially shield the charges and lower the traditional Coulomb force. This is an important term especially for very massive nuclei like Au or Pb and orbitals close to the nucleus.</p>
+<p><code class="docutils literal notranslate"><span class="pre">uehling_correction:</span> <span class="pre">T</span></code>: This accounts for the Uehling correction, a quantum field effect relevant to electrostatics at these high energies. It can be understood as accounting for the vacuum itself acting as a polarizable medium; because virtual electron-positron pairs can be generated in quantum field theory, these partially shield the charges and lower the traditional Coulomb force. This is an important term especially for very massive nuclei like Au or Pb and orbitals close to the nucleus.</p>
 <p><code class="docutils literal notranslate"><span class="pre">electronic_config:</span> <span class="pre">Au</span></code>: This term includes approximatively the effect of the other electrons orbiting the nucleus. It does not solve the equations for them, rather it just places them in fixed idealised orbitals and builds a negative charge background from them. The result is an additional correction to the energy, that is however tiny compared to the previous two terms, and often easily ignored.</p>
 <p>Try running again MuDirac with this input. The calculation should take longer, and this time the output in <code class="docutils literal notranslate"><span class="pre">Au.xr.out</span></code> should be:</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="c1"># Z = 79, A = 197 amu, m = 206.768 au</span>

index.html

@@ -98,13 +98,9 @@ <h1>Welcome to MuDirac’s documentation<a class="headerlink" href="#welcome-to-
 <li class="toctree-l1"><a class="reference internal" href="example.html">Example of MuDirac Usage</a></li>
 </ul>
 </div>
-<p>MuDirac is a simulation software that integrates the Dirac equation for muonic atoms to compute their X-Ray transition energies; it is written in C++ and can be found on <a class="reference external" href="https://github.com/muon-spectroscopy-computational-project/mudirac">GitHub</a>. The use and functioning of MuDirac 1.0 is extensively documented in the paper <a class="reference external" href="https://onlinelibrary.wiley.com/doi/full/10.1002/xrs.3212">S. Sturniolo, A. Hillier, “Mudirac: A Dirac equation solver for elemental analysiswith muonic X-rays”, X-Ray Spectrom. 2020;1–17</a>, which should be cited by any work using it. Here we will give a quick tutorial on how to start using it for simple cases.</p>
-<section id="installation">
-<h2>Installation<a class="headerlink" href="#installation" title="Link to this heading"></a></h2>
-<p>Details for how to install and use MuDirac is given <a class="reference internal" href="installation.html"><span class="doc">here</span></a>.</p>
-</section>
+<p>MuDirac is a simulation software that integrates the Dirac equation for muonic atoms to compute their X-Ray transition energies; it is written in C++ and can be found on <a class="reference external" href="https://github.com/muon-spectroscopy-computational-project/mudirac">GitHub</a>. The use and functioning of MuDirac 1.0 is extensively documented in the paper <a class="reference external" href="https://onlinelibrary.wiley.com/doi/full/10.1002/xrs.3212">S. Sturniolo, A. Hillier, “Mudirac: A Dirac equation solver for elemental analysis with muonic X-rays”, X-Ray Spectrom. 2020;1–17</a>, which should be cited by any work using it. Here we will give a quick tutorial on how to start using it for simple cases.</p>
 <section id="citing-mudirac">
-<h2>Citing mudirac<a class="headerlink" href="#citing-mudirac" title="Link to this heading"></a></h2>
+<h2>Citing MuDirac<a class="headerlink" href="#citing-mudirac" title="Link to this heading"></a></h2>
 <p>For the theoretical background on the software and examples of its applications, see the published paper:</p>
 <p>Sturniolo, S, Hillier, A. Mudirac: A Dirac equation solver for elemental analysis with muonic X‐rays. X‐Ray Spectrom. 2020; 1– 17. <a class="reference external" href="https://doi.org/10.1002/xrs.3212">https://doi.org/10.1002/xrs.3212</a></p>
 <p>Cite the above paper if you make use of the software in your work too.</p>

installation.html

@@ -81,15 +81,17 @@
 
   <section id="installation-of-mudirac">
 <h1>Installation of MuDirac<a class="headerlink" href="#installation-of-mudirac" title="Link to this heading"></a></h1>
-<p>MuDirac used CMake as a build system, and requires a C++ compiler. In order to compile it and prepare it to be executed on a Linux, Unix, or MacOS system with a working C++ compiler installes, follow these steps:
-1. download and unpack (or <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span></code>) the repository on your local system;
-2. within the main folder of the repository (the one containing the <code class="docutils literal notranslate"><span class="pre">READ.md</span></code> file), create a subfolder called <code class="docutils literal notranslate"><span class="pre">build</span></code>;
-3. within the <code class="docutils literal notranslate"><span class="pre">build</span></code> folder, run the following commands:</p>
+<p>MuDirac uses CMake as a build system, and requires a C++ compiler. In order to compile it and prepare it to be executed on a Linux, Unix, or MacOS system with a working C++ compiler installed, follow these steps:</p>
+<ol class="arabic simple">
+<li><p>Download and unpack (or <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">clone</span></code>) the repository on your local system.</p></li>
+<li><p>Within the main folder of the repository (the one containing the <code class="docutils literal notranslate"><span class="pre">READ.md</span></code> file), create a subfolder called <code class="docutils literal notranslate"><span class="pre">build</span></code>.</p></li>
+<li><p>Within the <code class="docutils literal notranslate"><span class="pre">build</span></code> folder, run the following commands:</p></li>
+</ol>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>cmake<span class="w"> </span>..
 make<span class="w"> </span>mudirac
 </pre></div>
 </div>
-<p>In order to run the test suite. within the same directory, run</p>
+<p>In order to run the test suite, within the same directory run:</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>make<span class="w"> </span>tests
 make<span class="w"> </span><span class="nb">test</span>
 </pre></div>