NetSmith: Fast Network Analysis Library

NetSmith computes the standard network measures — community detection, centrality, shortest paths, clustering, k-core and null models — on graphs large enough that the usual Python tools become the bottleneck. The algorithms are Rust kernels that release the GIL and parallelize across cores; every one has a pure-Python fallback, so the library works whether or not the compiled extension is present.

It needs only NumPy. NetworkX is optional, and only for converting a graph to one (Graph.as_networkx()) — no computation reaches for it.

import netsmith
from netsmith.core.graph import Graph
from netsmith.core.community import louvain_hooks
from netsmith.api import betweenness

graph = Graph(edges=[(0, 1), (1, 2), (0, 2), (3, 4), (4, 5), (3, 5), (2, 3)], n_nodes=6)

louvain_hooks(graph, seed=42)["n_communities"]   # 2
betweenness(graph)                               # brokerage per node

Measured against NetworkX on this machine: betweenness on 5,000 nodes takes 0.34s against 29.7s (87x), and five degree-preserving null models of a 25,000-edge graph take 0.11s against 9.4s (86x).

Architecture

NetSmith follows a four-layer architecture:

Layer 1: Core

Pure math, no I/O, no global state. Located in src/netsmith/core/:

  • graph.py: Core graph types (Graph, GraphView)
  • metrics.py: Degree, centrality (degree, betweenness), assortativity, clustering, k-core, components
  • paths.py: Shortest paths, reachability, walk metrics
  • community.py: Modularity, Louvain and label propagation (all built-in kernels)
  • nulls.py: Null models and permutation tests
  • stats.py: Distributions, confidence intervals, bootstrap

Layer 2: Engine

Performance and execution. Located in src/netsmith/engine/:

  • python/: Reference Python implementations
  • rust/: Rust-accelerated kernels (to be implemented)
  • dispatch.py: Backend selection (auto, python, rust)
  • contracts.py: Data contracts (EdgeList, GraphData)

Layer 3: API

Public surface. Located in src/netsmith/api/:

  • load.py: Load edges from pandas, polars, parquet, csv
  • graph.py: Public Graph API
  • compute.py: Stable compute functions (degree, pagerank, communities)
  • validate.py: Input validation

Layer 4: Apps

Opinionated use cases. Located in src/netsmith/apps/:

  • cli/: Command-line interface
  • reports/: HTML/markdown report generation
  • datasets/: Sample graphs and download helpers

Data Contracts

Canonical edge representation:

EdgeList(
    u: NDArray[np.int64],      # Source nodes (length m)
    v: NDArray[np.int64],      # Destination nodes (length m)
    w: Optional[NDArray[np.float64]],  # Edge weights (optional)
    directed: bool,
    n_nodes: Optional[int]     # Preferred but inferred if not provided
)

Usage Examples

Basic Usage

import netsmith
import numpy as np

# Create edge list
u = np.array([0, 1, 2], dtype=np.int64)
v = np.array([1, 2, 0], dtype=np.int64)
edges = netsmith.api.load.EdgeList(u=u, v=v, directed=False, n_nodes=3)

# Compute degree
degrees = netsmith.degree(edges, backend="auto")
print(degrees)  # [2, 2, 2]

# Compute PageRank
pr = netsmith.pagerank(edges, alpha=0.85, backend="auto")
print(pr)

# Compute communities
communities = netsmith.communities(edges, method="louvain", backend="auto")
print(communities)

Loading from Files

# Load from parquet
edges = netsmith.load_edges("edges.parquet", u_col="source", v_col="target")

# Load from CSV
edges = netsmith.load_edges("edges.csv", u_col="u", v_col="v", w_col="weight")

CLI Usage

# Compute degree
netsmith compute degree --input edges.parquet --out degree.parquet

# Compute PageRank
netsmith compute pagerank --input edges.parquet --out pr.parquet --alpha 0.85

# Compute communities
netsmith compute communities --input edges.parquet --out communities.parquet

Installation

Minimal installation (numpy only - ~10MB):

pip install netsmith

With optional dependencies:

pip install netsmith[scipy]      # For sparse matrices (adjacency_matrix format='sparse'/'coo')
pip install netsmith[cli]        # For the `netsmith` command-line tool
pip install netsmith[networkx]   # Interop only: Graph.as_networkx()
pip install netsmith[pandas]     # For pandas data loading
pip install netsmith[polars]     # For polars data loading

# Or install all optional dependencies:
pip install netsmith[scipy,networkx,pandas,polars]

# Development
pip install netsmith[dev]

Note: Every algorithm works with just numpy — community detection, k-core, null models, centrality and paths included. scipy is only needed for sparse matrix formats, and networkx only for Graph.as_networkx() interop; no computation reaches for it.

Rust Backend

The Rust backend will be automatically used if available. To build:

# Install Rust
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Build and install
maturin develop --release

Status

✅ Completed:

  • Core layer structure (graph types, metrics, paths, community, nulls, stats)
  • Engine layer structure (Python backend, dispatch system, contracts)
  • API layer (load, graph, compute, validate)
  • Apps layer (CLI skeleton)
  • pyproject.toml configuration

🚧 In Progress:

  • Rust backend implementation (degree, clustering, paths, components, Louvain done)
  • Full metric implementations
  • Test suite

📋 Planned:

  • Rust acceleration for Phase 1 kernels (degree, strength, components, BFS, k-core)
  • Comprehensive test coverage
  • Documentation
  • Performance benchmarks

Design Philosophy

NetSmith focuses on pure network analysis. For time series to network conversion, use downstream libraries that build on NetSmith.

License

MIT

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 kylejones from gravatar.com kylejones

Credits

Author: Kyle T. Jones

License

MIT License

Requires

