From 6a2f981e3e7b78c1aa0295121be9b2c9f16fb93e Mon Sep 17 00:00:00 2001 From: Daniel Kotik Date: Wed, 18 Aug 2021 14:17:45 +0200 Subject: [PATCH 01/15] Add support for API documentation --- docs/Makefile | 2 +- docs/source/conf.py | 5 ++++- docs/source/index.md | 8 ++++++++ 3 files changed, 13 insertions(+), 2 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index adf61f4..13a903f 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -21,4 +21,4 @@ help: apidocs: - sphinx-apidoc -f -o source/api ../optbeam + sphinx-apidoc -fP -o source/api ../optbeam diff --git a/docs/source/conf.py b/docs/source/conf.py index 6e7776d..7ced1cb 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -47,7 +47,10 @@ 'cython', ] -autodoc_member_order = 'groupwise' +autodoc_default_options = { + 'private-members': False, + 'member-order': 'groupwise', +} # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/docs/source/index.md b/docs/source/index.md index 9cdd896..cb230b1 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -5,6 +5,14 @@ :relative-images: ``` +```{toctree} +--- +caption: API Reference +maxdepth: 1 +--- + +api/modules +``` # Indices and tables From 9c34cb6e2ce14c9ae3064218bc0677144d750252 Mon Sep 17 00:00:00 2001 From: Daniel Kotik Date: Wed, 18 Aug 2021 14:31:54 +0200 Subject: [PATCH 02/15] Add Python style checks to CI --- .github/workflows/gh-pages.yml | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index 744705d..c8bb7e7 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -10,6 +10,28 @@ on: - develop jobs: + python-style-checks: + runs-on: ubuntu-18.04 + steps: + - name: Check out repository + uses: actions/checkout@v2 + + - name: Setup Python + uses: actions/setup-python@v2 + with: + python-version: '3.8' + + - name: Upgrade pip + run: python3 -m pip install --upgrade pip + + - name: Install dependencies + run: pip install -qU pydocstyle flake8 + + - name: Check docstrings + run: pydocstyle --convention=numpy optbeam + + - name: Lint with flake8 + run: flake8 optbeam --count --show-source --statistics build-and-deploy-pages: runs-on: ubuntu-18.04 steps: From eeaeb0dac467c00cff41b991a80de9bde7ba610c Mon Sep 17 00:00:00 2001 From: Daniel Kotik Date: Thu, 19 Aug 2021 15:38:18 +0200 Subject: [PATCH 03/15] Update `.gitignore` --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index e925824..d5fa00e 100644 --- a/.gitignore +++ b/.gitignore @@ -78,6 +78,7 @@ coverage.xml # Sphinx documentation docs/_build/ +docs/source/api/ # PyBuilder target/ From f475f798106a701ab455a2d4efd5d6f1e3ad9991 Mon Sep 17 00:00:00 2001 From: Daniel Kotik Date: Thu, 19 Aug 2021 15:39:10 +0200 Subject: [PATCH 04/15] Fix docs in `__init__.py` --- optbeam/__init__.py | 44 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 42 insertions(+), 2 deletions(-) diff --git a/optbeam/__init__.py b/optbeam/__init__.py index bcb6130..78fd038 100644 --- a/optbeam/__init__.py +++ b/optbeam/__init__.py @@ -1,3 +1,15 @@ +"""optbeam: exact and fast calculation of optical beam profiles. + +Copyright (c) 2021 Daniel Kotik, Jörg B. Götte. +All rights reserved. + +optbeam is a Cython-based package for fast calculation of exact field +configurations of various optical beams in two and three dimensions. +Intended for use together with `PyMeep`_. + +.. _PyMeep: https://meep.readthedocs.io/en/latest/ + +""" __version__ = "2.1.2" @@ -10,11 +22,39 @@ def critical(n1, n2): - """Calculate critical angle in degrees.""" + """Calculate critical angle. + + Parameters + ---------- + n1 : float + Index of refraction of the incident medium. + n2 : float + Index of refraction of the refractive medium. + + Returns + ------- + float + Angle in degrees. + + """ assert n1 > n2, "\nWarning: Critical angle is not defined, since n1 <= n2!" return _degrees(_asin(n2/n1)) def brewster(n1, n2): - """Calculate Brewster angle in degrees.""" + """Calculate Brewster angle. + + Parameters + ---------- + n1 : float + Index of refraction of the incident medium. + n2 : float + Index of refraction of the refractive medium. + + Returns + ------- + float + Angle in degrees. + + """ return _degrees(_atan(n2/n1)) From 3334f4df778c6ea764a6296e47935db76c79c082 Mon Sep 17 00:00:00 2001 From: Daniel Kotik Date: Thu, 19 Aug 2021 16:16:48 +0200 Subject: [PATCH 05/15] Update workflow to generate API docs --- .github/workflows/gh-pages.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index c8bb7e7..bcdde7d 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -50,8 +50,9 @@ jobs: run: | pip install -q -r docs/requirements.txt - - name: Build docs + - name: Build API and docs run: | + sphinx-apidoc -fP -o docs/source/api optbeam sphinx-build -W --keep-going -b html -d docs/_build/doctrees docs/source docs/_build/html mv -v docs/_build/html public From 7d5cae4b740ba9d1c14523be0922d853369e8d89 Mon Sep 17 00:00:00 2001 From: Daniel Kotik Date: Fri, 20 Aug 2021 15:52:42 +0200 Subject: [PATCH 06/15] Improve docstrings for `Laguerre-Gauss` class --- optbeam/_3d/beams.py | 73 ++++++++++++++++++++++++++++++++++++-------- 1 file changed, 61 insertions(+), 12 deletions(-) diff --git a/optbeam/_3d/beams.py b/optbeam/_3d/beams.py index f4b0aed..eca14d8 100644 --- a/optbeam/_3d/beams.py +++ b/optbeam/_3d/beams.py @@ -116,11 +116,7 @@ def _integrand(self, k_y, k_z): # base classes depending on the choice of a suitable coordinate system # ----------------------------------------------------------------------------- class LaguerreGauss3dCartesian(Beam3dCartesian): - """Cartesian implementaion of a 3d Laguerre-Gauss beam. - - This class serves only as an example for a will be removed in future - versions. - """ + """Cartesian implementaion of a 3d Laguerre-Gauss beam.""" def __init__(self, x, params, called=False): """Laguerre-Gauss beam specifc parameters.""" @@ -175,12 +171,32 @@ def _f_Laguerre_Gauss_cartesian(self, k_y, k_z, W_y, k, m): class LaguerreGauss3d(Beam3dSpherical): - """3d Laguerre-Gauss beam. + r"""3d Laguerre-Gauss beam. + + The implementation is based on [1]_. + + Parameters + ---------- + x : type + Description of parameter `x`. + params : type + Description of parameter `params`. + called : type + Description of parameter `called` (the default is False). + + + References + ---------- + .. [1] Bliokh, K Y, Aiello, A: Goos-Hänchen and Imbert-Fedorov beam shifts: + an overview, Journal of Optics 15(1), 014001, 2013. + + Examples + -------- + + >>> LGbeam = LaguerreGauss3d(x=x, params=params) + >>> LGbeam.profile(r) + >>> LGbeam.spectrum(sin_theta, theta, phi) - Usage: - LGbeam = LaguerreGauss3d(x=x, params=params) - LGbeam.profile(r) - LGbeam.spectrum(sin_theta, theta, phi) """ def __init__(self, x, params, called=False): @@ -191,14 +207,47 @@ def __init__(self, x, params, called=False): self._norm = 4 * math.pi / (self._W_y**2) def profile(self, r): - """...""" + r"""Beam profile, psi. + + Parameters + ---------- + r : type + Description of parameter `r`. + + Returns + ------- + type + Description of returned object. + + Notes + ----- + .. math:: + + \psi_\text{LG}(x,y,z) = k^2 \int_0^{\pi/2}\mathrm{d}\theta\int_0^{2\pi}\mathrm{d}\phi\, \sin{\theta}\cos{\theta}\,f_\text{LG}(\theta, \phi) \exp\bigl[\mathrm{i}k \bigl(x \cos{\theta} + y\sin{\theta}\sin{\phi} - z \sin{\theta}\cos{\phi}\bigr)\bigr] + + """ if self.x == 0 and self._m == 0: return self._norm * _exp(-((r.y**2 + r.z**2) / self._W_y**2)) else: return super().profile(r) def spectrum(self, sin_theta, theta, phi): - """Spectrum amplitude function, f.""" + r"""Spectrum amplitude function, f. + + Notes + ----- + The implementation is based on [1]_. + + The spectrum amplitude is of the form + + .. math:: + + f_\text{LG}(\theta,\phi) = \theta^{|m|} \ + \exp\biggl[-\Bigl(\frac{kw_0}{2} \ + \sin\theta\Bigr)^2 \ + \biggr] \exp(\mathrm{i} m \phi) + + """ if self._m == 0: return self._f_Gauss_spherical(sin_theta, self._W_y, self._k) else: From 9a6f6256604d5ff1d591f3e271e274a4e8223b0b Mon Sep 17 00:00:00 2001 From: Daniel Kotik Date: Fri, 20 Aug 2021 16:44:31 +0200 Subject: [PATCH 07/15] Complete docstring for `spectrum` --- optbeam/_3d/beams.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/optbeam/_3d/beams.py b/optbeam/_3d/beams.py index eca14d8..1f57b2c 100644 --- a/optbeam/_3d/beams.py +++ b/optbeam/_3d/beams.py @@ -234,6 +234,20 @@ def profile(self, r): def spectrum(self, sin_theta, theta, phi): r"""Spectrum amplitude function, f. + Parameters + ---------- + sin_theta : type + Description of parameter `sin_theta`. + theta : type + Description of parameter `theta`. + phi : type + Description of parameter `phi`. + + Returns + ------- + type + Description of returned object. + Notes ----- The implementation is based on [1]_. From 53d01bb2055769f8d8c236a8ef1857972a6258a5 Mon Sep 17 00:00:00 2001 From: Daniel Kotik Date: Fri, 20 Aug 2021 16:45:19 +0200 Subject: [PATCH 08/15] Improve docstrings for `IncAiry2d` --- optbeam/_2d/beams.py | 73 ++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 70 insertions(+), 3 deletions(-) diff --git a/optbeam/_2d/beams.py b/optbeam/_2d/beams.py index d4a8898..0beac6e 100644 --- a/optbeam/_2d/beams.py +++ b/optbeam/_2d/beams.py @@ -91,7 +91,26 @@ def _f_Gauss(self, k_y, W_y): class IncAiry2d(Beam2dCartesian): - """2d incomplete Airy beam.""" + """2d incomplete Airy beam. + + The implementation is based on [2]_. + + Parameters + ---------- + x : type + Description of parameter `x`. + params : type + Description of parameter `params`. + called : type + Description of parameter `called` (the default is False). + + References + ---------- + .. [2] Ring, J D, Howls, C J, Dennis, M R: Incomplete Airy beams: + finite energy from a sharp spectral cutoff , Optics Letters 38(10), + OSA, 1639–1641, May 2013. + + """ def __init__(self, x, params, called=False): """...""" @@ -101,7 +120,30 @@ def __init__(self, x, params, called=False): super().__init__(x, params, called) def profile(self, r): - """...""" + r"""Beam profile, psi. + + Parameters + ---------- + r : type + Description of parameter `r`. + + Returns + ------- + type + Description of returned object. + + Notes + ----- + The beam profile at waist is defined by the incomplete Airy function, + see [2]_ + + .. math:: + + \psi^\text{Airy}_{M,W}(x, z=0) = \int_{M-W}^{M+W}\mathrm{d}\xi\, \ + \mathrm{exp}\left[\mathrm{i}\left(\frac{1}{3} \xi^3 + \ + \xi \frac{x}{w_0}\right)\right] + + """ if self.x == 0: # adjust integration boundaries self._a = self._M-self._W @@ -110,7 +152,32 @@ def profile(self, r): return super().profile(r) def spectrum(self, k_y): - """...""" + r"""Spectrum amplitude function, f. + + Parameters + ---------- + k_y : type + Description of parameter `k_y`. + + Returns + ------- + f_Airy: complex + Spectrum amplitude function + + Notes + ----- + .. math:: + + \begin{align*} + f^\text{Airy}_{M,W}(k_x) &= \frac{1}{2 \pi} \int_{-\infty}^\infty\mathrm{d}x\, \psi^\text{Airy}_{M,W}(x, z=0) \exp(-\mathrm{i}k_x x)\\ + &= \int_{M-W}^{M+W}\mathrm{d}\xi\, \exp\Bigl(\mathrm{i}\frac{1}{3}\xi^3 \Bigr) \delta\Bigl(\frac{\xi}{w_0} -k_x\Bigr)\\ + &=\begin{cases} + w_0 \exp\Bigl[\mathrm{i} \frac{1}{3} \bigl(w_0k_x \bigr)^3\Bigr] & M-W < w_0k_x Date: Mon, 23 Aug 2021 13:53:42 +0200 Subject: [PATCH 09/15] Add reference to classes in top module docsting --- optbeam/__init__.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/optbeam/__init__.py b/optbeam/__init__.py index 78fd038..184a28a 100644 --- a/optbeam/__init__.py +++ b/optbeam/__init__.py @@ -9,6 +9,12 @@ .. _PyMeep: https://meep.readthedocs.io/en/latest/ +Classes +------- +* :class:`._2d.beams.Gauss2d` : 2d Gaussian beam +* :class:`._2d.beams.IncAiry2d` : 2d incomplete Airy beam +* :class:`._3d.beams.LaguerreGauss3d` : 3d vortex beam + """ __version__ = "2.1.2" From d0762d73ab61508187033f0db24cfee658602241 Mon Sep 17 00:00:00 2001 From: Daniel Kotik Date: Wed, 25 Aug 2021 17:23:04 +0200 Subject: [PATCH 10/15] Add module docstrings --- optbeam/_2d/beams.py | 1 + optbeam/_3d/beams.py | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/optbeam/_2d/beams.py b/optbeam/_2d/beams.py index 0beac6e..e589cca 100644 --- a/optbeam/_2d/beams.py +++ b/optbeam/_2d/beams.py @@ -1,3 +1,4 @@ +"""Contains classes for beams in 2d.""" import math import sys diff --git a/optbeam/_3d/beams.py b/optbeam/_3d/beams.py index 1f57b2c..6224ddf 100644 --- a/optbeam/_3d/beams.py +++ b/optbeam/_3d/beams.py @@ -1,4 +1,4 @@ - +"""Contains classes for beams in 3d.""" import math import sys From 483ae5bcca66338146ea4a7317b85041b417fc44 Mon Sep 17 00:00:00 2001 From: Daniel Kotik Date: Thu, 26 Aug 2021 14:55:41 +0200 Subject: [PATCH 11/15] Add docstring template --- optbeam/_2d/beams.py | 25 ++++++++++++++++++++++++- 1 file changed, 24 insertions(+), 1 deletion(-) diff --git a/optbeam/_2d/beams.py b/optbeam/_2d/beams.py index e589cca..72a4540 100644 --- a/optbeam/_2d/beams.py +++ b/optbeam/_2d/beams.py @@ -75,7 +75,30 @@ def __init__(self, x, params, called=False): super().__init__(x, params, called) def profile(self, r): - """...""" + r"""Field amplitude function. + + Plane wave decomposition: calculate field amplitude at light source + position if not coinciding with beam waist. + + Parameters + ---------- + r : type + Description of parameter `r`. + + Returns + ------- + type + Description of returned object. + + Notes + ----- + The beam profile at waist is given by + + .. math:: + + \psi_\text{G} (x, z=0) = \exp\biggl[-\Bigl(\frac{x}{w_0} \Bigr)^2\biggr] + + """ # beam profile distribution (field amplitude) at the waist of the beam if self.x == 0: return self._norm * _exp(-(r.y / self._W_y)**2) From 42288a7e0fef048a44040460b3395ca3c40b0d71 Mon Sep 17 00:00:00 2001 From: Daniel Kotik Date: Thu, 26 Aug 2021 15:02:42 +0200 Subject: [PATCH 12/15] Remove not allowed blank line --- optbeam/_3d/beams.py | 1 - 1 file changed, 1 deletion(-) diff --git a/optbeam/_3d/beams.py b/optbeam/_3d/beams.py index 6224ddf..7cfe980 100644 --- a/optbeam/_3d/beams.py +++ b/optbeam/_3d/beams.py @@ -192,7 +192,6 @@ class LaguerreGauss3d(Beam3dSpherical): Examples -------- - >>> LGbeam = LaguerreGauss3d(x=x, params=params) >>> LGbeam.profile(r) >>> LGbeam.spectrum(sin_theta, theta, phi) From 12c61b6dfb8bcf7210251ad501dbecc3ad1b7876 Mon Sep 17 00:00:00 2001 From: Daniel Kotik Date: Thu, 26 Aug 2021 16:33:15 +0200 Subject: [PATCH 13/15] Add some types to docstrings --- optbeam/_3d/beams.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/optbeam/_3d/beams.py b/optbeam/_3d/beams.py index 7cfe980..3efd154 100644 --- a/optbeam/_3d/beams.py +++ b/optbeam/_3d/beams.py @@ -179,9 +179,9 @@ class LaguerreGauss3d(Beam3dSpherical): ---------- x : type Description of parameter `x`. - params : type + params : dict Description of parameter `params`. - called : type + called : bool Description of parameter `called` (the default is False). @@ -215,7 +215,7 @@ def profile(self, r): Returns ------- - type + complex Description of returned object. Notes @@ -244,7 +244,7 @@ def spectrum(self, sin_theta, theta, phi): Returns ------- - type + complex Description of returned object. Notes From 1fc62a83d9e559f83d75bc058be63142f2fea1d5 Mon Sep 17 00:00:00 2001 From: Daniel Kotik Date: Thu, 26 Aug 2021 16:45:14 +0200 Subject: [PATCH 14/15] Add a docstring --- optbeam/_2d/beams.py | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/optbeam/_2d/beams.py b/optbeam/_2d/beams.py index 72a4540..2f724b7 100644 --- a/optbeam/_2d/beams.py +++ b/optbeam/_2d/beams.py @@ -106,7 +106,25 @@ def profile(self, r): return super().profile(r) def spectrum(self, k_y): - """Spectrum amplitude function, f.""" + r"""Gauss spectrum amplitude function, f. + + Parameters + ---------- + k_y : type + Description of parameter `k_y`. + + Returns + ------- + type + Description of returned object. + + Notes + ----- + .. math:: + f_\text{G} (k_x) = \frac{w_0}{2 \sqrt{\pi}} \ + \exp\biggl[-\Bigl(\frac{k_x w_0}{2} \Bigr)^2 \biggr] + + """ return self._f_Gauss(k_y, self._W_y) def _f_Gauss(self, k_y, W_y): From 2dd8872669fbec19718e8e6c520cde3b0d23efd7 Mon Sep 17 00:00:00 2001 From: Daniel Kotik Date: Sun, 29 Aug 2021 10:56:54 +0200 Subject: [PATCH 15/15] Use customized api docs files: - exclude helper module from documentation - remove `sphinx-apidocs` from pipeline --- .github/workflows/gh-pages.yml | 2 +- .gitignore | 2 +- docs/Makefile | 4 ++-- docs/source/api/optbeam._2d.rst | 20 ++++++++++++++++++++ docs/source/api/optbeam._3d.rst | 19 +++++++++++++++++++ docs/source/api/optbeam.rst | 17 +++++++++++++++++ docs/source/index.md | 2 +- 7 files changed, 61 insertions(+), 5 deletions(-) create mode 100644 docs/source/api/optbeam._2d.rst create mode 100644 docs/source/api/optbeam._3d.rst create mode 100644 docs/source/api/optbeam.rst diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml index bcdde7d..c9b9f8f 100644 --- a/.github/workflows/gh-pages.yml +++ b/.github/workflows/gh-pages.yml @@ -52,7 +52,7 @@ jobs: - name: Build API and docs run: | - sphinx-apidoc -fP -o docs/source/api optbeam + # sphinx-apidoc -fPM -o docs/source/api optbeam sphinx-build -W --keep-going -b html -d docs/_build/doctrees docs/source docs/_build/html mv -v docs/_build/html public diff --git a/.gitignore b/.gitignore index d5fa00e..b5356b0 100644 --- a/.gitignore +++ b/.gitignore @@ -78,7 +78,7 @@ coverage.xml # Sphinx documentation docs/_build/ -docs/source/api/ +#docs/source/api/ # PyBuilder target/ diff --git a/docs/Makefile b/docs/Makefile index 13a903f..a59fed3 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -20,5 +20,5 @@ help: @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -apidocs: - sphinx-apidoc -fP -o source/api ../optbeam +# apidocs: + # sphinx-apidoc -fPM -o source/api ../optbeam diff --git a/docs/source/api/optbeam._2d.rst b/docs/source/api/optbeam._2d.rst new file mode 100644 index 0000000..179d64d --- /dev/null +++ b/docs/source/api/optbeam._2d.rst @@ -0,0 +1,20 @@ +optbeam.\_2d package +==================== + +.. automodule:: optbeam._2d + :members: + :undoc-members: + :show-inheritance: + :private-members: + + +optbeam.\_2d.beams module +------------------------- + +.. automodule:: optbeam._2d.beams + :members: + :undoc-members: + :show-inheritance: + :private-members: + + diff --git a/docs/source/api/optbeam._3d.rst b/docs/source/api/optbeam._3d.rst new file mode 100644 index 0000000..0c6fdbc --- /dev/null +++ b/docs/source/api/optbeam._3d.rst @@ -0,0 +1,19 @@ +optbeam.\_3d package +==================== + +.. automodule:: optbeam._3d + :members: + :undoc-members: + :show-inheritance: + :private-members: + + +optbeam.\_3d.beams module +------------------------- + +.. automodule:: optbeam._3d.beams + :members: + :undoc-members: + :show-inheritance: + :private-members: + diff --git a/docs/source/api/optbeam.rst b/docs/source/api/optbeam.rst new file mode 100644 index 0000000..c13ba4c --- /dev/null +++ b/docs/source/api/optbeam.rst @@ -0,0 +1,17 @@ +optbeam package +=============== + +.. automodule:: optbeam + :members: + :undoc-members: + :show-inheritance: + :private-members: + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + optbeam._2d + optbeam._3d diff --git a/docs/source/index.md b/docs/source/index.md index f54c503..41b811f 100644 --- a/docs/source/index.md +++ b/docs/source/index.md @@ -11,7 +11,7 @@ caption: API Reference maxdepth: 1 --- -api/modules +api/optbeam ``` ```{toctree}