MatCascade

Hierarchical multi-model materials screening and validation.

MatCascade is a general workflow for cascading composition, structure, multi-property, dynamic, and independent-validation models across large materials spaces. This repository provides a frozen application snapshot and the submission dataset accompanying “A Hierarchical Synergistic Deep Learning Framework Integrating Composition, Structure, and Ionic Transport for Solid-State Electrolyte Discovery.” It contains the screening code, auditable candidate lists at the manuscript's key screening nodes, crystal structures for the 124 transport candidates and final 97 hits, and processed transport, E/F/S, and BVSE validation results.

What is included

Manuscript stage	Candidate count	Repository record
Alex/ICSD-derived generated space	30,364,908	Count, method, and input contract; raw licensed structures are not redistributed
Composition formation-energy screen	5,068,744	Count and criterion
Structure-sensitive static screen	14,596	Count and criteria
Electrochemical/mechanical/availability screen	1,251	Material-ID/formula manifest reconstructed from the frozen workflow inventory
300 K transport pre-screen	124	Full property table, embedded-CIF JSON, and 124 standalone CIFs
Final conductivity/MSD consensus	97 pass + 27 fail	Complete split, standalone CIFs, and trajectory-quality diagnostics

The repository also includes:

• processed E/F/S-to-DFT validation arrays and per-structure summaries for 916 structures;
• CAVD+BVSE cross-validation for the broad pool and all 97 final candidates (96 applicable/completed and one chemically not applicable);
• final-97 Li-MSD and jump-network connectivity figures;
• tested, model-agnostic filtering and final-selection commands;
• optional heavy-stage entry points for candidate generation, property prediction, MD, and validation, plus the DFT-labeling interface contract.

Quick verification

The core release audit uses only the Python standard library:

python scripts/check_release.py

For the complete processed-result verification and test suite, use Python 3.11 or newer:

python -m pip install -r requirements/reproducibility-lock.txt
python -m pip install -e . --no-deps
python scripts/reproduce_processed_results.py
python -m pytest

The installed command-line tool exposes the same integrity and final-split operations:

matcascade audit --repo .
matcascade select-final \
  data/candidates/candidates_124.json \
  /tmp/final_97.json \
  --failed-output /tmp/below_threshold_27.json \
  --threshold 0.1

Re-running the workflow

The lightweight stages consume ordinary JSON/CSV tables and are immediately testable. The large prediction and simulation stages additionally require the model packages, model checkpoints, licensed source structures, and compute resources described in docs/REPRODUCIBILITY.md. No API key, trained checkpoint, raw trajectory, VASP output, or proprietary ICSD record is stored in this repository.

The exact public/private boundary for every stage is summarized in docs/REPRODUCTION_MATRIX.md. In particular, the released snapshot supports exact identity/count verification at the 1,251-candidate node, exact reconstruction of the 124-to-97/27 final split, and exact recomputation of the processed E/F/S and BVSE statistics. It does not by itself constitute a fresh end-to-end rerun from the licensed 30-million-structure source space or reproduce the omitted 1,251-to-124 MD campaign.

Start with:

1. docs/WORKFLOW.md for the stage-by-stage commands;
2. docs/DATA_DICTIONARY.md for released fields;
3. docs/DATA_PROVENANCE.md for source and licensing boundaries;
4. docs/MANUSCRIPT_DATA_MAP.md for manuscript-to-file correspondence;
5. docs/MODEL_INTERFACES.md for model handoff schemas; and
6. environment/model_artifacts.json for upstream commit pins and external-artifact SHA-256 digests.

Release status

This is a frozen submission dataset, not a live production database. The primary final conductivity field is conductivity_300K_mS_cm; auxiliary MSD values are trajectory diagnostics and must not be interpreted as additional, independent conductivity estimates. No software license is granted until the authors select one for the public release.