Merge branch 'development' into fix_propagator_xyt_transpose

LASY-org · Dec 10, 2023 · 579aa3a · 579aa3a
2 parents 62a6f6b + 13f0e45
commit 579aa3a
Show file tree

Hide file tree

Showing 43 changed files with 302 additions and 171 deletions.
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -18,7 +18,7 @@
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
     - id: trailing-whitespace
       args: [--markdown-linebreak-ext=md]
@@ -64,7 +64,7 @@ repos:
 
 # Autoremoves unused Python imports
 - repo: https://github.com/hadialqattan/pycln
-  rev: v2.2.2
+  rev: v2.4.0
   hooks:
   - id: pycln
     name: pycln (python)
@@ -101,15 +101,15 @@ repos:
 
 # Python Formatting
 - repo: https://github.com/psf/black
-  rev: 23.7.0 # Keep in sync with blacken-docs
+  rev: 23.11.0  # Keep in sync with blacken-docs
   hooks:
   - id: black
 - repo: https://github.com/asottile/blacken-docs
   rev: 1.16.0
   hooks:
   - id: blacken-docs
     additional_dependencies:
-    - black==22.12.0 # keep in sync with black hook
+    - black==23.9.1  # keep in sync with black hook
   # TODO: black-jupyter
 
 # Jupyter Notebooks: clean up all cell outputs

diff --git a/README.md b/README.md
@@ -1,7 +1,5 @@
 # lasy
 
-**Warning: This library is currently in development, and it is, at this stage, only meant to be used/tested by developers. We plan on releasing the first version for general users (i.e. beta version) by summer 2023.**
-
 ## Overview
 
 `lasy` is a Python library that facilitates the initialization of complex laser pulses, in simulations of laser-plasma interactions.
@@ -54,7 +52,7 @@ Then, for each contribution:
 ## Install
 
 ```
-python3 -m pip install -v .
+python3 -m pip install lasy
 ```
 
 For tests, you need to have a few extra packages, such as `pytest` and `openpmd-viewer` installed:

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,8 +1,11 @@
 # install this from the source root (!) directory like this:
 #   python -m pip install --upgrade -r docs/requirements.txt
 -e .
+jupyter
 matplotlib
+nbsphinx
 numpydoc
 pydata-sphinx-theme
+sphinx-copybutton
 sphinx-design
 sphinx-gallery
diff --git a/docs/source/api/profiles/combined_profile.rst b/docs/source/api/profiles/combined_profile.rst
@@ -1,5 +1,5 @@
 Combined Longitudinal and Transverse Profile
 ============================================
 
-.. autoclass:: lasy.profiles.gaussian_profile.CombinedLongitudinalTransverseProfile
+.. autoclass:: lasy.profiles.CombinedLongitudinalTransverseProfile
     :members:
diff --git a/docs/source/api/profiles/from_array_profile.rst b/docs/source/api/profiles/from_array_profile.rst
@@ -1,5 +1,5 @@
 Profile defined from external Numpy array
 =========================================
 
-.. autoclass:: lasy.profiles.from_array_profile.FromArrayProfile
+.. autoclass:: lasy.profiles.FromArrayProfile
     :members:
diff --git a/docs/source/api/profiles/from_openpmd_profile.rst b/docs/source/api/profiles/from_openpmd_profile.rst
@@ -1,5 +1,5 @@
 Profile read from an openPMD file
 =================================
 
-.. autoclass:: lasy.profiles.from_openpmd_profile.FromOpenPMDProfile
+.. autoclass:: lasy.profiles.FromOpenPMDProfile
     :members:
diff --git a/docs/source/api/profiles/gaussian.rst b/docs/source/api/profiles/gaussian.rst
@@ -1,5 +1,5 @@
 Gaussian Laser Profile
 ======================
 
-.. autoclass:: lasy.profiles.gaussian_profile.GaussianProfile
+.. autoclass:: lasy.profiles.GaussianProfile
     :members:
