[challenge]: 2D crystal completion from partial materials information

Released by

Longli Zheng, HKUST(GZ)

Contact email

lzheng228@connect.hkust-gz.edu.cn

Method

Other

Challenge issue

Overview

A 2D-materials researcher rarely starts from nothing.

They often know part of the material: a formula, a parent scaffold, a layer group, lattice constants, a metal sublattice, a surface chemistry, a microscopy motif, or a few diffraction peaks. What they do not yet have is the object needed for computation and comparison:

a concrete, CIF-level atomic structure.

Examples:

• TMDs: “This is monolayer Mo/W/S/Se chemistry, maybe 1H, 1T, or 1T′; some lattice and spectroscopy data are known, but the full phase/coordination/stacking model is ambiguous.”
• Borophene: “STM shows a periodic boron sheet on a substrate, but many ordered vacancy/hole patterns and buckled polymorphs can explain the motif.”
• MXenes: “The backbone is Ti₃C₂ or V₂C, and XPS says O/F/OH terminations are present, but Tₓ does not specify which atoms sit on which surface sites.”

This challenge is to turn CrystalFormer-2D into a 2D crystal completion engine:

Given partial information about a layered material, generate plausible full 2D structures consistent with the known constraints.

This is not “generate random 2D materials.”
This is constrained structure proposal for researchers who already know something and need atomistic hypotheses to test.

The method: constrained 2D structure completion

CrystalFormer-2D samples a 2D crystal as:

layer group → Wyckoff sites → atom types → coordinates → lattice

In this challenge, we turn sampling into completion. The user provides partial information about a material, and the model fills in the missing structure variables.

The guiding rule is:

known information → fix it
impossible choices → mask them
unknown information → sample it
approximate evidence → use it to rank candidates

For example, if the user knows the layer group, formula, and metal sublattice, the sampler should keep those fixed and only propose the missing ligand sites, atom assignments, coordinates, and lattice parameters.

A minimal implementation can start with:

1. fixed layer-group sampling;
2. atom and Wyckoff masks;
3. formula-aware filtering or masking;
4. CIF generation and validity checks;
5. optional MLFF relaxation and ranking.

A stronger implementation can use particle filtering or beam search to keep multiple plausible partial structures during generation, rather than generating first and filtering afterward.

The goal is to return a small set of plausible CIF-level structures, each with a report showing which constraints were satisfied and which parts of the structure were generated.

Background

The general problem is well known in materials science: structure prediction from composition alone is hard, and incomplete experimental information can still be useful for guiding candidate structures.

• Tsujimoto et al., Crystal Structure Prediction Supported by Incomplete Experimental Data
  https://arxiv.org/abs/1705.08613

For 2D materials, the need becomes especially concrete:

• Sung et al. show that 2D-material properties can change strongly with stacking order, thickness, twist, interlayer spacing, and intralayer coordination; they also emphasize that these structural order parameters are often difficult to determine from real-space measurements alone.
  https://arxiv.org/abs/1905.11354

• Caffrey discusses MXenes with mixed –O, –F, and –OH surface terminations that are randomly distributed with limited experimental control. Most theoretical calculations simplify this into uniform terminations, which leaves a gap between experimental partial information and atomistic models.
  https://arxiv.org/abs/1807.01596

• C2DB and 2DMatPedia show that the 2D-materials community already depends on concrete atomistic structures for screening, modeling, and design.
  https://arxiv.org/abs/1806.03173
  https://arxiv.org/abs/1901.09487

This challenge asks:

Can we build a practical bridge from partial 2D-material information to testable atomistic structures?

Tracks

Pick one material family. Each track starts from partial information that researchers may realistically know, then asks the model to propose full CIF-level 2D structures.

Track A — TMD phase and sublattice completion

Transition-metal dichalcogenides, or TMDs, such as MoS₂, WS₂, MoSe₂, and WTe₂, are often described by formula and phase labels such as 1H, 1T, or 1T′. But in real samples, the exact phase, distortion, chalcogen positions, stacking, or Janus/asymmetric assignment may be ambiguous.

The challenge:

