updated theory page with image

_sources/index.rst.txt

@@ -12,7 +12,7 @@ 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>`_. Its use and functioning 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 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.
 
 Installation
 -------------

_sources/installation.rst.txt

@@ -1,7 +1,7 @@
 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 loacal system;
+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:
 
@@ -21,7 +21,7 @@ and wait for a few seconds for the tests to complete. If you want :literal:`mudi
 
 Usage
 --------
-MuDirac works simplyby running it with an input file:
+MuDirac works simply by running it with an input file:
 
 .. code-block:: bash
 

_sources/theory.rst.txt

@@ -6,8 +6,17 @@ 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;
-2. for the same reason, the orbitals can overlap significantly with the atomic nucleus, and their energy is affected by the shape of its charge distribution;
-3. the orbitals have much higher binding energies, which means they can also be treated only with a relativistic theory. In classical terms, you could say the muons are 'orbiting' the nucleus at speeds close to that of light.
+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);
 
-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 derived 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 as said above, 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.
+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;
+
+3. the muon orbitals have much higher binding energies, which means they can also be treated only with a relativistic theory. In classical terms, you could say the muons are 'orbiting' the nucleus at speeds close to that of 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). 
+
+
+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.

index.html

@@ -98,7 +98,7 @@ <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>. Its use and functioning 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>
+<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>

installation.html

@@ -82,7 +82,7 @@
   <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 loacal system;
+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>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>cmake<span class="w"> </span>..
@@ -97,7 +97,7 @@ <h1>Installation of MuDirac<a class="headerlink" href="#installation-of-mudirac"
 <p>and wait for a few seconds for the tests to complete. If you want <code class="docutils literal notranslate"><span class="pre">mudirac</span></code> to be accessible from any folder in your computer, add the resulting <code class="docutils literal notranslate"><span class="pre">bin</span></code> directory to your system <code class="docutils literal notranslate"><span class="pre">PATH</span></code> environment variable.</p>
 <section id="usage">
 <h2>Usage<a class="headerlink" href="#usage" title="Link to this heading"></a></h2>
-<p>MuDirac works simplyby running it with an input file:</p>
+<p>MuDirac works simply by running it with an input file:</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>mudirac<span class="w"> </span>input.in
 </pre></div>
 </div>