Mudirac documentation

.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 937f00123d6a1910ae9922ae9b5621b2
+config: d97a62c9336ac8f233cc36c07e0cb655
 tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/example.rst.txt

@@ -0,0 +1,73 @@
+Example of MuDirac Usage
+========================
+To learn how to use mudirac, let's try a simple example. Open a text editor and write the following:
+
+.. code-block:: bash
+
+    element: Au
+    isotope: 197
+    xr_lines: K1-L2,K1-L3
+    write_spec: T
+
+Save this as :literal:`Au_basic.in` and then pass it to MuDirac. The simulation should be really fast and it should produce the files :literal:`Au_basic.xr.out`, :literal:`Au_basic.log`, :literal:`Au_basic.err` and :literal:`Au_basic.spec.dat`. The :literal:`.log` and :literal:`.err` files are just a log of the program's calculations and a file where any errors are stored; they are not important unless you're trying to figure out what went wrong in a failed calculation. The :literal:`.xr.out` file contains a text summary of the result, and the :literal:`.spec.dat` file contains tabulated data for a simulated spectrum. Let's look at the input file and at what each line does.
+::
+
+    element: Au; isotope: 197
+
+This specifies that we're interested in studying gold, specifically the 197-Au isotope.
+::
+
+    xr_lines: K1-L2,K1-L3
+
+This indicates which X-ray transitions we want to know about. The notation is the IUPAC standard notation for X-ray spectrometry. These would be the transitions connecting the 1s shell (K1) to the 2p1/2 and 2p3/2 shells (L2, L3). Remember that because these orbitals are relativistic, spin-orbit coupling is built into them, and orbitals with different total angular momentum (orbital + spin) have different energies.
+::
+
+   write_spec: T
+
+Finally, this tells to the program to write also a :literal:`.spec.dat` file. Without this line, it wouldn't be created. T here stands for True.
+
+Now open the :literal:`Au_basic.xr.out` file. The contents should look something like this:
+
+.. code-block:: bash
+
+    # Z = 79, A = 197 amu, m = 206.768 au
+    Line    DeltaE (eV)     W_12 (s^-1)
+    K1-L2   1.43693e+07             4.94871e+18
+    K1-L3   1.48315e+07             4.63201e+18
+
+The first line is a header that records the context of the calculation - the element's atomic number and atomic mass, and the mass of the particle in atomic units (for a muon this will always be 206.768 au). The next lines show for each line the transition energy in electron volts and the transition rate in 1/seconds, which connects to the relative intensity of the line in the spectrum. Generally speaking, lines with higher transition rates will be stronger, though the connection isn't perfect as there are other factors at play.
+
+Now, this result is achieved with the default settings, that are in fact insufficient to simulate accurately an atom with a large Z like gold; as a general rule, the higher the charge of a nucleus, the more important all the additional terms. Copy :literal:`Au_basic.in` as :literal:`Au.in` and edit it to add lines so that it looks like this:
+
+.. code-block:: bash
+
+    element: Au
+    isotope: 197
+    xr_lines: K1-L2,K1-L3
+    write_spec: T
+    nuclear_model: FERMI2
+    uehling_correction: T
+    electronic_config: Au
+
+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:`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.
+
+Try running again MuDirac with this input. The calculation should take longer, and this time the output in :literal:`Au.xr.out` should be:
+
+.. code-block:: bash
+
+    # Z = 79, A = 197 amu, m = 206.768 au
+    Line    DeltaE (eV)     W_12 (s^-1)
+    K1-L2   5.5936e+06              1.62308e+18
+    K1-L3   5.76294e+06             1.76987e+18
+
+Note the significant changes - the energies are almost three times smaller than previously! You can try removing each of the new terms individually, or commenting them out by adding :literal:`#` at the beginning of a line, and re-running to see their effects. Now to familiarize yourself you can try a few more things:
+
+1. try adding more :literal:`xr_lines`, for example L1-M2 and L1-M3;
+2. try adding a range of lines; this can be written as K1:M5-K1:M5. It will compute all transitions within the given ranges that obey the selection rules to be allowed;
+3. try plotting the spectra in the :literal:`.spec.dat files`, using Gnuplot or importing them in software like Excel or Origin.

_sources/index.rst.txt

@@ -1,57 +1,37 @@
 .. mudirac- homepage master file
 
-Welcome to mudirac's documentation
+Welcome to MuDirac's documentation
 ===================================
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
-   mudirac- List of input keywords's documentation
-   ...
+
+   installation.rst
+   theory.rst
+   keywords.rst
+   example.rst
 
-mudirac is a muonic atom Dirac equation solver.
+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.
 
