Merge pull request #9 from muon-spectroscopy-computational-project/mu…

…dirac_keyword_doc

Mudirac keyword doc

.gitignore

@@ -74,3 +74,17 @@ cscope.files
 cscope.out
 cscope.in.out
 cscope.po.out
+
+# Sphinx
+.DS_Store
+.idea
+_build
+__source
+__test
+.doctrees
+doctrees
+.buildinfo
+objects.inv
+_plantuml
+__pycache__
+docs/build/*

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/conf.py

@@ -0,0 +1,42 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'MuDirac documentation'
+copyright = '2024, Simone Sturniolo'
+author = 'Simone Sturniolo'
+release = 'November 16, 2020'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    #'sphinx.ext.autodoc',
+    #'breathe',
+    'sphinx_rtd_theme',
+    # Other extensions...
+]
+
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+html_context = {
+    "display_github": True, # Integrate GitHub
+    "github_user": "muon-spectroscopy-computational-project", # Username
+    "github_repo": "mudirac", # Repo name
+    "github_version": "main", # Version
+    "conf_py_path": "/docs/source", # Path in the checkout to the docs root
+}

docs/source/example.rst

@@ -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 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.
+
+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.

docs/source/index.rst

@@ -0,0 +1,32 @@
+.. mudirac- homepage master file
+
+Welcome to MuDirac's documentation
+===================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   installation.rst
+   theory.rst
+   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 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.
+
+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
+--------
+leandro.liborio@stfc.ac.uk
+
+Acknowledgments
+----------------
+Written with funding from the Ada Lovelace Centre, in collaboration with the ISIS Muon Group.
+

docs/source/installation.rst

@@ -0,0 +1,31 @@
+Installation of MuDirac
+========================
+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:
+
+.. 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 simply by 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`.

docs/source/keywords.rst

@@ -0,0 +1,75 @@
+.. mudirac- List of input keywords documentation master file, created by
+   sphinx-quickstart on Thu Feb 15 09:03:01 2024.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+.. _section_mudirac_input_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.
+* :literal:`nuclear_model`: model used to describe the nucleus. Can be POINT (point charge), SPHERE (finite size, uniformly charged spherical nucleus) or FERMI2 (Fermi 2-term charge distribution). Default is POINT.
+* :literal:`electronic_config`: electronic configuration to use in order to describe the negative charge background. Can be a full string describing the configuration (e.g. ``1s2 2s2 2p2``), an element symbol to represent the default configuration of that atom when neutral (e.g. ``C``) or a mix of the two (e.g. ``[He] 2s2 2p2``). Default is the empty string (no electrons).
+* :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. 
+
+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 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).
+
+* :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.
+* :literal:`energy_tol`: absolute tolerance for energy convergence when searching for eigenvalues. Iterations will stop once the energy change is smaller than this number, in atomic units. Default is 1E-7.
+* :literal:`energy_damp`: a damping parameter used in steepest descent energy search to ease convergence. Used to multiply the suggested step :math:`\delta E` and make it smaller. Helps avoiding overshooting; fine-tuning it might help to converge difficult calculations, while making it bigger might make convergence faster in simple ones. Default is 0.5.
+* :literal:`max_dE_ratio`: maximum ratio between energy step, :math:`\delta E`, and current energy :math:`E` in convergence search. If the suggested step exceeds this ratio times the guessed energy, it will be rescaled. This also serves as a measure to avoid overshooting and can be tweaked to get around cases of bad convergence. Default is 0.1.
+* :literal:`node_tol`: tolerance parameter used to identify and count nodes in wavefunctions. Very unlikely to need any tweaking. Default is 1E-6.
+* :literal:`loggrid_step`: step of the logarithmic grid. Default is 0.005.
+* :literal:`loggrid_center`: center of the logarithmic grid in units of :math:`a_0 = 1/(Zm)`. Default is 1.
+* :literal:`uehling_lowcut`: low cutoff for Uehling potential, under which the radius will be considered 0. Default is 0.
+* :literal:`uehling_highcut`: high cutoff for Uehling potential, over which the radius will be considered :math:`r >> c`. Default is INFINITY.
+* :literal:`econf_rhoeps`: charge density threshold under which the electronic charge background will be truncated and treated as zero. Default is 1E-4.
+* :literal:`econf_rin_max`: upper limit for the innermost radius of the electronic charge background grid. Default is -1 (no limit).
+* :literal:`econf_rout_min`: lower limit for the outermost radius of the electronic charge background grid. Default is -1 (no limit)
+* :literal:`spec_step`: energy step for the simulated spectrum, in eV. Only has effect if :literal:`write\_spec = TRUE`. Default is 1E2 eV.
+* :literal:`spec_linewidth`: Gaussian broadening width for the simulated spectrum, in eV. Only has effect if :literal:`write\_spec = TRUE`. Default is 1E3 eV.
+* :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.
+* :literal:`max_E_iter`: maximum number of iterations to perform when searching for the energy of a state. If exceeded, convergence will fail. Increase this value for slow convergences that are however progressing. Default is 100.
+* :literal:`max_nodes_iter`: maximum number of iterations to perform when searching for a starting energy value that gives a state the expected number of nodes. If exceeded, convergence will fail. Should generally not need to be adjusted. Default is 100.
+* :literal:`max_state_iter`: maximum number of iterations to perform when searching for a state. This loop encloses both node-based and energy-based search. Once a state is converged, the program checks again that it has the correct number of nodes. If it does not, the state is stored for future use and to provide an upper or lower limit to the energy of the searches and then the process is repeated. This number represents how much can the process be repeated before failing. Should not generally need to be adjusted. Default is 100.
+* :literal:`uehling_steps`: integration steps for the Uehling potential. Higher numbers will make the Uehling energy more precise but increase computation times. Default is 100.
+* :literal:`xr_print_precision`: number of digits after the point to use when printing out energies and transition rates in the :literal:`.xr.out` file. Default is -1 (print as many as possible).
+* :literal:`verbosity`: verbosity level. Going from 1 to 3 will increase the amount of information printed to the log file. Default is 1.
+* :literal:`output`: output level. Going from 1 to 3 will increase the amount of files produced. Specifically:
+   1. will print out only the transition energies and rates in the :literal:`.xr.out` file;
+   2. will print out also each of the states in a separate ASCII file as well as the transition matrices for each line;
+   3. is reserved for future uses and currently has the same effect as 2.
+
+