SALSA

SALSA: Substitution Approximation evoLutionary Search and Ab initio

Materials-discovery and thermodynamic-stability workflow (v2.0.0)

• Combines empirical ionic substitution probabilities, compositional property interpolation, evolutionary crystal structure prediction (USPEX), and hybrid-DFT electronic-structure calculations (CRYSTAL23) to discover earth-abundant semiconductors for photovoltaics and photocatalytic water splitting.

• New in v2.0.0 (Stage 5): Automated hybrid-DFT convex-hull phase stability analysis and chemical-potential stability diagrams across single-point (SP), enthalpy (H), and Gibbs free energy (G) levels, integrating competing phases scraped from AFLOW (AFLUX) and the Materials Project.

• Strictly structure-keyed provenance (structure_id rather than collapsed composition formulas) to preserve polymorph energetics across all stages.

• Software Developers: M. Djokic, G. Martinez, R. Yarlagadda, K. Shih, A. Aduenko, and J. L. Mendoza-Cortés

• Related Publications:

  • Stages 1–4 (SALSA Method): S. M. Stafford, A. Aduenko, M. Djokic, Y.-H. Lin, and J. L. Mendoza-Cortés, Transforming materials discovery for artificial photosynthesis: High-throughput screening of earth-abundant semiconductors, J. Appl. Phys. 134, 235706 (2023) (arXiv:2310.00118).

  • Stage 5 (Convex-Hull Extension): M. Djokic, A. M. Gaona-Carranza, G. Martinez, Y.-H. Lin, and J. L. Mendoza-Cortés, Can We Predict Synthesizability? First-Principles Chemical-Potential Stability Diagrams for the Design of Earth-Abundant Photocatalytic Semiconductors: The SALSA Method Extended for Convex Hull Analysis (in preparation).

• Links: GitHub Repository (mendozacortesgroup/SALSA) | Zenodo v2.0.0 (DOI: 10.5281/zenodo.23045852) | Zenodo v1.0.0 (DOI: 10.5281/zenodo.23045693)

Where to Start (Setup & Prerequisites)

• 1. Prerequisites: Requires Python 3.10+ and jq (used by setup_project.sh to parse defaults.json). For Stage 3 structure prediction, ensure USPEX is configured (see the USPEX Wiki Page).

• 2. Install Python Dependencies:pip install --user -r requirements.txt

• 3. Configure Environment Variables (~/.bashrc): Run setup_env.sh from the repository root to automatically set SALSA_DIR (and optionally VASP_PP_PATH for Stage 3):./setup_env.sh./setup_env.sh /path/to/vasp/potentials./setup_env.sh --print(Ensure your ~/.bashrc also exports MCRROOT, USPEXPATH, PATH, and PYTHONPATH for USPEX v10.5).

• 4. Populate VASP POTCARs (Required for Stage 3 Only): VASP PAW pseudopotentials (potpaw_PBE) are proprietary and not distributed in the repo. Populate 3. USPEX_setup/POTCARs/ using:"3. USPEX_setup/USPEX_scripts/compile_POTCARs_locally.sh" /path/to/potpaw_PBE(Stages 1, 2, 4, and 5 do not require VASP).

• 5. Initialize & Manage a Project: Run SALSA_WorkFlow_Manager.py (or setup_project.sh) to create an isolated project workspace inside Projects/<project_name>/ and link reference datasets from original_datasets/ and data/.

The 5-Stage SALSA v2.0 Workflow

• Stage 1 — Substitution (1. Substitution/):

  • generate_substitutions_textual.py, icsd_parser.py, and Semiconductors_Workflow.py parse ICSD-compositions.csv and Element_Charge_Dictionary.txt into charge-balanced ionic compositions, count single-ion exchanges across identical chemical environments, normalize by the geometric mean of ion occurrences, and output the empirical substitution probability matrix (substitutions_textual.txt and substitution_matrix_alpha.png, where alpha_AB > 1 indicates above-average substitutability).

