Skip to content

Commit

Permalink
Merge branch 'develop' into bp2
Browse files Browse the repository at this point in the history
  • Loading branch information
@brendapraggastis
brendapraggastis committed May 11, 2023
2 parents 95f318f + bec4791 commit b342aa7
Show file tree
Hide file tree
Showing 20 changed files with 719 additions and 2,220 deletions.
2 changes: 1 addition & 1 deletion .cz.toml
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
[tool.commitizen]
name = "cz_conventional_commits"
version = "2.0"
version = "2.0.0"
version_files = [
"setup.py",
"docs/source/conf.py",
Expand Down
2 changes: 1 addition & 1 deletion CODE_OF_CONDUCT.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -131,4 +131,4 @@ https://www.contributor-covenant.org/translations.

This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/),
version 2.1, available at
https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
6 changes: 3 additions & 3 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,13 +11,13 @@ The world of open source is wide; it can be a lot to take in! If this is your f
Here are the [steps to creating an issue on github](https://docs.github.com/en/issues/tracking-your-work-with-issues/quickstart). When reporting a bug,

- search for related issues on Github. You might be able to get answer without the hassle of creating an issue
- describe the current behavior and explain which behavior you expected to see instead and why. At this point you can also tell which alternatives do not work for you.
- describe the current behavior and explain which behavior you expected to see instead and why. At this point you can also tell which alternatives do not work for you.
- (if applicable) provide error messages
- (if applicable) provide a step by step description of the problem; if possible include code that others can use to reproduce it
- You may want to **include screenshots and animated GIFs** which help you demonstrate the steps or point out the part which the suggestion is related to. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux.
- provide clear, specific title
- include details on your setup (operating system, python version, etc.)
- use the most recent version of this library and the source language (e.g. Rust); that fixes a lot of problems
- use the most recent version of this library and the source language (e.g. Rust); that fixes a lot of problems
- here are [more details on getting the most out of issue reporting!](https://marker.io/blog/how-to-write-bug-report)

## Contribute new code
Expand All @@ -36,4 +36,4 @@ If you're stuck or don't know where to begin, then you're in good company -- we'

# Code of conduct

Our shared values as software developers guide us in our day-to-day interactions and decision-making. Our open source projects are no exception. Trust, respect, collaboration and transparency are core values we believe should live and breathe within our projects. Our community welcomes participants from around the world with different experiences, unique perspectives, and great ideas to share. Our [code of conduct](CODE_OF_CONDUCT) describes these values, and our standards for contributing.
Our shared values as software developers guide us in our day-to-day interactions and decision-making. Our open source projects are no exception. Trust, respect, collaboration and transparency are core values we believe should live and breathe within our projects. Our community welcomes participants from around the world with different experiences, unique perspectives, and great ideas to share. Our [code of conduct](CODE_OF_CONDUCT) describes these values, and our standards for contributing.
41 changes: 14 additions & 27 deletions Makefile
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@

SHELL = /bin/bash

VENV = venv-hnx
Expand All @@ -8,16 +7,15 @@ PYTHON3 = python3

## Test

test: clean venv
@$(PYTHON_VENV) -m pip install -e .'[auto-testing]' --use-pep517
@$(PYTHON_VENV) -m tox -e py38 -e py311
test: test-deps
@$(PYTHON3) -m tox

test-ci:
@$(PYTHON3) -m pip install -e .'[auto-testing]' --use-pep517
test-ci: test-deps
@$(PYTHON3) -m pip install 'pytest-github-actions-annotate-failures>=0.1.7'
pre-commit install
pre-commit run --all-files
@$(PYTHON3) -m tox -e py38 -r
@$(PYTHON3) -m tox -e py38-notebooks -r

.PHONY: test, test-ci

Expand All @@ -38,26 +36,14 @@ publish-to-pypi: publish-deps build-dist
@echo "Publishing to PyPi"
$(PYTHON3) -m twine upload dist/*

.PHONY: build-dist publish-to-test-pypi publish-to-pypi publish-deps
.PHONY: build-dist publish-to-pypi publish-deps

### Update version

version-deps: clean-venv venv
@$(PYTHON_VENV) -m pip install .'[releases]'

bump-version-major: version-deps
bump2version --dry-run --verbose major
bump2version --verbose major

bump-version-minor: version-deps
bump2version --dry-run --verbose minor
bump2version --verbose minor
version-deps:
@$(PYTHON3) -m pip install .'[releases]'

bump-version-patch: version-deps
bump2version --dry-run --verbose patch
bump2version --verbose patch

.PHONY: version-deps bump-version-major bump-version-minor bump-version-patch
.PHONY: version-deps

#### Documentation

Expand All @@ -75,15 +61,16 @@ commit-docs:
clean-venv:
rm -rf $(VENV)

clean: clean-venv
clean:
rm -rf .out .pytest_cache .tox *.egg-info dist build

venv:
venv: clean-venv
@$(PYTHON3) -m venv $(VENV);

test-deps:
@$(PYTHON3) -m pip install -e .'[testing]' --use-pep517

all-deps:
@$(PYTHON3) -m pip install -e .'[all]' --use-pep517

.PHONY: venv

.PHONY: clean clean-venv venv all-deps
.PHONY: clean clean-venv venv all-deps test-deps
187 changes: 95 additions & 92 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -46,29 +46,31 @@ distributions by their attributes.

What's New
----------
#. The Hypergraph constructor now accepts nested dictionaries with incidence cell properties, pandas.DataFrames, and 2-column Numpy arrays.
#. Additional constructors accept incidence matrices and incidence dataframes.
#. Hypergraph constructors accept cell, edge, and node metadata.
#. Metadata available as attributes on the cells, edges, and nodes.
#. User-defined cell weights and default weights available to incidence matrix.
#. Meta data persists with restrictions and removals.
#. Meta data persists onto s-linegraphs as node attributes of Networkx graphs.
#. New module and tutorial for *Barycentric homology*.
#. New hnxwidget available using `pip install hnxwidget`.
1. The Hypergraph constructor now accepts nested dictionaries with incidence cell properties, pandas.DataFrames, and 2-column Numpy arrays.
1. Additional constructors accept incidence matrices and incidence dataframes.
1. Hypergraph constructors accept cell, edge, and node metadata.
1. Metadata available as attributes on the cells, edges, and nodes.
1. User-defined cell weights and default weights available to incidence matrix.
1. Meta data persists with restrictions and removals.
1. Meta data persists onto s-linegraphs as node attributes of Networkx graphs.
1. New module and tutorial for *Barycentric homology*.
1. New hnxwidget available using `pip install hnxwidget`.


What's Changed
--------------
#. 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.
#. Methods for adding nodes and hyperedges are currently not supported.
#. The `nwhy` optimizations are no longer supported.
#. Entity and EntitySet classes are being moved to the background. The Hypergraph constructor does not accept either.
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 may be run in your browser using Google Colab
-------------------------------------------------------

**Additional Tutorials may be found on in the Tutorials Folder.**

<a href="https://colab.research.google.com/github/pnnl/HyperNetX/blob/master/tutorials/Tutorial%201%20-%20HNX%20Basics.ipynb" target="_blank">
<img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
<span >Tutorial 1 - HNX Basics</span>
Expand All @@ -93,23 +95,18 @@ Tutorials may be run in your browser using Google Colab
</a>
</br>

<a href="https://colab.research.google.com/github/pnnl/HyperNetX/blob/master/tutorials/Tutorial%205%20-%20Homology%20mod%202%20for%20TriLoop%20Example.ipynb" target="_blank">
<a href="https://colab.research.google.com/github/pnnl/HyperNetX/blob/master/tutorials/Tutorial%205%20-%20s-Centrality.ipynb" target="_blank">
<img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
<span >Tutorial 5 - Homology mod2 for TriLoop Example</span>
<span >Tutorial 5 - s-Centrality</span>
</a>
</br>

<a href="https://colab.research.google.com/github/pnnl/HyperNetX/blob/master/tutorials/Tutorial%206%20-%20Static%20Hypergraphs%20and%20Entities.ipynb" target="_blank">
<a href="https://colab.research.google.com/github/pnnl/HyperNetX/blob/master/tutorials/Tutorial%206%20-%20Homology%20mod%202%20for%20TriLoop%20Example.ipynb" target="_blank">
<img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
<span >Tutorial 6 - Static Hypergraphs and Entities</span>
<span >Tutorial 6 - Homology mod2 for TriLoop Example</span>
</a>
</br>

<a href="https://colab.research.google.com/github/pnnl/HyperNetX/blob/master/tutorials/Tutorial%207%20-%20s-centrality.ipynb" target="_blank">
<img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/>
<span >Tutorial 7 - s-Centrality</span>
</a>
</br>

Installing HyperNetX
====================
Expand All @@ -118,14 +115,14 @@ HyperNetX may be cloned or forked from: <https://github.com/pnnl/HyperNetX>
To install in an Anaconda environment
-------------------------------------

>>> conda create -n <env name> python=3.7
>>> conda create -n <env name> python=3.8
>>> source activate <env name>
>>> pip install hypernetx

Mac Users: If you wish to build the documentation you will need
the conda version of matplotlib:

>>> conda create -n <env name> python=3.7 matplotlib
>>> conda create -n <env name> python=3.8 matplotlib
>>> source activate <env name>
>>> pip install hypernetx

Expand All @@ -140,7 +137,7 @@ To use [NWHy](docs/build/nwhy.html) use python=3.9 and the conda version of tbb
To install in a virtualenv environment
--------------------------------------

>>> virtualenv --python=<path to python 3.7 executable> <path to env name>
>>> virtualenv --python=<path to python 3.8 executable> <path to env name>

This will create a virtual environment in the specified location using
the specified python executable. For example:
Expand Down Expand Up @@ -171,12 +168,15 @@ For an editable installation with access to jupyter notebooks:

>>> pip install [-e] .

> ℹ️ **TIP:** For the following installation commands, if you are using ZSH as your shell, you might encounter the
> following error:
> ℹ️ **TIP:** For the following installation commands, if you are using ZSH as your shell, you might encounter an error; for example:
>>**zsh: no matches found: .[tutorials]**
>
> To successfully run the below installation commands, put the single quote around the square brackets. For example:
> This error occurs because ZSH uses square brackets for globbing and pattern matching, which means that ZSH will not respect the square brackets as string literals when running commands such as pip install -e .[tutorials].
> To successfully run the following installation commands, put single quotes around the square brackets.
> For example:
> >pip install -e .'[tutorials]'
> or
>>pip install -e .\['tutorials'\]
>
> For more information on this ZSH-related issue, see this [StackOverflow post](https://stackoverflow.com/a/68888466/11145086).
Expand Down Expand Up @@ -212,60 +212,6 @@ To install the whole shabang:

>>> pip install -e .['all']

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 align=center>
<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>


License
-------

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


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](https://cli.github.com/). See instructions below on how to manually trigger CI on GitHub Actions:

```commandline
# 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
----------

Versioning is automated using [bump2version](https://pypi.org/project/bump2version/).
To automatically update the version when preparing a release, run the following commands:

```
# part is one of "major", "minor", or "patch"
make bump-version-<part>
make commit-docs
```


# Development

Expand All @@ -276,17 +222,19 @@ HyperNetX uses a number of tools to maintain code quality:
* Pylint
* Black

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

```commandline
pip install -e .['linting']
```


### Pylint

[Pylint](https://pylint.pycqa.org/en/latest/index.html) is a static code analyzer for Python-based projects. From the [Pylint docs](https://pylint.pycqa.org/en/latest/index.html#what-is-pylint):

> 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.
Before using this tool, ensure that you install Pylint in your environment:

```commandline
pip install -e .['auto-testing']
```

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:
Expand All @@ -307,11 +255,6 @@ For more information on configuration, see https://pylint.pycqa.org/en/latest/us

[Black](https://black.readthedocs.io/en/stable/) 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.

Before using this tool, ensure that you install Pylint in your environment:

```commandline
pip install -e .['auto-testing']
```

```commandline
black hypernetx
Expand Down Expand Up @@ -352,3 +295,63 @@ The HTML pages are in docs/html.

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](https://cli.github.com/). See instructions below on how to manually trigger CI on GitHub Actions:

```commandline
# 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`](https://github.com/commitizen-tools/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:

```shell
# 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.

<div align=center>
<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>


License
-------

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

0 comments on commit b342aa7

Please sign in to comment.