Sovereign 8s.is mirror of standardgalactic/graph-id-core
  • C++ 51.8%
  • Python 47.7%
  • CMake 0.5%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Koki MURAOKA 94ee6253d3
Some checks failed
Deploy Docs / build (push) Has been cancelled
Deploy Docs / deploy (push) Has been cancelled
Build Wheels / build (push) Has been cancelled
Build Wheels / Build wheels on macos-latest (push) Has been cancelled
Build Wheels / Build wheels on ubuntu-latest (push) Has been cancelled
Build Wheels / Build source distribution (push) Has been cancelled
Test / test (macos-latest, 3.11) (push) Has been cancelled
Test / test (macos-latest, 3.12) (push) Has been cancelled
Test / test (ubuntu-latest, 3.11) (push) Has been cancelled
Test / test (ubuntu-latest, 3.12) (push) Has been cancelled
🔖
2026-06-18 13:48:51 +09:00
.github pre-commit auto-fixes 2026-06-08 02:41:55 +00:00
cpp 📚 2026-01-23 11:32:37 +09:00
docs 🔖 2026-06-18 13:48:51 +09:00
examples 📚 2026-01-23 11:37:36 +09:00
graph_id Cope with pre-commit warinig 2026-06-06 19:47:15 +09:00
library Add gtl::flat_hash_set<unsigned long long int> 2023-09-30 00:30:01 +09:00
tests pre-commit auto-fixes 2026-03-30 02:45:00 +00:00
.codespell.ignorewords ignore words 2025-11-19 22:09:55 +09:00
.gitignore chore: Update .gitignore to include 'junit.xml' 2025-11-20 11:53:10 +09:00
.gitmodules Add gtl::flat_hash_set<unsigned long long int> 2023-09-30 00:30:01 +09:00
.pre-commit-config.yaml chore: Enhance codespell configuration and dependencies 2025-11-19 22:45:35 +09:00
build.py 👕 2026-01-23 11:51:16 +09:00
CMakeLists.txt Add build.yml 2023-10-13 22:54:07 +09:00
mkdocs.yml docs: Configure Graph ID Documentation site with mkdocs.yml settings 2026-01-23 11:16:14 +09:00
poetry.lock lock 2026-06-06 20:11:32 +09:00
pyproject.toml Update pyproject.toml 2026-06-08 07:43:43 +09:00
README.md Update release instructions in README 2025-12-12 16:50:54 +09:00

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.

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.

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 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.
  • Create a new PR from main branch to release branch.