Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add proper docstrings in Numpy Style #22

Draft
wants to merge 16 commits into
base: develop
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 24 additions & 1 deletion .github/workflows/gh-pages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -28,8 +50,9 @@ jobs:
run: |
pip install -q -r docs/requirements.txt

- name: Build docs
- name: Build API and docs
run: |
# 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

Expand Down
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -78,6 +78,7 @@ coverage.xml

# Sphinx documentation
docs/_build/
#docs/source/api/

# PyBuilder
target/
Expand Down
4 changes: 2 additions & 2 deletions docs/Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -20,5 +20,5 @@ help:
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)


apidocs:
sphinx-apidoc -f -o source/api ../optbeam
# apidocs:
# sphinx-apidoc -fPM -o source/api ../optbeam
20 changes: 20 additions & 0 deletions docs/source/api/optbeam._2d.rst
Original file line number Diff line number Diff line change
@@ -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:


19 changes: 19 additions & 0 deletions docs/source/api/optbeam._3d.rst
Original file line number Diff line number Diff line change
@@ -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:

17 changes: 17 additions & 0 deletions docs/source/api/optbeam.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
optbeam package
===============

.. automodule:: optbeam
:members:
:undoc-members:
:show-inheritance:
:private-members:

Subpackages
-----------

.. toctree::
:maxdepth: 4

optbeam._2d
optbeam._3d
5 changes: 4 additions & 1 deletion docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -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']
Expand Down
8 changes: 8 additions & 0 deletions docs/source/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,14 @@
:relative-images:
```

```{toctree}
---
caption: API Reference
maxdepth: 1
---

api/optbeam
```

```{toctree}
---
Expand Down
119 changes: 114 additions & 5 deletions optbeam/_2d/beams.py
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
"""Contains classes for beams in 2d."""

import math
import sys
Expand Down Expand Up @@ -74,15 +75,56 @@ 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)
else:
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):
Expand All @@ -91,7 +133,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):
"""..."""
Expand All @@ -101,7 +162,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
Expand All @@ -110,7 +194,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 <M+W \\
0 & \text{otherwise}
\end{cases}
\end{align*}

"""
return self._f_Airy(k_y, self._W_y, self._M, self._W)

def _f_Airy(self, k_y, W_y, M, W):
Expand Down
Loading