Merge pull request #64 from f-dangel/release

Release 1.1.1, Part 3

.darglint

@@ -0,0 +1,4 @@
+[darglint]
+docstring_style = google
+# short, long, full
+strictness = full

.github/workflows/lint.yaml

@@ -3,7 +3,13 @@ name: Lint
 on:
   push:
     branches:
-      - pep8-style
+      - development
+      - master
+  pull_request:
+    branches:
+      - development
+      - master
+
 
 jobs:
   flake8:
@@ -36,3 +42,35 @@ jobs:
     - name: Run black
       run: |
         make black-check
+  pydocstyle:
+    if: false
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v1
+    - name: Set up Python 3.7
+      uses: actions/setup-python@v1
+      with:
+        python-version: 3.7
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        make install-lint
+    - name: Run pydocstyle
+      run: |
+        make pydocstyle-check
+  darglint:
+    if: false
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v1
+    - name: Set up Python 3.7
+      uses: actions/setup-python@v1
+      with:
+        python-version: 3.7
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        make install-lint
+    - name: Run darglint
+      run: |
+        make darglint-check

.pre-commit-config.yaml

@@ -2,17 +2,29 @@ repos:
 - repo: https://github.com/psf/black
   rev: stable
   hooks:
-    - id: black
-      args: [--config=black.toml]
+  - id: black
+    args: [--config=black.toml]
 - repo: https://gitlab.com/pycqa/flake8
   rev: '3.7.9'
   hooks:
-    - id: flake8
-      additional_dependencies: [
-        mccabe,
-        pycodestyle,
-        pyflakes,
-        pep8-naming,
-        flake8-bugbear,
-        flake8-comprehensions,
-      ]
+  - id: flake8
+    additional_dependencies: [
+      mccabe,
+      pycodestyle,
+      pyflakes,
+      pep8-naming,
+      flake8-bugbear,
+      flake8-comprehensions,
+    ]
+- repo: https://github.com/pycqa/pydocstyle
+  rev: 5.0.2
+  hooks:
+  - id: pydocstyle
+    args:
+    - --count
+- repo: https://github.com/terrencepreilly/darglint
+  rev: master
+  hooks:
+  - id: darglint
+    args:
+    - --verbosity 2

.pydocstyle

@@ -0,0 +1,6 @@
+[pydocstyle]
+convention = google
+match = .*\.py
+# ignore =
+#   A,
+#   B,

.travis.yml

@@ -12,7 +12,6 @@ cache:
 - pip
 script:
 - pytest -vx --cov=backpack/ .
-- python examples/run_examples.py
 after_success:
 - coveralls
 notifications:

README-dev.md

@@ -1,10 +1,78 @@
-Basics about the development setup 
+# <img alt="BackPACK" src="./logo/backpack_logo_torch.svg" height="90"> BackPACK developer manual
 
