From fd87fb801f7e8a996127220b437831a6a86a7138 Mon Sep 17 00:00:00 2001 From: Severin Diederichs <65728274+SeverinDiederichs@users.noreply.github.com> Date: Fri, 7 May 2021 13:39:52 +0200 Subject: [PATCH 1/9] documented example input file --- examples/get_started/inputs_normalized | 40 ++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 examples/get_started/inputs_normalized diff --git a/examples/get_started/inputs_normalized b/examples/get_started/inputs_normalized new file mode 100644 index 0000000000..461a3f4d93 --- /dev/null +++ b/examples/get_started/inputs_normalized @@ -0,0 +1,40 @@ +### 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 = 0 # 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 + +### 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 = xyz # full 3D output. Options: xyz, xz, yz From e5781b4a440bd18f771553aeba73afa785ab68bd Mon Sep 17 00:00:00 2001 From: Maxence Thevenet Date: Fri, 7 May 2021 14:05:02 +0200 Subject: [PATCH 2/9] update get_started input file and provide an example notebook --- examples/get_started/inputs_normalized | 7 +-- examples/get_started/notebook.ipynb | 71 ++++++++++++++++++++++++++ 2 files changed, 75 insertions(+), 3 deletions(-) create mode 100644 examples/get_started/notebook.ipynb diff --git a/examples/get_started/inputs_normalized b/examples/get_started/inputs_normalized index 461a3f4d93..c919ff2825 100644 --- a/examples/get_started/inputs_normalized +++ b/examples/get_started/inputs_normalized @@ -6,9 +6,10 @@ amr.max_level = 0 # level of mesh refinement. Currently, o #### General simulation settings ################################ -max_step = 0 # max time step. 0 computes the fields of the initial beam +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.normalized_units = 1 # unit system: SI units: 0, normalized units: 1 +hipace.dt = 4.4 # Time step ### Simulation domain ################################ @@ -37,4 +38,4 @@ plasma.ppc = 1 1 # particles per cell in x,y ### Diagnostics ################################ -diagnostic.diag_type = xyz # full 3D output. Options: xyz, xz, yz +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 new file mode 100644 index 0000000000..86de661a5b --- /dev/null +++ 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 +} From 1e1c7736554d6d0c222ec6b6d331c862a10e78d0 Mon Sep 17 00:00:00 2001 From: Maxence Thevenet Date: Fri, 7 May 2021 16:38:27 +0200 Subject: [PATCH 3/9] examples/get_started can have any filename --- .github/workflows/source/wrongFileNameInExamples | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/source/wrongFileNameInExamples b/.github/workflows/source/wrongFileNameInExamples index 793714468c..928d35be37 100755 --- 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 "" From fa8fa1ab33cec52030893c05a5d7e0fefb723250 Mon Sep 17 00:00:00 2001 From: Maxence Thevenet Date: Fri, 7 May 2021 17:23:39 +0200 Subject: [PATCH 4/9] add a get_started --- README.md | 2 +- docs/source/building/building.rst | 25 --------------------- docs/source/contributing.rst | 15 ++++++++++++- docs/source/index.rst | 5 +++-- docs/source/run/get_started.rst | 37 +++++++++++++++++++++++++++++++ 5 files changed, 55 insertions(+), 29 deletions(-) create mode 100644 docs/source/run/get_started.rst diff --git a/README.md b/README.md index cc7c5061a2..34c1e715fc 100644 --- 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! \ No newline at end of file +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 index 5e28750e7a..af9455857a 100644 --- 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__internal=OFF`` and add installation prefix of the dependency to the environment variable `CMAKE_PREFIX_PATH `. 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 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 index 61ed448479..31169d6870 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -1,10 +1,23 @@ Contribute to Hipace++ ====================== -New contributors are welcome! +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 ```` from it - Commit your changes as usual, and push them on your fork - Open a PR between ```` on your for and ``development`` on baseline + + 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/index.rst b/docs/source/index.rst index f03075f8df..8c77412dcd 100644 --- 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 `__. It is a full re-writing of the DESY-LBNL legacy code `HiPACE `__, 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 `__ - Diagnostics compliant with the `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 `__ library, which provides for particle and field data structures. @@ -21,6 +21,7 @@ Hipace++ relies on the `AMReX `__ library, which building/building.rst run/run.rst run/parameters.rst + run/get_started.rst visualize/visualization.rst documentation/documentation.rst style.rst diff --git a/docs/source/run/get_started.rst b/docs/source/run/get_started.rst new file mode 100644 index 0000000000..bb5cee52f5 --- /dev/null +++ b/docs/source/run/get_started.rst @@ -0,0 +1,37 @@ +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 + + +# :literal: + +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 `__ 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/`` From fe11aa22b1882a6ac2aa48bc8039da7138afb949 Mon Sep 17 00:00:00 2001 From: Maxence Thevenet Date: Fri, 7 May 2021 17:33:06 +0200 Subject: [PATCH 5/9] put style and guidelines into contributing --- docs/source/contributing.rst | 2 +- docs/source/index.rst | 1 - docs/source/style.rst | 14 -------------- 3 files changed, 1 insertion(+), 16 deletions(-) delete mode 100644 docs/source/style.rst diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst index 31169d6870..1fd4a3ab12 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing.rst @@ -9,7 +9,7 @@ To contribute to Hipace++, the steps are as follows: - Commit your changes as usual, and push them on your fork - Open a PR between ```` on your for and ``development`` on baseline - Style and conventions +Style and conventions --------------------- - All new element (class, member of a class, struct, function) declared in a .H file must have a Doxygen-readable documentation diff --git a/docs/source/index.rst b/docs/source/index.rst index 8c77412dcd..74f138abbd 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -24,5 +24,4 @@ Hipace++ relies on the `AMReX `__ library, which run/get_started.rst visualize/visualization.rst documentation/documentation.rst - style.rst contributing.rst diff --git a/docs/source/style.rst b/docs/source/style.rst deleted file mode 100644 index 8484218eb2..0000000000 --- a/docs/source/style.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _style-source: - -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. From 5e327f2a1f54b89b15a1dbaa62583f9ef2b878fe Mon Sep 17 00:00:00 2001 From: Maxence Thevenet Date: Fri, 7 May 2021 17:39:49 +0200 Subject: [PATCH 6/9] clean up contrib doc --- docs/source/{ => contributing}/contributing.rst | 15 +++++++++++++++ .../documentation/documentation.rst | 1 + docs/source/index.rst | 3 +-- 3 files changed, 17 insertions(+), 2 deletions(-) rename docs/source/{ => contributing}/contributing.rst (71%) rename docs/source/{ => contributing}/documentation/documentation.rst (77%) diff --git a/docs/source/contributing.rst b/docs/source/contributing/contributing.rst similarity index 71% rename from docs/source/contributing.rst rename to docs/source/contributing/contributing.rst index 1fd4a3ab12..ce9fdbc2e1 100644 --- a/docs/source/contributing.rst +++ b/docs/source/contributing/contributing.rst @@ -9,6 +9,21 @@ To contribute to Hipace++, the steps are as follows: - Commit your changes as usual, and push them on your fork - Open a PR between ```` 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 --------------------- diff --git a/docs/source/documentation/documentation.rst b/docs/source/contributing/documentation/documentation.rst similarity index 77% rename from docs/source/documentation/documentation.rst rename to docs/source/contributing/documentation/documentation.rst index ef3f8d2dac..11f542fe92 100644 --- a/docs/source/documentation/documentation.rst +++ b/docs/source/contributing/documentation/documentation.rst @@ -13,3 +13,4 @@ Hipace++ has a full (all functions and classes and their members, albeit sometim The last line would work on MacOS. On another platform, open the html file with your favorite browser. +Our Doxygen C++ API documentation in classic formatting `is located here <../_static/doxyhtml/index.html>`_. diff --git a/docs/source/index.rst b/docs/source/index.rst index 74f138abbd..db6a96444e 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -23,5 +23,4 @@ Hipace++ relies on the `AMReX `__ library, which run/parameters.rst run/get_started.rst visualize/visualization.rst - documentation/documentation.rst - contributing.rst + contributing/contributing.rst From 7d3da2470569316300b002184f5847401a2a296c Mon Sep 17 00:00:00 2001 From: Maxence Thevenet Date: Fri, 7 May 2021 17:40:27 +0200 Subject: [PATCH 7/9] remove redundant doc page --- .../contributing/documentation/documentation.rst | 16 ---------------- 1 file changed, 16 deletions(-) delete mode 100644 docs/source/contributing/documentation/documentation.rst diff --git a/docs/source/contributing/documentation/documentation.rst b/docs/source/contributing/documentation/documentation.rst deleted file mode 100644 index 11f542fe92..0000000000 --- a/docs/source/contributing/documentation/documentation.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _documentation-source: - -Documentation -============= - -Hipace++ has a full (all 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. - -Our Doxygen C++ API documentation in classic formatting `is located here <../_static/doxyhtml/index.html>`_. From 3441ca867d196f37e8520d6540adb10d654cf505 Mon Sep 17 00:00:00 2001 From: Maxence Thevenet Date: Fri, 7 May 2021 17:42:45 +0200 Subject: [PATCH 8/9] eol --- docs/source/contributing/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/contributing/contributing.rst b/docs/source/contributing/contributing.rst index ce9fdbc2e1..3547ad09d6 100644 --- a/docs/source/contributing/contributing.rst +++ b/docs/source/contributing/contributing.rst @@ -23,7 +23,7 @@ Hipace++ has a full (functions and classes and their members, albeit sometimes b 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 --------------------- From c948aac8c5ea4d18dc924247887f637de3a3313a Mon Sep 17 00:00:00 2001 From: Maxence Thevenet Date: Fri, 7 May 2021 17:50:29 +0200 Subject: [PATCH 9/9] typo --- docs/source/run/get_started.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/source/run/get_started.rst b/docs/source/run/get_started.rst index bb5cee52f5..bd964dd7f9 100644 --- a/docs/source/run/get_started.rst +++ b/docs/source/run/get_started.rst @@ -6,9 +6,6 @@ All the input parameters available in the simulation are available in the :doc:` .. literalinclude:: ../../../examples/get_started/inputs_normalized - -# :literal: - 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.