Given partial information about a TMD monolayer, complete the full layer structure.

Example input:

system: TMD
elements: [Mo, S, Se]
known:
  formula: MoSSe
  metal_sublattice: Mo
  parent_family: MX2
  possible_phase: [1H, 1T, 1T_prime]
unknown:
  - chalcogen_site_assignment
  - z_coordinates
  - layer_group
  - lattice_parameters

Possible tasks:

Task	Known information	Missing structure
phase completion	formula + approximate lattice	1H / 1T / 1T′ structure
Janus completion	parent MX₂ scaffold + two chalcogens	top/bottom chalcogen assignment
sublattice completion	metal sites fixed	chalcogen Wyckoff sites and coordinates
distorted-phase completion	formula + low-symmetry hint	distorted coordinates and layer group

Useful checks:

Check	Why it matters
formula correctness	output should match the requested TMD chemistry
valid layer symmetry	generated structure should map to a valid layer group
metal/chalcogen coordination	avoids chemically nonsensical completions
relaxation survival	structure should remain plausible after MLFF/DFT relaxation
phase plausibility	proposed phase should be compatible with the input evidence

This is the cleanest track for CrystalFormer-2D because ordered TMD monolayers naturally fit the layer-group/Wyckoff representation.

Track B — Borophene polymorph completion

Borophene is a one-atom-thick boron sheet with many possible ordered polymorphs. Experiments may observe a periodic pattern on a metal substrate, but multiple vacancy/hole arrangements, buckling patterns, or unit cells may explain the observation.

The challenge:

Given partial information about a boron sheet, propose plausible ordered borophene polymorphs.

Example input:

system: borophene
elements: [B]
known:
  substrate: Ag111
  approximate_lattice: optional
  motif_hint: striped_or_hole_pattern
unknown:
  - vacancy_pattern
  - unit_cell
  - buckling
  - layer_group
  - fractional_coordinates

Possible tasks:

Task	Known information	Missing structure
polymorph completion	boron sheet + lattice/motif hint	β₁₂ / χ₃ / striped-like structure
vacancy-pattern completion	triangular boron network	ordered hexagonal-hole pattern
buckling completion	2D projected motif	out-of-plane coordinates
substrate-guided completion	substrate orientation + periodicity	free-standing layer approximant

Useful checks:

Check	Why it matters
valid boron network	avoids disconnected or unphysical sheets
motif match	generated structure should match the provided STM-like or lattice hint
diversity of polymorphs	multiple plausible borophene structures may fit the same partial data
relaxation survival	boron sheet should remain stable or metastable after relaxation
known-polymorph comparison	compare against β₁₂, χ₃, striped, or other known models

This track tests whether completion can produce multiple plausible structural hypotheses when the experimental signal does not uniquely determine the atomistic model.

Track C — MXene surface-termination completion

MXenes are 2D transition-metal carbides, nitrides, or carbonitrides often written as:

M_{n+1}X_nT_x

The backbone M_{n+1}X_n may be known from the parent MAX phase, but T_x hides real atomistic information: which terminations are present, their ratios, which surface sites they occupy, whether the two sides are equivalent, and whether water or ions are intercalated.

The challenge:

Given a known MXene backbone and partial surface-chemistry information, generate ordered atomistic approximants of plausible termination patterns.

Example input:

system: MXene
backbone: Ti3C2
allowed_terminations: [O, F, OH]
composition_hint:
  O: 0.5
  F: 0.3
  OH: 0.2
known_lattice:
  a: optional
  b: optional
unknown:
  - termination_sites
  - termination_species
  - surface_asymmetry
  - ordered_supercell

Possible tasks:

Task	Known information	Missing structure
termination completion	Ti₃C₂ backbone + O/F/OH ratio	surface-site assignment
asymmetric-surface completion	different top/bottom chemistry suspected	two-sided termination pattern
ordered-approximant generation	average T_x chemistry	supercell model for DFT
intercalation stretch goal	backbone + interlayer spacing	water/ion placement

Useful checks:

