Frequently Asked Questions#
FAQs#
Is there a changelog or release notes?#
Yes! Notes for each release are currently on GitHub here:
How do I cite Python-graphblas?#
Zenodo provides DOIs for the latest and specific versions of python-graphblas here:
https://doi.org/10.5281/zenodo.7328791
Follow instructions in “Cite as” in the lower right of the Zenodo webpage.
Where can I find help?#
If you think you found a bug, have a feature request, have a question, or have a suggestion for improving our documentation, please raise an issue here:
python-graphblas/python-graphblas#issues
More open-ended discussions can be posted here:
python-graphblas/python-graphblas#discussions
You may also join our chat on Discord (in the #graphblas channel):
https://discord.com/invite/vur45CbwMz
and join our weekly community calls (we’re friendly!):
How and where are decisions made?#
We seek consensus and input from all members of the community. Anyone with an interest in the project can join the community, contribute to the project design, and participate in the decision making process. We want to hear from you!
We are currently a small team, and decisions must be agreed upon by both co-creators Erik Welch and Jim Kitchen. PRs must be approved by at least one core developer, and Erik and Jim must both approve new releases.
We strive for openness, transparency, and institutional neutrality. Discussions typically occur in our weekly community calls and documented in meeting notes and relevant GitHub issues.
As our community grows, we would welcome additional core developers, a Steering Committee,
and other roles to help manage and direct python-graphblas.
We aspire to have (and formalize) governance such as
NetworkX
and Dask have.
What is the Code of Conduct?#
The Code of Conduct describes expected behavior for interactions within our community and by individuals when they represent the project. Our full Code of Conduct with instructions for how to report complaints or potential CoC violations is here:
What is the deprecation policy?#
python-graphblas uses a time-based deprecation policy:
deprecations must last at least eight months, and may be removed after eight months.
We care deeply about stability and want other libraries and applications
to be able to depend on python-graphblas with minimal disruption.
We try hard “to get things right” the first time.
Nevertheless, backwards-incompatible changes are inevitable in most software projects.
If possible, API or behavioral changes should be done in a backwards-compatible way
that allows a transition to the new way. Using the previous (deprecated) way should
give a DeprecationWarning that identifies what is deprecated,
how the user should update, and when the deprecation may be removed.
Changes must also be documented in the release notes and docstrings if appropriate.
Bugs are not considered deprecations and may be fixed immediately.
What is the version support policy?#
Each major Python version will be supported for at least 36 to 42 months. Major dependencies such as NumPy should be supported for at least 24 months. This is motivated by these guidelines:
python-graphblas itself follows a “single trunk” versioning strategy.
For example, if a CVE is discovered, we won’t retroactively apply the fix to previous releases.
Instead, the fix will only be available starting with the next release.
The GraphBLAS C API specification is expected to change slowly, but it does change. We aim to support the latest version of the GraphBLAS spec and of implementations. We will announce plans to drop support of old versions of the spec or major versions of implementations before we do so. We will make the announcements in the release notes and in our Discord channel. If the proposed changes will negatively affect you, please let us know so we may work together towards a solution.
To see which versions of SuiteSparse:GraphBLAS we support, look at the version specification
of suitesparse under [projects.optional-dependencies] in pyproject.toml.
What is the relationship between python-graphblas and pygraphblas?#
They are different libraries with similar goals. Both wrap SuiteSparse:GraphBLAS and use the
same underlying python-suitesparse-graphblas CFFI wrapper, making their underlying objects
compatible with each other.
The biggest difference is in how the C calls are mapped to equivalent Python functions.
For simple expressions, the two libraries are very similar.
# pygraphblas
A += 1
# python-graphblas
A += 1
For more complex expressions, however, the two libraries diverge significantly.
pygraphblas tends towards the numpy style of immediate execution and using
keyword arguments to affect the output.
# pygraphblas
A.mxm(B.transpose(), mask=A, out=C, accum=FP64.PLUS, semiring=FP64.MIN_PLUS)
python-graphblas uses delayed expressions and keeps the output-affecting arguments
together with the output.
# python-graphblas
C(A, accum=binary.plus) << semiring.min_plus(A @ B.T)
python-graphblas also contains many additional features such as the Recorder and advanced aggregators.
What is the performance penalty of writing algorithms with python-graphblas vs writing them directly in C?#
For large graphs, the performance penalty is negligible as the bulk of the work of operating on Matrices and Vectors is done purely in C. The overhead is only in the calls made from Python to C.
For small graphs, the call overhead may become more significant, but smaller graphs usually don’t take much time to compute, so the extra overhead should not be noticeable at a human scale.