diff --git a/docs/source/api/profiles/index.rst b/docs/source/api/profiles/index.rst
@@ -1,18 +1,12 @@
 Laser Profiles
 ==============
 
-Laser pulses are incorporated into *lasy* via the ``Profile`` class.
-Typically a laser will be constructed through a combination of two classes ``LongitudinalProfile`` and ``TransverseProfile`` which represent the longitudinal and transverse profiles  of the laser.
-
-.. autoclass:: lasy.profiles.profile.Profile
-    :members:
-
 .. toctree::
    :hidden:
 
    gaussian
-   combined_profile
    from_array_profile
    from_openpmd_profile
+   combined_profile
    longitudinal/index
    transverse/index
diff --git a/docs/source/api/profiles/longitudinal/gaussian.rst b/docs/source/api/profiles/longitudinal/gaussian.rst
@@ -1,5 +1,5 @@
 Gaussian Longitudinal Profile
 =============================
 
-.. autoclass:: lasy.profiles.longitudinal.gaussian_profile.GaussianLongitudinalProfile
+.. autoclass:: lasy.profiles.longitudinal.GaussianLongitudinalProfile
     :members:
diff --git a/docs/source/api/profiles/longitudinal/index.rst b/docs/source/api/profiles/longitudinal/index.rst
@@ -1,9 +1,6 @@
 Longitudinal Profiles
 =====================
 
-.. autoclass:: lasy.profiles.longitudinal.longitudinal_profile.LongitudinalProfile
-    :members:
-
 .. toctree::
    :maxdepth: 4
    :hidden:

diff --git a/docs/source/api/profiles/longitudinal/longitudinal_profile_from_data.rst b/docs/source/api/profiles/longitudinal/longitudinal_profile_from_data.rst
@@ -1,5 +1,5 @@
 Longitudinal Profile From Data
 ==============================
 
-.. autoclass:: lasy.profiles.longitudinal.longitudinal_profile_from_data.LongitudinalProfileFromData
+.. autoclass:: lasy.profiles.longitudinal.LongitudinalProfileFromData
     :members:
diff --git a/docs/source/api/profiles/transverse/gaussian.rst b/docs/source/api/profiles/transverse/gaussian.rst
@@ -6,5 +6,5 @@ This transverse profile can also be implemented via the lowest order mode of eit
 
 ------------
 
-.. autoclass:: lasy.profiles.transverse.gaussian_profile.GaussianTransverseProfile
+.. autoclass:: lasy.profiles.transverse.GaussianTransverseProfile
     :members:
diff --git a/docs/source/api/profiles/transverse/hermite_gaussian_profile.rst b/docs/source/api/profiles/transverse/hermite_gaussian_profile.rst
@@ -9,5 +9,5 @@ Hermite-Gaussian modes are a family of solutions to the paraxial wave equation w
 
 ------------
 
-.. autoclass:: lasy.profiles.transverse.hermite_gaussian_profile.HermiteGaussianTransverseProfile
+.. autoclass:: lasy.profiles.transverse.HermiteGaussianTransverseProfile
     :members:
diff --git a/docs/source/api/profiles/transverse/index.rst b/docs/source/api/profiles/transverse/index.rst
@@ -1,9 +1,6 @@
 Transverse Laser Profiles
 =========================
 
-.. autoclass:: lasy.profiles.transverse.transverse_profile.TransverseProfile
-    :members:
-
 .. toctree::
    :maxdepth: 4
    :hidden:

diff --git a/docs/source/api/profiles/transverse/jinc_profile.rst b/docs/source/api/profiles/transverse/jinc_profile.rst
@@ -11,5 +11,5 @@ The shape of the profile is characterised by the waist :math:`w_0`.
 
 ------------
 
-.. autoclass:: lasy.profiles.transverse.jinc_profile.JincTransverseProfile
+.. autoclass:: lasy.profiles.transverse.JincTransverseProfile
     :members:
