crystal-scene

crystal-scene converts one CIF string or a pymatgen Structure into a deterministic, renderer-neutral Pydantic scene. It resolves bonds and periodic images on the backend so HSC, Materiae, and other consumers can draw the same scientific structure consistently.

The package consumes source-neutral values from matdomain-structure and owns only renderer-facing scene derivation.

The package intentionally does not depend on Crystal Toolkit, Dash, a database, or a frontend framework.

Python 3.12 or newer is required.

Installation

Install the published distribution with:

pip install crystal-scene

From a matdomain checkout, install both workspace distributions into an active environment:

python -m pip install -e ./packages/matdomain-structure -e ./packages/crystal-scene

Usage

from pathlib import Path

from crystal_scene import build_crystal_scene

cif_text = Path("structure.cif").read_text(encoding="utf-8")
scene = build_crystal_scene(cif_text)
payload = scene.model_dump(mode="json")

build_crystal_scene also accepts a pymatgen Structure. Structure inputs are copied, then fractional coordinates along periodic lattice axes are wrapped into the input unit cell; nonperiodic axes retain their input values and callers are not mutated. CIF input must contain exactly one non-empty structure. Blank input, parser errors, multiple structures, and empty structures raise ValueError or a pymatgen parser exception.

JSON contract

scene.model_dump(mode="json") is the canonical TypeScript-facing payload. Field names are camel case and schemaVersion is currently "1.0". A payload contains:

• generator: the CrystalNN implementation, exact pymatgen and pymatgen-core versions, disorder policy, and whether every input species has an oxidation state;
• lattice.matrix: three row vectors in angstroms;
• sites: stable input-cell indices, source labels, full species occupancies and oxidation states, and wrapped fractional coordinates;
• siteImages: every input-cell site plus the one-hop periodic site images needed as endpoints of the emitted bonds;
• bonds: each input-cell site's complete CrystalNN neighbor view, including distance in angstroms and CrystalNN topology weight.

A physical CrystalNN bond is undirected. Each serialized bond anchors one view of that connection at sourceSite in the input cell, while targetImage translates targetSite by an integer linear combination of the three lattice rows. The reverse neighbor view is also emitted, so every input-cell site retains its complete coordination environment. In fractional coordinates, the anchored bond vector is:

sites[targetSite].fractional + targetImage - sites[sourceSite].fractional

Swapping the source and target therefore also requires negating targetImage. Renderers can materialize siteImages directly and deduplicate coincident undirected segments. Distinct images remain distinct connections, including bonds from a site to its own periodic images.

For disordered sites, the scene always retains every species and occupancy. CrystalNN uses pymatgen's take_max_species policy only to choose a representative species for bond inference; equal maximum occupancies use pymatgen's deterministic first-maximum behavior. Isotope mass numbers and idealized species spin are accepted as structure identity, while scene schema 1.0 retains its legacy projection of element, occupancy, and oxidation state only.

The input cell is preserved deliberately. Primitive, conventional, refined, or reduced cells change site indices and may depend on symmetry tolerances, so they are not implicit view switches in schema 1.0. Callers that need another cell must supply that pymatgen Structure explicitly.

Colors, atomic radii, bond-cylinder dimensions, boundary-face duplicates, incomplete-bond stubs, labels, and camera state are renderer policy and are not scene data. Magnetic moments and coordination polyhedra are not part of scene schema 1.0: moments require an explicit basis/unit contract, while polyhedra are derived geometry that renderers can construct from the complete neighbor topology when needed. CrystalNN weight is a method-specific topology value (and is normally 1 in the default unweighted mode), not a chemical bond order.

The project is distributed under the terms of the MIT License. See LICENSE.