• Stars
    star
    544
  • Rank 81,699 (Top 2 %)
  • Language
    Python
  • License
    Other
  • Created about 6 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Python package for hypergraph analysis and visualization.

HyperNetX

Pytest Code style: black linting: pylint

The HyperNetX library provides classes and methods for the analysis and visualization of complex network data modeled as hypergraphs. The library generalizes traditional graph metrics.

HypernetX was developed by the Pacific Northwest National Laboratory for the Hypernets project as part of its High Performance Data Analytics (HPDA) program. PNNL is operated by Battelle Memorial Institute under Contract DE-ACO5-76RL01830.

  • Principal Developer and Designer: Brenda Praggastis
  • Development Team: Madelyn Shapiro, Mark Bonicillo
  • Visualization: Dustin Arendt, Ji Young Yun
  • Principal Investigator: Cliff Joslyn
  • Program Manager: Brian Kritzstein
  • Principal Contributors (Design, Theory, Code): Sinan Aksoy, Dustin Arendt, Mark Bonicillo, Helen Jenne, Cliff Joslyn, Nicholas Landry, Audun Myers, Christopher Potvin, Brenda Praggastis, Emilie Purvine, Greg Roek, Madelyn Shapiro, Mirah Shi, Francois Theberge, Ji Young Yun

The code in this repository is intended to support researchers modeling data as hypergraphs. We have a growing community of users and contributors. Documentation is available at: https://pnnl.github.io/HyperNetX

For questions and comments contact the developers directly at: [email protected]

New Features in Version 2.0

HNX 2.0 now accepts metadata as core attributes of the edges and nodes of a hypergraph. While the library continues to accept lists, dictionaries and dataframes as basic inputs for hypergraph constructions, both cell properties and edge and node properties can now be easily added for retrieval as object attributes.

The core library has been rebuilt to take advantage of the flexibility and speed of Pandas Dataframes. Dataframes offer the ability to store and easily access hypergraph metadata. Metadata can be used for filtering objects, and characterize their distributions by their attributes.

Version 2.0 is not backwards compatible. Objects constructed using version 1.x can be imported from their incidence dictionaries.

What's New

  1. The Hypergraph constructor now accepts nested dictionaries with incidence cell properties, pandas.DataFrames, and 2-column Numpy arrays.
  2. Additional constructors accept incidence matrices and incidence dataframes.
  3. Hypergraph constructors accept cell, edge, and node metadata.
  4. Metadata available as attributes on the cells, edges, and nodes.
  5. User-defined cell weights and default weights available to incidence matrix.
  6. Meta data persists with restrictions and removals.
  7. Meta data persists onto s-linegraphs as node attributes of Networkx graphs.
  8. New hnxwidget available using pip install hnxwidget.

What's Changed

  1. The static and dynamic distinctions no longer exist. All hypergraphs use the same underlying data structure, supported by Pandas dataFrames. All hypergraphs maintain a state_dict to avoid repeating computations.
  2. Methods for adding nodes and hyperedges are currently not supported.
  3. The nwhy optimizations are no longer supported.
  4. Entity and EntitySet classes are being moved to the background. The Hypergraph constructor does not accept either.

Tutorials may be run in your browser using Google Colab

Additional Tutorials may be found on in the Tutorials Folder.

Open In Colab Tutorial 1 - HNX Basics
Open In Colab Tutorial 2 - Visualization Methods
Open In Colab Tutorial 3 - LesMis Case Study
Open In Colab Tutorial 4 - LesMis Visualizations-Book Tour
Open In Colab Tutorial 5 - s-Centrality
Open In Colab Tutorial 6 - Homology mod2 for TriLoop Example

Installation

The recommended installation method for most users is to create a virtual environment and install HyperNetX from PyPi.

HyperNetX may be cloned or forked from Github.

Prerequisites

HyperNetX officially supports Python 3.8, 3.9, 3.10 and 3.11.

Create a virtual environment

Using venv

python -m venv venv-hnx
source venv-hnx/bin/activate

Using Anaconda

conda create -n venv-hnx python=3.11 -y
conda activate venv-hnx

Using virtualenv

virtualenv env-hnx
source env-hnx/bin/activate

For Windows Users

On both Windows PowerShell or Command Prompt, you can use the following command to activate your virtual environment:

.\env-hnx\Scripts\activate

To deactivate your environment, use:

.\env-hnx\Scripts\deactivate

Installing HyperNetX

Regardless of how you install HyperNetX, ensure that your environment is activated and that you are running Python >=3.8.

Installing from PyPi

pip install hypernetx

Installing from Source

Ensure that you have git installed.

