TopoMetrics#

Date: Mar 01, 2026 — Author: Thomas C Nicholas — Version: 0.1.7

topo-metrics is a Python package for calculating topological metrics of network materials.

The core functionality is taking atomic structures and turning them into graphs, and then computing a range of graph and topology-based metrics (rings, clusters, coordination sequences) that are useful for analysing porous materials, frameworks, and other periodic networks.

Installation#

Install topo-metrics using pip (preferably in a fresh environment):

conda create -n topo-metrics python=3.11 -y
conda activate topo-metrics
pip install topo-metrics

Quick start#

from ase.io import read
import topo_metrics as tm

# read in a structure with ASE
atoms = read("zeolite-sodalite.cif")

# build the Si-O graph, remove bridging oxygens, and compute ring statistics
graph = tm.Topology.from_ase(ase_atoms=atoms, cutoff=1.7, remove_types={"O"})
ring_stats = graph.get_clusters()
print(ring_stats)

RingsResults(
   depth=12,
   strong_rings=False,
   ring_size_count=RingSizeCounts(n_rings=46, min=4, max=12),
   VertexSymbol=[4.4.6.6.6.6],
   CARVS={4(2).6(4).12(32)}
)

Where to go next#

  • Basics - basic definitions and concepts used throughout TopoMetrics.

  • Examples – end-to-end, copy-and-pasteable examples.

  • API Reference – full auto-generated API docs.