-|-|-|
-|-|-|
-| Python version | The subset of Python 3 and Pytorch (`3.5, 3.6, 3.7`) and use `3.7` for development |
-| Tooling management | [`make`](https://www.gnu.org/software/make/) as an interface to the dev tools ([makefile](makefile)) |
-| Testing | [`pytest`](https://docs.pytest.org) ([testing readme](test/readme.md))
-| Style | [`black`](https://black.readthedocs.io) ([rules](black.toml)) for formatting and [`flake8`](http://flake8.pycqa.org/) ([rules](.flake8)) for linting |
-| CI/QA | [`Travis`](https://travis-ci.org/f-dangel/backpack) ([config](.travis.yaml)) to run tests and [`Github workflows`](https://github.com/f-dangel/backpack/actions) ([config](.github/workflows)) to check formatting and linting |
+## General standards 
+- Python version: support 3.5+, use 3.7 for development
+- `git` [branching model](https://nvie.com/posts/a-successful-git-branching-model/)
+- Docstring style:  [Google](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)
+- Test runner: [`pytest`](https://docs.pytest.org/en/latest/)
+- Formatting: [`black`](https://black.readthedocs.io) ([`black` config](black.toml))
+- Linting: [`flake8`](http://flake8.pycqa.org/) ([`flake8` config](.flake8))
 
+---
+
+The development tools are managed using [`make`](https://www.gnu.org/software/make/) as an interface ([`makefile`](makefile)). For an overview, call
+```bash
+make help 
+```
+
+## Suggested workflow with [Anaconda](https://docs.anaconda.com/anaconda/install/)
+1. Clone the repository. Check out the `development` branch
+```bash
+git clone https://github.com/f-dangel/backpack.git ~/backpack
+cd ~/backpack
+git checkout development
+```
+2. Create `conda` environment `backpack` with the [environment file](.conda_env.yml). It comes with all dependencies installed, and BackPACK installed with the [--editable](http://codumentary.blogspot.com/2014/11/python-tip-of-year-pip-install-editable.html) option. Activate it.
+```bash
+make conda-env
+conda activate backpack
+```
+3. Install the development dependencies and `pre-commit` hooks
+```bash
+make install-dev
+```
+4. **You're set up!** Here are some useful commands for developing
+  - Run the tests
+    ```bash
+    make test
+    ```
+  - Lint code
+    ```bash
+    make flake8
+    ```
+  - Check format (code, imports, and docstrings)
+    ```bash
+    make format-check
+    ```
+
+## Documentation
+
+### Build
+- Use `make build-docs`
+- To use the RTD theme, uncomment the line `html_theme = "sphinx_rtd_theme"` in `docs/rtd/conf.py` (this line needs to be uncommented for automatic deployment to RTD)
+
+### View
+- Go to `docs_src/rtd_output/html`, open `index.html`
+
+### Edit
+- Content in `docs_src/rtd/*.rst`
+- Docstrings in code
+- Examples in `examples/rtd_examples` (compiled automatically)
+
+
+## Details
+
+- Running quick/extensive tests: ([testing readme](test/readme.md))
+- Continuous Integration (CI)/Quality Assurance (QA)
+  - [`Travis`](https://travis-ci.org/f-dangel/backpack) ([`Travis` config](.travis.yaml))
+    - Run tests: [`pytest`](https://docs.pytest.org/en/latest/)
+    - Report test coverage: [`coveralls`](https://coveralls.io)
+    - Run examples
+  - [`Github workflows`](https://github.com/f-dangel/backpack/actions) ([config](.github/workflows))
+    - Check code formatting: [`black`](https://black.readthedocs.io) ([`black` config](black.toml))
+    - Lint code: [`flake8`](http://flake8.pycqa.org/) ([`flake8` config](.flake8))
+    - Check docstring style: [`pydocstyle`](https://github.com/PyCQA/pydocstyle) ([`pydocstyle` config](.pydocstyle))
+    - Check docstring description matches definition: [`darglint`](https://github.com/terrencepreilly/darglint) ([`darglint` config](.darglint))
+- Optional [`pre-commit`](https://github.com/pre-commit/pre-commit) hooks [ `pre-commit` config ](.pre-commit-config.yaml)
+
+###### _BackPACK is not endorsed by or affiliated with Facebook, Inc. PyTorch, the PyTorch logo and any related marks are trademarks of Facebook, Inc._

README.md

@@ -1,29 +1,41 @@
-# BACKpropagation PACKage - a backpack for `PyTorch`
+# <img alt="BackPACK" src="./logo/backpack_logo_torch.svg" height="90"> BackPACK: Packing more into backprop
 
-| branch | tests & examples | coverage |
-|--------|---------------------------|----------|
-|`master` | [![Build Status](https://travis-ci.org/f-dangel/backpack.svg?branch=master)](https://travis-ci.org/f-dangel/backpack) | [![Coverage Status](https://coveralls.io/repos/github/f-dangel/backpack/badge.svg?branch=master)](https://coveralls.io/github/f-dangel/backpack) |
-| `development` | [![Build Status](https://travis-ci.org/f-dangel/backpack.svg?branch=development)](https://travis-ci.org/f-dangel/backpack) | [![Coverage Status](https://coveralls.io/repos/github/f-dangel/backpack/badge.svg?branch=development)](https://coveralls.io/github/f-dangel/backpack) |
+[![Travis](https://travis-ci.org/f-dangel/backpack.svg?branch=master)](https://travis-ci.org/f-dangel/backpack)
+[![Coveralls](https://coveralls.io/repos/github/f-dangel/backpack/badge.svg?branch=master)](https://coveralls.io/github/f-dangel/backpack)
+[![Python 3.5+](https://img.shields.io/badge/python-3.5+-blue.svg)](https://www.python.org/downloads/release/python-350/)
 
-A backpack for PyTorch that extends the backward pass of feedforward networks to compute quantities beyond the gradient.
+BackPACK is built on top of [PyTorch](https://github.com/pytorch/pytorch). It efficiently computes quantities other than the gradient.
+
+- **Website:** https://backpack.pt
+- **Documentation:** https://docs.backpack.pt/en/master/
+- **Bug reports & feature requests:** https://github.com/f-dangel/backpack/issues
+
+Provided quantities include:
+- Individual gradients from a mini-batch
+- Estimates of the gradient variance or second moment
+- Approximate second-order information (diagonal and Kronecker approximations)
+
+**Motivation:** Computation of most quantities is not necessarily expensive (often just a small modification of the existing backward pass where backpropagated information can be reused). But it is difficult to do in the current software environment.
 
-- Check out the [cheatsheet](examples/cheatsheet.pdf) for an overview of quantities.
-- Check out the [examples](https://f-dangel.github.io/backpack/) on how to use the code.
 
 ## Installation
 ```bash
 pip install backpack-for-pytorch
 ```
 
-Alternative: Clone the repository and run `setup.py`
-```bash
-git clone https://github.com/f-dangel/backpack.git ~/backpack
-cd ~/backpack
-python setup.py install
-```
+## Examples
+- [Basic usage](https://docs.backpack.pt/en/use-cases/examples/example_all_in_one.html)
+- [Some use cases](https://docs.backpack.pt/en/use-cases/use_cases/index.html)
+
+#
+## Contributing
+BackPACK is actively being developed. 
+We are appreciating any help.
+If you are considering to contribute, do not hesitate to contact us.
+An overview of the development procedure is provided in the [developer `README`](https://github.com/f-dangel/backpack/blob/master/README-dev.md).
 
 ## How to cite
-If you are using `backpack` for your research, consider citing the [paper](https://openreview.net/forum?id=BJlrF24twB) 
+If you are using BackPACK, consider citing the [paper](https://openreview.net/forum?id=BJlrF24twB) 
 ```
 @inproceedings{dangel2020backpack,
     title     = {Back{PACK}: Packing more into Backprop},
@@ -33,3 +45,6 @@ If you are using `backpack` for your research, consider citing the [paper](https
     url       = {https://openreview.net/forum?id=BJlrF24twB}
 }
 ```
+
+###### _BackPACK is not endorsed by or affiliated with Facebook, Inc. PyTorch, the PyTorch logo and any related marks are trademarks of Facebook, Inc._
+

backpack/__init__.py

@@ -1,21 +1,22 @@
-"""
-BackPACK
-"""
+"""BackPACK."""
+import inspect
+
 import torch
+from backpack.extensions.backprop_extension import BackpropExtension
 
 from . import extensions
 from .context import CTX
 
 
 class backpack:
-    """
+    """Activates Backpack Extensions.
+
     Activates the BackPACK extensions passed as arguments for the
     :code:`backward` calls in the current :code:`with` block.
     """
 
-    def __init__(self, *args, debug=False):
-        """
-        Activate the Backpack extensions.
+    def __init__(self, *exts: BackpropExtension, debug=False):
+        """Activate the Backpack extensions.
 
         Example usage:
         ```
@@ -38,19 +39,33 @@ def __init__(self, *args, debug=False):
             exiting the `with` clause. Use them within the `with` clause or
             assign them to another variable.
 
-        Parameters:
+        Attributes:
             args: [BackpropExtension]
                 The extensions to activate for the backward pass.
             debug: Bool, optional (default: False)
                 If true, will print debug messages during the backward pass.
         """
-        self.args = args
+        for ext in exts:
+            if not isinstance(ext, BackpropExtension):
+                if inspect.isclass(ext) and issubclass(ext, BackpropExtension):
+                    raise ValueError(
+                        "backpack expect instances of BackpropExtension,"
+                        + " but received a class instead [{}].".format(ext)
+                        + " Instantiate it before passing it to backpack."
+                    )
+                else:
+                    raise ValueError(
+                        "backpack expects instances of BackpropExtension,"
+                        + " but received [{}].".format(ext)
+                    )
+
+        self.exts = exts
         self.debug = debug
 
     def __enter__(self):
         self.old_CTX = CTX.get_active_exts()
         self.old_debug = CTX.get_debug()
-        CTX.set_active_exts(self.args)
+        CTX.set_active_exts(self.exts)
         CTX.set_debug(self.debug)
 
     def __exit__(self, type, value, traceback):
@@ -59,13 +74,26 @@ def __exit__(self, type, value, traceback):
 
 
 def hook_store_io(module, input, output):
+    """Saves the input and output as attributes of the module.
+
+    Args:
+        module: module
+        input: List of input tensors
+        output: output tensor
+    """
     for i in range(len(input)):
         setattr(module, "input{}".format(i), input[i])
     module.output = output
 
 
 def hook_store_shapes(module, input, output):
-    """Store dimensionality of output as buffer."""
+    """Store dimensionality of output as buffer.
+
+    Args:
+        module: module
+        input: List of input tensors shapes
+        output: output tensor shape
+    """
     for i in range(len(input)):
         module.register_buffer(
             "input{}_shape".format(i), torch.IntTensor([*input[i].size()])
@@ -74,6 +102,10 @@ def hook_store_shapes(module, input, output):
 
 
 def memory_cleanup(module):
+    """Remove I/O stored by backpack during the forward pass.
+
+    Deletes the attributes created by `hook_store_io` and `hook_store_shapes`.
+    """
     if hasattr(module, "output"):
         delattr(module, "output")
     if hasattr(module, "output_shape"):
@@ -98,16 +130,17 @@ def hook_run_extensions(module, g_inp, g_out):
         memory_cleanup(module)
 
 
-def extend(module, debug=False):
-    """
-    Extends the `module` to make it backPACK-ready.
-
-    Attributes
-    ----------
-    module: torch.nn.Module
-        The module to extend
-    debug: Bool, optional (default: False)
-        If true, will print debug messages during the extension.
+def extend(module: torch.nn.Module, debug=False):
+    """Extends the ``module`` to make it backPACK-ready.
+
+    If the ``module`` has children, e.g. for a ``torch.nn.Sequential``,
+    they will also be extended.
+
+    Args:
+        module: torch.nn.Module
+            The module to extend
+        debug: Bool, optional (default: False)
+            If true, will print debug messages during the extension.
     """
     if debug:
         print("[DEBUG] Extending", module)