Merge branch 'diag_new_particles' into 'develop'

Diag new particles

See merge request smilei/smilei!132

.gitlab-ci.yml

@@ -16,6 +16,7 @@ install:
   only:
     - develop
     - BTIS3_for_develop
+    - diag_new_particles
 
   script:
     # Force workdir cleaning in case of retried
@@ -35,6 +36,7 @@ compile_default:
   only:
     - develop
     - BTIS3_for_develop
+    - diag_new_particles
 
   script:
     # Move in test dir
@@ -47,6 +49,7 @@ runQuick:
   only:
     - develop
     - BTIS3_for_develop
+    - diag_new_particles
 
   script:
     # Move in test dir
@@ -59,6 +62,7 @@ run1D:
   only:
     - develop
     - BTIS3_for_develop
+    - diag_new_particles
 
   script:
     # Move in test dir
@@ -72,6 +76,7 @@ run2D:
   only:
     - develop
     - BTIS3_for_develop
+    - diag_new_particles
 
   script:
     # Move in test dir
@@ -87,6 +92,7 @@ run3D:
   only:
     - develop
     - BTIS3_for_develop
+    - diag_new_particles
 
   script:
     # Move in test dir
@@ -103,6 +109,7 @@ runAM:
   only:
     - develop
     - BTIS3_for_develop
+    - diag_new_particles
 
   script:
     # Move in test dir
@@ -115,6 +122,7 @@ runCollisions:
   only:
     - develop
     - BTIS3_for_develop
+    - diag_new_particles
 
   script:
     # Move in test dir
@@ -127,6 +135,7 @@ compile_picsar:
   only:
     - develop
     - BTIS3_for_develop
+    - diag_new_particles
 
   script:
     - cd /sps3/gitlab-runner/$CI_PIPELINE_ID/smilei
@@ -138,6 +147,7 @@ run_picsar:
   only:
     - develop
     - BTIS3_for_develop
+    - diag_new_particles
 
   script:
     - cd /sps3/gitlab-runner/$CI_PIPELINE_ID/smilei/validation
@@ -148,6 +158,7 @@ compile_debug:
   only:
     - develop
     - BTIS3_for_develop
+    - diag_new_particles
 
   script:
     - cd /sps3/gitlab-runner/$CI_PIPELINE_ID/smilei
@@ -159,6 +170,7 @@ compile_no_mpi_threadmultiple:
   only:
     - develop
     - BTIS3_for_develop
+    - diag_new_particles
 
   script:
     - cd /sps3/gitlab-runner/$CI_PIPELINE_ID/smilei
@@ -170,6 +182,7 @@ compile_no_openmp:
   only:
     - develop
     - BTIS3_for_develop
+    - diag_new_particles
 
   script:
     - cd /sps3/gitlab-runner/$CI_PIPELINE_ID/smilei
@@ -181,6 +194,7 @@ compile_omptasks:
   only:
     - develop
     - BTIS3_for_develop
+    - diag_new_particles
 
   script:
     - cd /sps3/gitlab-runner/$CI_PIPELINE_ID/smilei
@@ -192,6 +206,7 @@ run_omptasks:
   only:
     - develop
     - BTIS3_for_develop
+    - diag_new_particles
 
   script:
     - cd /sps3/gitlab-runner/$CI_PIPELINE_ID/smilei/validation

benchmarks/tst1d_05_tunnel_ionisation.py

@@ -116,4 +116,10 @@ def Bz(t):
 	species = "electron",
 	every = [1,1000,30],
 	attributes = ["x","px","py","pz","w","Wy"]
-)
+)
+
+DiagNewParticles(
+	species = "electron",
+	every = 100,
+	attributes = ["x","py","w","q"],
+)

doc/Sphinx/Overview/releases.rst

