Pull request #192: Release/2.3.3

Merge in HYP/hypernetx from release/2.3.3 to master

* commit 'c9d9b94ba2b79c8377716ab51d22716a0812dedc':
  bump: version 2.3.2 → 2.3.3
  Update README, documentation
  Add Docker build and publish to GitHub CI
  Fix Dockerfile
  Update Dockerfile
  Allow image in README to show on both PyPi and GitHub
  Add docker support
  Fix readme

.cz.toml

@@ -1,6 +1,6 @@
 [tool.commitizen]
 name = "cz_conventional_commits"
-version = "2.3.2"
+version = "2.3.3"
 version_files = [
     "pyproject.toml",
     "docs/source/conf.py",

.github/workflows/publish-to-dockerhub.yml

@@ -0,0 +1,68 @@
+# This workflow uses actions that are not certified by GitHub.
+# They are provided by a third-party and are governed by
+# separate terms of service, privacy policy, and support
+# documentation.
+
+# GitHub recommends pinning actions to a commit SHA.
+# To get a newer version, you will need to update the SHA.
+# You can also reference a tag or branch, but the action may change without warning.
+
+# This Workflow is based on GitHub's documentation at https://docs.github.com/en/actions/publishing-packages/publishing-docker-images
+name: Publish Docker image
+
+on:
+  release:
+    types: [published]
+
+  workflow_dispatch:
+    inputs:
+      triggeredBy:
+        description: 'Name of team member who is manually triggering this workflow'
+        required: true
+
+jobs:
+
+  push_to_registry:
+    name: Push Docker image to Docker Hub
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+      contents: read
+      attestations: write
+      id-token: write
+    steps:
+      - run: |
+          echo "This workflow was triggered by: $TRIGGER_PERSON"
+        env:
+          TRIGGER_PERSON: ${{ inputs.triggeredBy }}
+          IMAGE_NAME: hypernetx/hypernetx:latest
+
+      - run: echo "🎉 The job was automatically triggered by a ${{ github.event_name }} event."
+      - run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by GitHub!"
+      - run: echo "🔎 The name of your branch is ${{ github.ref }} and your repository is ${{ github.repository }}."
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_USERNAME }}
+          password: ${{ secrets.DOCKER_TOKEN }}
+
+      - name: Build and push Docker image
+        id: push
+        uses: docker/build-push-action@v5
+        with:
+          tags: ${{ env.IMAGE_NAME }}
+          push: true
+
+      - name: Generate artifact attestation
+        uses: actions/attest-build-provenance@v1
+        with:
+          subject-name: hypernetx/hypernetx
+          subject-digest: ${{ steps.push.outputs.digest }}
+          push-to-registry: true

.github/workflows/publish-to-pypi.yml

@@ -36,7 +36,8 @@ jobs:
     - run: echo "🔎 The name of your branch is ${{ github.ref }} and your repository is ${{ github.repository }}."
     - run: echo "Building wheel from branch ${{ github.ref_name }}"
 
-    - uses: actions/checkout@v4
+    - name: Check out the repo
+      uses: actions/checkout@v4
 
     - name: Build and publish distribution 📦 to Test PyPI
       uses: JRubics/[email protected]

Dockerfile

@@ -0,0 +1,30 @@
+# This Dockerfile uses multistage-build to copy only the tutorial notebooks into the image
+# See https://stackoverflow.com/questions/49939960/docker-copy-files-using-glob-pattern
+
+# Stage 1: Copy all tutorial folders into first stage
+FROM quay.io/jupyter/base-notebook:python-3.11 AS builder
+
+WORKDIR /source
+
+COPY tutorials/basic .
+COPY tutorials/advanced .
+COPY tutorials/widget .
+
+# Stage 2: Copy only the Jupyter Notebooks defined in first stage (i.e. builder)
+FROM quay.io/jupyter/base-notebook:python-3.11
+
+# Use Jupyter Notebook as the Frontend (default is Jupyter Lab)
+# See https://jupyter-docker-stacks.readthedocs.io/en/latest/index.html#choosing-jupyter-frontend
+ENV DOCKER_STACKS_JUPYTER_CMD=notebook
+
+# Only copy the Jupyter notebooks
+# notebooks will be copied into '/home/jovyan' in the container
+COPY --from=builder /source/Basic* ./
+COPY --from=builder /source/Advanced* ./
+COPY --from=builder /source/Demo* ./
+
+# Install the latest versions of HyperNetX and HNXWidget from PyPi
+RUN pip install --no-cache-dir hypernetx hnxwidget
+
+# When starting the Jupyter server, do not require a token when accessing URL: http://localhost:8888/tree
+ENTRYPOINT ["start-notebook.py", "--IdentityProvider.token=''"]