Check	Why it matters
backbone preserved	known MXene scaffold should not be destroyed
termination stoichiometry	generated approximant should match partial chemistry
surface-site validity	terminations should occupy chemically sensible sites
relaxation survival	structure should not collapse under MLFF/DFT
property sensitivity	work function, voltage, adsorption, or conductivity may depend on termination

This is the most application-driven track. It directly addresses the gap between experimental average surface chemistry and the concrete atomistic structures needed for simulation.

Getting started

A minimal implementation can be built around four components.

1. Constraint schema

Define a small YAML/JSON format for partial material information.

Example:

name: mxene_termination_completion
system: MXene
backbone: Ti3C2
allowed_terminations: [O, F, OH]
composition_hint:
  O: 0.5
  F: 0.3
  OH: 0.2
num_candidates: 20

The schema does not need to support everything. A good week-one target is:

• material family;
• fixed layer group, if known;
• allowed element set;
• fixed or masked Wyckoff positions;
• fixed atom type on selected sites;
• optional fixed coordinates or lattice ranges;
• formula or composition constraint.

2. Constrained sampler

Extend the CrystalFormer-2D sampler so known variables can be clamped and invalid choices can be masked.

Minimal useful controls:

Control	Purpose
layergroup	fixed 2D symmetry
w_mask	force or restrict Wyckoff choices
atom_mask	restrict allowed elements globally
site-specific atom mask	restrict elements per site
coordinate mask	fix or bound known coordinates
lattice prior/range	keep lattice near experimental values
formula constraint	reject or guide samples toward target stoichiometry

The MVP can use rejection sampling after generation, but the better method should enforce constraints during sampling whenever possible.

3. Validators

Every candidate should pass exact validators before expensive calculations.

Required validators:

• parseable CIF;
• 2D periodicity;
• formula / element constraint;
• layer-group range;
• Wyckoff multiplicity consistency;
• no empty structures;
• no impossible short bonds;
• no duplicate candidates.

Useful validators:

• post-relaxation structure still resembles the input constraint;
• symmetry retained or symmetry-lowered in a controlled way;
• energy/stability estimate from MLFF;
• optional match to experimental observables.

4. Reporter

The output should be useful to a human researcher.

Produce:

structures/
  candidate_000001.cif
  candidate_000002.cif
completion_report.csv
completion_summary.md

The report should include:

• input constraints;
• exact checks;
• sampled variables;
• model score/log probability;
• relaxation status;
• nearest known structures;
• why each top candidate is plausible;
• failure notes.

Deliverables

A strong submission should demonstrate a working 2D structure-completion workflow on one of the material tracks: TMDs, borophene, or MXenes.

Required deliverables

1. A concrete completion problem

   Pick one realistic partial-information scenario, for example:

   • TMD: complete possible MoSSe / WSeTe / distorted MX₂ monolayer structures from formula, parent scaffold, and phase hints.
   • Borophene: propose ordered boron-sheet polymorphs from lattice/motif hints.
   • MXene: generate ordered Ti₃C₂Tₓ or V₂CTₓ termination models from backbone and average surface chemistry.

2. Input constraint file

   Provide a small YAML/JSON file describing what is known and what is unknown.

   Example:

   system: MXene
   backbone: Ti3C2
   known:
     allowed_terminations: [O, F, OH]
     approximate_ratio:
       O: 0.5
       F: 0.3
       OH: 0.2
   unknown:
     - termination_sites
     - top_bottom_assignment
     - ordered_supercell
   

3. Generated candidate structures

   Return a small ranked set of CIF-level structures, not thousands of unfiltered samples.

   candidates/
     candidate_0001.cif
     candidate_0002.cif
     candidate_0003.cif
   completion_report.csv
   

4. Constraint-validation report

   For each candidate, report:

   • formula / composition;
   • layer group or effective symmetry;
   • Wyckoff assignment, if available;
   • which constraints were satisfied;
   • which parts were generated;
   • whether the structure passed basic geometry checks;
   • whether it survived optional MLFF relaxation.