git clone https://github.com/pnnl/HyperNetX.git
cd HyperNetX
pip install .

Post-Installation Actions

Running Tests

python -m pytest

Development

Install an editable version

pip install -e .

Install an editable version with access to jupyter notebooks

pip install -e .'[all]'

Install support for testing

ℹ️ NOTE: This project has a pytest configuration file named 'pytest.ini'. By default, pytest will use those configuration settings to run tests.

pip install .'[testing]'

# run tests
python -m pytest

# run tests and show coverage report
python -m pytest --cov=hypernetx

# Generate an HTML code coverage report and view it on a browser
coverage html
open htmlcov/index.html

Install support for tutorials

pip install .'[tutorials]'

Install support for documentation

pip install .'[documentation]'
cd docs

## This will generate the documentation in /docs/build/
## Open them in your browser with docs/build/html/index.html
make html

Code Quality

HyperNetX uses a number of tools to maintain code quality:

  • Pylint
  • Black

Before using these tools, ensure that you install Pylint in your environment:

pip install .'[linting]'

Pylint

Pylint is a static code analyzer for Python-based projects. From the Pylint docs:

Pylint analyses your code without actually running it. It checks for errors, enforces a coding standard, looks for code smells, and can make suggestions about how the code could be refactored. Pylint can infer actual values from your code using its internal code representation (astroid). If your code is import logging as argparse, Pylint will know that argparse.error(...) is in fact a logging call and not an argparse call.

We have a Pylint configuration file, .pylintrc, located at the root of this project. To run Pylint and view the results of Pylint, run the following command:

pylint hypernetx --rcfile=.pylintrc

You can also run Pylint on the command line to generate a report on the quality of the codebase and save it to a file named "pylint-results.txt":

pylint hypernetx --output=pylint-results.txt

For more information on configuration, see https://pylint.pycqa.org/en/latest/user_guide/configuration/index.html

Black

Black is a PEP 8 compliant formatter for Python-based project. This tool is highly opinionated about how Python should be formatted and will automagically reformat your code.

black hypernetx

Documentation

Build and view documentation locally

cd docs
make html
open docs/build/html/index.html

Editing documentation

NOTE: make sure you install the required dependencies using: make docs-deps

When editing documentation, you can auto-rebuild the documentation locally so that you can view your document changes live on the browser without having to rebuild every time you have a change.

cd docs
make livehtml

This make script will run in the foreground on your terminal. You should see the following:

The HTML pages are in docs/html.
[I 230324 09:50:48 server:335] Serving on http://127.0.0.1:8000
[I 230324 09:50:48 handlers:62] Start watching changes
[I 230324 09:50:48 handlers:64] Start detecting changes
[I 230324 09:50:54 handlers:135] Browser Connected: http://127.0.0.1:8000/install.html
[I 230324 09:51:02 handlers:135] Browser Connected: http://127.0.0.1:8000/

Click on http://127.0.0.1:8000/install.html to open the docs on your browser. Since this will auto-rebuild, every time you change a document file, it will automatically render on your browser, allowing you to verify your document changes.

Continuous Integration

This project runs Continuous Integration (CI) using GitHub Actions. Normally, CI runs on pull requests, pushes to certain branches, and other events.

Maintainers of the GitHub repository can manually trigger CI using GitHub CLI. See instructions below on how to manually trigger CI on GitHub Actions:

# login to Github
gh auth login --with-token <  ~/.ssh/tokens/<path to my personal access token>

# Trigger CI
gh workflow run ci.yml --repo pnnl/HyperNetX --ref <name of branch that you want CI to run on> --field triggeredBy="<Your name>"

# Get the status of the workflow
gh run list --workflow=ci.yml --repo pnnl/HyperNetX

Versioning

This project uses commitizen to manage versioning. The files where "version" will be updated are listed in the '.cz.toml' file. To create a new version and the associated tag, run the following commands:

# Install commitizen tool to environment
make releases

# Updates version; values for '--increment' can be MAJOR, MINOR, or PATCH
# Autocreates a tag and commit for the updated version
cz bump  --increment MAJOR  --dry-run
cz bump  --increment MAJOR

Notice

This material was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor the United States Department of Energy, nor Battelle, nor any of their employees, nor any jurisdiction or organization that has cooperated in the development of these materials, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness or any information, apparatus, product, software, or process disclosed, or represents that its use would not infringe privately owned rights. Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or any agency thereof, or Battelle Memorial Institute. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or any agency thereof.

   PACIFIC NORTHWEST NATIONAL LABORATORY
   operated by
   BATTELLE
   for the
   UNITED STATES DEPARTMENT OF ENERGY
   under Contract DE-AC05-76RL01830
   