README.md

@@ -1,6 +1,7 @@
 HyperNetX
 ==========
-<img src="docs/source/images/harrypotter_basic_hyp.png" align="right" width="300pt">
+
+<img src="https://raw.githubusercontent.com/pnnl/HyperNetX/master/docs/source/images/harrypotter_basic_hyp.png" align="right" width="300pt">
 
 [![Pytest](https://github.com/pnnl/HyperNetX/actions/workflows/ci.yml/badge.svg)](https://github.com/pnnl/HyperNetX/actions/workflows/ci.yml)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
@@ -39,26 +40,22 @@ New features have been added, most notably the ability to add and remove edges,
 can be imported using their incidence dictionaries and/or property datafames.**
 
 What's New
-~~~~~~~~~~~~~~~~~~~~~~~~~
-#. Hypergraph now supports adding and removing edges, nodes, and incidences
-#. Hypergraph also supports the sum, difference, union, and intersection of a Hypergraph to another Hypergraph
-#. New factory methods to support the Hypergraph constructor
-#. EntitySet has been replaced by HypergraphView
-#. IncidenceStore and PropertyStore are new classes that maintain the structure and attributes of a Hypergraph
-#. Hypergraph constructors accept cell, edge, and node metadata.
+----------
+1. Hypergraph now supports adding and removing edges, nodes, and incidences
+1. Hypergraph also supports the sum, difference, union, and intersection of a Hypergraph to another Hypergraph
+1. New factory methods to support the Hypergraph constructor
+1. EntitySet has been replaced by HypergraphView
+1. IncidenceStore and PropertyStore are new classes that maintain the structure and attributes of a Hypergraph
+1. Hypergraph constructors accept cell, edge, and node metadata.
 
 
 What's Changed
-~~~~~~~~~~~~~~~~~~~~~~~~~
-#. HNX now requires Python ^3.10,<=3.12
-#. HNX core libraries have been updated
-#. Updated tutorials
 --------------
+1. HNX now requires Python ">=3.10,<4.0.0"
+1. HNX core libraries have been updated
+1. Updated tutorials
 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.
-1. Methods for adding nodes and hyperedges are currently not supported.
 1. The `nwhy` optimizations are no longer supported.
-1. Entity and EntitySet classes are being moved to the background. The Hypergraph constructor does not accept either.
-
 
 
 Tutorials Available for Colab
@@ -119,7 +116,7 @@ HyperNetX may be cloned or forked from [GitHub](https://github.com/pnnl/HyperNet
 
 Prerequisites
 -------------
-HyperNetX officially supports Python 3.8, 3.9, 3.10 and 3.11.
+HyperNetX officially supports Python >=3.10,<4.0.0
 
 Create a virtual environment
 ----------------------------
@@ -168,7 +165,7 @@ To deactivate your environment, use:
 Installing HyperNetX
 ====================
 
-Regardless of how you install HyperNetX, ensure that your environment is activated and that you are running Python >=3.10.
+Regardless of how you install HyperNetX, ensure that your environment is activated and that you are running Python ">=3.10,<4.0.0".
 
 
 Installing from PyPi
@@ -195,6 +192,49 @@ source venv-hnx/bin/activate
 make install
 ```
 
+# Using HyperNetX on Docker
+
+As an alternative to installing HyperNetX, you can use the officially supported HyperNetX Docker image maintained at
+[DockerHub](https://hub.docker.com/r/hypernetx/hypernetx). 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.
+
+## Run the Container
+
+* Using Docker CLI, run the container in the foreground:
+
+```
+docker run -it --rm -p 8888:8888 -v "${PWD}":/home/jovyan/work hypernetx/hypernetx:latest
+```
+
+* Alternatively, you can create a `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
+```
+
+## Open Jupyter Notebook
+
+After the container has started, access the HyperNetX Jupyter Notebooks by opening the following URL in a browser:
+
+[http://localhost:8888/tree](http://localhost:8888/tree)
+
+
 Development
 ===========
 
@@ -245,9 +285,6 @@ Create and activate a virtual environment.
 poetry shell
 ```
 
-NOTE: If you plan to use Poetry to manage your virtual environment, you can activate the virtual environment
-using poerty: `poetry shell`. Another option is to directly
-
 Install required dependencies and HyperNetX in editable mode.
 ```
 poetry install
@@ -256,7 +293,7 @@ poetry install
 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.
+> ℹ️ **NOTE:** This project has pytest configuration contained in pyproject.toml. By default, pytest will use those configuration settings to run tests.
 
 ```shell
 poetry install --with test
@@ -299,6 +336,7 @@ Before using these tools, ensure that you install Pylint in your environment:
 
 ```shell
 poetry install --with lint
+
 # activate your virtual environment created by poetry
 poetry shell
 ```
@@ -342,9 +380,8 @@ pull request. More importantly, using pre-commit will automatically format your
 automatically run the formatter Black on your code changes.
 
 ```shell
-pre-commit install
-
 # Once installed, pre-commit will be triggered every time you make a commit in your environment
+pre-commit install
 ```
 
 Documentation
@@ -354,6 +391,7 @@ Build and view documentation locally:
 
 ```shell
 poetry install --with docs
+
 # activate your virtual environment created by poetry
 poetry shell
 
@@ -381,28 +419,40 @@ The HTML pages are in docs/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
+Click on [http://127.0.0.1:8000/install.html](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.
 
+Testing the Docker Image
+------------------------
+
+If you want to test the Docker image after making any source code changes, follow this workflow:
+
+1. Make a change in the HNX codebase
+2. Build image: `docker build --rm --tag hypernetx/hypernetx:latest`
+3. Test image: `docker run -it --rm -p 8888:8888 -v "${PWD}":/home/jovyan/work hypernetx/hypernetx:latest`
+4. Open a browser to [http://localhost:8888/tree](http://localhost:8888/tree). Check that tutorials still work and/or open a notebook and test the changes that you made.
+5. Once finished testing, kill the container using Ctrl-C
+
 
 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.
 
-   <div>
-   <pre style="align-text:center;font-size:10pt">
-   PACIFIC NORTHWEST NATIONAL LABORATORY
-   operated by
-   BATTELLE
-   for the
-   UNITED STATES DEPARTMENT OF ENERGY
-   under Contract DE-AC05-76RL01830
-   </pre>
-   </div>
+<div>
+  <pre style="text-align: center; font-size: 10pt;">
+    PACIFIC NORTHWEST NATIONAL LABORATORY
+    operated by
+    BATTELLE
+    for the
+    UNITED STATES DEPARTMENT OF ENERGY
+    under Contract DE-AC05-76RL01830
+  </pre>
+</div>
+
 
 
 License
 =======
 
-Released under the 3-Clause BSD license (see License.rst)
+Released under the [3-Clause BSD license](LICENSE.rst)

docker-compose.yml

@@ -0,0 +1,11 @@
+version: '3'
+
+services:
+  hypernetx:
+    image: hypernetx/hypernetx:latest
+    ports:
+      - "8888:8888"
+    tty: true
+    stdin_open: true
+    volumes:
+      - "${PWD}:/home/jovyan/work"