LDAmorim · ax3l · Jul 30, 2021
diff --git a/docs/src/example/figs.rst b/docs/src/example/figs.rst
@@ -3,11 +3,11 @@
 Results
 =======
 
-The *input.txt* text file contained in the `example` folder of the GitHub repo models 20 primary electrons interacting with a 10 mm thick Tungsten foil generating electron-positron pairs through the decay of Bremsstrahlung radiation.
+The ``input.txt`` text file contained in the ``example`` folder of the GitHub repo models 20 primary electrons interacting with a 10 mm thick Tungsten foil generating electron-positron pairs through the decay of Bremsstrahlung radiation.
 
 The resulting particles drift for 1 mm in vaccum intersecting a wide thin lens tuned to focus low energy (65 MeV) positrons.
 
-Running GPos with it and then using the Python script *gpos_plot.py* (instructions on how to use it can be found in :ref:`vis`) will generate various plots showing the 2D particle distributions at different stages of the simulation.
+Running GPos with it and then using the Python script ``gpos_plot.py`` (instructions on how to use it can be found in :ref:`vis`) will generate various plots showing the 2D particle distributions at different stages of the simulation.
 
 At the end of the simulation the lower energy and higher divergence electrons and positrons from the cloud will be spread out as can be seen in Fig. :numref:`fig_2d`.
 