License

Released under the 3-Clause BSD license (see License.rst)

More Repositories

1

neuromancer

Pytorch-based framework for solving parametric constrained optimization problems, physics-informed system identification, and parametric model predictive control.
Python
904
star
2

safekit

Python
140
star
3

SHAD

Scalable High-performance Algorithms and Data-structures
C++
122
star
4

OpenCGRA

OpenCGRA is an open-source framework for modeling, testing, and evaluating CGRAs.
Verilog
97
star
5

NWGraph

Complete Project Documentation
C++
93
star
6

cmaputil

Python
80
star
7

QASMBench

A low-level OpenQASM benchmark suite for NISQ evaluation and simulation. Please see our paper for details.
OpenQASM
79
star
8

ExaGO

High-performance power grid optimization for stochastic, security-constrained, and multi-period ACOPF problems.
C++
64
star
9

isicle

In silico chemical library engine for high-accuracy chemical property prediction
Python
58
star
10

DM-Sim

DM-Sim: Quantum Simulator on GPU Cluster using Density Matrix
OpenQASM
51
star
11

deps_arXiv2020

Differentiable predictive control (DPC) policy optimization examples.
MATLAB
47
star
12

lamellar-runtime

Lamellar is an asynchronous tasking runtime for HPC systems developed in RUST
Rust
42
star
13

DHSVM-PNNL

C
39
star
14

tesp

Python
39
star
15

COMET

C++
34
star
16

soda-opt

C++
32
star
17

deimos

Python
31
star
18

ripples

A C++ Library for Influence Maximization
C++
31
star
19

darkchem

Python
31
star
20

TCBNN

Cuda
31
star
21

chemreasoner

ChemReasoner - Catalyst Discovery via Large Language Model-driven Reasoning
Python
31
star
22

chgl

Chapel HyperGraph Library (CHGL) - HPC-class Hypergraphs in Chapel
Chapel
29
star
23

SLiCE

Subgraph Based Learning of Contextual Embedding
Python
28
star
24

gmt

Global Memory and Threading runtime system
C
23
star
25

chissl

Interactive machine learning interface
Jupyter Notebook
22
star
26

s-blas

This package includes the implementation for four sparse linear algebra kernels: Sparse-Matrix-Vector-Multiplication (SpMV), Sparse-Triangular-Solve (SpTRSV), Sparse-Matrix-Transposition (SpTrans) and Sparse-Matrix-Matrix-Multiplication (SpMM) for Single-node Multi-GPU (scale-up) platforms such as NVIDIA DGX-1 and DGX-2.
C++
22
star
27

MSAC

Jupyter Notebook
21
star
28

socialsim

Python
20
star
29

qasmtrans

A C++ based quantum transpiler for NISQ devices
OpenQASM
20
star
30

cactus

LLM Agent that leverages cheminformatics tools to provide informed responses.
Jupyter Notebook
20
star
31

torchntk

Jupyter Notebook
19
star
32

buildingid

Unique Building Identifier (UBID)
18
star
33

mol_dgnn

Molecular Dynamic Graph Neural Network
Python
18
star
34

DeepDataProfiler

Python library for analyzing the internal structure of deep neural networks.
Jupyter Notebook
18
star
35

mercat

MerCat: python code for versatile k-mer counting and diversity estimation for database independent property analysis for meta -ome data
Python
18
star
36

leapR

R
17
star
37

E4D

Standard ML
17
star
38

socialsim_package

Jupyter Notebook
17
star
39

DDKS

A high-dimensional Kolmogorov-Smirnov distance for comparing high dimensional distributions
Jupyter Notebook
16
star
40

GridSTAGE

MATLAB
16
star
41

slim

Drop-in replacements for PyTorch nn.Linear for stable learning and inductive priors in physics informed machine learning applications.
Cuda
16
star
42

pychip_gui

pyCHIP is a tool for segmentation and feature classification in transmission electron microscopy (TEM) images based on a small support set of user-provided examples.
HTML
16
star
43

NWQ-Sim

OpenQASM
15
star
44

sven

JavaScript
15
star
45

arena

The programming runtime and interfaces for ARENA.
C++
14
star
46

fqc

📈 Extensible quality control dashboard built around FASTQ assessment.
JavaScript
14
star
47

buildingid-py

Unique Building Identifier (UBID)
Python
14
star
48

hundo

💯 Snakemake-based amplicon processing protocol for 16S and ITS sequences.
HTML
14
star
49

memgaze

C
12
star
50

SV-Sim

SV-Sim: Scalable PGAS-based State Vector Simulation of Quantum Circuits
OpenQASM
11
star
51

