Merge pull request #43 from RemiLehe/laser_doc

Add more documentation for the laser parameters

Author: ax3l

PICMI_Python/lasers.py

@@ -13,11 +13,31 @@
 
 class PICMI_GaussianLaser(_ClassWithInit):
     """
-    Specifies a Gaussian laser distribution
-      - name=None: Optional name of the laser
-      - wavelength: Laser wavelength
-      - waist: Waist of the Gaussian pulse at focus [m]
-      - duration: Duration of the Gaussian pulse [s]
+    Specifies a Gaussian laser distribution.
+
+    More precisely, the electric field **near the focal plane** is given by:
+
+    .. math::
+
+        E(\\boldsymbol{x},t) = a_0\\times E_0\,
+        \exp\left( -\\frac{r^2}{w_0^2} - \\frac{(z-z_0-ct)^2}{c^2\\tau^2} \\right)
+        \cos[ k_0( z - z_0 - ct ) - \phi_{cep} ]
+
+    where :math:`k_0 = 2\pi/\\lambda_0` is the wavevector and where
+    :math:`E_0 = m_e c^2 k_0 / q_e` is the field amplitude for :math:`a_0=1`.
+
+    .. note::
+
+        The additional terms that arise **far from the focal plane**
+        (Gouy phase, wavefront curvature, ...) are not included in the above
+        formula for simplicity, but are of course taken into account by
+        the code, when initializing the laser pulse away from the focal plane.
+
+    Parameters:
+    -----------
+      - wavelength: Laser wavelength [m], defined as :math:`\\lambda_0` in the above formula
+      - waist: Waist of the Gaussian pulse at focus [m], defined as :math:`w_0` in the above formula
+      - duration: Duration of the Gaussian pulse [s], defined as :math:`\\tau` in the above formula
       - focal_position=[0,0,0]: Position of the laser focus (vector) [m]
       - centroid_position=[0,0,0]: Position of the laser centroid at time 0 (vector) [m]
       - propagation_direction=[0,0,1]: Direction of propagation (unit vector) [1]
@@ -31,6 +51,7 @@ class PICMI_GaussianLaser(_ClassWithInit):
       - beta: Angular dispersion at focus (in the lab frame) [rad.s]
       - phi2: Temporal chirp at focus (in the lab frame) [s^2]
       - fill_in=True: Flags whether to fill in the empty spaced opened up when the grid moves
+      name=None: Optional name of the laser
     """
     def __init__(self, wavelength, waist, duration,
                  focal_position = [0., 0., 0.],