pbcgraph 0.1.0

Translation-labeled periodic graphs on Z^d with exact component lattice invariants.

pbcgraph

pbcgraph is a compact Python library for translation-labeled periodic graphs on the integer lattice Z^d.

You store a finite quotient graph (internally a NetworkX MultiDiGraph), but every directed edge carries an integer translation vector. This gives the quotient an exact infinite-lift semantics and lets you do instance-aware connectivity tests without enumerating the infinite graph.

What you get in v0.1:

• PeriodicGraph / PeriodicDiGraph: unique edge per (u, v, tvec).
• PeriodicMultiGraph / PeriodicMultiDiGraph: parallel edges allowed for the same (u, v, tvec).
• PeriodicComponent: lattice invariants (rank, SNF torsion) and exact instance connectivity via same_fragment(...).

Status

pbcgraph is alpha (v0.1). The core containers and component invariants are implemented and covered by tests. The API may still evolve, but the library is already useful for research code and prototyping.

Install

Requires Python 3.10+.

Once the project is published on PyPI:

python -m pip install pbcgraph

Until then (or for the latest dev branch), install from GitHub:

python -m pip install git+https://github.com/IvanChernyshov/pbcgraph.git

For local development:

python -m pip install -e ".[dev]"

Quickstart

from pbcgraph import PeriodicGraph

# A quotient graph in Z^2.
G = PeriodicGraph(dim=2)

# Undirected edges are stored internally as two directed realizations
# with tvec and -tvec.
G.add_edge('A', 'B', tvec=(0, 0))
G.add_edge('B', 'C', tvec=(0, 0))
G.add_edge('C', 'A', tvec=(1, 0))  # closes a periodic cycle (rank-1 along x)

# Lifted nodes are (node_id, cell_shift).
neighbors = list(G.neighbors_inst(('A', (0, 0))))

comp = G.components()[0]
assert comp.same_fragment(('A', (0, 0)), ('A', (1, 0)))
assert not comp.same_fragment(('A', (0, 0)), ('A', (0, 1)))

Documentation

• Online docs (GitHub Pages): https://IvanChernyshov.github.io/pbcgraph/

Local docs build:

python -m pip install -e ".[docs]"
mkdocs serve

Notebooks in docs/examples/ are executed during mkdocs build (MkDocs + mkdocs-jupyter).

License

GNU LGPLv3 (or later). See LICENSE / COPYING.