Merge branch 'dev'

# Conflicts:
#	pynever/config/configuration.ini
#	pyproject.toml

Author: sdemarch

.github/workflows/deploy-docs.yml

@@ -10,42 +10,42 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v3
-
-    - name: Set up Python
-      uses: actions/setup-python@v4
-      with:
-        python-version: '3.11'
-
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install .
-        pip install sphinx sphinx-autodoc-typehints sphinx-rtd-theme
-
-    - name: Build Sphinx documentation
-      run: |
-        cd docs
-        sphinx-build -M html . _build/
-
-    - name: Clone GitHub Pages repo
-      run: |
-        git config --global user.name "github-actions"
-        git config --global user.email "github-actions@github.com"
-        git clone https://x-access-token:${{ secrets.GH_PAGES_DEPLOY }}@github.com/nevertools/nevertools.github.io.git gh-pages
-      env:
-        GH_PAGES_DEPLOY_TOKEN: ${{ secrets.GH_PAGES_DEPLOY }}
-
-    - name: Copy docs to gh-pages/pynever
-      run: |
-        rm -rf gh-pages/pynever
-        mkdir -p gh-pages/pynever
-        cp -r docs/_build/html/* gh-pages/pynever/
-
-    - name: Commit and push changes
-      run: |
-        cd gh-pages
-        git add pynever
-        git commit -m "Update API docs from pynever" || echo "No changes to commit"
-        git push origin master
+      - name: Checkout code
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install .
+          pip install -r docs/requirements.txt
+
+      - name: Build Sphinx documentation
+        run: |
+          cd docs
+          sphinx-build -M html . _build/
+
+      - name: Clone GitHub Pages repo
+        run: |
+          git config --global user.name "github-actions"
+          git config --global user.email "github-actions@github.com"
+          git clone https://x-access-token:${{ secrets.GH_PAGES_DEPLOY }}@github.com/nevertools/nevertools.github.io.git gh-pages
+        env:
+          GH_PAGES_DEPLOY_TOKEN: ${{ secrets.GH_PAGES_DEPLOY }}
+
+      - name: Copy docs to gh-pages/pynever
+        run: |
+          rm -rf gh-pages/pynever
+          mkdir -p gh-pages/pynever
+          cp -r docs/_build/html/* gh-pages/pynever/
+
+      - name: Commit and push changes
+        run: |
+          cd gh-pages
+          git add pynever
+          git commit -m "Update API docs from pynever" || echo "No changes to commit"
+          git push origin master

docs/Guide/usage.rst

@@ -1,4 +1,4 @@
-Verification
+Stand-alone
 ============
 
 Command-line interface

docs/conf.py

@@ -34,18 +34,20 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.napoleon',
     'sphinx_autodoc_typehints',
-    'sphinx.ext.linkcode',
+    'sphinx.ext.linkcode'
 ]
 
 autodoc_member_order = 'bysource'
+# nbsphinx_execute = 'never'
+# nbsphinx_allow_errors = True
 
 # Add any paths that contain templates here, relative to this directory.
 # templates_path = ['_templates']
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README*']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'README*', '**.ipynb_checkpoints']
 
 # -- Options for HTML output -------------------------------------------------
 

docs/requirements.txt

@@ -0,0 +1,7 @@
+# Packages in addition to test_requirements.txt
+# needed to build python documentation
+Sphinx
+sphinx-rtd-theme
+sphinx-autodoc-typehints
+Pygments
+nbsphinx

examples/notebooks/00 - Introduction.ipynb

@@ -0,0 +1,143 @@
+{
+ "cells": [
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "# API - Networks\n",
+    "\n",
+    "This notebook illustrates the main features of pyNeVer for the creation of a neural network"
+   ],
+   "id": "7386e4bcb1b4c027"
+  },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "## The _networks_ module\n",
+    "\n",
+    "The module *networks* contains the classes __SequentialNetwork__ and __AcyclicNetwork__ to represent feed-forward and residual neural networks, respectively. Both subclass the abstract class __NeuralNetwork__ that provides base methods and utilities."
+   ],
+   "id": "180d25f1124192a2"
+  },
+  {
+   "metadata": {},
+   "cell_type": "code",
+   "source": [
+    "from pynever.networks import NeuralNetwork, SequentialNetwork, AcyclicNetwork\n",
+    "\n",
+    "# Create an empty FF network with identifier 'my_net' and input identifier 'X'\n",
+    "my_ff_net = SequentialNetwork('my_awesome_ff_net', 'X')\n",
+    "\n",
+    "# Create an empty ResNet. Notice that the input identifiers are in a list to allow multiple inputs.\n",
+    "my_res_net = AcyclicNetwork('my_awesome_res_net', ['X_b', 'X_b'])\n",
+    "\n",
+    "print(my_ff_net)\n",
+    "print(my_res_net)\n",
+    "\n",
+    "print(isinstance(my_ff_net, NeuralNetwork))\n",
+    "print(isinstance(my_res_net, NeuralNetwork))"
+   ],
+   "id": "b63800010ce3b95a",
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "## The _nodes_ module\n",
+    "\n",
+    "The module *nodes* contains the definition of NN layers as nodes in the computational graph. For the list of all supported layers, see [the documentation](http://www.neuralverification.org/pynever/API/1_Nodes.html). All nodes require a string identifier and the definition of the input dimension: the neural network object contains no information about this."
+   ],
+   "id": "2c88535153a53d36"
+  },
+  {
+   "metadata": {},
+   "cell_type": "code",
+   "source": [
+    "from pynever import nodes\n",
+    "import torch\n",
+    "\n",
+    "w = torch.Tensor([[1, 1], [-1, 1]])\n",
+    "b = torch.zeros(2)\n",
+    "\n",
+    "# Create a fully connected layer with 2 inputs and 2 neurons.\n",
+    "# The input dimension in_dim is always a tuple\n",
+    "fc = nodes.FullyConnectedNode('fc', (2,), 2, weight=w, bias=b)\n",
+    "\n",
+    "# Add it to the ff network\n",
+    "my_ff_net.append_node(fc)\n",
+    "# Let's add a ReLU layer now\n",
+    "my_ff_net.append_node(nodes.ReLUNode('relu', (2,)))\n",
+    "\n",
+    "print(my_ff_net)"
+   ],
+   "id": "2667008980c520b5",
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": [
+    "## Residual networks\n",
+    "\n",
+    "For ResNets we provide a different method to add layers: *add_node* allows to specify the layer parents and, possibly, children"
+   ],
+   "id": "a8b5ddea7d01fad7"
+  },
+  {
+   "metadata": {},
+   "cell_type": "code",
+   "source": [
+    "rl = nodes.ReLUNode('relu', (2,))\n",
+    "fc_2 = nodes.FullyConnectedNode('fc_2', (2,), 2, weight=w, bias=b)\n",
+    "rl_2 = nodes.ReLUNode('relu_2', (2,))\n",
+    "\n",
+    "my_res_net.add_node(fc)  # This is the first layer\n",
+    "my_res_net.add_node(rl, [fc])  # Layer rl follows fc\n",
+    "my_res_net.add_node(fc_2, [rl])  # Layer fc_2 follows rl\n",
+    "my_res_net.add_node(rl_2, [fc, fc_2])  # Layer rl_2 has a skip connection and has as parents both fc and fc_2\n",
+    "\n",
+    "print(my_res_net)\n",
+    "\n",
+    "# A few utility methods\n",
+    "print(f'Topological sort: {my_res_net.get_topological_order()}')\n",
+    "print(f'Parents of rl_2:  {my_res_net.get_parents(rl_2)}')\n",
+    "print(f'Children of fc:   {my_res_net.get_children(fc)}')\n",
+    "print(f'Leaves of the nn: {my_res_net.get_leaves()}')"
+   ],
+   "id": "fedaca77cdea61f",
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "metadata": {},
+   "cell_type": "markdown",
+   "source": "",
+   "id": "bada530cf2b5aa93"
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}