Add get_started example (#488)

* documented example input file * update get_started input file and provide an example notebook * examples/get_started can have any filename * add a get_started * put style and guidelines into contributing * clean up contrib doc * remove redundant doc page * eol * typo Co-authored-by: Severin Diederichs <65728274+SeverinDiederichs@users.noreply.github.com>
Hi-PACE · May 7, 2021 · 752d650 · 752d650
1 parent 9f6a1e7
commit 752d650
Show file tree

Hide file tree

Showing 11 changed files with 191 additions and 72 deletions.
diff --git a/.github/workflows/source/wrongFileNameInExamples b/.github/workflows/source/wrongFileNameInExamples
@@ -13,6 +13,7 @@ files=()
 
 for pathtofile in $(find examples -type f)
 do
+    if [[ ${pathtofile:0:20} == examples/get_started ]]; then continue; fi
     file=$(basename $pathtofile)
     if [[ ${file:0:6 } != inputs       ]] &&
        [[ ${file:0:12} != PICMI_inputs ]] &&
@@ -29,8 +30,7 @@ if [ $ok -ne 0 ]
 then
     echo ""
     echo "Files in examples/ must start with one of:"
-    echo " - inputs       : for WarpX input files"
-    echo " - PICMI_inputs : for PICMI-compliant input scripts"
+    echo " - inputs       : for Hipace++ input files"
     echo " - analysis     : for scripts testing the accuracy of a test"
     echo " - README       : for readme files"
     echo ""

diff --git a/README.md b/README.md
@@ -14,4 +14,4 @@ Its main features are:
  - more coming soon...
 Hipace++ relies on the [AMReX](https://amrex-codes.github.io) library, which provides for particle and field data structures.
 
-Feel free to have a look at our documentation!
+Please have a look at our [documentation](https://hipace.readthedocs.io)!
diff --git a/docs/source/building/building.rst b/docs/source/building/building.rst
@@ -160,18 +160,6 @@ You can speed up the install further if you pre-install these dependencies, e.g.
 Set ``-DHiPACE_<dependency-name>_internal=OFF`` and add installation prefix of the dependency to the environment variable `CMAKE_PREFIX_PATH <https://cmake.org/cmake/help/latest/envvar/CMAKE_PREFIX_PATH.html>`.
 Please see the [short CMake tutorial that we linked above](#Developers) if this sounds new to you.
 
-Run a first simulation and look at the results
-----------------------------------------------
-
-After compiling Hipace++ (see above), from the Hipace++ root directory, execute
-
-.. code-block:: bash
-
-   cd examples/linear_wake/
-   ../../build/bin/hipace inputs # Run the simulation with fields and plasma and beam particles
-   ./analysis.py # Plot results with the [openPMD-viewer](https://github.com/openPMD/openPMD-viewer), and save in img.png
-
-
 Documentation
 -------------
 
@@ -185,16 +173,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.
-
-Style and conventions
----------------------
-
-- All new element (class, member of a class, struct, function) declared in a .H file must have a Doxygen-readable documentation
-- Indent four spaces
-- No tabs allowed
-- No end-of-line whitespaces allowed
-- Classes use CamelCase
-- Objects use snake_case
-- Lines should not have >100 characters
-- The declaration and definition of a function should have a space between the function name and the first bracket (``my_function (...)``), function calls should not (``my_function(...)``).
-  This is a convention introduce in AMReX so ``git grep "my_function ("`` returns only the declaration and definition, not the many function calls.
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
diff --git a/docs/source/contributing/contributing.rst b/docs/source/contributing/contributing.rst
@@ -0,0 +1,38 @@
+Contribute to Hipace++
+======================
+
+We welcome new contributors!
+
+To contribute to Hipace++, the steps are as follows:
+ - Fork the Hipace++ repo, so you have your own fork
+ - Pull the latest development from baseline, and create your ``<new branch>`` from it
+ - Commit your changes as usual, and push them on your fork
+ - Open a PR between ``<new branch>`` on your for and ``development`` on baseline
+
+Documentation
+-------------
+
+Hipace++ has a full (functions and classes and their members, albeit sometimes basic) Doxygen-readable documentation. You can compile it with
+
+.. code-block:: bash
+
+   cd docs
+   doxygen
+   open doxyhtml/index.html
+
+The last line would work on MacOS. On another platform, open the html file with your favorite browser.
+
+The Hipace++ Doxygen documentation can be found `here <../_static/doxyhtml/index.html>`__.
+
+Style and conventions
+---------------------
+
+- All new element (class, member of a class, struct, function) declared in a .H file must have a Doxygen-readable documentation
+- Indent four spaces
+- No tabs allowed
+- No end-of-line whitespaces allowed
+- Classes use CamelCase
+- Objects use snake_case
+- Lines should not have >100 characters
+- The declaration and definition of a function should have a space between the function name and the first bracket (``my_function (...)``), function calls should not (``my_function(...)``).
+  This is a convention introduce in AMReX so ``git grep "my_function ("`` returns only the declaration and definition, not the many function calls.
diff --git a/docs/source/documentation/documentation.rst b/docs/source/documentation/documentation.rst
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,7 +1,7 @@
 Hipace++ documentation
 ======================
 
-Hipace++ is an open-source portable (GPU-capable) quasistatic particle-in-cell code written in C++.
+Hipace++ is an open-source portable (GPU-capable) quasistatic particle-in-cell code written in C++, available `here <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:
 
@@ -10,7 +10,7 @@ Its main features are:
 - Two field solver methods, the original HiPACE predictor-corrector loop and an `explicit solver <https://arxiv.org/abs/2012.00881>`__
 - Diagnostics compliant with the `openPMD standard <https://github.com/openPMD/openPMD-standard>`__
 - Read an arbitrary particle beam from file
-- Adaptive time step
+- Adaptive time step and sub-cycling
 - more coming soon...
 
 Hipace++ relies on the `AMReX <https://amrex-codes.github.io>`__ library, which provides for particle and field data structures.
@@ -21,7 +21,6 @@ Hipace++ relies on the `AMReX <https://amrex-codes.github.io>`__ library, which
    building/building.rst
    run/run.rst
    run/parameters.rst
+   run/get_started.rst
    visualize/visualization.rst
-   documentation/documentation.rst
-   style.rst
-   contributing.rst
+   contributing/contributing.rst
diff --git a/docs/source/run/get_started.rst b/docs/source/run/get_started.rst
@@ -0,0 +1,34 @@
+Get started
+===========
+
+A full Hipace++ input file can be found below, with a detailed description of the main parameters.
+All the input parameters available in the simulation are available in the :doc:`parameters` section.
+
+.. literalinclude:: ../../../examples/get_started/inputs_normalized
+
+This input file is ``inputs_normalized`` in ``examples/get_started/``, which is the recommended place to start running a first simulation.
+
+See the :doc:`../building/building` section to install the code locally or on your favorite platform.
+After compiling Hipace++ from the Hipace++ root directory, execute
+
+.. code-block:: bash
+
+   cd examples/get_started/
+   ../../build/bin/hipace inputs # run the simulation
+
+Then you can use the `openPMD-viewer <https://github.com/openPMD/openPMD-viewer>`__ to read the simulation output data. Directory `examples/get_started/` also contains this :download:`example notebook <../../../examples/get_started/notebook.ipynb>`. Reading the simulation output only takes these few Python commands:
+
+.. code-block:: python
+
+   # import statements
+   import numpy as np
+   import matplotlib.pyplot as plt
+   from openpmd_viewer import OpenPMDTimeSeries
+   # Read the simulation data
+   ts = OpenPMDTimeSeries('./diags/hdf5/')
+   # Get beam and field data at iteration 20
+   iteration = 20
+   x, z = ts.get_particle(species='beam', iteration=iteration, var_list=['x', 'z'])
+   F, m = ts.get_field(field='Ez', iteration=iteration)
+
+Other examples can be found in ``examples/``
diff --git a/docs/source/style.rst b/docs/source/style.rst
diff --git a/examples/get_started/inputs_normalized b/examples/get_started/inputs_normalized
@@ -0,0 +1,41 @@
+### AMReX parameters
+################################
+amr.n_cell = 64 64 100                  # number of grid points in x, y, z
+amr.blocking_factor = 1                 # blocking factor. n_cell must be divisible by it
+amr.max_level = 0                       # level of mesh refinement. Currently, only 0 available
+
+#### General simulation settings
+################################
+max_step = 20                           # max time step. 0 computes the fields of the initial beam
+hipace.output_period = 1                # output period. Last step is always written
+hipace.normalized_units = 1             # unit system: SI units: 0, normalized units: 1
+hipace.dt = 4.4                         # Time step
+
+### Simulation domain
+################################
+geometry.coord_sys   =  0               # 0: Cartesian
+geometry.is_periodic =  1     1     0   # Is periodic?
+geometry.prob_lo     = -8.   -8.   -6   # physical domain: dimension must be provided
+geometry.prob_hi     =  8.    8.    6   # in the respective unit system
+
+### Beam(s)
+################################
+beams.names = beam                      # name(s) of the beam(s)
+beam.injection_type = fixed_weight      # injection type: fixed_weight, fixed_ppc, or from_file
+beam.num_particles = 100000             # number of constant weight particles
+beam.position_mean = 0. 0. 0            # mean position in x,y,z in the respective unit system
+beam.position_std = 0.3 0.3 1.41        # rms size in x,y,z in the respecitve unit system
+beam.density = 3.                       # peak density
+beam.u_mean = 0. 0. 2000                # normalized mean momentum in x,y,z
+beam.u_std = 0. 0. 0.                   # normalized rms of the momentum in x,y,z
+
+### Plasma
+################################
+plasmas.names = plasma                  # name(s) of the plasma(s)
+plasma.element = electron               # type of plasma: electron, proton, or an element e.g. He
+plasma.density = 1.                     # peak density in the respective unit systems
+plasma.ppc = 1 1                        # particles per cell in x,y
+
+### Diagnostics
+################################
+diagnostic.diag_type = xz               # 2D xz slice output. Options: xyz, xz, yz
diff --git a/examples/get_started/notebook.ipynb b/examples/get_started/notebook.ipynb
@@ -0,0 +1,71 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "%matplotlib notebook\n",
+    "import matplotlib.pyplot as plt\n",
+    "from openpmd_viewer import OpenPMDTimeSeries"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Replace the string below, to point to your data\n",
+    "ts = OpenPMDTimeSeries('./diags/hdf5/')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Interactive GUI\n",
+    "ts.slider()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "iteration = 20\n",
+    "x, z = ts.get_particle(species='beam', iteration=iteration, var_list=['x', 'z'])\n",
+    "F, m = ts.get_field(field='Ez', iteration=iteration)\n",
+    "plt.figure()\n",
+    "plt.imshow(F, extent=m.imshow_extent, origin='lower')\n",
+    "plt.scatter(x, z, color='k', s=.02)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.7.9"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}