diff --git a/docs/source/api/profiles/transverse/laguerre_gaussian_profile.rst b/docs/source/api/profiles/transverse/laguerre_gaussian_profile.rst
@@ -11,5 +11,5 @@ The modes can have azimuthally varying fields (for :math:`m > 0`) but any single
 
 ------------
 
-.. autoclass:: lasy.profiles.transverse.laguerre_gaussian_profile.LaguerreGaussianTransverseProfile
+.. autoclass:: lasy.profiles.transverse.LaguerreGaussianTransverseProfile
     :members:
diff --git a/docs/source/api/profiles/transverse/super_gaussian_profile.rst b/docs/source/api/profiles/transverse/super_gaussian_profile.rst
@@ -10,5 +10,5 @@ The shape of the profile is characterised by the waist :math:`w_0` and by one "o
 
 ------------
 
-.. autoclass:: lasy.profiles.transverse.super_gaussian_profile.SuperGaussianTransverseProfile
+.. autoclass:: lasy.profiles.transverse.SuperGaussianTransverseProfile
     :members:
diff --git a/docs/source/api/profiles/transverse/transverse_profile_from_data.rst b/docs/source/api/profiles/transverse/transverse_profile_from_data.rst
@@ -5,5 +5,5 @@ This class allows the user to import an experimentally measured transverse profi
 
 ------------
 
-.. autoclass:: lasy.profiles.transverse.transverse_profile_from_data.TransverseProfileFromData
+.. autoclass:: lasy.profiles.transverse.TransverseProfileFromData
     :members:
diff --git a/docs/source/api/utils/gerchberg_saxton.rst b/docs/source/api/utils/gerchberg_saxton.rst
@@ -0,0 +1,4 @@
+Gerchberg-Saxton phase retrieval
+================================
+
+.. autofunction:: lasy.utils.phase_retrieval.gerchberg_saxton_algo
diff --git a/docs/source/api/utils/index.rst b/docs/source/api/utils/index.rst
@@ -6,5 +6,4 @@ Utils
    :hidden:
 
    grid
-   laser_energy
-   openpmd_output
+   gerchberg_saxton
diff --git a/docs/source/api/utils/laser_energy.rst b/docs/source/api/utils/laser_energy.rst
diff --git a/docs/source/api/utils/openpmd_output.rst b/docs/source/api/utils/openpmd_output.rst
diff --git a/docs/source/code_overview/codes_supporting_lasy.rst b/docs/source/code_overview/codes_supporting_lasy.rst
diff --git a/docs/source/code_overview/data_standards.rst b/docs/source/code_overview/data_standards.rst
diff --git a/docs/source/code_overview/index.rst b/docs/source/code_overview/index.rst
@@ -3,12 +3,22 @@ Overview of the Code
 
 ``lasy`` manipulates laser pulses, and operates on the laser envelope.
 It can be used to define the 3D profile of a laser pulse.
-The user can define seperately the transverse and longitudinal profile of the laser pulse either from a range common analytic profiles or using experimental measurements.
+The user can define separately the transverse and longitudinal profile of the laser pulse either from a range common analytic profiles or using experimental measurements.
 Once defined the laser pulse may be propagated to a user defined location.
 Finally the laser profile may be outputted to file for use as an input to a variety of different simulation tools.
 
-Structure
-#########
+Codes Supporting LASY Data
+##########################
+
+A list of codes which support LASY Data as input:
+
+* `FBPIC <https://github.com/fbpic/fbpic>`_
+* `Wake-T <https://github.com/AngelFP/Wake-T>`_
+* `WarpX <https://github.com/ECP-WarpX/WarpX>`_
+* `HiPACE++ <https://github.com/Hi-PACE/hipace>`_
+
+Structure of lasy
+#################
 
 All information pertaining to the representation of the laser pulse in the code is stored in the :doc:`laser <../api/laser>` object.
 This contains both the physical and computational parameters.
