GRAPE: GRAph Parallel Environment

Table of contents

• Description
• Dependencies and installation
  • Installing from pip
  • Installing from source
• Documentation
• Testing
• Authors and contributors
• How to contribute
  • Submitting a patch
• License

Description

GRAPE (GRAph Parallel Environment) is a Python package that takes advantage of Graph Theory into a High Performance Computing (HPC) environment to develope a screening tool aimed at studying the effect of different kinds of perturbations in interconnected systems, such as industrial plants.

The package represents the dependencies between graph elements and predicts the effects of a perturbation. The results obtained from the graph analysis can be therefore used to improve the robustness, and resilience profile of industrial facilities against domino effect propagation.

In particular, the contribution to the cascade effects resulting from adverse events can be evaluated through centrality and efficiency measures, highlighting the plants major criticalities, vulnerabilities and potential weak points.

Considering that the most computationally expensive parts of the program involve the calculation of shortest paths, parallelization of shortest path computation in large unweighted graphs was integrated in the program. This was done taking advantage of the Python modules multiprocessing and threading. Two different sequential algorithms for the solution of the shortest path problem have been parallelized including a Single Source Shortest Path (SSSP) algorithm for sparse graphs and an All Pairs Shortest Path one (APSP) for dense graphs.

We acknowledge Aurora Maurizio for her substantial contributions to this package, including the conception of the algorithm and the implementation of the original code.

Dependencies and installation

GRAPE requires numpy, scipy, matplotlib, networkx, deap, pandas, pytest (for local test) and sphinx (to generate the documentation). The code is compatible with Python 3.6, NetworkX 2.5, Pandas 1.1 and DEAP 1.3.

Installing from pip

To install the latest release of the package, which corresponds to the online documentation, just type:

> pip install grape-mathlab

Installing from source

The official distribution is on GitHub, and you can clone the repository using

> git clone https://github.com/mathLab/GRAPE

To install the package just type:

> pip install -e .

To uninstall the package you have to rerun the installation and record the installed files in order to remove them:

> pip uninstall grape-mathlab

Documentation

GRAPE uses Sphinx for code documentation. To build the html versions of the docs simply:

> cd docs
> make html

The generated html can be found in docs/build/html. Open up the index.html you find there to browse.

Testing

We are using Travis CI for continuous intergration testing. You can check out the current status here.

To run tests locally:

> pytest

Authors and contributors

GRAPE is currently developed and mantained at SISSA mathLab by

• Aurora Maurizio
• Teruzzi Martina
• Nicola Demo

under the supervision of Prof. Gianluigi Rozza.

Contact us by email for further information or questions about GRAPE, or suggest pull requests. GRAPE is at an early development stage, so contributions improving either the code or the documentation are welcome!

How to contribute

We'd love to accept your patches and contributions to this project. There are just a few small guidelines you need to follow.

Submitting a patch

1. It's generally best to start by opening a new issue describing the bug or feature you're intending to fix. Even if you think it's relatively minor, it's helpful to know what people are working on. Mention in the initial issue that you are planning to work on that bug or feature so that it can be assigned to you.

2. Follow the normal process of forking the project, and setup a new branch to work in. It's important that each group of changes be done in separate branches in order to ensure that a pull request only includes the commits related to that bug or feature.

3. To ensure properly formatted code, please make sure to use 4 spaces to indent the code. The easy way is to run on your bash the provided script: ./code_formatter.sh. You should also run pylint over your code. It's not strictly necessary that your code be completely "lint-free", but this will help you find common style issues.

4. Any significant changes should almost always be accompanied by tests. The project already has good test coverage, so look at some of the existing tests if you're unsure how to go about it. We're using coveralls that is an invaluable tools for seeing which parts of your code aren't being exercised by your tests.

5. Do your best to have well-formed commit messages for each change. This provides consistency throughout the project, and ensures that commit messages are able to be formatted properly by various git tools.

6. Finally, push the commits to your fork and submit a pull request. Please, remember to rebase properly in order to maintain a clean, linear git history.

License

See the LICENSE file for license rights and limitations (MIT).