Refactoring documentation (#989)

* add workshop and update README.md * restructuring index.rst * start to restructure input parameters * some corrections * Apply suggestions from code review --------- Co-authored-by: Maxence Thévenet <[email protected]>
Hi-PACE · Jun 27, 2023 · ed383dc · ed383dc
1 parent 6ece70d
commit ed383dc
Show file tree

Hide file tree

Showing 6 changed files with 316 additions and 167 deletions.
diff --git a/README.md b/README.md
@@ -6,16 +6,23 @@
 [![DOI (source)](https://img.shields.io/badge/DOI%20(source)-10.5281/zenodo.5358483-blue.svg)](https://doi.org/10.5281/zenodo.5358483)
 [![DOI (paper)](https://img.shields.io/badge/DOI%20(paper)-10.1016/j.cpc.2022.108421-blue.svg)](https://doi.org/10.1016/j.cpc.2022.108421)
 
-HiPACE++ is an open-source portable GPU-capable quasistatic particle-in-cell code for wakefield acceleration written in C++.
+HiPACE++ is an open-source portable GPU-capable quasi-static particle-in-cell code for wakefield acceleration written in C++.
 It is a full re-writing of the legacy code [HiPACE](http://dx.doi.org/10.1088/0741-3335/56/8/084012), the Highly efficient Plasma ACcelerator Emulator.
 Its main features are:
- - Multiple beams and multiple plasma species to simulation beam-driven wakefield acceleration
- - Field ionization of the plasma using the ADK model
- - Two field solver methods, the original HiPACE predictor-corrector loop and an [explicit solver](https://arxiv.org/abs/2012.00881)
+ - Multiple beam and plasma species to simulation beam-driven wakefield acceleration
+ - A laser envelope solver to simulate laser-driven wakefield acceleration
+ - An advanced [explicit field solver](https://doi.org/10.1103/PhysRevAccelBeams.25.104603) for increased accuracy
  - Diagnostics compliant with the [openPMD standard](https://github.com/openPMD/openPMD-standard)
- - Read an arbitrary particle beam from file
- - more coming soon...
+ - Arbitrary profiles for the beams and plasma profiles
+ - Readers from files for the beam and laser profiles
+ - Adaptive time step and sub-cycling
+ - Additional physics (field ionization, binary collisions, temperature effects, radiation reactions)
 
 HiPACE++ is built on the [AMReX](https://amrex-codes.github.io) library, which provides for particle and field data structures.
 
-Please have a look at our [documentation](https://hipace.readthedocs.io) and join the [chat](https://hipace.readthedocs.io/en/latest/run/chat.html)!
+Please have a look at our [documentation](https://hipace.readthedocs.io) and join the [chat](https://hipace.readthedocs.io/en/latest/run/chat.html)!
+
+# Announcement
+
+On the 11th of July 2023, there will be a virtual HiPACE++ workshop from 4pm to 7pm CET.
+Feel free to sign up on the [indico webpage](https://indico.desy.de/event/40158/)
diff --git a/docs/source/acknowledge_hipace.rst b/docs/source/acknowledge_hipace.rst
@@ -0,0 +1,12 @@
+.. _acknowledge_hipace:
+
+Acknowledge HiPACE++
+====================
+
+Please acknowledge the role that HiPACE++ played in your research by citing the main HiPACE++ reference in your publication:
+
+- S. Diederichs, C. Benedetti, A. Huebl, R. Lehe, A. Myers, A. Sinn, J.-L. Vay, W. Zhang, M. Thévenet,
+  **HiPACE++: A portable, 3D quasi-static particle-in-cell code**.
+  *Computer Physics Communications*. ISSN 0010-4655,
+  Volume 278, 108421, 2022
+  `DOI:10.1016/j.cpc.2022.108421 <https://doi.org/10.1016/j.cpc.2022.108421>`__
diff --git a/docs/source/building/building.rst b/docs/source/building/building.rst
@@ -1,5 +1,6 @@
 .. _build-source:
 
+.. these lines below don't seem to work anymore, fixing it by hand
 .. raw:: html
 
    <style>
@@ -51,11 +52,19 @@ Optional dependencies include:
 
 Please choose **one** of the installation methods below to get started:
 
+HPC platforms
+-------------
+
+If you want to use HiPACE++ on a specific high-performance computing (HPC) systems, jump directly to our :ref:`HPC system-specific documentation <install-hpc>`.
+
 .. _install-spack:
 
 .. only:: html
 
    .. image:: spack.svg
+      :width: 32px
+      :align: left
+
 
 Using the Spack package manager
 -------------------------------
@@ -81,15 +90,19 @@ The dependencies can be installed via the package manager
 (in new terminals, re-activate the environment with ``spack env activate hipace-dev`` again)
 
 .. note::
-   On Ubuntu distributions, the InstallError ``"OpenMPI requires both C and Fortran compilers"`` can occur because the Fortran compilers are sometimes not set automatically in Spack.
+   On Linux distributions, the InstallError ``"OpenMPI requires both C and Fortran compilers"`` can occur because the Fortran compilers are sometimes not set automatically in Spack.
    To fix this, the Fortran compilers must be set manually using ``spack config edit compilers`` (more information can be found `here <https://spack.readthedocs.io/en/latest/getting_started.html#compiler-configuration>`__).
    For GCC, the flags ``f77 : null`` and ``fc : null`` must be set to ``f77 : gfortran`` and ``fc : gfortran``.
 
+   On macOS, a Fortran compiler like gfortran might be missing and must be installed by hand to fix this issue.
+
 .. _install-brew:
 
 .. only:: html
 
    .. image:: brew.svg
+      :width: 32px
+      :align: left
 
 Using the Brew package manager
 ------------------------------
@@ -225,15 +238,3 @@ The documentation is written at the `RST <https://sphinx-tutorial.readthedocs.io
    open build/html/index.html
 
 The last line would work on MacOS. On another platform, open the html file with your favorite browser.
-
-HPC platforms
--------------
-
-.. toctree::
-   :maxdepth: 1
-
-   platforms/booster_jsc.rst
-   platforms/maxwell_desy.rst
-   platforms/lumi_csc.rst
-   platforms/perlmutter_nersc.rst
-   platforms/spock_olcf.rst
diff --git a/docs/source/building/hpc.rst b/docs/source/building/hpc.rst
@@ -0,0 +1,44 @@
+.. _install-hpc:
+
+HPC platforms
+=============
+
+Specific installation instructions for a set of supercomputers can be found below.
+Follow the guide here instead of the generic installation routines for optimal stability and best performance.
+
+
+.. _install-hpc-profile:
+
+hipace.profile
+--------------
+
+Use a ``hipace.profile`` file to set up your software environment without colliding with other software.
+Ideally, store that file directly in your ``$HOME/`` and source it after connecting to the machine:
+
+.. code-block:: bash
+
+   source $HOME/hipace.profile
+
+We list example ``hipace.profile`` files below, which can be used to set up HiPACE++ on various HPC systems.
+
+
+.. _install-hpc-machines:
+
+HPC Machines
+------------
+
+This section documents quick-start guides for a selection of supercomputers that HiPACE++ users are active on.
+
+.. toctree::
+   :maxdepth: 1
+
+   platforms/booster_jsc
+   platforms/lumi_csc
+   platforms/maxwell_desy
+   platforms/perlmutter_nersc
+   platforms/spock_olcf
+
+.. tip::
+
+   Your HPC system is not in the list?
+   `Open an issue <https://github.com/Hi-PACE/hipace/issues>`__ and we can document it together!
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -4,27 +4,80 @@ HiPACE++
 .. figure:: https://user-images.githubusercontent.com/26292713/144571005-b0ba2624-48ad-4293-a8c1-a19d577c44df.png
  :alt: HiPACE++
 
-HiPACE++ is a 3D open-source portable (GPU-capable) quasistatic particle-in-cell code written in C++, available `here <https://github.com/Hi-PACE/hipace>`__.
+.. tip::
+   There will be a virtual HiPACE++ user workshop at the 11th of July 2023 from 4pm to 7pm CET.
+   Please register on the `indico webpage <https://indico.desy.de/event/40158/>`__  in case you are interested.
+
+HiPACE++ is a 3D open-source portable (GPU-capable) quasi-static particle-in-cell code written in C++, available on `GitHub <https://github.com/Hi-PACE/hipace>`__.
 It is a full re-writing of the DESY-LBNL legacy code `HiPACE <http://dx.doi.org/10.1088/0741-3335/56/8/084012>`__, the Highly efficient Plasma Accelerator Emulator.
 Its main features are:
 
 - Multiple beams and plasma species to simulation beam-driven wakefield acceleration
 - A laser envelope solver to simulate laser-driven wakefield acceleration
-- An advanced `explicit field solver <https://arxiv.org/abs/2012.00881>`__ for increased accuracy
+- An advanced `explicit field solver <https://doi.org/10.1103/PhysRevAccelBeams.25.104603>`__ for increased accuracy
 - Diagnostics compliant with the `openPMD standard <https://github.com/openPMD/openPMD-standard>`__
 - Arbitrary profiles for the beams and plasma profiles
 - Readers from files for the beam and laser profiles
 - Adaptive time step and sub-cycling
-- Additional physics for the plasma (field ionization, binary collisions, temperature effects)
+- Additional physics (field ionization, binary collisions, temperature effects, radiation reaction)
 
 HiPACE++ relies on the `AMReX <https://amrex-codes.github.io>`__ library, which provides for particle and field data structures.
 
+.. raw:: html
+
+   <style>
+   /* front page: hide chapter titles
+    * needed for consistent HTML-PDF-EPUB chapters
+    */
+   section#installation,
+   section#usage,
+   section#theory,
+   section#data-analysis,
+   section#community {
+       display:none;
+   }
+   </style>
+
 .. toctree::
+   :hidden:
+
+   acknowledge_hipace
+
+Installation
+------------
+.. toctree::
+   :caption: INSTALLATION
    :maxdepth: 1
+   :hidden:
 
    building/building.rst
+   building/hpc.rst
+
+Usage
+-----
+.. toctree::
+   :caption: USAGE
+   :maxdepth: 1
+   :hidden:
+
    run/parameters.rst
    run/get_started.rst
+
+Data Analysis
+-------------
+.. toctree::
+   :caption: DATA ANALYSIS
+   :maxdepth: 1
+   :hidden:
+
    visualize/visualization.rst
+
+Community
+---------
+.. toctree::
+   :caption: COMMUNITY
+   :maxdepth: 1
+   :hidden:
+
    run/chat.rst
    contributing/contributing.rst