Skip to main content

PyPI version Python versions codecov

Graph ID

Graph ID is a universal identifier system for atomistic structures including crystals and molecules. It generates unique, deterministic identifiers based on the topological and compositional properties of atomic structures, enabling efficient structure comparison, database indexing, and materials discovery. For more information, refer our docs.

Overview

Graph ID works by:

  1. Converting atomic structures into graph representations where atoms are nodes and bonds are edges
  2. Analyzing the local chemical environment around each atom using compositional sequences
  3. Computing a hash-based identifier that captures both topology and composition
  4. Supporting various modes including topology-only comparisons and Wyckoff position analysis

Features

  • Universal Structure Identification: Generate unique IDs for any crystal or molecular structure
  • Topological Analysis: Option to generate topology-only IDs for structure type comparison
  • Wyckoff Position Support: Include crystallographic symmetry information in ID generation
  • Distance Clustering: Advanced clustering-based analysis for complex structures
  • C++ Performance: High-performance C++ backend with Python bindings
  • Multiple Neighbor Detection: Support for various neighbor-finding algorithms (MinimumDistanceNN, CrystalNN, etc.)

Installation

From PyPI

pip install graph-id-core
pip install graph-id-db  # optional database component

From Source

git clone https://github.com/kmu/graph-id-core.git
cd graph-id-core
git submodule update --init --recursive
pip install -e .

Quick Start

Basic Usage

from pymatgen.core import Structure, Lattice
from graph_id import GraphIDMaker

# Create a structure (NaCl)
structure = Structure.from_spacegroup(
    "Fm-3m",
    Lattice.cubic(5.692),
    ["Na", "Cl"],
    [[0, 0, 0], [0.5, 0.5, 0.5]]
)

# Generate Graph ID
maker = GraphIDMaker()
graph_id = maker.get_id(structure)
print(graph_id)  # Output: NaCl-88c8e156db1b0fd9

Loading from Files

from pymatgen.core import Structure
from graph_id_cpp import GraphIDGenerator

# Load structure from file
structure = Structure.from_file("path/to/structure.cif")
generator = GraphIDGenerator()
graph_id = generator.get_id(structure)

Advanced Configuration

from graph_id_cpp import GraphIDGenerator
from pymatgen.analysis.local_env import CrystalNN

# Topology-only comparison (ignores composition)
topo_gen = GraphIDGenerator(topology_only=True)
topo_id = topo_gen.get_id(structure)

# Include Wyckoff positions
wyckoff_gen = GraphIDGenerator(wyckoff=True)
wyckoff_id = wyckoff_gen.get_id(structure)

# Use different neighbor detection
crystal_gen = GraphIDGenerator(nn=CrystalNN())  # Faster CrystalNN using C++ is also available
crystal_id = crystal_gen.get_id(structure)

Search Structures from Database

Use graph-id-db to search structures in the Materials Project using precomputed Graph ID stored in graph-id-db

# pip install graph-id-db
from graph_id_cpp import GraphIDGenerator

from pymatgen.core import Structure, Lattice

structure = Structure.from_spacegroup(
    "Fm-3m",
    Lattice.cubic(5.692),
    ["Na", "Cl"],
    [[0, 0, 0], [0.5, 0.5, 0.5]]
).get_primitive_structure()
gen = GraphIDGenerator()
graph_id = gen.get_id(structure)
print(f"Graph ID of NaCl is {graph_id}")

from graph_id_db import Finder

# Search for structures in graph-id-db using GraphID
finder = Finder()
finder.find(graph_id)

Examples

More comprehensive examples can be found in the tests/ and examples/ directories.

Applications

Graph ID is particularly useful for:

  • Materials Databases: Efficient indexing and deduplication of structure databases
  • High-throughput Screening: Rapid identification of unique structures in computational workflows
  • Polymorph Identification: Distinguishing between different polymorphs of the same composition

Web Service (experimental)

You can search materials using Graph ID at matfinder.net.

Citation

If you use Graph ID in your research, please cite:

Muraoka, K., Tanimoto, T., Munekata, T. & Nakayama, A. Universal graph-based identifiers of chemical structures for linking large material databases. Nature Communications 17, 5409 (2026). https://doi.org/10.1038/s41467-026-74536-5

@article{muraoka2026graphid,
  title   = {Universal graph-based identifiers of chemical structures for linking large material databases},
  author  = {Muraoka, Koki and Tanimoto, Taku and Munekata, Tsubasa and Nakayama, Akira},
  journal = {Nature Communications},
  volume  = {17},
  number  = {1},
  pages   = {5409},
  year    = {2026},
  doi     = {10.1038/s41467-026-74536-5}
}

