L-G-DCNN

Reproducible implementation of L-G-DCNN for formula-only materials property prediction, with integrated CrabNet and Roost composition-model baselines for controlled comparisons. L-G-DCNN is based on:

Hongwei Du, Jiayu Hui, Lei Zhang, and Hong Wang. Rational Design of Deep Learning Networks Based on a Fusion Strategy for Improved Material Property Predictions. Journal of Chemical Theory and Computation 20, 6756-6771 (2024). DOI: 10.1021/acs.jctc.4c00187

This repository modernizes the original DeepModelFusion code into a scriptable project. The old Windows-only path assumptions and notebook-only workflow have been removed. All three models share the same formula,target input, data splits, trainer, metrics, prediction format, and checkpoint interface; no separate CrabNet or Roost installation is required.

• lgdcnn/: PyTorch implementations of L-G-DCNN, CrabNet, and Roost.
• data/benchmark_data/: 18 original benchmark train/val/test splits.
• data/element_properties/: element embeddings, including mat2vec.csv.
• scripts/: command-line entry points for training, three-model comparison, prediction, benchmarks, committee uncertainty, and case studies.
• examples/: lightweight formation-energy split and representative lithium solid electrolyte formulas.
• docs/paper8/: copied paper8 benchmark summaries used to audit how L-G-DCNN was reused and revalidated there.
• docs/table1_reproduction.md: original Table 1 coverage, published values, aligned Roost rerun summary, and commands for local L-G-DCNN reruns.
• docs/active_learning_uncertainty.md: committee uncertainty workflow and validation gate for active-learning candidate selection.
• docs/uncertainty_case_study.md: committed uncertainty accuracy, reliability, and stability PNG outputs with a conservative gate decision.
• docs/composition_models.md: architecture mapping, upstream CrabNet/Roost references, implementation boundary, and comparison commands.

CrabNet follows Wang et al. (2021), DOI 10.1038/s41524-021-00545-1, and its official implementation. Roost follows Goodall and Lee (2020), DOI 10.1038/s41467-020-19964-7, and its official implementation. Both local versions are native adaptations to this repository's padded formula interface. See docs/composition_models.md.

cd L-G-DCNN
python -m pip install -e .

Or with conda:

conda env create -f environment.yml
conda activate lgdcnn
python -m pip install -e .

This trains a tiny demonstration model and predicts representative solid electrolyte formulas. It checks that the workflow is functional; it is not a high-accuracy pretrained checkpoint.

python scripts/run_sse_case.py

Outputs:

• runs/sse_case/checkpoint.pt
• runs/sse_case/metrics.json
• runs/sse_case/solid_electrolyte_predictions.csv

lgdcnn train \
  --model lgdcnn \
  --train-csv data/benchmark_data/OQMD_Formation_Enthalpy/train.csv \
  --val-csv data/benchmark_data/OQMD_Formation_Enthalpy/val.csv \
  --test-csv data/benchmark_data/OQMD_Formation_Enthalpy/test.csv \
  --output-dir runs/OQMD_Formation_Enthalpy \
  --epochs 300 \
  --batch-size 256 \
  --d-model 512 \
  --hidden-dim 256 \
  --filter-map 512

Choose CrabNet or Roost without changing the CSV files:

lgdcnn train \
  --model crabnet \
  --train-csv examples/formation_energy_small/train.csv \
  --val-csv examples/formation_energy_small/val.csv \
  --test-csv examples/formation_energy_small/test.csv \
  --output-dir runs/crabnet_example \
  --epochs 20

lgdcnn train \
  --model roost \
  --train-csv examples/formation_energy_small/train.csv \
  --val-csv examples/formation_energy_small/val.csv \
  --test-csv examples/formation_energy_small/test.csv \
  --output-dir runs/roost_example \
  --epochs 20

The comparison command trains each model on exactly the same supplied rows and writes a combined metric table:

lgdcnn compare \
  --train-csv examples/formation_energy_small/train.csv \
  --val-csv examples/formation_energy_small/val.csv \
  --test-csv examples/formation_energy_small/test.csv \
  --output-dir runs/composition_comparison \
  --epochs 20 \
  --batch-size 64

Outputs are stored under runs/composition_comparison/{lgdcnn,crabnet,roost}/, with the aggregate result in runs/composition_comparison/summary.csv. Use --models crabnet roost to run a subset. Architecture-specific controls are listed by lgdcnn compare --help and documented in docs/composition_models.md.

For a fast CPU check, reduce the model and epochs:

lgdcnn train \
  --train-csv examples/formation_energy_small/train.csv \
  --val-csv examples/formation_energy_small/val.csv \
  --test-csv examples/formation_energy_small/test.csv \
  --output-dir runs/example_cpu \
  --epochs 3 \
  --batch-size 16 \
  --d-model 64 \
  --hidden-dim 32 \
  --filter-map 64 \
  --blocks 1 \
  --fraction-noise 0

lgdcnn predict \
  --checkpoint runs/OQMD_Formation_Enthalpy/checkpoint.pt \
  --csv examples/solid_electrolyte_formulas.csv \
  --output-csv runs/OQMD_Formation_Enthalpy/sse_predictions.csv

Input CSV must contain a formula column. A target column is optional for prediction and required for evaluation.

The single-model uncertainty output is not treated as a production acquisition signal. For active learning, train a seed-diverse committee, aggregate prediction_mean, epistemic_std, aleatoric_mean, and total_uncertainty, then validate that uncertainty ranks labelled errors before selecting candidates.

python scripts/train_lgdcnn_committee.py \
  --train-csv examples/formation_energy_small/train.csv \
  --val-csv examples/formation_energy_small/val.csv \
  --output-dir runs/example_committee \
  --n-members 5 \
  --epochs 300 \
  --batch-size 256

python scripts/predict_lgdcnn_committee.py \
  --committee-manifest runs/example_committee/committee_manifest.csv \
  --csv examples/solid_electrolyte_formulas.csv \
  --output-csv runs/example_committee/sse_committee_predictions.csv

Selection with scripts/select_lgdcnn_candidates.py requires a passed validation JSON unless --allow-uncalibrated is explicitly supplied. See docs/active_learning_uncertainty.md and docs/uncertainty_case_study.md.

lgdcnn benchmark \
  --model lgdcnn \
  --datasets aflow__ael_bulk_modulus_vrh mp_e_hull OQMD_Formation_Enthalpy \
  --output-dir runs/benchmarks \
  --epochs 300 \
  --batch-size 256

Omit --datasets to run all 18 bundled datasets. Set --model crabnet or --model roost to benchmark either integrated baseline with the same workflow.

The original Table 1 Matbench task set is covered in three layers:

• published L-G-DCNN/L-G-DCNN-V1/CrabNet/Finder values are captured in docs/paper8/original_table1_published_values.csv;
• aligned Roost reruns cover all 10 tasks x 5 official folds in docs/paper8/table1_three_model_mae_summary.csv;
• scripts/prepare_matbench_table1_splits.py and scripts/run_matbench_table1_lgdcnn.py regenerate Matbench formula-only splits and run L-G-DCNN on selected or all folds.

See docs/table1_reproduction.md for the exact commands and the current evidence boundary.

Before pushing this repository to GitHub, run the strict release audit:

python scripts/pre_push_audit.py

The audit checks release files, sensitive/local paths, large artifacts, data integrity, Python compilation, unit tests, CLI help, the small case study, and committee uncertainty PNG/JSON/CSV assets, and a benchmark smoke run. Do not push if it exits nonzero. See docs/pre_push_review.md.

paper8 is a partial, auditable reproduction and extension of the L-G-DCNN evidence needed for the paper8 screening workflow, not a full reproduction of every original L-G-DCNN table and visualization. See docs/reproduction_status.md and docs/table1_reproduction.md.

GPL-3.0-only, consistent with the original DeepModelFusion repository.