@@ -31,4 +31,4 @@ Figure :numref:`fig_lens` shows the impact of introducing the lens (solid vs das
    Trajectory of each positron (various colours) created as they propagate in vacuum from the end of the foil, pass through the thin lens (vertical blue line) at z=6 mm and reach the end of the drift.
    Solid/dashed lines represent results with/out the effect of the lens.
    The dots at the drift position corroborate the lens calculations done in the code and those in the python scripts.
-   Axis show the propagation (horizontal) and transverse (vertical) directions.
+   Axis show the propagation (horizontal) and transverse (vertical) directions.
diff --git a/docs/src/example/index.rst b/docs/src/example/index.rst
@@ -9,11 +9,11 @@ To help you start using GPos, there is an example folder contained in its GitHub
    :widths: 20 20
    :header-rows: 0
 
-   * - input.txt
+   * - ``input.txt``
      - sample short run input file - parameters are detailed in :ref:`eg`
-   * - gpos-run.sh
+   * - ``gpos-run.sh``
      - bash script to run GPos - refer to :ref:`build` for more information
-   * - gpos_***.py  
+   * - ``gpos_***.py``
      - python analysis and visualization scripts - described in :ref:`vis`
 
 To get more information on the example case and its results, please see:

diff --git a/docs/src/index.rst b/docs/src/index.rst
@@ -2,27 +2,27 @@ GPos
 ====
 
 
-Geant4 based positron beam source (GPos) is an easy-to-use publicly available `c++` code, with support for hybrid MPI and openPMD as well as parallel I/O, tool created to model relativistic particle beam and solid targets interactions.
+Geant4 based positron beam source (GPos) is an easy-to-use publicly available *C++* code, with support for hybrid MPI and openPMD as well as parallel I/O, tool created to model relativistic particle beam and solid targets interactions.
 
 It is developed at LBNL to address the problem of building a compact, high-energy (GeV) and efficient positron source (via Bremsstrahlung and photon-decay in the target) using the LBNL `BELLA <https://bella.lbl.gov/>`_ center laser-plasma technology.
 
-The code relies on the Object-Oriented `Geant4 <https://geant4.web.cern.ch/node/1>`_ HEP Monte Carlo based toolkit libraries, produces particle data in `openPMD <https://openpmd-api.readthedocs.io/en/0.13.3/#>`_ format and has been adapted to run in the supercompter at `NERSC <https://www.nersc.gov/>`_.
+The code relies on the Object-Oriented `Geant4 <https://geant4.web.cern.ch/node/1>`_ HEP Monte Carlo based toolkit libraries, produces particle data in `openPMD <https://www.openPMD.org>`_ format and has been adapted to run on the supercompters at `NERSC <https://www.nersc.gov/>`_.
 
 Users can easily change the beam properties (such as mean energy, energy spread, divergence, size), the vacuum space and foil configuration (varying foil type and dimensions) as well as the drift space, where the resulting particles can be ballistically propagated and focused/defocused by a thin lens (users can alter the drift distance and tune the lens energy), in the input file.
 
-GPos can be compiled with `CMAKE` and scripts using the open-source `spack` package manager (located in the `src`, `docs` and `example` folders) .
+GPos can be compiled with `CMake <https://hsf-training.github.io/hsf-training-cmake-webpage/>`__ and scripts using the open-source `Spack <https://www.spack.io>`_ package manager (located in the ``src``, ``docs`` and ``example`` folders) .
 
 
 Code
 ----
 
 The open-source code can be found in the *GitHub* repo `GPos <https://github.com/LDAmorim/GPos>`_.
 
-For questions, bug reports or to request new features and changes, please feel free to open a new `issues <https://github.com/LDAmorim/GPos/issues>`_.
+For questions, bug reports or to request new features and changes, please feel free to open a new `issue <https://github.com/LDAmorim/GPos/issues>`_.
 
-Changes can be tested locally using the scripts *GPos_test.py* and *GPos_plot.py* (located in the `example` folder).
+Changes can be tested locally using the scripts ``GPos_test.py`` and ``GPos_plot.py`` (located in the ``example`` folder).
 
-There is a small stand-alone electron-beam-tungsten-foil example input file, run, test and analysis script in the repo (also located in the `example` folder).
+There is a small stand-alone electron-beam-tungsten-foil example input file, run, test and analysis script in the repo (also located in the ``example`` folder).
 
 
 Documentation

diff --git a/docs/src/intro/intro.rst b/docs/src/intro/intro.rst
@@ -19,15 +19,15 @@ Multiple new methods, where the plasmas were excited by Laguerre Gaussian laser
 Although there are positron sources available and codes that have been explored to model them [:ref:`Ushakov <Ushakov>`], our goal is to build a higher-energy (GeV) and more compact positron source to test and develop those methods experimentally at the BELLA center of the Lawrence Berkeley National Laboratory [:ref:`BELLA <BELLA>`].
 We used GPos as well as the Particle-In-Cell Warpx code [:ref:`WarpX <WarpX>`] to find the optimal configuration for that source using the Petta-Watt (PW) laser and plasma capillary technology available at BELLA, numerically.
 
-The c++ GPos code is a parallelized tool to apply the physics modeled by the Geant4 toolkit [:ref:`Geant4 <Allison>`] to the case in which a relativistic electron beam is sent into a single, thin, solid and high atomic-number foil.
+The C++ GPos code is a parallelized tool to apply the physics modeled by the Geant4 toolkit [:ref:`Geant4 <Allison>`] to the case in which a relativistic electron beam is sent into a single, thin, solid and high atomic-number foil.
 As each of the modeled electrons propagate near the deflecting fields of the intense foil atoms, they are deccelerated and produce what is called *Bremsstrahlung* radiation.
 That radiation, also near the fields of the foil atoms, can be converted into electron-positron pairs from where positrons can be extracted to form the positron beam of interest.
 In our study, we understood that the key challenges for producing high quality positron beams directly from the foil is their broad energy spectrum and high divergence that increase with the number of interactions responsible for creating more positrons.
 We found that in the optimal case, the foil is thin enough (near 1 mm) to provide sufficient positrons whilst maintaining the beam and positrons quality (transverse size and divergence).
 Varying the foil type (i.e. material) has a similar effect, in numerical terms, as changing the thickness by increasing or reducing the number of electron-atom and radiation-atom interactions.
 We also used GPos to explore how making the beams drift in vacuum (ballistically, i.e. in regimes where space-charge effects are negligible) with and witout a focusing lens (modeled by the thin lens approximation) could aid to improving the final positron beam quality and longitudinal separation of the three species.
 
-The data of all three species at the exit of the foil, the primary electron beam and secondary electron-positron cloud, is stored in the `openPMD` standard `HDF5` format [:ref:`openPMD <openPMD>`] that is compatible with `WarpX` input - allowing direct simulations of the beams evolution and acceleration in plasmas.
+The data of all three species at the exit of the foil, the primary electron beam and secondary electron-positron cloud, is stored in the `openPMD` standard `HDF5` format [:ref:`openPMD <openPMD-standard>`] that is compatible with `WarpX` input - allowing direct simulations of the beams evolution and acceleration in plasmas.
 In our research we determined that the best option for building a source at BELLA is to send the positrons generated in the foil into a laser-driven plasma acceleration stage, as opposed to being sent directly into a plasma to be excited by the primary electron beam [:ref:`Amorim <Amorim>`].
 
 Although GPos was designed and tested with properties similar to those delivered from PW laser driven plasma capillary at BELLA, it's simple input file (where beam, foil and space properties can be changed) can be easily adapted to model various configurations useful to other laboratories and generation of other particles (for example muons).
@@ -37,48 +37,48 @@ References
 
 .. _Harari:
 
-`Y. N. Harari, *Sapiens: A Brief History of Humankind*, Harvill Secker, 2014, ISBN 1846558239, 9781846558238 <https://books.google.pt/books/about/Sapiens.html?id=B4ARBAAAQBAJ&redir_esc=y>`_.
+Y. N. Harari, *Sapiens: A Brief History of Humankind*, Harvill Secker, 2014, `ISBN 1846558239, 9781846558238 <https://books.google.pt/books/about/Sapiens.html?id=B4ARBAAAQBAJ&redir_esc=y>`_.
 
 .. _Gray:
 
-`H. M. Gray, *Future colliders for the high-energy frontier*, Reviews in Phys., Vol. 6, 100053, 2021, ISSN 2405-4283 <https://doi.org/10.1016/j.revip.2021.100053>`_.
+H. M. Gray, *Future colliders for the high-energy frontier*, Reviews in Phys., Vol. 6, 100053, 2021, `ISSN 2405-4283 <https://doi.org/10.1016/j.revip.2021.100053>`_.
 
 .. _ATLAS:
 
-`atlas.cern/updates/press-statement/new-year-13-tev <https://atlas.cern/updates/press-statement/new-year-13-tev>`_
+K. Anthony, *ATLAS kicks off a new year at 13 TeV*, 2017. `atlas.cern/updates/press-statement/new-year-13-tev <https://atlas.cern/updates/press-statement/new-year-13-tev>`_
 
 .. _Joshi:
 
-`C. Joshi, *Plasma-based accelerators: then and now*, Plasma Phys. Control. Fusion, Vol. 61, 10, 104001, 2019 <https://doi.org/10.1088/1361-6587/ab396a>`_
+C. Joshi, *Plasma-based accelerators: then and now*, Plasma Phys. Control. Fusion, Vol. 61, 10, 104001, 2019. `DOI:10.1088/1361-6587/ab396a <https://doi.org/10.1088/1361-6587/ab396a>`_
 
 .. _Gonsalves:
 
-`A. J. Gonsalves et al., *Petawatt Laser Guiding and Electron Beam Acceleration to 8 GeV in a Laser-Heated Capillary Discharge Waveguide*, Phys. Rev. Lett. 122, 084801, 2019 <https://doi.org/10.1103/PhysRevLett.122.084801>`_.
+A. J. Gonsalves et al., *Petawatt Laser Guiding and Electron Beam Acceleration to 8 GeV in a Laser-Heated Capillary Discharge Waveguide*, Phys. Rev. Lett. 122, 084801, 2019. `DOI:10.1103/PhysRevLett.122.084801 <https://doi.org/10.1103/PhysRevLett.122.084801>`_.
 
 .. _BELLA:
 
-`bella.lbl.gov <https://bella.lbl.gov/>`_.
+The Berkeley Lab Laser Accelerator (BELLA) Center, `bella.lbl.gov <https://bella.lbl.gov>`_.
 
 .. _Ushakov:
 
-`A. Ushakov∗ et al., *Positron Source simulation using Geant4*, Proceedings of IPAC’10, Kyoto, Japan, POSITRON SOURCE SIMULATIONS USING GEANT4 <https://accelconf.web.cern.ch/IPAC10/papers/thpec023.pdf>`_
+A. Ushakov et al., *Positron Source simulation using Geant4*, Proceedings of IPAC’10, Kyoto, Japan, `POSITRON SOURCE SIMULATIONS USING GEANT4 <https://accelconf.web.cern.ch/IPAC10/papers/thpec023.pdf>`_
 
 .. _WarpX:
 
-`warpx.readthedocs.io/en/latest <https://warpx.readthedocs.io/en/latest>`_.
+J.-L. Vay et al., *Modeling of a chain of three plasma accelerator stages with the WarpX electromagnetic PIC code on GPUs*, Physics of Plasmas 28, 023105, 2021. `DOI:10.1063/5.0028512 <https://doi.org/10.1063/5.0028512>`_. Repository: `github.com/ECP-WarpX/WarpX <https://github.com/ECP-WarpX/WarpX>`__
 
 .. _Sarri:
 
-`G. Sarri, *Spectral and spatial characterisation of laser-driven positron beams*, Plasma Phys. Control. Fusion, 59, 2017 <https://doi.org/10.1088/0741-3335/59/1/014015>`_.
+G. Sarri, *Spectral and spatial characterisation of laser-driven positron beams*, Plasma Phys. Control. Fusion, 59, 2017. `DOI:10.1088/0741-3335/59/1/014015 <https://doi.org/10.1088/0741-3335/59/1/014015>`_.
 
 .. _Allison:
 
-`J. Allison et al., *Recent developments in Geant4*, Nucl. Instrum. Methods: Phys. Res 835, 186-225, 2016 <https://doi.org/10.1016/j.nima.2016.06.125>`_
+J. Allison et al., *Recent developments in Geant4*, Nucl. Instrum. Methods: Phys. Res 835, 186-225, 2016. `DOI:10.1016/j.nima.2016.06.125 <https://doi.org/10.1016/j.nima.2016.06.125>`_
 
-.. _openPMD:
+.. _openPMD-standard:
 
-`readthedocs.org/projects/openpmd-api <https://readthedocs.org/projects/openpmd-api>`_
+A. Huebl et al., *openPMD: A meta data standard for particle and mesh based data*, 2015. `DOI:10.5281/zenodo.591699 <https://doi.org/10.5281/zenodo.591699>`_
 
 .. _Amorim:
 
-L. D. Amorim et al., *Positron beam plasma-based source for BELLA* (to be submitted 2021)
+L. D. Amorim et al., *Positron beam plasma-based source for BELLA* (to be submitted 2021)
diff --git a/docs/src/structure/structure.rst b/docs/src/structure/structure.rst
@@ -88,8 +88,8 @@ Selection
 
 GPos stores particles final track information if (according to user-defined values specified in input.txt):
 
-* particle species is in *s_list*
+* particle species is in ``s_list``
 * particle did not decay / reached cut-off (explained in list below)
 * particle did not leave the world space transversely
-* particle energy is above species *encutoff*
-* particle longitudinal momentum is above species *pzcutoff*
+* particle energy is above species ``encutoff``
+* particle longitudinal momentum is above species ``pzcutoff``
diff --git a/docs/src/visualization/visualization.rst b/docs/src/visualization/visualization.rst
@@ -4,15 +4,15 @@ Visualization
 =============
 
 
-GPos output data can be analysed using the Python (version 3 or higher) example scripts present in the `example` repo folder:
+GPos output data can be analysed using the Python (version 3 or higher) example scripts present in the ``example`` repo folder:
 
 ``gpos_funcs.py``
   Script that includes the functions to read, analyse and plot GPos data files of selected species and positions.
 
-``gpos_test.py`` (python gpos_test.py <path to folder containing openPMD files> <array of species>)
-  Script that uses the necessary functions of `gpos_funcs.py` to compare selected GPos output particle data and species properties.
+``gpos_test.py <path to folder containing openPMD files> <array of species>``
+  Script that uses the necessary functions of ``gpos_funcs.py`` to compare selected GPos output particle data and species properties.
 
-``gpos_plot.py`` (python gpos_test.py <path to folder containing openPMD files> <array of species>)
+``gpos_plot.py <path to folder containing openPMD files> <array of species>``
   Script that generates plots of the overlap of the 2D distributions of selected species at selected positions  and stores them under a new "Plots" folder.
 
 
@@ -51,4 +51,4 @@ To install using the `spack <https://spack.readthedocs.io/en/latest/>`_ package
 
 .. note::
 
-  Syntax of all Python scripts is tested at each `Pull Request` and `Push` in the *linux* workflow of the GitHub repo and *gpos_test.py* is executed to confirm accuracy of results.
+  Syntax of all Python scripts is tested at each `Pull Request` and `Push` in the *Linux* workflow of the GitHub repo and ``gpos_test.py`` is executed to confirm accuracy of results.