Developer's notes

This repo is managed by poetry.

Installation

  1. Clone the repository:
git clone https://github.com/kmu/graph-id-core.git
cd graph-id-core
  1. Initialize git submodules (required for the C++ build):
git submodule update --init --recursive
  1. Install the package and dependencies using Poetry:
poetry install
  1. Install pre-commit
pre-commit install

Note: The git submodules (library/pybind11, library/eigen, library/gtl) are required for building the C++ extension. Without them, the installation will fail during the CMake build step.

Testing

poetry install
poetry run pytest

If you have made changes to the C++ code, run poetry run pip install -e --force-reinstall to apply the changes before running the tests.

Releasing

  • Bump version in pyproject.toml.
  • Merge automatically created PR to merge main branch to release branch.

Metadata

Release files for graph-id-core 0.1.24

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for graph-id-core 0.1.24
File Size Uploaded Provenance Actions
graph_id_core-0.1.24.tar.gz 6.3 MB With provenance Details for graph_id_core-0.1.24.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for graph-id-core 0.1.24
File Actions
graph_id_core-0.1.24-cp313-cp313-win_amd64.whl CPython 3.13 CPython 3.13 Windows x86-64 Details for graph_id_core-0.1.24-cp313-cp313-win_amd64.whl
graph_id_core-0.1.24-cp313-cp313-manylinux_2_28_x86_64.manylinux_2_27_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 Details for graph_id_core-0.1.24-cp313-cp313-manylinux_2_28_x86_64.manylinux_2_27_x86_64.whl
graph_id_core-0.1.24-cp313-cp313-macosx_15_0_arm64.whl CPython 3.13 CPython 3.13 macOS 15.0+ ARM64 Details for graph_id_core-0.1.24-cp313-cp313-macosx_15_0_arm64.whl
graph_id_core-0.1.24-cp312-cp312-win_amd64.whl CPython 3.12 CPython 3.12 Windows x86-64 Details for graph_id_core-0.1.24-cp312-cp312-win_amd64.whl
graph_id_core-0.1.24-cp312-cp312-manylinux_2_28_x86_64.manylinux_2_27_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 Details for graph_id_core-0.1.24-cp312-cp312-manylinux_2_28_x86_64.manylinux_2_27_x86_64.whl
graph_id_core-0.1.24-cp312-cp312-macosx_15_0_arm64.whl CPython 3.12 CPython 3.12 macOS 15.0+ ARM64 Details for graph_id_core-0.1.24-cp312-cp312-macosx_15_0_arm64.whl
graph_id_core-0.1.24-cp311-cp311-win_amd64.whl CPython 3.11 CPython 3.11 Windows x86-64 Details for graph_id_core-0.1.24-cp311-cp311-win_amd64.whl
graph_id_core-0.1.24-cp311-cp311-manylinux_2_28_x86_64.manylinux_2_27_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 Details for graph_id_core-0.1.24-cp311-cp311-manylinux_2_28_x86_64.manylinux_2_27_x86_64.whl
graph_id_core-0.1.24-cp311-cp311-macosx_15_0_arm64.whl CPython 3.11 CPython 3.11 macOS 15.0+ ARM64 Details for graph_id_core-0.1.24-cp311-cp311-macosx_15_0_arm64.whl

Total release size: 9.1 MB

Release files / graph_id_core-0.1.24.tar.gz

Download URL graph_id_core-0.1.24.tar.gz
Size 6.3 MB
Tags Source
SHA-256 checksum
How to use checksums
6c4ead0d6664661d6ecf8107d93eab2f24bf0aaec89afc2e29f315d67667c18c
BLAKE2b-256 checksum
How to use checksums
4c3b7a7729412d09cfcbe1cb3f75caf3bd26df88803f1146fe7b504c90950994
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 14, 2026.

Transparency log

Release files / graph_id_core-0.1.24-cp313-cp313-win_amd64.whl

Download URL graph_id_core-0.1.24-cp313-cp313-win_amd64.whl
Size 313.5 kB
Tags CPython 3.13 Windows x86-64
SHA-256 checksum
How to use checksums
13ca64c14d7a1a65eb80e48026444660f5ece9afc2d695c87ab1c509cbcefee0
BLAKE2b-256 checksum
How to use checksums
55ff5d1d9e678b3e3682af0f3aa6039e185d5ea8b271bb425d05569273a5b9c6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 14, 2026.

Transparency log

Release files / graph_id_core-0.1.24-cp313-cp313-manylinux_2_28_x86_64.manylinux_2_27_x86_64.whl

