Skip to content

Commit

Permalink
deploy: bf2497a
Browse files Browse the repository at this point in the history
  • Loading branch information
Z10Frank committed Dec 5, 2023
0 parents commit b748438
Show file tree
Hide file tree
Showing 47 changed files with 21,269 additions and 0 deletions.
4 changes: 4 additions & 0 deletions .buildinfo
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Sphinx build info version 1
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
config: b9d481773819ad7fd5af4e3e4057f9b0
tags: 645f666f9bcd5a90fca523b33c5a78b7
Empty file added .nojekyll
Empty file.
Binary file added _images/Laser_definition.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _images/Mesh_and_Reference.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _images/Schema_Simulation_0.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _images/Schema_Simulation_1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _images/Schema_Simulation_2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _images/Schema_Simulation_3.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
730 changes: 730 additions & 0 deletions _sources/exercises.rst.txt

Large diffs are not rendered by default.

26 changes: 26 additions & 0 deletions _sources/index.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
.. TP-M2-GI_doc documentation master file, created by
sphinx-quickstart on Mon Apr 11 11:21:56 2022.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
A tutorial on Particle in Cell simulation of Laser Wakefield Acceleration
------------------------------------------------------------------------------------


.. toctree::
:maxdepth: 2
:caption: Main contributors: F. Massimo, S. Marini. We are grateful to all the students who attend this TP each year, contributing to the improvement of its material through their invaluable feedback.

introduction
exercises
useful_tools



.. Indices and tables
.. ==================
.. * :ref:`genindex`
.. * :ref:`modindex`
.. * :ref:`search`
89 changes: 89 additions & 0 deletions _sources/introduction.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,89 @@
Introduction
-------------------


In this practical work, you will familiarize yourself with a Particle in Cell (PIC) code ([BirdsallLangdon]_, [Lapenta]_),
learn how to set up and run a basic PIC simulation to study laser plasma acceleration of electrons, and how to analyze the results.
The PIC code you will use, `Smilei <https://smileipic.github.io/Smilei/index.html>`_ ([Derouillat2018]_), is not a simplified version
but a full PIC code that you can use for your future studies.




Summary of this practical
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In the case study of this practical work, an intense laser pulse is injected into the plasma,
exciting a relativistic plasma wave used to accelerate an externally injected relativistic electron bunch.
This plasma acceleration scheme is known as laser wakefield acceleration, or LWFA ([Esarey2009]_, [Malka2012]_).

The practical will consist in four parts:

- :ref:`Exploring the Input Namelist <exploringthenamelist>` (**Exercises 1-2**): we will explore the Python ``InputNamelist.py`` file to understand the basic set-up of the problem (simulation window size, resolution, ...). In this part the simulation window is empty.
- :ref:`Laser pulse in vacuum <laserpulseinvacuum>` (**Exercises 4-6**): we will add a laser laser pulse propagating in vacuum and check that its diffraction follows the one predicted for a Gaussian beam.
- :ref:`Laser wakefield excitation <plasmawave>` (**Exercises 7-11**): we will add a pre-ionized plasma and visualize how the laser pulse excites plasma waves in its wake, also checking the results against the analytical theory in the linear regime.
- :ref:`Laser wakefield acceleration of an electron bunch <laserplasmainjection>` (**Exercises 12-20**): we will add a relativistic electron bunch, injecting it into the plasma waves and studying its acceleration.

We will arrive progressively to the full simulation set-up,
familiarizing with the postprocessing using the Python postprocessing library
`happi <https://smileipic.github.io/Smilei/Use/post-processing.html>`_ and adding step by step all
the necessary blocks to the input namelist file called `InputNamelist.py <https://github.com/SmileiPIC/TP-M2-GI/blob/main/InputNamelist.py>`_ .

