Cluster materials lux schema

[RajbanulAkhond]

Summary

This PR adds an MPContribs Lux schema for the Cluster Materials project under:

mpcontribs-lux/mpcontribs/lux/projects/cluster_materials/

The schema describes contributed cluster-analysis results and selected flat-band annotations linked to Materials Project materials through materialId.

Included models

• ClusterMaterial — one contributed record per MP material
• ClusterDescriptor — properties of an individual identified cluster
• ClusterPointGroup — point-group assignment for a unique cluster type
• FlatBandProperties — selected flat-band annotations from the cited study

The schema retains the polar, piezoelectric, and enantiomorphic classification flags. It also includes:

• hasFlatData
• hasBatteryData

hasBatteryData is only a membership indicator for the reviewed MP Battery Explorer dataset. Battery properties already available through the Materials Project are not duplicated.

Data-scope decisions

This contribution is limited to:

1. Cluster-analysis results generated by Cluster Finder.
2. Selected flat-band annotations from Neves et al.
3. Minimal identifiers and classification flags required to interpret and link the contributed records.

Materials Project properties and Battery Explorer data are intentionally not reproduced. materialId serves as the external linkage key for retrieving those properties directly from MP.

The previously considered normalizedSingularValues and rankScore fields are not included.

Validation

The models enforce internal consistency, including:

• numberOfClusters equals the number of cluster descriptors.
• Each cluster’s size equals the length of its elements list.
• minimumAverageDistance equals the minimum reported cluster distance.
• Cluster point-group labels are unique within a material.
• Flat-band lattice IDs and dimensionalities have matching lengths.
• hasFlatData agrees with the presence or absence of flatBand.
• Unknown fields and non-finite numeric values are rejected.

The schema passes:

• All 21 MPContribs Lux Arrow-compatibility tests
• Black formatting
• Ruff/Flake8 checks
• Pydocstyle
• Mypy

Citation

Flat-band annotations are based on:

Neves et al., npj Computational Materials 10, 39 (2024).
https://doi.org/10.1038/s41524-024-01220-x

Repository scope

This PR contains only the two files required to register and expose the schema:

• cluster_materials/__init__.py
• cluster_materials/schema.py

No CSV, Parquet, generated dataset, or duplicated Materials Project data is included.

Md. Rajbanul Akhond (mdakhond@iu.edu)

[Copilot]

🟡 Changes recommended

The current validators include a too-strict float equality check and miss a basic structural invariant, which can cause valid data to fail validation or allow inconsistent payloads.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a new MPContribs Lux schema package for the Cluster Materials project, defining Pydantic models and validators for contributed cluster-analysis results and optional cited flat-band annotations linked by materialId.

Changes:

• Introduces ClusterMaterial, ClusterDescriptor, ClusterPointGroup, and FlatBandProperties Pydantic models with strict validation (extra="forbid", allow_inf_nan=False).
• Adds cross-field invariants to enforce internal consistency (counts, uniqueness, presence/absence agreement).
• Exposes the public model surface via cluster_materials/__init__.py.

File summaries

File	Description
mpcontribs-lux/mpcontribs/lux/projects/cluster_materials/schema.py	New Pydantic schema models and validators for cluster + flat-band contribution records.
mpcontribs-lux/mpcontribs/lux/projects/cluster_materials/init.py	Exports the public models for the new Cluster Materials schema package.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 3
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟢 Approval recommended

The schema implementation and validations look consistent and well-scoped, with only minor wording nits identified.

Review details

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

mpcontribs-lux/mpcontribs/lux/projects/cluster_materials/schema.py:46

• The unit is written as "in angstrom" (singular); update to a standard plural form or symbol (e.g., Å) for clarity and consistency.

This issue also appears on line 184 of the same file.

            "Mean Cartesian distance, in angstrom, over the connected site pairs "

mpcontribs-lux/mpcontribs/lux/projects/cluster_materials/schema.py:184

• The unit is written as "in angstrom" (singular); update to a standard plural form or symbol (e.g., Å) for clarity and consistency.

            "Minimum, in angstrom, of averageDistance over all reported cluster "

• Files reviewed: 2/2 changed files
• Comments generated: 0 new
• Review effort level: Lite

[bfoley12]

Great first round. I left a decent amount of comments, but they are all minor things. Let me know if you have questions/comments on my reviews.
👍

[bfoley12]

Seems like the last round of review. 2 minor tweaks, two checks on strict var > 0 fields to ensure that is the intent.

[bfoley12]

Looks good. Will be merging soon