Neural-Modules-for-Differential-Algebraic-Equations

Jupyter Notebook
11
star
52

rofi

C
10
star
53

hexwatershed

Flow routing using a hexagonal grid.
C++
10
star
54

HiParTI

C
10
star
55

solubility-prediction-paper

Jupyter Notebook
10
star
56

blueprint-styler

Make custom blueprint.css styles
TypeScript
10
star
57

copper

Performance curve generator for building energy simulation
Python
9
star
58

hypernetx-widget

JavaScript
9
star
59

building-energy-standards-data

Database of building energy standards data for building energy simulation.
Python
8
star
60

eqc

Python
8
star
61

ANIMATE

Jupyter Notebook
8
star
62

i2x

Interconnection Innovation e-Xchange (i2x) Test Systems
Python
8
star
63

esteem

JavaScript
8
star
64

psl

Jupyter Notebook
8
star
65

GeoCLUSTER

GeoCLUSTER is a Python-based web application that provides a collection of interactive methods for streamlining the visualization of the technical and economic modeling of closed-loop geothermal systems.
Python
8
star
66

mcl

C
7
star
67

grid_prediction

Jupyter Notebook
7
star
68

ruleset-checking-tool

Python
7
star
69

ARTS

Abstract RunTime System
C
7
star
70

ConStrain

ConStrain is a data-driven knowledge-integrated framework that automatically verifies that building system controls function as intended.
Jupyter Notebook
7
star
71

gparm

A tool for developing parametric inputs for other software.
Perl
6
star
72

sds

Jupyter Notebook
6
star
73

DMIPL

Differentiable Mixed-Integer Programming Layers
Jupyter Notebook
6
star
74

brislawn-2018-founders-species

🦠 📓 a microbiome paper
HTML
6
star
75

DPC_for_robotics

Python
6
star
76

AutoMicroED

Python
6
star
77

qFeature

Extract features from time series using moving windows of regression fits
HTML
6
star
78

STOMP-W

Fortran 90 source code, example problems, and output conversion scripts for the STOMP-W simulator.
Fortran
6
star
79

lamellar

Lamellar is an asynchronous tasking runtime for HPC systems developed in RUST
5
star
80

ThermalTracker

C++
5
star
81

Active-Sampling-for-Atomistic-Potentials

Active sampling for neural network potentials: Accelerated simulations of shear-induced deformation in Cu–Ni multilayers
Python
5
star
82

NWPEsSE

Python
5
star
83

NWHypergraph

C++
4
star
84

nwqbench

Python
4
star
85

nmrfit

Quantitative NMR analysis through least-squares fit of spectroscopy data
Python
4
star
86

LOPO

Learning to Optimize with Proximal Operators (LOPO)
Jupyter Notebook
4
star
87

DieselWolf

Open source data set for radio frequency machine learning research
Jupyter Notebook
4
star
88

pytorch_soo

Second Order Optimizers for Machine Learning
HTML
4
star
89

pecblocks

Generalized block diagram modeling of power electronic converters for grid solar and storage applications.
Python
4
star
90

external_sort

Rust
4
star
91

conformer_selection

Jupyter Notebook
4
star
92

neural_ODE_ICLR2020

Python
4
star
93

sppsi_cppf

Simulate microstructure evolution using the coupled CP and PF methods for the SPPSI project.
GLSL
4
star
94

rsed

Stream editing in R: Manipulating text files with insertions, replacements, deletions, substitutions, and commenting
R
4
star
95

ssass-e

SSASSE software is responsible for validating, and verifying innovative safe scanning methodologies, models, architectures, and prototypes to safely assess operational technology (OT) installed in critical energy infrastructure.
Python
4
star
96

oedisi_dopf

OpenEDI - System Integration (OEDI-SI) - PNNL Distributed Optimal Power Flow (DOPF)
Jupyter Notebook
4
star
97

DREAM_V2

The DREAM tool is an optimization software that determines subsurface monitoring configurations which detect carbon dioxide (CO2) leakage in the least amount of time. DREAM reads ensembles of CO2 leakage scenarios and determines optimal monitoring locations and techniques to deploy based on user-identified constraints. These data result in well configurations with the highest potential to detect leakage and minimize aquifer degradation in the shortest amount of time. DREAM was developed as part of the National Risk Assessment Partnership.
Java
4
star
98

pakman

PaKman: A Scalable Algorithm for Generating Genomic Contigs on Distributed Memory Machines
C++
4
star
99

renyiqnets

Python
3
star
100

mass1

Modular Aquatic Simulation System 1D (MASS1)
Fortran
3
star