Merge pull request #162 from asogaard/installation

Installation and contributing guides

.github/actions/install-torch-cpu/action.yml

@@ -4,7 +4,7 @@ inputs:
   torch-verison:
     description: 'Version of pytorch to install'
     required: true
-    default: '1.9.1'
+    default: '1.9.0'
   pyg-verison:
     description: 'Version of pytorch-geometric to install'
     required: true

.github/workflows/build.yml

@@ -5,10 +5,10 @@ name: build
 on:
   # Triggers the workflow on push and PRs
   push:
-    paths-ignore: [ misc/badges/ ]
+    paths-ignore: [ assets/badges/ ]
   pull_request:
     branches: [ main ]
-    paths-ignore: [ misc/badges/ ]
+    paths-ignore: [ assets/badges/ ]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -39,16 +39,16 @@ jobs:
       - name: Generate unit test/build and coverage badges
         run: |
           tail -1 results_coverage.txt | sed 's/.* \(.*\)%/\1/g' | xargs -I {} anybadge -f coverage.svg -v {} coverage
-          mkdir -p misc/badges/
-          mv coverage.svg misc/badges/
+          mkdir -p assets/badges/
+          mv coverage.svg assets/badges/
       - name: Configure git
         run: |
           git config user.email "[email protected]"
           git config user.name "Andreas Søgaard"
           git status
       - name: Stage badges
         run: |
-          git add -f misc/badges/
+          git add -f assets/badges/
       - name: Commit and push changes
         if: ${{ github.event_name == 'pull_request' }}
         run: |

.github/workflows/docs.yml

@@ -6,7 +6,7 @@ on:
   # Triggers the workflow on push to the main branch
   push:
     branches: [ main ]
-    paths-ignore: [ misc/badges/ ]
+    paths-ignore: [ assets/badges/ ]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:

.github/workflows/lint.yml

@@ -5,10 +5,10 @@ name: lint
 on:
   # Triggers the workflow on push and PRs
   push:
-    paths-ignore: [ misc/badges/ ]
+    paths-ignore: [ assets/badges/ ]
   pull_request:
     branches: [ main ]
-    paths-ignore: [ misc/badges/ ]
+    paths-ignore: [ assets/badges/ ]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
@@ -34,16 +34,16 @@ jobs:
       - name: Generate badge
         run: |
           grep rated < results_pylint.txt | sed 's/.* at //g;s/\/.*//g' | xargs -I {} anybadge -f pylint.svg -v {} pylint
-          mkdir -p misc/badges/
-          mv pylint.svg misc/badges/
+          mkdir -p assets/badges/
+          mv pylint.svg assets/badges/
       - name: Configure git
         run: |
           git config user.email "[email protected]"
           git config user.name "Andreas Søgaard"
           git status
       - name: Stage badges
         run: |
-          git add -f misc/badges/
+          git add -f assets/badges/
       - name: Commit and push changes
         if: ${{ github.event_name == 'pull_request' }}
         run: |

.gitignore

@@ -133,7 +133,7 @@ docs/build/html
 docs/**/*.rst
 
 # Badges
-misc/badges
+assets/badges
 lightning_logs/
 wandb/
 **.png

CONTRIBUTING.md