To add the physical elements or required additional outputs, you just need to
decomment (i.e. remove the symbol ``#`` in front of the) lines with the relative variables and blocks,
as will be described in the exercises.
For example, to activate a block that introduces a laser in the simulation,
you only need to remove the symbol ``#`` in front the ``LaserEnvelopeGaussianAM`` block
and the lines defining the variables used by that block.

Prerequisites
^^^^^^^^^^^^^^^^^

Although the `InputNamelist.py <https://github.com/SmileiPIC/TP-M2-GI/blob/main/InputNamelist.py>`_ is written in Python,
no extensive knowledge of that language is required to understand its contents.
Knowing how to define variables (and, optionally, how to define numpy arrays) should be sufficient.

This practical work assumes that the reader knows how to navigate in a directory tree, create folders,
and copy files from the command line (for a quick recap, see Sections 4-9, 13-14, and 17
in [ShawCommandLineCrashCourse]_).

Some clarifications
^^^^^^^^^^^^^^^^^^^^^^^^
**Warning** Although external injection of an electron bunch in a plasma wave
is not common or easy to realize experimentally, it was chosen due its conceptual simplicity,
which allows to easily study some basic concepts underlying laser-plasma acceleration.

**Warning:** Many parameters of the simulation were chosen as a compromise between having a quick simulation
and being able to describe the physical phenomena of laser plasma acceleration of electron.
More physically accurate simulations of this phenomenon would require larger mesh sizes, a different resolution,
etc., that would require much longer simulations.

A quick word on Smilei
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
As previously stated, the numerical tool you will use for this
practical is the PIC code Smilei [Derouillat2018]_. A prior knowledge of Smilei
is not mandatory for the purposes of the practical exercises. Yet,
feel free to check `Smilei’s website on GitHub <https://smileipic.github.io/Smilei/>`_ .
The interested reader can also find additional
`tutorials <https://smileipic.github.io/tutorials/>`_ focusing on physical
processes not covered by this practical.

Smilei is an open-source and collaborative
code freely distributed under a CeCILL-B license
(equivalent to the GPL license for free-softwares).
It can be run in 1D,2D,3D and cylindrical geometry with azimuthal modes decomposition,
with a diverse suite of physical models and numerical techniques,
from a laptop to supercomputers.


----

References
^^^^^^^^^^

.. [BirdsallLangdon] `C. K. Birdsall and A. B. Langdon, Plasma Physics via Computer Simulation, Taylor and Francis Group, 2004`
.. [Lapenta] `G. Lapenta, Kinetic plasma simulation: Particle in cell method <https://juser.fz-juelich.de/record/283633/files/Lapenta_KT-2.pdf>`_
.. [Derouillat2018] `J. Derouillat et al., Smilei : A collaborative, open-source, multi-purpose particle-in-cell code for plasma simulation, Computer Physics Communications, 222:351 – 373, 2018 <https://doi.org/10.1016/j.cpc.2017.09.024>`_
.. [Esarey2009] `E. Esarey et al., Physics of laser-driven plasma-based electron accelerators, Rev. Mod. Phys., 81:1229–1285, 2009 <http://dx.doi.org/10.1103/RevModPhys.81.1229>`_
.. [Malka2012] `V. Malka, Laser plasma accelerators, Physics of Plasmas, 19(5):055501, 2012 <https://doi.org/10.1063/1.3695389>`_
.. [ShawCommandLineCrashCourse] `Z. A. Shaw, Command line crash course <https://www.computervillage.org/articles/CommandLine.pdf>`_
260 changes: 260 additions & 0 deletions _sources/useful_tools.rst.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,260 @@
.. _UsefulTools:
Appendix: Cheatsheet
----------------------------


A: Command Line Terminal Cheatsheet
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- When you feel lost, use the command ``pwd`` (mnemonic ``pwd``: present working directory) to display your present path. In general a path will have for example the form ``/gpfs/users/user_01``. This specific example means that you are in the folder ``user_01``, which is inside the folder ``users``, which is inside the folder ``gpfs``.

- To check the content of your present path, use the command ``ls`` (mnemonic ``ls``: list)

- Similarly, you can check the content of another directory, e.g. with a path called ``folder/subfolder``, using the command ``ls folder/subfolder/``

- To move to a specific path, e.g. ``path/to/your/folder`` use ``cd path/to/your/folder`` (mnemonic ``cd``: change directory)

- To move up by one level from your present path, use the shortcut ``cd ..``

- To change the name of a file or directory, use ``mv old_name new_name`` (mnemonic ``mv``: move)

- To move a file/folder into a folder ``move source destination_folder/``. The `source` can be a file or a folder.

- *Warning* This operation is irreversible! To remove a file, use ``rm filename`` (mnemonic ``rm``: remove).

- *Warning* This operation is irreversible! To remove an entire folder and its content, use ``rm foldername``

----------

.. _sec13:
B: How to prepare a simulation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Each time an exercise asks to run a new simulation, it is recommended to
create a new directory, where you will insert the required files and run this new simulation.
This will ensure that no previous data is lost or overwritten.

Following are the instructions to complete this process.

- Create a new simulation folder, for example called ``sim``, where you will run your simulation:

.. code-block:: bash
mkdir simulation_folder_name
cd simulation_folder_name
Each time you do it, choose a convenient name of the folder to
remember which simulation it contains. In order to avoid overwriting data, it is recommended to create
a new simulation folder for each simulation.

- Go inside the simulation folder, e.g. with the command ``cd simulation_folder_name``.

- Inside the simulation folder, you will need a file to submit a simulation job to the job scheduler, e.g. ``submission_script.sh``.
You can transfer the file you already have through the comand ``cp``:

.. code-block:: bash
cp $WORKDIR/TP-M2-GI/submission_script.sh simulation_folder_name/
The last command will copy the file ``$WORKDIR/TP-M2-GI/submission_script.sh`` inside the folder called ``simulation_folder_name`` in your present working directory.

- Inside the simulation folder, you will need also the input file of your simulation ``InputNamelist.py``. A copy of the ``InputNamelist.py`` should be in ``cd $WORKDIR/TP-M2-GI`` of Ruche,
have a copy in another folder you can use the ``cp`` command (add the source and destination paths.)

----------

C: How to Run your simulation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Check if you have all the required files (submission script, input namelist) through the command ``ls``

- Remember to uncomment the necessary variables and blocks as explained in the exercise before launching a simulation.

- Launch your simulation job:

.. code-block:: bash
sbatch submission_script.sh
- To check the status (running/queueing etc) of yout job:

.. code-block:: bash
squeue -u $USER
This should also return the number ``JobId`` of your job, necessary for the next command.

- To delete your job from the queue:

.. code-block:: bash
scancel JobId
- To read the end of the log file and let it refresh (if you want to watch your simulation execute for example):

.. code-block:: bash
tail -f smilei.log
The the comand ``ctrl+C`` will allow you to stop watching the file `smilei.log`.

----------

D: How to postprocess your simulation results
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

- Open ``IPython`` (before, you will need to load the Python modules and define variables like how you did to compile the code, and be sure you have compiled ``happi``):

.. code-block:: bash
ipython
- Import the libraries you need:

.. code-block:: bash
import happi
import numpy as np
import matplotlib.pyplot as plt
The output files have the extension ``.h5`` and can be opened with the postprocessing library ``happi``. You will need also the
file ``smilei.py``, generated at the start of your simulation.

- Open your simulation:

.. code-block:: bash
S = happi.Open("path/to/my/results")
Here, ``"path/to/my/results"`` is just an example of path, you need to put the path of your simulation.
If you use simply ``S = happi.Open()``, the library ``happi`` open the results inside the current working directory.

For your convenience and quick reference, some of the most commonly used commands of ``happi`` are reported.
Do not hesitate to copy and paste the following commands in ``IPython`` and adapt them to the problem you are solving.

Remember that the results are in normalized units, but you can specify also SI units for the plot.



D.02: Open a simulation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To import the library ``happi`` in ``IPython`` and open a simulation in the folder, use::

import happi; S = happi.Open("path/to/simulation")

In this specific example the folder’s path is called for example ``"path/to/simulation"``
(use the path of your simulation instead!).

The last command will create an object called ``S``, our simulation,
which contains all the necessary data, taken from the input namelist and from the
output files.

You can easily access parameters from the input namelist, for example::

S.namelist.dx
S.namelist.Main.geometry

In general, if you tap ``S.`` or add the name of the blocks and then use the tab key,
you will see the available blocks and variables.

D.03: Plot diagnostics
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To open a specific diagnostic, like the ``Probe1`` defined in the namelist,
and plot the longitudinal electric field ``Ex`` contained in that diagnostic, use::

S.Probe.Probe1("Ex").plot()

Other physical fields defined on the grid that you can plot are for example ``Ey``
(the electric field component in the `y` direction),
``Rho`` (the charge density). Remember that you can also specify operations
on the fields, like ``2.*Ey-Ex``, when you declare your variable.

By default, the last command will only plot the requested field obtained
in the last simulation output available for that diagnostic.
You may instead be interested in a specific iteration of the simulation (in code units),
like iteration 1200. To plot only that timestep, just specify it inside the diagnostic block::

S.Probe.Probe1("Ex", timesteps=1200).plot()

Remember that this timestep corresponds to physical time ``1200*dt``, where ``dt``
is the simulation timestep, which can be found with ``dt=S.namelist.Main.timestep``.

To know which iterations are available in your diagnostic, you can use::

S.Probe.Probe1("Ex").getAvailableTimesteps()
D.04: Specifying the physical units
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The code, including its outputs, uses normalized units.
You can specify the units you want to use, e.g.::

S.Probe.Probe1("Ex",units=["um","GV/m"]).plot()

D.05: Visualize multiple timesteps
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Normally you have a sequence of outputs, so you may want to see an animation
of the outputs or to be able to slide between the saved timesteps.
It is possible to do it with these commands respectively::

S.Probe.Probe1("Ex").animate()
S.Probe.Probe1("Ex").slide()

In the last case, just slide with the horizontal bar to see the evolution of the plotted quantity at
different iterations.

D.06: Modify elements of the plot
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Like in Python, you may be interested into specifying the figure number,
or change the colormap, or specifying a maximum or minimum value plotted.
You can include the same corresponding keywords inside the plot/animate/slide command.
As an example where all these elements are specified::

S.Probe.Probe1("Ex").plot(figure=2, vmin = -0.1, vmax = 0.1 , cmap = "seismic")

D.07: Plot multiple lines in the same window
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
You may be interested in visualizing multiple curves in the same plot window.
Then the command ``happi.multiPlot`` is what you need.

For example, if you want to plot two quantities from the same simulation,
scaling them through multiplying factors::

import happi
S = happi.Open("path/to/simulation")
E = S.Probe.Probe1("0.1*Ex", timesteps=1000, label = "E")
rho = S.Probe.Probe1("-10.*Rho", timesteps=1000, label="charge density")
happi.multiPlot(E, rho, figure = 1)

The previous example draws two curves, but you can use multiPlot to plot more curves.

Note that you can plot also different timesteps from the same simulation with the same procedure.
Similarly, you can plot two quantities from two or more simulations::

import happi
S1 = happi.Open("path/to/simulation1")
Ex1 = S1.Probe.Probe0("Ex",timesteps=1000)
S2 = happi.Open("path/to/simulation2")
Ex2 = S2.Probe.Probe0("Ex",timesteps=1000)
happi.multiPlot(Ex1,Ex2)

D.08: Export the data
^^^^^^^^^^^^^^^^^^^^^^^^^
Those shown above are all the ``happi`` commands you may need for this practical.
If you prefer instead to analyze your results with ``numpy`` arrays in Python,
you can easily export your diagnostic to a ``numpy`` array, for example::

import happi
import numpy as np
S = happi.Open("path/to/simulation")
myArrayVariable = S.Probe.Probe1("Ex").getData()
myArrayVariable = S.Probe.Probe1("Ex", timesteps=1200).getData()
myArrayVariable = np.asarray(myArrayVariable)

In case you want to export the data to a text file ``.txt`` and read it with
another language, you can write this array on a text file using::

np.savetxt("file_name.txt", myArrayVariable)
Binary file added _static/BPmonoRound.otf
Binary file not shown.
Binary file added _static/BPreplay.otf
Binary file not shown.
Binary file added _static/BPreplayBold.otf
Binary file not shown.
Binary file added _static/BPreplayBoldItalics.otf
Binary file not shown.
Binary file added _static/BPreplayItalics.otf
Binary file not shown.
Binary file added _static/Envelope_Figure.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _static/ExScatterXPx.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _static/EyScatterXY.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _static/Laser_definition.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _static/Mesh_and_Reference.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _static/Schema_Simulation_0.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _static/Schema_Simulation_1.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _static/Schema_Simulation_2.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added _static/Schema_Simulation_3.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit b748438

Please sign in to comment.