Read species distribution from OPMD - part 3 (#883)

* Added <species>.profile=external_file and .profile_file

* Added description of input parameters to Docs

* Changed from profile to injection option for external file

* Fix typo in amrex abort message (due to copy paste)

* Added the OpenPMD use amrex abort message

* Minor fix - not sure how to remove EOL issue

* Tried to add AddExternalFileBeam functon to PhysicalParticleContainer

* Trued to fix EOL white space issue

* Added read/print species name from OPMD file

* Fixed OpenPMD charge and mass read

* Added number of particles in species

* Added nparts and converted charge/mass units to SI

* Fix to nr of particles

* Added q_tot parameter to determine part weight

* Added macroparticle's weight

* Fixed std::int typo - use only int

* Added read x,y and z + ifdef 3D

* Added velocity of particles and stored in container

* Converted velocities to SI

* No need to specfy momentum distribution if external file is used

* Update Source/Initialization/PlasmaInjector.cpp

Co-Authored-By: Axel Huebl <axel.huebl@plasma.ninja>

* Update Source/Particles/PhysicalParticleContainer.cpp

Co-Authored-By: Axel Huebl <axel.huebl@plasma.ninja>

* Update Source/Particles/PhysicalParticleContainer.cpp

Co-Authored-By: Axel Huebl <axel.huebl@plasma.ninja>

* Update Source/Particles/PhysicalParticleContainer.H

Co-Authored-By: Axel Huebl <axel.huebl@plasma.ninja>

* Update Source/Particles/PhysicalParticleContainer.cpp

Co-Authored-By: Axel Huebl <axel.huebl@plasma.ninja>

* No need to include openPMD header yet

* Fixed const in AddExternalFileBeam

* Fix compatibility with read_opmd and read_opmd_2

* Corrected position and charge units/sign

* Added Doc note and abort message for RZ

* Fix typo and EOL

* Minor fixes

* Fixed details. Added fix to EOL - testing

* Changed to physical_charge and explained it in Docs

* Fix header extra openPMD include files

* Removed additional debugging comments

* Try doxygen again

* Fix plasmainjector physical_q_tot

* Change apart to auto (not long as in gaussian beam injection style)

Co-Authored-By: Axel Huebl <axel.huebl@plasma.ninja>

* Correct for new type of npart

Co-Authored-By: Axel Huebl <axel.huebl@plasma.ninja>

* Removed Geant4 renormalization

* Read openPMD file and checked its units

* Trying to correct momentum information in plotfiles

* Compilation error - > SegFault 11

* Added unitSI() to each position/momentum direction. Compilation SegFault

* Re-structured code to use only once series.flush()

* Commented out amrex::Print() s

* Path to fix issue

* Update after review

* Chanegd <physical_q_tot> to <q_tot> and made it optional

* Fixed documentation typo and re-organized it

* Added const to npart as per reviewer recommendation

* Fixed issue with velocity - which became momentum

* Fixed 2D and 3D options + documentation

* Implemented fixes from past reviewsand fixed duplicate entry in Docs

* Fix auto in iterator in for loop

* Added fixes according to reviewer

* Revert "Added fixes according to reviewer"

This reverts commit 0a485d83c28014c8b6f53a30f26719f23f89bad5.

* Fixed IO block and reordered logic with Axel

* Fix spaces

Co-authored-by: Axel Huebl <axel.huebl@plasma.ninja>

1 files changed, 8 insertions, 4 deletions

diff --git a/Docs/source/running_cpp/parameters.rst b/Docs/source/running_cpp/parameters.rst
index 904741ebf..287f534b0 100644
--- a/Docs/source/running_cpp/parameters.rst
+++ b/Docs/source/running_cpp/parameters.rst
@@ -296,7 +296,7 @@ Particle initialization
 
     * ``gaussian_beam``: Inject particle beam with gaussian distribution in
       space in all directions. This requires additional parameters:
-      ``<species_name>.q_tot`` (beam charge),
+      ``<species_name>.q_tot`` (beam charge) optional (default is ``q_tot=0``),
       ``<species_name>.npart`` (number of particles in the beam),
       ``<species_name>.x/y/z_m`` (average position in `x/y/z`),
       ``<species_name>.x/y/z_rms`` (standard deviation in `x/y/z`),
@@ -305,9 +305,13 @@ Particle initialization
       and optional argument ``<species_name>.do_symmetrize`` (whether to
       symmetrize the beam in the x and y directions).
 
-    * ``external_file``: inject macroparticles with properties (charge, mass, position, and momentum) according to data in external file.
-      It requires the additional arguments ``<species_name>.injection_file`` and ``<species_name>.q_tot``, which are the string corresponding to the openPMD file name and the beam charge.
-      When using this style, it is not necessary to add other ``<species_name>.(...)`` paramters, because they will be read directly from the file.
+    * ``external_file``: Inject macroparticles with properties (mass, charge, position, and momentum - :math:`\gamma \beta m c`) read from an external openPMD file.
+      It requires the additional arguments:
+      ``<species_name>.injection_file`` (`string`) openPMD file name and
+      ``<species_name>.q_tot`` (`double`) optional (default is ``q_tot=0`` and no re-scaling is done, ``weight=q_p``) when specified it is used to re-scale the weight of externally loaded ``N`` physical particles, each of charge ``q_p``, to inject macroparticles of ``weight=<species_name>.q_tot/q_p/N``.
+      The external file should include the species ``openPMD::Record`` s labeled ``mass`` and ``charge`` (`double` scalars) and also the ``position`` and ``momentum`` (`double` arrays), with dimensionality and units set via ``openPMD::setUnitDimension`` and ``setUnitSI``.
+      The ``external_file`` option is currently implemented for 2D and 3D geometries, with record components ``x``, ``z`` and ``y`` for 3D.
+      For more information on the `openPMD format <https://github.com/openPMD>`__ and how to build WarpX with it, please visit :doc:`../building/openpmd`.
 
 * ``<species_name>.num_particles_per_cell_each_dim`` (`3 integers in 3D and RZ, 2 integers in 2D`)
     With the NUniformPerCell injection style, this specifies the number of particles along each axis