scigraphs-utils

Utilities for scientific graph layouts.

The Python import package is scigraphs_utils.

import numpy as np
from scigraphs_utils import sfdp_layout

edges = np.array([[0, 1], [1, 2], [2, 3]], dtype=np.int32)
xy = sfdp_layout(4, edges, seed=42, overlap="false", maxiter=100)

For Graphviz parameters that are not listed explicitly, pass them as keyword arguments. They are forwarded as Graphviz graph attributes:

from scigraphs_utils import graphviz_layout

xy = graphviz_layout(4, edges, engine="sfdp", start=42, K=1.2)

Barnes-Hut forces

quadtree_repulsion exposes the repulsion term sfdp uses internally: Graphviz's own QuadTree_get_repulsive_force, compiled into this package's extension. It works on 2D and 3D points and is roughly two orders of magnitude faster than an all-pairs numpy evaluation at a few thousand points.

import numpy as np
from scigraphs_utils import quadtree_repulsion

points = np.random.default_rng(0).normal(size=(20_000, 3))
forces = quadtree_repulsion(points, theta=0.6)

theta is the Barnes-Hut opening angle (sfdp uses 0.6; smaller is more accurate and slower, and theta -> 0 converges to the exact all-pairs result). Pass weights= for per-point masses, p= for a different force exponent, and return_counts=True for Graphviz's interaction counters.

quadtree_cells returns the same tree flattened into arrays, so an overlay can draw the cells the forces actually used instead of a uniform grid:

from scigraphs_utils import quadtree_cells

cells = quadtree_cells(points)
cells.lower      # (cells, dim) lower corner
cells.size       # (cells,) edge length
cells.count      # (cells,) points per cell
cells.is_leaf    # (cells,) bool

Both functions build the tree the same way, so pass matching weights and max_level to get the tree that produced a given force field.

Development

The current MVP builds a native extension against a local Graphviz installation:

python -m pip install -e ".[test]"
pytest

To build against a private Graphviz prefix, run:

tools/build_graphviz.sh
GRAPHVIZ_PREFIX="$PWD/build/vendor/graphviz-install" python -m pip install -e ".[test]"

Wheels

The project is configured for cibuildwheel CPython 3.13 builds. The wheel build hook compiles a pinned Graphviz release into a private prefix and builds the native extension against that prefix. On Linux, auditwheel then bundles the required shared libraries into the wheel so users do not need Graphviz installed at runtime.

python -m pip install ".[wheel]"
python -m cibuildwheel --output-dir wheelhouse

Pushing a v* tag runs .github/workflows/publish.yml, which builds the three wheels and uploads them to PyPI through trusted publishing.

Vendored Graphviz source

The quadtree is compiled from a copy of Graphviz's lib/sparse/QuadTree.c under vendor/graphviz/, because those symbols are not exported from the layout plugin. Those files stay under the Eclipse Public License — see THIRD_PARTY_NOTICES.md and vendor/graphviz/README.md. When bumping vendor/graphviz.version, run:

python tools/sync_quadtree.py

Project links

Data verified by PyPI on Aug 25, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for josemarinfarina from gravatar.com josemarinfarina

Credits

Author: Jose Marin

GitHub Statistics

Data verified by PyPI on Aug 25, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT License)

Requires

Python >=3.13

Provides Extra

test wheel

Tags

graphviz layout graphs sfdp scientific-visualization

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

scigraphs_utils-0.2.0-cp313-cp313-win_amd64.whl (1.1 MB view details)

Uploaded CPython 3.13Windows x86-64

scigraphs_utils-0.2.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (5.9 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.27+ x86-64manylinux: glibc 2.28+ x86-64

scigraphs_utils-0.2.0-cp313-cp313-macosx_11_0_arm64.whl (924.4 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

File details

Details for the file scigraphs_utils-0.2.0-cp313-cp313-win_amd64.whl.

File metadata

File hashes

Hashes for scigraphs_utils-0.2.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 3ae8497b5ef6ac0bf5bb62a09434c11280d3dd1f0f50c28c2b0bc09676ad191f
MD5 65b2b92c749706cd8d946d2d416cba41
BLAKE2b-256 1b837e876a8fd60e90e2df456225f229d87acfb9156e90ceae90fd64dcee050e

See more details on using hashes here.

Provenance

The following attestation bundles were made for scigraphs_utils-0.2.0-cp313-cp313-win_amd64.whl:

Publisher: publish.yml on josemarinfarina/scigraphs-utils

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file scigraphs_utils-0.2.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for scigraphs_utils-0.2.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 6da6c76804ea25b7bc3a8d80845937fdb9cf8f2caac7cc23f6853bd53632f82a
MD5 07877ba879554f9bbb0366e4eb65880d
BLAKE2b-256 7b294cdf959720c979a04fa68d560b16bf97dcca2d864dd51fdc9b3f0bf5573c

See more details on using hashes here.

Provenance

The following attestation bundles were made for scigraphs_utils-0.2.0-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl:

Publisher: publish.yml on josemarinfarina/scigraphs-utils

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file scigraphs_utils-0.2.0-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for scigraphs_utils-0.2.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 04f933aa9d36660cec41201099d0628457920578c965ce5220175e8c5a92c694
MD5 64fa9515add91cd4a7daada8aca4137a
BLAKE2b-256 776c74a348ffed0d3c53c100b015dbe0246fc053d8c9e54806991ecc955f588d

See more details on using hashes here.

Provenance

The following attestation bundles were made for scigraphs_utils-0.2.0-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: publish.yml on josemarinfarina/scigraphs-utils

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.2.0 This release

3 files

0.1.1

3 files

0.1.0

1 file

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page