Include examples as notebooks in the documentation (#197)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
LASY-org · Oct 25, 2023 · 9eaa975 · 9eaa975
1 parent 3ab8552
commit 9eaa975
Show file tree

Hide file tree

Showing 6 changed files with 160 additions and 50 deletions.
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,7 +1,9 @@
 # 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-design

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -41,6 +41,7 @@
     "sphinx_design",
     "numpydoc",
     "matplotlib.sphinxext.plot_directive",
+    "nbsphinx",
 ]
 
 # Numpydoc settings

diff --git a/docs/source/tutorials/gaussian_laser.ipynb b/docs/source/tutorials/gaussian_laser.ipynb
@@ -0,0 +1,151 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "996ae31d-192b-4988-bd6b-649c833ae967",
+   "metadata": {},
+   "source": [
+    "# Gaussian laser pulse"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "f25efcc9-1ed0-4f9a-8c62-da36f56ba02f",
+   "metadata": {},
+   "source": [
+    "We will try a simple example to get familiar with the code structure and to verify the installation was successful.\n",
+    "Let's generate a Gaussian pulse at focus, propagate it backwards by one Rayleigh length (the pulse is then located upstream of the focal plane) and then output it to a file.\n",
+    "\n",
+    "First let's load in the required functions from the library."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ed0a409c-3c02-4fc4-b41b-ef41d0fb5a3a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from lasy.profiles.gaussian_profile import GaussianProfile\n",
+    "from lasy.laser import Laser"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "83519896-2653-4895-8d90-789c4f0729ae",
+   "metadata": {},
+   "source": [
+    "Next, define the physical parameters of the laser pulse and create the laser profile object."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "15491762-c2d5-4b65-8cd3-4633a4cb7eff",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "wavelength     = 800e-9  # Laser wavelength in meters\n",
+    "polarization   = (1,0)   # Linearly polarized in the x direction\n",
+    "energy         = 1.5     # Energy of the laser pulse in joules\n",
+    "spot_size      = 25e-6   # Waist of the laser pulse in meters\n",
+    "pulse_duration = 30e-15  # Pulse duration of the laser in seconds\n",
+    "t_peak         = 0.0     # Location of the peak of the laser pulse in time\n",
+    "\n",
+    "laser_profile = GaussianProfile(wavelength,polarization,energy,spot_size,pulse_duration,t_peak)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c303d3b6-2422-445b-a332-bc3f48388612",
+   "metadata": {},
+   "source": [
+    "Now create a full laser object containing the above physical parameters together with the computational settings."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "84cb6fd2-2f44-4cc9-a5c1-6dd1e0d72c67",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "dimensions     = 'rt'                              # Use cylindrical geometry\n",
+    "lo             = (0,-2.5*pulse_duration)           # Lower bounds of the simulation box\n",
+    "hi             = (5*spot_size,2.5*pulse_duration)  # Upper bounds of the simulation box\n",
+    "num_points     = (300,500)                         # Number of points in each dimension\n",
+    "\n",
+    "laser = Laser(dimensions,lo,hi,num_points,laser_profile)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "292c6e63-0480-4fb9-b1ad-6b679a3472d0",
+   "metadata": {},
+   "source": [
+    "By default, the values of the laser envelope are injected on the focal plan. One can propagate it backwards by one Rayleigh length (optional)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "00b4f258-ca10-4bc7-b550-75fb10c3603a",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "z_R            = 3.14159*spot_size**2/wavelength    # The Rayleigh length\n",
+    "laser.propagate(-z_R)                               # Propagate the pulse upstream of the focal plane"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8df816dc-9b47-4cb0-8716-600352fafb72",
+   "metadata": {},
+   "source": [
+    "Output the result to a file. Here we utilise the openPMD standard."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b6a4c66b-651e-40b7-b15e-53f8a27caeb2",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "file_prefix    = 'test_output' # The file name will start with this prefix\n",
+    "file_format    = 'h5'          # Format to be used for the output file\n",
+    "\n",
+    "laser.write_to_file(file_prefix, file_format)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "1edc3e0b-f88a-4a8a-8802-3d5ec9098f9c",
+   "metadata": {},
+   "source": [
+    "The generated file may now be viewed or used as a laser input to a variety of other simulation tools."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.11.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/docs/source/tutorials/index.rst b/docs/source/tutorials/index.rst
@@ -2,7 +2,6 @@ Tutorials
 =========
 
 .. toctree::
-   :hidden:
-   :maxdepth: 4
+   :maxdepth: 1
 
-   initialise_gaussian
+   gaussian_laser.ipynb
diff --git a/docs/source/tutorials/initialise_gaussian.rst b/docs/source/tutorials/initialise_gaussian.rst
diff --git a/docs/source/user_guide/index.rst b/docs/source/user_guide/index.rst
@@ -12,50 +12,9 @@ Installation
 First Example
 #############
 
-We will try a simple example to get familiar with the code structure and to verify the installation was successful.
-Let's generate a Gaussian pulse at focus, propagate it backwards by one Rayleigh length (the pulse is then located upstream of the focal plane) and then output it to a file.
+To see how to create a simple Gaussian laser pulse with ``lasy``, see this short example:
 
-..  code-block:: python
-   :caption: First lets load in the required functions from the library.
+.. toctree::
+   :maxdepth: 1
 
-   from lasy.profiles.gaussian_profile import GaussianProfile
-   from lasy.laser import Laser
-
-
-..  code-block:: python
-   :caption: Next, define the physical parameters of the laser pulse and create the laser profile object.
-
-   wavelength     = 800e-9  # Laser wavelength in meters
-   polarization   = (1,0)   # Linearly polarized in the x direction
-   energy         = 1.5     # Energy of the laser pulse in joules
-   spot_size      = 25e-6   # Waist of the laser pulse in meters
-   pulse_duration = 30e-15  # Pulse duration of the laser in seconds
-   t_peak         = 0.0     # Location of the peak of the laser pulse in time
-
-   laser_profile = GaussianProfile(wavelength,polarization,energy,spot_size,pulse_duration,t_peak)
-
-..  code-block:: python
-   :caption: Now create a full laser object containing the above physical parameters together with the computational settings.
-
-   dimensions     = 'rt'                              # Use cylindrical geometry
-   lo             = (0,-2.5*pulse_duration)           # Lower bounds of the simulation box
-   hi             = (5*spot_size,2.5*pulse_duration)  # Upper bounds of the simulation box
-   num_points     = (300,500)                         # Number of points in each dimension
-
-   laser = Laser(dimensions,lo,hi,num_points,laser_profile)
-
-..  code-block:: python
-   :caption: By default, the values of the laser envelope are injected on the focal plan. One can propagate it backwards by one Rayleigh length (optional).
-
-   z_R            = 3.14159*spot_size**2/wavelength    # The Rayleigh length
-   laser.propagate(-z_R)                               # Propagate the pulse upstream of the focal plane
-
-..  code-block:: python
-   :caption: Output the result to a file. Here we utilise the openPMD standard.
-
-   file_prefix    = 'test_output' # The file name will start with this prefix
-   file_format    = 'h5'          # Format to be used for the output file
-
-   laser.write_to_file(file_prefix, file_format)
-
-The generated file may now be viewed or used as a laser input to a variety of other simulation tools.
+   ../tutorials/gaussian_laser.ipynb