add example notebooks (and their execution through devops_tests) (#222)

Author: slayoo

.binder/postBuild

@@ -0,0 +1,4 @@
+#!/bin/bash
+set -e
+shopt -s extglob
+rm -rfv !("examples")

.binder/requirements.txt

@@ -0,0 +1,6 @@
+PyPartMC>=0.0.19
+matplotlib
+ipywidgets
+voila
+open-atmos-jupyter-utils
+PySDM

.github/workflows/pylint.yml

@@ -20,6 +20,8 @@ jobs:
         python-version: 3.9
     - run: |
         python -m pip install --upgrade pip
-        pip install pylint
+        pip install pylint nbqa
         pip install -e .[tests]
+        pip install -r .binder/requirements.txt
     - run: pylint --unsafe-load-any-extension=y --disable=fixme,no-member,trailing-newlines,missing-module-docstring,missing-class-docstring,missing-function-docstring,unnecessary-pass $(git ls-files '*.py')
+    - run: nbqa pylint --unsafe-load-any-extension=y --disable=fixme,no-member,wrong-import-position,trailing-whitespace,missing-function-docstring,missing-module-docstring $(git ls-files '*.ipynb')

.github/workflows/tests+pypi.yml

@@ -15,18 +15,6 @@ on:
     types: [published]
 
 jobs:
-  devops_tests:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-        with:
-          submodules: recursive
-          fetch-depth: 0  # https://github.com/pypa/setuptools_scm/issues/480
-      - run: pip install -r gitmodules/devops_tests/requirements.txt
-      - env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: pytest --durations=10 -v -s -We -p no:unraisableexception gitmodules/devops_tests
-
   debug_build_ok:
     runs-on: ubuntu-latest
     steps:
@@ -37,11 +25,12 @@ jobs:
       - run: DEBUG=1 VERBOSE=1 pip install --verbose -e .[tests]
 
   build:
-    needs: [devops_tests, debug_build_ok]
+    needs: [debug_build_ok]
     strategy:
       matrix:
         platform: [ubuntu-latest, macos-12, windows-latest]
         python-version: ["3.7", "3.8", "3.9", "3.10", "3.11"]
+      fail-fast: false
     runs-on: ${{ matrix.platform }}
     steps:
       - if: startsWith(matrix.platform, 'macos-')
@@ -118,6 +107,14 @@ jobs:
           cd tests
           python -c "import PyPartMC"
           pytest --durations=10 -v -s -We -p no:unraisableexception -k 'not test_todos_annotated' .
+          cd ..
+
+      - if: matrix.python-version != '3.7'
+        run: |
+          pip install -r gitmodules/devops_tests/requirements.txt
+          ex -sc 'g/^PyPartMC/d' -cx .binder/requirements.txt
+          pip install -r .binder/requirements.txt
+          GITHUB_TOKEN=${{ secrets.GITHUB_TOKEN }} pytest --durations=10 -v -s -We -p no:unraisableexception gitmodules/devops_tests
 
 ### uncomment to gain ssh access in case of failure
 #      - if: ${{ failure() }}

README.md

@@ -28,6 +28,14 @@ The Python API can facilitate using PartMC from other environments - see, e.g.,
 import PyPartMC
 ```
 
+#### Jupyter notebooks with examples 
+
+- Dry-Wet Particle Size Equilibration with PartMC and PySDM:   
+[![nbviewer](https://raw.githubusercontent.com/jupyter/design/master/logos/Badges/nbviewer_badge.svg)](https://nbviewer.jupyter.org/github/open-atmos/PyPartMC/blob/main/examples/lognorm_ex.ipynb)
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/open-atmos/PyPartMC/blob/main/examples/lognorm_ex.ipynb)
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/open-atmos/PyPartMC.git/main?urlpath=lab/tree/examples/lognorm_ex.ipynb)
+[![Voila](https://img.shields.io/static/v1?label=Voil%C3%A0&logo=jupyter&color=teal&message=web+app)](https://mybinder.org/v2/gh/open-atmos/PyPartMC/main?urlpath=voila%2Frender%2Fexamples%2Flognorm_ex.ipynb)
+
 ## Features
 
 - works on Linux, macOS and Windows (compatibility assured with [CI builds](https://github.com/open-atmos/PyPartMC/blob/main/.github/workflows/tests.yml))

examples/hello_world.ipynb

@@ -0,0 +1,94 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "[![nbviewer](https://raw.githubusercontent.com/jupyter/design/master/logos/Badges/nbviewer_badge.svg)](https://nbviewer.jupyter.org/github/open-atmos/PyPartMC/blob/main/examples/hello_world.ipynb)   \n",
+    "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/open-atmos/PyPartMC/blob/main/examples/hello_world.ipynb)    \n",
+    "[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/open-atmos/PyPartMC.git/main?urlpath=lab/tree/examples/hello_world.ipynb)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {
+    "id": "iEavJeJoPWzg"
+   },
+   "outputs": [],
+   "source": [
+    "import sys\n",
+    "if 'google.colab' in sys.modules:\n",
+    "    !pip --verbose install PyPartMC"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {
+    "id": "VnLSclLsOxRz"
+   },
+   "outputs": [],
+   "source": [
+    "import PyPartMC as ppmc"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {
+    "id": "s2VeF72qPsKB"
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "16"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "ppmc.pow2_above(13)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "id": "I_kD6AomXW6h"
+   },
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "colab": {
+   "collapsed_sections": [],
+   "name": "Untitled13.ipynb",
+   "provenance": []
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "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.9.1"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 1
+}