5. Researcher-facing explanation

   Write a short note explaining why the top candidates are plausible and how a 2D-materials researcher could use them next.

   For example:

   • “These MXene structures are ordered approximants of mixed O/F/OH termination chemistry and can be used as DFT starting points.”
   • “These borophene candidates realize different vacancy-pattern completions compatible with the same lattice motif.”
   • “These Janus TMD candidates preserve the metal sublattice while exploring top/bottom chalcogen assignments.”

Optional stretch deliverables

• MLFF or DFT relaxation of the top candidates.

• Simulated diffraction / STM / STEM signatures for comparison with experiment.

• Property estimates relevant to the chosen family, such as work function for MXenes, phase stability for TMDs, or relative energy for borophene polymorphs.

• A simple CLI:

  crystalformer-2d-complete constraints.yaml \
    --num_candidates 20 \
    --save_path runs/completion_demo
  

Judging

• Does the submission solve a realistic 2D-materials completion problem?
• Are the generated structures concrete and reusable as CIF files?
• Are the input constraints clearly stated?
• Are known facts enforced rather than ignored?
• Are the candidates chemically and geometrically plausible?
• Does the report explain how a researcher could use the results?
• Is the workflow reproducible?

Bonus for a demo where the generated structures lead to a meaningful scientific next step: relaxation, property calculation, experimental comparison, or hypothesis generation.

Failure modes

This is where the research lives.

• Fake constraint satisfaction: the output appears to satisfy the prompt but violates Wyckoff multiplicities, stoichiometry, or site constraints.
• Rejection-sampling collapse: constraints are enforced only by filtering, producing very low yield.
• Memorization: completions are nearest-neighbor copies of training structures.
• Symmetry hallucination: the pre-relaxation structure has the requested layer group, but relaxation destroys it.
• MXene disorder oversimplification: a random Tₓ surface is replaced by an unrealistically high-symmetry ordered model without saying so.
• Unphysical bonds: the structure is crystallographically valid but chemically absurd.
• Overconfident ranking: model likelihood is mistaken for physical stability.
• Experimental overfitting: a candidate matches one lattice constant or peak but fails all other evidence.

Good submissions should show at least one failure, explain how it was detected, and improve the pipeline.

Research extensions

• Partial occupancy and disordered surface chemistry.
• Supercell-based completion for MXenes and alloys.
• Diffraction- or STM-conditioned likelihoods.
• Bayesian posterior sampling over multiple plausible structures.
• Active learning: use DFT/MLFF feedback to improve completions.
• Multi-fidelity validation: exact checks → MLFF → DFT.
• Property-guided completion: complete structures that both match partial data and optimize a target property.
• Generalization: train on clean ordered 2D crystals, test on distorted, Janus, alloyed, or terminated systems.
• Human-in-the-loop workflows for experimentalists.

Resources

• CrystalFormer-2D branch: https://github.com/Br0kenSmi1e/CrystalFormer/tree/crystalformer-2d
• CrystalFormer upstream: https://github.com/deepmodeling/CrystalFormer
• Tsujimoto et al., Crystal Structure Prediction Supported by Incomplete Experimental Data: https://arxiv.org/abs/1705.08613
• Sung et al., Stacking, Strain, & Twist in 2D Materials Quantified by 3D Electron Diffraction: https://arxiv.org/abs/1905.11354
• Caffrey, Effect of mixed surface terminations on Ti₃C₂T₂ and V₂CT₂ MXenes: https://arxiv.org/abs/1807.01596
• C2DB: https://arxiv.org/abs/1806.03173
• 2DMatPedia: https://arxiv.org/abs/1901.09487
• Tools: pymatgen, spglib, matminer, ASE, ORB/MACE/MatGL
• Concepts: layer groups, Wyckoff positions, structure matching, energy above hull, ML force-field relaxation, diffraction simulation, constrained generation, structure completion

Start by locating the CrystalFormer-2D sampler and the existing structure-generation entry point; the issue does not name repository files or tests. Define the partial-material schema and trace how layer groups, Wyckoff sites, atom types, coordinates, lattice values, and formula constraints are represented. Done means constrained candidates produce parseable CIFs, pass the listed validators, and include the requested completion report.