@@ -23,30 +23,34 @@ You can find older, `unsupported versions here <https://github.com/SmileiPIC/Smi
 Changes made in the repository (not released)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-* ``LaserEnvelope`` model:
+* **LaserEnvelope model**:
 
   * Now compatible with ``PML`` boundaries
   * In ``AMcylindrical`` geometry, the number of modes can be greater than 1 (only affects electromagnetic
     fields and the densities, not envelope or susceptibility)
+  * multi-level tunnel ionization creates multiple electrons, improving the sampling
 
-* Much faster ``DiagFields`` (speedup ~ x3)
-* ``DiagFields`` and ``DiagProbe``: new parameter ``datatype``
-* ``DiagPerformances``: new parameter ``cumulative``
-* ``Collisions``: new parameter ``time_frozen``
-* Laser Envelope: multi-level tunnel ionization creates multiple electrons, improving the sampling
-* ``Species`` block: in ``AMcylindrical`` geometry now it is possible to define initial drift velocity profiles either in the longitudinal, radial and azimuthal directions with ``mean_velocity_AM`` or in the cartesian directions as usual with ``mean_velocity``.
-* Happi:
+* **Diagnostics**
+
+  * Much faster ``DiagFields`` (speedup ~ x3)
+  * ``DiagFields`` and ``DiagProbe``: new parameter ``datatype``
+  * ``DiagPerformances``: new parameter ``cumulative``
+
+* **Collisions**: new parameter ``time_frozen``
+* **Species**: in ``AMcylindrical`` geometry, the initial drift velocity profiles may be defined
+  either in the ``x,r,θ``  directions with ``mean_velocity_AM`` or in the ``x,y,z`` directions with ``mean_velocity``.
+
+* **Happi**:
 
   * operations in ``Fields``, ``Probe``, and ``ParticleBinning`` may now accept physical constants, units,
     or basic functions such as ``exp()`` or ``sin()``
   * ``Probe`` has a new method ``changeField``
   * ``Open`` has a new argument ``pint`` to disable the *Pint* package
 
-* For developers: new table management for Monte-Carlo physical processes (transparent to users)
-* Friedman filter: now available in geometries ``1Dcartesian`` and ``AMcylindrical`` (previously available only in ``2Dcartesian``)
-* ``Lehe`` solver for Maxwell equations now available in ``AMcylindrical`` geometry
+* **Friedman filter**: now available in geometries ``1Dcartesian`` and ``AMcylindrical`` (previously available only in ``2Dcartesian``)
+* **Lehe solver** for Maxwell equations now available in ``AMcylindrical`` geometry
 
-* Bugfixes:
+* **Bugfixes**:
 
   * Poisson Solver correction was not properly accounted for with SDMD.
   * Bug correction using Monte-Carlo radiation and multiphoton Breit-Wheeler processes with checkpoints
@@ -58,11 +62,14 @@ Changes made in the repository (not released)
   * ``Field.getAxis`` was not accounting for the ``timestep``
   * Bug correction in 1D relativistic Poisson solver
 
-* Experimental
+* **Experimental**
 
   * :doc:`/Understand/task_parallelization` of macro-particle operations with OpenMP
   * Rudimentary visualization for macro-particle operation scheduling, activated through a compilation flag
   * B-TIS3 interpolation scheme to reduce the effects of numerical Cherenkov radiation is implemented up to interpolation order 2
+  * New diagnostic: ``DiagNewParticles`` records particle information when they are created by ionization or other mechanisms
+
+* **For developers**: new table management for Monte-Carlo physical processes (transparent to users)
 
 ----
 

doc/Sphinx/Use/namelist.rst

@@ -3340,6 +3340,37 @@ for instance::
 
 ----
 
+.. rst-class:: experimental
+
+.. _DiagNewParticles:
+
+*NewParticles* diagnostics
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A *new-particle diagnostic* records the macro-particle information only at the time when
+they are generated by :doc:`../Understand/ionization` or other :doc:`../Understand/physics_modules`.
+
+You can add a new-particle diagnostic by including a block ``DiagNewParticles()`` in the namelist,
+for instance::
+
+  DiagNewParticles(
+      species = "electron",
+      every = 10,
+  #    attributes = ["x", "px", "py", "Ex", "Ey", "Bz"]
+  )
+
+**All the arguments are identical to those of TrackParticles.**
+However, there are particular considerations:
+
+* Although the creation of particles is recorded at every timestep, the argument ``every``
+  only indicates how often the data is written to the file. It is recommended to avoid 
+  small values of ``every`` for better performance.
+* In the case of :doc:`../Understand/ionization`, if the chosen ``species`` is that of the ionized electrons,
+  then the attribute "``q``" is not the charge of the electron, but the charge of the
+  ion, *before ionization occurred*.
+
+----
+
 .. _DiagPerformances:
 
 *Performances* diagnostics

doc/Sphinx/Use/post-processing.rst

@@ -400,6 +400,28 @@ Open a TrackParticles diagnostic
   | For example, ``select="any((t>30)*(t<60), px>1) + all(t>0, (x>1)*(x<2))"``
 
 
+----
+
+.. rst-class:: experimental
+
+Open a NewParticles diagnostic
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. py:method:: NewParticles(species=None, select="", axes=[], units=[""], **kwargs)
+
+  * ``units``: same as before.
+  * ``species``: same as for ``TrackParticles``
+  * ``axes``: same as for ``TrackParticles``, with the addition of another axis ``t``
+    that represents the time when the particle was born.
+  * ``select``: Instructions for selecting particles among those available.
+    It must be a condition on particles properties ``axes``, for instance ``px>0``.
+    It is possible to make logical operations: ``+`` is *OR*; ``*`` is *AND*; ``~`` is *NOT*.
+
+    | **Example:** ``select="(x>1)*(x<2)"``
+    
+    It is also possible to select directly a list of IDs.
+
+    | **Example:** ``select=[ID1, ID2, ...]``
 
 ----
 

doc/Sphinx/smilei_theme/static/smilei_theme.css_t

@@ -709,8 +709,8 @@ div.header > * {
 	font-size:1.3em;
 }
 
-div.experimental > h1:first-of-type::after,
-div.experimental > h2:first-of-type::after,
+.experimental > h1:first-of-type::after,
+.experimental > h2:first-of-type::after,
 dl.experimental > dt:first-of-type::after,
 ul.experimental p:first-of-type::after
 {