• Stage 2 — Approximation (2. Approximation/):

  • GenerateCandidateCompoundInventory.py combines known semiconductors (known_compositions_and_properties.csv) with substitutions_textual.txt to interpolate charge-neutral hybrid compositions, predict band gaps and redox potentials via weighted per-atom linear interpolation, and filter against property_space_selection_criteria.csv to export new_candidate_compound_inventory.csv.

• Stage 3 — Evolutionary Structure Search (3. USPEX_setup/ & propagate.py):

  • Automatically populates reusable DefaultUSPEXinput templates and USPEX_scripts to launch evolutionary crystal structure prediction on candidate compositions.

• Stage 4 — Hybrid-DFT Electronic Structure (4. CRYSTAL_setup/ & propagate.py):

  • Prepares CRYSTAL23 inputs (DefaultCRYSTALinput and DefaultBasisSetsCRYSTAL) for geometry optimization (OPT2), single-point electronic structure (SP), and vibrational frequencies (FREQ).

• Stage 5 — Convex-Hull & Chemical-Potential Stability (5. ConvexHullAnalysis/):

  • Materials_Scraper.py: Queries competing phases from AFLOW (AFLUX) and the Materials Project (mp-select, mp-coverage, mp-formation).

  • ConvexHullStability.py: Constructs GGA reference hulls and identifies near-hull competing phases for hybrid-DFT recalculation.

  • generate_cifs.py: Exports CIFs of competing phases ready for Stage 4 CRYSTAL23 calculations.

  • Results_Aggregator.py: Parses CRYSTAL23 outputs (OPT2/, SP/, FREQ/) into structure-keyed tables (crystal_hull_data.csv and crystal_hull_references.json).

  • make_paper_figures.py & Hull_Plotter.py: Generates publication convex hulls, chemical-potential stability diagrams, leave-one-out stability tables (target_stability.csv, leave_one_out_G.csv), and multi-level (SP, H, G) hull animations.

Reproducing the Stage 5 Convex-Hull Analysis & Tests

• Run the built-in unit test suite (uses synthetic data; no external deposit needed): python -m pytest "5. ConvexHullAnalysis/tests"

• Reproduce the convex-hull dataset and figures from the data deposit (for large raw CRYSTAL23 output deposits, use the Zenodo deposit or Group Dropbox rather than hosting outputs on the Wiki):
  cd "5. ConvexHullAnalysis"
  
  python Results_Aggregator.py aggregate --results-dir <deposit> --output-dir out --se-placeholder --with-bonding --with-cifs
  
  python make_paper_figures.py --input out/crystal_hull_data.csv --references out/crystal_hull_references.json --bonding-cache out/crystal_sp_bonding_cache.json --aflow-dir <deposit>/processed/pbe_reference/aflow --mp-cache <deposit>/processed/pbe_reference/mp_formation_energies_rawPBE.json --targets Ag4Br2S,Ag4Cl2S,Ag4Cl2Se,Ag4Cl2Te1,Ti2O4Pb3Se3,PbCuSeCl --output-dir Fig

Citing SALSA

• Software (v2.0.0): M. Djokic, G. Martinez, R. Yarlagadda, K. Shih, A. Aduenko, and J. L. Mendoza-Cortés, SALSA: Substitution Approximation evoLutionary Search and Ab-initio, version 2.0.0, Zenodo (2026). https://doi.org/10.5281/zenodo.23045852 (v1.0.0 Steps 1–4: https://doi.org/10.5281/zenodo.23045693).

• Primary Method Paper (Stages 1–4): S. M. Stafford, A. Aduenko, M. Djokic, Y.-H. Lin, and J. L. Mendoza-Cortés, J. Appl. Phys. 134, 235706 (2023). https://doi.org/10.1063/5.0178907.

• Convex-Hull Stability Extension (Stage 5): M. Djokic, A. M. Gaona-Carranza, G. Martinez, Y.-H. Lin, and J. L. Mendoza-Cortés, Can We Predict Synthesizability? First-Principles Chemical-Potential Stability Diagrams for the Design of Earth-Abundant Photocatalytic Semiconductors: The SALSA Method Extended for Convex Hull Analysis (in preparation).