deploy: c5cf6d1

.buildinfo

@@ -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

_sources/index.rst.txt

@@ -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: Contributors: F. Massimo, S. Marini
+
+   introduction
+   exercises
+   useful_tools
+
+
+
+.. Indices and tables
+.. ==================
+
+.. * :ref:`genindex`
+.. * :ref:`modindex`
+.. * :ref:`search`

_sources/introduction.rst.txt

@@ -0,0 +1,88 @@
+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]_). 
+
+- :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, 5, 7, 8, 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>`_

_sources/useful_tools.rst.txt

@@ -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)