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.
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: hypernetx@pnnl.gov
HyperNetX 2.3. is the latest, stable release. The core library has been refactored to take better advantage of Pandas Dataframes, improve readability and maintainability, address bugs, and make it easier to change. New features have been added, most notably the ability to add and remove edges, nodes, and incidences.
Version 2.3 is not backwards compatible. Objects constructed using earlier versions can be imported using their incidence dictionaries and/or property datafames.
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.nwhy optimizations are no longer supported.
Basic 1 - HNX Basics
Basic 2 - Visualization Methods
Basic 3 - LesMis Case Study
Basic 4 - LesMis Visualizations-Book Tour
Basic 5 - HNX attributed hypergraph
Basic 6 - Hypergraph Arithmetic.ipynb
Additional tutorials that can be run as Jupyter Notebooks are found under tutorials.
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.
HyperNetX officially supports Python >=3.10,<4.0.0
python -m venv venv-hnx
source venv-hnx/bin/activate
conda create -n venv-hnx python=3.11 -y
conda activate venv-hnx
virtualenv venv-hnx
source venv-hnx/bin/activate
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
Regardless of how you install HyperNetX, ensure that your environment is activated and that you are running Python ">=3.10,<4.0.0".
pip install hypernetx
Ensure that you have git installed.
git clone https://github.com/pnnl/HyperNetX.git
cd HyperNetX
# Create a virtual environment
make venv
source venv-hnx/bin/activate
# install required dependencies
make install
As an alternative to installing HyperNetX, you can use the officially supported HyperNetX Docker image maintained at DockerHub. Use the image to quickly start HyperNetX in a Docker container. The container starts a Jupyter Notebook that has the latest version of HyperNetX and HNXWidget installed; it also contains all the HyperNetX tutorials.
docker run -it --rm -p 8888:8888 -v "${PWD}":/home/jovyan/work hypernetx/hypernetx:latest
docker-compose.yml file with the following:version: '3'
services:
hypernetx:
image: hypernetx/hypernetx:latest
ports:
- "8888:8888"
tty: true
stdin_open: true
volumes:
- "${PWD}:/home/jovyan/work"
Once docker-compose.yml is created, run the container:
docker-compose up
After the container has started, access the HyperNetX Jupyter Notebooks by opening the following URL in a browser:
As a developer, set up your environment using either the standard pip tool or Poetry.
Create a virtual environement. Then install an editable version of HNX and also install additional dependencies to support testing and jupyter notebooks:
python -m venv venv-hnx
source venv-hnx/bin/activate
pip install -e .
pip install -r requirements.txt
As an alternative, you can also install all these requirements in one Make target:
make venv
source venv-hnx/bin/activate
make install
Use the pre-commit framework to automatically point out issues and resolve those issues before code review. It is highly recommended to install pre-commit in your development environment so that issues with your code can be found before you submit a pull request. More importantly, using pre-commit will automatically format your code changes so that they pass the CI build. For example, pre-commit will automatically run the formatter Black on your code changes.
# Once installed, pre-commit will be triggered every time you make a commit in your environment
pre-commit install
This library uses Poetry to manage dependencies and packaging. Poetry can also be used to manage your environment for development.
Configure your Poetry to ensure that the virtual environment gets created in your project directory (this is not necessary but recommended for convenience):
poetry config virtualenvs.in-project true
# check the poetry configuration
poetry config --list
Create and activate a virtual environment.
poetry shell
Install HyperNetX in editable mode, the library's core/required dependencies, and the optional dependencies to support development.
poetry install --with test,lint,docs,release,tutorials
Details about these dependencies are defined in pyproject.toml.
Use the pre-commit framework to automatically point out issues and resolve those issues before code review. It is highly recommended to install pre-commit in your development environment so that issues with your code can be found before you submit a pull request. More importantly, using pre-commit will automatically format your code changes so that they pass the CI build. For example, pre-commit will automatically run the formatter Black on your code changes.
# Once installed, pre-commit will be triggered every time you make a commit in your environment
pre-commit install
ℹ️ NOTE: This project has pytest configuration contained in pyproject.toml. By default, pytest will use those configuration settings to run tests.
poetry install --with test
# activate your virtual environment created by poetry
poetry shell
# 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
poetry install --with tutorials
# activate your virtual environment created by poetry
poetry shell
# open Jupyter notebooks in a browser
make tutorials
HyperNetX uses a number of tools to maintain code quality:
Before using these tools, ensure that you install Pylint in your environment:
poetry install --with lint
# activate your virtual environment created by poetry
poetry shell
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.
To run Pylint and view the results of Pylint, run the following command:
pylint hypernetx
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 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
Build and view documentation locally:
poetry install --with docs
# activate your virtual environment created by poetry
poetry shell
cd docs
make html
open docs/build/html/index.html
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.
If you want to test the Docker image after making any source code changes, follow this workflow:
docker build --platform linux/amd64,linux/arm64 --rm --tag hypernetx/hypernetx:latest .
3. If you're having issues building, see https://docs.docker.com/desktop/containerd/docker run -it --rm -p 8888:8888 -v "${PWD}":/home/jovyan/work hypernetx/hypernetx:latestThis 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
Released under the 3-Clause BSD license
FAQs
HyperNetX is a Python library for the creation and study of hypergraphs.
We found that hypernetx demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.