Adding contribution guide and enable copyright checks as a pre-commit…

… hook (#91)

* Adding contribution guide

* adding pre-commit checks on copyright

* and a badge of course

* adding copyrights

* updating text

* Apply suggestions from code review

Co-authored-by: Andrew Fitzgibbon <[email protected]>

* don't blame the os for the python version

---------

Co-authored-by: Andrew Fitzgibbon <[email protected]>

.flake8

@@ -0,0 +1,4 @@
+[flake8]
+
+copyright-check = True
+copyright-author = Graphcore Ltd

.github/workflows/pre-commit.yaml

@@ -0,0 +1,14 @@
+name: Pre-Commit Checks
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: actions/setup-python@v3
+    - uses: pre-commit/[email protected]

.pre-commit-config.yaml

@@ -0,0 +1,7 @@
+repos:
+  - repo: https://github.com/PyCQA/flake8
+    rev: 6.0.0
+    hooks:
+      - id: flake8
+        args: [--select=C]
+        additional_dependencies: [flake8-copyright]

CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing to pyscf-ipu
+
+This project is still evolving but at the moment is focused around a high-performance and easily hackable implementation of Gaussian basis set DFT.
+We hope this is useful for the generation of large-scale datasets needed
+for training machine-learning models. We are interested in hearing any and
+all feedback so feel free to raise any questions, bugs encountered, or enhancement requests as [Issues](https://github.com/graphcore-research/pyscf-ipu/issues).
+
+## Setting up a development environment
+We recommend using the conda package manager as this can automatically enable
+the Graphcore Poplar SDK.  This is particularly useful in VS Code which can automatically
+activate the conda environment in a variety of scenarios:
+* visual debugging
+* running quick experiments in an interactive Jupyter window
+* using VS code for Jupyter notebook development.
+
+The following assumes that you have already set up an install of conda and that
+the conda command is available on your system path.  Refer to your preferred conda
+installer:
+* [miniforge installation](https://github.com/conda-forge/miniforge#install)
+* [conda installation documentation](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html).
+
+1. Create a new conda environment with the same python version as required by the Poplar SDK.
+   For example, on ubuntu 20 use `python=3.8.10`
+   ```bash
+   conda create -n pyscf-ipu python=3.8.10
+   ```
+
+2. Confirm that you have the Poplar SDK installed on your machine and store the location
+   in a temporary shell variable.  The following will test that the SDK is found and
+   configured correctly:
+   ```bash
+   TMP_POPLAR_SDK=/path/to/sdk
+   source $TMP_POPLAR_SDK/enable
+   gc-monitor
+
+3. Activate the environment and make POPLAR_SDK a persistent environment variable.
+   ```bash
+   conda activate pyscf-ipu
+   conda env config vars set POPLAR_SDK=$TMP_POPLAR_SDK
+   ```
+
+4. You have to reactivate the conda environment to use the `$POPLAR_SDK`
+   variable in the environment.
+   ```bash
+   conda deactivate
+   conda activate pyscf-ipu
+   ```
+
+5. Setup the conda environment to automatically enable the Poplar SDK whenever
+   the environment is activated.
+   ```bash
+   mkdir -p $CONDA_PREFIX/etc/conda/activate.d
+   echo "source $POPLAR_SDK/enable" > $CONDA_PREFIX/etc/conda/activate.d/enable.sh
+   ```
+
+6. Check that everything is working by once reactivating the pyscf-ipu
+   environment _in a new shell_ and calling `gc-monitor`:
+   ```bash
+   conda deactivate
+   conda activate pyscf-ipu
+   gc-monitor
+
+7. Install all required packages for developing JAX DFT:
+   ```bash
+   pip install -e ".[ipu,test]"
+   ```
+
+8. Install the pre-commit hooks
+   ```bash
+   pre-commit install
+   ```
+
+9. Create a feature branch, make changes, and when you commit them the
+   pre-commit hooks will run.
+   ```bash
+   git checkout -b feature
+   ...
+   git push --set-upstream origin feature
+   ```
+   The last command will prints a link that you can follow to open a PR.
+
+
+## Testing
+Run all the tests using `pytest`
+```bash
+pytest
+```
+We also use the nbmake package to check our notebooks work in the `IpuModel` environment.  These checks can also be run on IPU hardware equiped machines e.g.:
+```bash
+pytest --nbmake --nbmake-timeout=3000 notebooks/nanoDFT-demo.ipynb
+```

README.md

@@ -3,6 +3,7 @@
 [![notebook-tests](https://github.com/graphcore-research/pyscf-ipu/actions/workflows/notebooks.yaml/badge.svg)](https://github.com/graphcore-research/pyscf-ipu/actions/workflows/notebooks.yaml)
 [![nanoDFT CLI](https://github.com/graphcore-research/pyscf-ipu/actions/workflows/cli.yaml/badge.svg)](https://github.com/graphcore-research/pyscf-ipu/actions/workflows/cli.yaml)
 [![unit tests](https://github.com/graphcore-research/pyscf-ipu/actions/workflows/unittest.yaml/badge.svg)](https://github.com/graphcore-research/pyscf-ipu/actions/workflows/unittest.yaml)
+[![pre-commit checks](https://github.com/graphcore-research/pyscf-ipu/actions/workflows/pre-commit.yaml/badge.svg)](https://github.com/graphcore-research/pyscf-ipu/actions/workflows/pre-commit.yaml)
 
 [**Installation guide**](#installation)
 | [**Example DFT Computations**](#example-dft-computations)

notebooks/plot_utils.py

@@ -1,3 +1,4 @@
+# Copyright (c) 2023 Graphcore Ltd. All rights reserved.
 import numpy as np
 import matplotlib as mpl
 import matplotlib.pyplot as plt

pyscf_ipu/electron_repulsion/__init__.py

@@ -0,0 +1 @@
+# Copyright (c) 2023 Graphcore Ltd. All rights reserved.

pyscf_ipu/exchange_correlation/__init__.py

@@ -0,0 +1 @@
+# Copyright (c) 2023 Graphcore Ltd. All rights reserved.

pyscf_ipu/exchange_correlation/b88.py

@@ -1,3 +1,4 @@
+# Copyright (c) 2023 Graphcore Ltd. All rights reserved.
 # The functional definition in this file was ported to Python
 # from XCFun, which is Copyright Ulf Ekström and contributors 2009-2020
 # and provided under the Mozilla Public License (v2.0)

pyscf_ipu/exchange_correlation/lyp.py

@@ -1,3 +1,4 @@
+# Copyright (c) 2023 Graphcore Ltd. All rights reserved.
 # The functional definition in this file was ported to Python
 # from XCFun, which is Copyright Ulf Ekström and contributors 2009-2020
 # and provided under the Mozilla Public License (v2.0)

pyscf_ipu/exchange_correlation/vwn.py

@@ -1,3 +1,4 @@
+# Copyright (c) 2023 Graphcore Ltd. All rights reserved.
 # The functional definition in this file was ported to Python
 # from XCFun, which is Copyright Ulf Ekström and contributors 2009-2020
 # and provided under the Mozilla Public License (v2.0)

pyscf_ipu/nanoDFT/__init__.py

@@ -1 +1,2 @@
+# Copyright (c) 2023 Graphcore Ltd. All rights reserved.
 from .nanoDFT import *

pyscf_ipu/nanoDFT/sparse_ERI.py

@@ -1,3 +1,4 @@
+# Copyright (c) 2023 Graphcore Ltd. All rights reserved.
 import numpy as np 
 import jax.numpy as jnp
 import os 

pyscf_ipu/nanoDFT/symmetric_ERI.py

@@ -1,3 +1,4 @@
+# Copyright (c) 2023 Graphcore Ltd. All rights reserved.
 import numpy as np 
 import jax.numpy as jnp
 import os 

requirements_test.txt

@@ -6,3 +6,6 @@
 #    requirements_ipu.txt for ipu backend configuration
 pytest
 nbmake
+pre-commit
+flake8
+flake8-copyright