Python >=3.12

Provides Extra

cli dev networkx pandas polars rust scipy

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 Distribution

netsmith-0.3.0.tar.gz (73.3 kB view details)

Uploaded Source

Built Distributions

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

netsmith-0.3.0-cp313-cp313-win_amd64.whl (307.7 kB view details)

Uploaded CPython 3.13Windows x86-64

netsmith-0.3.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (394.2 kB view details)

Uploaded CPython 3.13manylinux: glibc 2.17+ x86-64

netsmith-0.3.0-cp313-cp313-macosx_11_0_arm64.whl (355.7 kB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

netsmith-0.3.0-cp312-cp312-win_amd64.whl (307.7 kB view details)

Uploaded CPython 3.12Windows x86-64

netsmith-0.3.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (394.2 kB view details)

Uploaded CPython 3.12manylinux: glibc 2.17+ x86-64

netsmith-0.3.0-cp312-cp312-macosx_11_0_arm64.whl (355.7 kB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

File details

Details for the file netsmith-0.3.0.tar.gz.

File metadata

  • Download URL: netsmith-0.3.0.tar.gz
  • Upload date:
  • Size: 73.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for netsmith-0.3.0.tar.gz
Algorithm Hash digest
SHA256 e661e8dad26fe6adc726110ecb2ba903196f6611edb0400cf17f581079892462
MD5 2b47204f2ff59d1d105a2f2428c96deb
BLAKE2b-256 1a231ce1a4df584286901c71b1f6885fcd61b06696febf7ce86d5cecf740d931

See more details on using hashes here.

Provenance

The following attestation bundles were made for netsmith-0.3.0.tar.gz:

Publisher: release.yml on kylejones200/netsmith

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

File details

Details for the file netsmith-0.3.0-cp313-cp313-win_amd64.whl.

File metadata

  • Download URL: netsmith-0.3.0-cp313-cp313-win_amd64.whl
  • Upload date:
  • Size: 307.7 kB
  • Tags: CPython 3.13, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for netsmith-0.3.0-cp313-cp313-win_amd64.whl
Algorithm Hash digest
SHA256 990a7b4d645708759a520d3b97c5fb4d4728bb9273bf7f25bcffa9e21a79f31e
MD5 220eebb2deaa3c10e46cfe4fdfe6f572
BLAKE2b-256 487a4c4cb2b112f2e200ce695a04b0ef0e8fa85d159b664606fc03fe484a0bb2

See more details on using hashes here.

Provenance

The following attestation bundles were made for netsmith-0.3.0-cp313-cp313-win_amd64.whl:

Publisher: release.yml on kylejones200/netsmith

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

File details

Details for the file netsmith-0.3.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for netsmith-0.3.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 1953db67f5158ac5d2c88e28ecaa3c039040e613e9f310b7e618a255ee04393b
MD5 841e7e6a7e996b304d7f2011bb117bab
BLAKE2b-256 3e2a030eac8c73ad6992c0e84f2df11235b25a39eaf198f8d0594ad482929334

See more details on using hashes here.

Provenance

The following attestation bundles were made for netsmith-0.3.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on kylejones200/netsmith

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

File details

Details for the file netsmith-0.3.0-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for netsmith-0.3.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 7c067a46d891d7b5beb7d1dd8125b98cd384f4168f38ff289c88e69fb114acb0
MD5 5587bae69e89f66c7a6b3271df426d56
BLAKE2b-256 acc83a8c38b36f7019a38b8aca7b92258aaeb777d699aad7e8229eecb77ae221

See more details on using hashes here.

Provenance

The following attestation bundles were made for netsmith-0.3.0-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: release.yml on kylejones200/netsmith

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

File details

Details for the file netsmith-0.3.0-cp312-cp312-win_amd64.whl.

File metadata

  • Download URL: netsmith-0.3.0-cp312-cp312-win_amd64.whl
  • Upload date:
  • Size: 307.7 kB
  • Tags: CPython 3.12, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for netsmith-0.3.0-cp312-cp312-win_amd64.whl
Algorithm Hash digest
SHA256 28d12725b08458e6c0dbdfda345802089c2a6473effe0547db76de3fb61e625c
MD5 b840a0ad650b0204d3b9de5e4a4445b0
BLAKE2b-256 78454e6723a5238ed9c876192417ec84508a5f140009ab5b27d0e60d6d5c90ad

See more details on using hashes here.

Provenance

The following attestation bundles were made for netsmith-0.3.0-cp312-cp312-win_amd64.whl:

Publisher: release.yml on kylejones200/netsmith

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

File details

Details for the file netsmith-0.3.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for netsmith-0.3.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 3a171c686a7a36462311e239e14049445ffcdd6d4b99257f13293e3de6fccd86
MD5 4c3d66e749751ce52cede1575a6bb4f3
BLAKE2b-256 ed54459c32b8f22469b31ba85733ef121d88133807b5dd82ae8efa1940a2ce64

See more details on using hashes here.

Provenance

The following attestation bundles were made for netsmith-0.3.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on kylejones200/netsmith

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

File details

Details for the file netsmith-0.3.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for netsmith-0.3.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 9bcfd86389e8c10277c678f8cec55a99361b3aea58ecc1af3b640156e760d16c
MD5 d3751202c315d77d9b3609eb52d63fc1
BLAKE2b-256 67ae70b1d37cca774b6ff9dcb9f1a69c29238f5d39dc28a18acd9b43bbeedfd7

See more details on using hashes here.

Provenance

The following attestation bundles were made for netsmith-0.3.0-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: release.yml on kylejones200/netsmith

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.3.0 This release

7 files

0.2.2

7 files

0.2.1

7 files

0.2.0

7 files

0.1.1

7 files

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