Download URL graph_id_core-0.1.24-cp313-cp313-manylinux_2_28_x86_64.manylinux_2_27_x86_64.whl
Size 350.5 kB
Tags CPython 3.13 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
4302cf88107e2cb7cb998e41700d7c0f3f1c5581e2f22cf570e70cf37fedd2d4
BLAKE2b-256 checksum
How to use checksums
132b851d36f44a5c29d97e3397dbfc743786e5e0f9c3469b9b30e0043384c6ff
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 14, 2026.

Transparency log

Release files / graph_id_core-0.1.24-cp313-cp313-macosx_15_0_arm64.whl

Download URL graph_id_core-0.1.24-cp313-cp313-macosx_15_0_arm64.whl
Size 288.3 kB
Tags CPython 3.13 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
527f39f44c1bdd3386fe430ef206ce4a529106e4cf7ab4a5dad4ab5c9b9f3309
BLAKE2b-256 checksum
How to use checksums
086536612d703e441d46231303831b31a1d486ffbc83d7b9a5b209c72cbfaf39
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 14, 2026.

Transparency log

Release files / graph_id_core-0.1.24-cp312-cp312-win_amd64.whl

Download URL graph_id_core-0.1.24-cp312-cp312-win_amd64.whl
Size 313.5 kB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
e9ca56d5632c6ce7a17349ffc696eb552887c2108a9a2d5767f2ceface14e332
BLAKE2b-256 checksum
How to use checksums
f6097dcf616fd1c9c5f6c224335873092734dc862e71290cea63cc61ccad8ec9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 14, 2026.

Transparency log

Release files / graph_id_core-0.1.24-cp312-cp312-manylinux_2_28_x86_64.manylinux_2_27_x86_64.whl

Download URL graph_id_core-0.1.24-cp312-cp312-manylinux_2_28_x86_64.manylinux_2_27_x86_64.whl
Size 350.4 kB
Tags CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
5644b5795b3aef3db8f407dcc5ad86500cbe160f18d9b39147cb6f1187bc61ac
BLAKE2b-256 checksum
How to use checksums
7c729d66133f79ef17751edab1556cb73abb94cbb5ac9e1978e9a60cc977678f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 14, 2026.

Transparency log

Release files / graph_id_core-0.1.24-cp312-cp312-macosx_15_0_arm64.whl

Download URL graph_id_core-0.1.24-cp312-cp312-macosx_15_0_arm64.whl
Size 288.3 kB
Tags CPython 3.12 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
f4f6102fdfa3dd41e67815f88f0cd4f740b2cbbe447a093a80fa25042ca3c6ea
BLAKE2b-256 checksum
How to use checksums
e656373b5913c3b72ee69711fcca1fe267e375826107d8155e10b28aa4b1c576
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 14, 2026.

Transparency log

Release files / graph_id_core-0.1.24-cp311-cp311-win_amd64.whl

Download URL graph_id_core-0.1.24-cp311-cp311-win_amd64.whl
Size 309.9 kB
Tags CPython 3.11 Windows x86-64
SHA-256 checksum
How to use checksums
a28043b92de8b143c9c017600fc4b46483abf6802f235c33e2c36ee0ab97e309
BLAKE2b-256 checksum
How to use checksums
67e27f117ac652dca43724f1c1cb1f8686ae1b780be9b53447292759496405ec
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 14, 2026.

Transparency log

Release files / graph_id_core-0.1.24-cp311-cp311-manylinux_2_28_x86_64.manylinux_2_27_x86_64.whl

Download URL graph_id_core-0.1.24-cp311-cp311-manylinux_2_28_x86_64.manylinux_2_27_x86_64.whl
Size 349.9 kB
Tags CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
190293b547b82207789284b24a3ccca905c0b107950617d457b5bcad93ba613d
BLAKE2b-256 checksum
How to use checksums
1ccac4396d2eb46c0da4c1dabd1471edb80adb4c6350bc310647790a65b9a762
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 14, 2026.

Transparency log

Release files / graph_id_core-0.1.24-cp311-cp311-macosx_15_0_arm64.whl

Download URL graph_id_core-0.1.24-cp311-cp311-macosx_15_0_arm64.whl
Size 288.1 kB
Tags CPython 3.11 macOS 15.0+ ARM64
SHA-256 checksum
How to use checksums
1f3930888862fed84c0774916f59e6175aedac9c05c7e338661418bef155103f
BLAKE2b-256 checksum
How to use checksums
fbacb124405ee04ca1ea4806cc331c26296b9e1dc885bbd0ba64dcc209990e17
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 14, 2026.

Transparency log

Security for graph-id-core 0.1.24

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 10 files in this release have been uploaded with provenance metadata.

Select from 10 files

Attestation for graph_id_core-0.1.24.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jul 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

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