-Compiling
-==========
-To compile, create a directory called :literal:`mudirac`; then, within that directory, execute the commands
+Installation
+-------------
+Details for how to install and use MuDirac is given :doc:`here <installation>`.
 
-.. code-block:: bash
-
-   cmake ..
-   make mudirac
-
-In order to run the test suite. within the same directory, run
-
-.. code-block:: bash
-
-   make tests
-   make test
-
-and wait for a few seconds for the tests to complete. If you want :literal:`mudirac` to be accessible from any folder in your computer, add the resulting :literal:`bin` directory to your system :literal:`PATH` environment variable.
-
-Running
-========
-Simulations can be run simply with the command
-
-.. code-block:: bash
-
-   mudirac input.in
-
-where :literal:`.in` file can have any name one prefers. A full list of keywords employable in the :literal:`.in` file and their meaning can be found in :ref:`section_mudirac_input_keywords`.
 
 Citing mudirac
-===============
+---------------
 For the theoretical background on the software and examples of its applications, see the published paper:
 
 Sturniolo, S, Hillier, A. Mudirac: A Dirac equation solver for elemental analysis with muonic X‐rays. X‐Ray Spectrom. 2020; 1– 17. https://doi.org/10.1002/xrs.3212
 
 Cite the above paper if you make use of the software in your work too.
 
 Contact
-========
+--------
 [email protected]
 
 Acknowledgments
-=================
+----------------
 Written with funding from the Ada Lovelace Centre, in collaboration with the ISIS Muon Group.
 

_sources/installation.rst.txt

@@ -0,0 +1,30 @@
+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;
+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:
+
+.. code-block:: bash
+
+   cmake ..
+   make mudirac
+
+In order to run the test suite. within the same directory, run
+
+.. code-block:: bash
+
+   make tests
+   make test
+
+and wait for a few seconds for the tests to complete. If you want :literal:`mudirac` to be accessible from any folder in your computer, add the resulting :literal:`bin` directory to your system :literal:`PATH` environment variable.
+
+Usage
+--------
+MuDirac works simplyby running it with an input file:
+
+.. code-block:: bash
+
+   mudirac input.in
+
+where :literal:`.in` file can have any name one prefers. The input file is a text file containing rows of the form :literal:`keyword: value`. A full list of keywords employable in the :literal:`.in` file and their meaning can be found in :ref:`section_mudirac_input_keywords`.

_sources/keywords.rst.txt

@@ -5,7 +5,7 @@
 
 .. _section_mudirac_input_keywords:
 
-mudirac- List of input keywords's documentation
+Input keywords
 ===========================================================
 
 .. toctree::
@@ -19,12 +19,10 @@ mudirac- List of input keywords's documentation
    Integer keywords
    ...
 
-Input keywords
-===============
 :literal:`mudirac` takes a single input file, containing multiple lines with the format :literal:`<keyword>: <value>`. Here, we list all the currently available keywords, divided by type, their purpose, and default values.
 
 String keywords
-----------------
+~~~~~~~~~~~~~~~~~
 These keywords take a string as value; invalid strings (e.g. a chemical symbol that doesn't correspond to a known element) will give rise to errors.
 
 * :literal:`element`: symbol of the element for the calculation. Determines the nuclear charge. Can be any symbol in the periodic table up to Z=111, Roentgenium (Rg). Default is H.
@@ -40,15 +38,15 @@ These keywords take a string as value; invalid strings (e.g. a chemical symbol t
 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:`sort_byE`: if true, print out the transitions sorted by energy instead than by shell. Default is FALSE.
 
 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).
 
 * :literal:`mass`:  mass of the particle in atomic units (1 = mass of the electron). By default it's the mass of the muon, 206.7683.
@@ -68,7 +66,7 @@ These keywords accept a non-integer number. It can be written normally (e.g. 105
 * :literal:`spec_expdec`: exponential decay parameter :math:`E_{\text{dec}}` for a sensitivity function for the simulated spectrum, in eV. Multiplies the entire spectrum by a function :math:`\exp(-E/E_{\text{dec}})`. Only has effect if :literal:`write\_spec = TRUE`. Default is -1 (no decay).
 
 Integer keywords
------------------
+~~~~~~~~~~~~~~~~~
 Keywords that take an integer number as value.
 
 * :literal:`isotope`: which isotope of the element to consider. Important to determine the mass of the nucleus and its size. Default is -1, which means the most common isotope for the element will be used.

_sources/theory.rst.txt

@@ -0,0 +1,13 @@
+Theory
+=======
+Prediction of frequencies and probabilities of transition between energy levels of muonic atoms
+-------------------------------------------------------------------------------------------------
+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.
+
+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.