How matersim/lego-xtal works
Project Type and Purpose
• LEGO-Xtal is an open-source, research-grade pipeline for AI-driven crystal structure generation.
• It consists of a data-processing layer, generative-model training layer, structure-optimization layer, energy-ranking layer, and database/visualization layer.
High-Level Components
a. Data Layer
• Source databases (data/source/*.db)
• Training CSVs (data/train/*.csv)
b. Generative-Model Layer
• Model scripts (1_train_sample.py)
• Core libraries (lego/GAN.py, lego/VAE.py, lego/base.py, lego/builder.py)
c. Pre-Relaxation Layer
• Script (2_relax.py)
• Batch routines (lego/Batch_Pre-relaxation/*)
d. Energy-Ranking Layer
• Script (3_energy.py)
• Energy modules (lego/basinhopping.py, lego/util.py)
e. Database & Visualization Layer
• DB management (misc/dbs/*.py)
• Figures & demos (misc/Figs/*.py, misc/demos/*.py)
f. Utility & Deployment
• SLURM scripts (util/slurm/*.sh)
• VASP interface (util/vasp/vasp.py)
• Env config (environment.yml)
Simplified Workflow with Code-Stage Purposes
Stage 1: Data Collection & Augmentation
• Code: 0_make_traindata.py
• Purpose: Extract structural descriptors from source DBs; encode space group, cell parameters, Wyckoff sites; augment symmetry-equivalent representations.
• Helpers: lego/data_transformer.py, misc/dbs/db_fetch.py, symdata-aug.py.
Stage 2: Generative-Model Training
• Code: 1_train_sample.py
• Purpose: One-hot encode augmented features; train GANs/VAEs (via lego/GAN.py, lego/VAE.py) to learn crystal-feature distributions.
• Config: environment.yml, any hyperparameters in script.
Stage 3: Pre-Relaxation of Generated Structures
• Code: 2_relax.py
• Purpose: Decode model outputs into trial crystal structures; optimize local environments using L-BFGS/Adam through lego/batch_opt.py and SO3.py.
• Batch scripts: util/slurm/run_relax.sh for HPC submission.
Stage 4: Energy Ranking & Database Update
• Code: 3_energy.py
• Purpose: Evaluate pre-relaxed structures with ReaxFF, MACE, or DFT (via util/vasp/vasp.py); rank by energy; update results DB.
• DB scripts: misc/dbs/db_register_vasp.py, db_add.py.
Stage 5: Visualization & Demos
• Code: misc/Figs/*.py, misc/demos/*.py
• Purpose: Generate publication-quality figures (energy frameworks, distance plots, convergence) and demo scripts for optimization workflows.
Architectural Patterns & Design Principles
• Layered pipeline: clear separation of concerns (data → model → optimization → ranking → visualization).
• Modular Python packages under lego/ for core algorithms.
• Script wrappers at top level for orchestration.
• Utility subfolders (util/, misc/) for cross-cutting concerns (job submission, database, plotting).