@@ -0,0 +1,35 @@
+# Contributing
+
+To make sure that the process of contributing is as smooth and effective as possible, we provide a few guidelines in this contributing guide that we encourage contributors to follow.
+
+## GitHub issues
+
+Use [GitHub issues](https://github.com/icecube/graphnet/issues) for tracking and discussing requests and bugs. If there is anything you'd wish to contribute, the best place to start is to create a new issues and describe what you would like to work on. Alternatively you can assign open issues to yourself, to indicate that you would like to take ownership of a particular task. Using issues actively in this way ensures transparency and agreement on priorities. This helps avoid situations with a lot of development effort going into a feature that e.g. turns out to be outside of scope for the project; or a specific solution to a problem that could have been better solved differently.
+
+## Pull requests
+
+Develop code in a forks of the [main repo](https://github.com/icecube/graphnet). Make contributions in dedicated development/feature branches on your forked repositories, e.g. if you are implementing a specific `GraphBuiler` class you could create a branch named `add-euclidean-graph-builder` on your own fork.
+
+Create pull requests from your development branch into `icecube:main` to contribute to the project. **To be accepted,** pull requests must:
+  * pass all automated checks,
+  * be reviewed by at least one other contributor. These reviews should check for:
+    * standard python coding conventions, e.g. [PEP8](https://www.python.org/dev/peps/pep-0008/)
+    * docstring (Google-style) and type hinting as necessary,
+    * unit tests as nencessary,
+    * clean coding practices, see e.g. [here](https://gist.github.com/wojteklu/73c6914cc446146b8b533c0988cf8d29).
+
+
+## Version control best practices
+
+From "Software Best Practices Effective Version Control", Alex Olivas, IceCube Bootcamp 2020:
+* Make the commits small enough that they don't break the code.
+    * What constitutes "broken" code? Doesn't compile. Tests don't pass.
+* **Do not** commit something that covers more than one change: E.g. `git commit -m 'Refactor and critical bugfix'` is **bad.**
+* **Do not** wait until the end of the day or week to commit.
+* **Do not** mix functional changes with whitespace cleanups.
+* **Do** write good commit messages. Examples:
+    * Good commit message: `"Fixes issue #123: Use std::shared_ptr to avoid memory leaks. See C++ Coding Standards for more information."`
+    * Bad commit message: `"blerg"`
+
+Others:
+* Keep backward compatibility in mind when you change code.

README.md

@@ -1,14 +1,36 @@
-# GraphNeT
-
-Graph neural networks for neutrino telescope event reconstruction.
+![logo](./assets/identity/graphnet-logo-and-wordmark.png)
 
 ![build](https://github.com/icecube/graphnet/actions/workflows/build.yml/badge.svg)
-![pylint](./misc/badges/pylint.svg)
-![coverage](./misc/badges/coverage.svg)
+![pylint](./assets/badges/pylint.svg)
+![coverage](./assets/badges/coverage.svg)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
 
 
-### :test_tube: Experiment tracking
+
+## :gear:  Install
+
+We recommend installing `graphnet` in a separate environment, e.g. using Anaconda (see details on installation [here](https://www.anaconda.com/products/individual)). The fastest way to get up and running is to install the package in the provided conda environment:
+```bash
+$ git clone [email protected]:<your-username>/graphnet.git
+$ cd graphnet
+$ conda env create -f envs/gnn_py38.yml
+$ conda activate gnn_py38
+(gnn_py38) $ pip install -e .[develop]
+```
+
+This should allow you to e.g. run the scripts in [examples/](./examples/) out of the box.
+
+You can also install the package in a python virtual environment, or in your system python, but then you will have to contend with C++ compiler versions; the non-standard interplay between [pytorch](https://pytorch.org/) and [pytorch-geometric](https://pytorch-geometric.readthedocs.io/en/latest/) (see e.g. [here](https://github.com/pyg-team/pytorch_geometric/issues/861#issuecomment-566424944)), which `graphnet` uses internally; etc.
+
+
+## :handshake:  Contributing
+
+To make sure that the process of contributing is as smooth and effective as possible, we provide a few guidelines in the [contributing guide](CONTRIBUTING.md) that we encourage contributors to follow.
+
+In short, everyone who wants to contribute to this project is more than welcome to do so! Contributions are handled through pull requests, that should be linked to a [GitHub issue](https://github.com/icecube/graphnet/issues) describing the feature to be added or bug to be fixed. Pull requests will be reviewed by the project maintainers and merged into the main branch when accepted.
+
+
+## :test_tube:  Experiment tracking
 
 We're using [Weights & Biases](https://wandb.ai/) (W&B) to track the results — i.e. losses, metrics, and model artifacts — of training runs as a means to track model experimentation and streamline optimisation. To authenticate with W&B, sign up on the website and run the following in your terminal after having installed this package:
 ```bash