@@ -17,13 +27,12 @@ The physical laser pulse parameters are defined in the laser :doc:`profile <../a
 This is typically constructed from a :doc:`combination <../api/profiles/combined_profile>` of two classes representing the :doc:`longitudinal <../api/profiles/longitudinal/index>` and :doc:`transverse <../api/profiles/transverse/index>` profiles of the laser.
 Alternatively, one can define the full 3D profile in a single function, for example the :doc:`GaussianProfile <../api/profiles/gaussian>`
 
-The data associated with a given laser pulse is stored on a :doc:`grid <../api/utils/grid>`.
-To create this grid and populate it with a laser pulse, we need to know something about the computational parmaeters being used.
+The data associated with a given laser pulse is stored on a grid. To create this grid and populate it with a laser pulse, we need to know something about the computational parameters being used.
 For example, the metadata associated with this grid such as the coordinate system being used, lower and higher ends of the computational domain and number of points etc.
-All of this information is also stored in the :doc:`grid <../api/utils/grid>` class.
+All of this information is passed when initializing the :doc:`laser <../api/laser>` object.
 
 Once a laser :doc:`laser <../api/laser>` object has been defined, we can then propagate it forwards and backwards to see how it evolves or to set it in the right place for the beginning of a subsequent simulation.
-The laser object can be :doc:`outputted <../api/utils/openpmd_output>` to a standard file format for these subsequent calculations. This allows for easy incorporation of standardised laser pulses to a range of different simulation tools.
+The laser object can be written to a standard file format for these subsequent calculations. This allows for easy incorporation of standardized laser pulses to a range of different simulation tools.
 
 Coordinate Systems
 ##################
@@ -44,13 +53,3 @@ In cylindrical coordinates, the envelope is decomposed in :math:`N_m` azimuthal
    \begin{aligned}
    E_x (r,\theta,t) = \operatorname{Re}\left( \sum_{-N_m+1}^{N_m-1}\mathcal{E}_m(r,t) e^{-im\theta}e^{-i\omega_0t}p_x\right)\\
    E_y (r,\theta,t) = \operatorname{Re}\left( \sum_{-N_m+1}^{N_m-1}\mathcal{E}_m(r,t) e^{-im\theta}e^{-i\omega_0t}p_y\right).\end{aligned}
-
-
-.. toctree::
-   :hidden:
-   :maxdepth: 4
-
-   motivation
-   data_standards
-   laser_propagation
-   codes_supporting_lasy
diff --git a/docs/source/code_overview/laser_propagation.rst b/docs/source/code_overview/laser_propagation.rst
diff --git a/docs/source/code_overview/motivation.rst b/docs/source/code_overview/motivation.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -38,18 +38,17 @@
     "sphinx.ext.coverage",
     "sphinx.ext.autosummary",
     "sphinx.ext.viewcode",
+    "sphinx_copybutton",
     "sphinx_design",
     "numpydoc",
     "matplotlib.sphinxext.plot_directive",
+    "nbsphinx",
 ]
 
 # Numpydoc settings
 numpydoc_show_class_members = False
 numpydoc_use_plots = True
 
-# Autodoc Settings
-add_module_names = False
-
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -78,6 +77,7 @@
             "icon": "fa-brands fa-github",
         },
     ],
+    "navigation_with_keys": False,
 }
 
 # Prevent panels extension from modifying page style.

diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -6,11 +6,7 @@
 LASY |release| Documentation
 ============================
 
-.. warning::
-        Warning: This library is currently in development, and it is, at this stage, only meant to be used/tested by developers.
-        We plan on releasing the first version for general users (i.e. beta version) by summer 2023.
-
-``lasy`` (LAser SYmple manipulator) is a Python library that facilitates the initialization of complex laser pulses, in simulations of laser-plasma interactions.
+``lasy`` (LAser manipulations made eaSY) is a Python library that facilitates the initialization of complex laser pulses, in simulations of laser-plasma interactions.
 
 More specifically, ``lasy`` offers many ways to define complex laser pulses (e.g. from commonly-known analytical formulas, from experimental measurements, etc.) and offers pre-processing functionalities (e.g. propagation, re-normalization, geometry conversion).
 The laser field is then exported in a standardized file, that can be read by external simulation codes.