Required Input Files

This page summarizes all external files required to run the workflow.

The workflow itself is code-driven, but it depends on a small number of user-provided structure files and a configuration file.

Overview

At minimum, the following files are required:

  1. input.toml (workflow configuration).

  2. Pristine unit-cell structure of the crystal to be doped (POSCAR format)

  3. Optional: host and dopant reference bulk structures (POSCAR format)

All file paths are interpreted relative to the directory containing input.toml unless absolute paths are used.

Directory Layout Example

A clean minimal directory structure may look like:

project_root/
    input.toml
    reference_structures/
        base.POSCAR        # pristine unit cell
        host.POSCAR        # host elemental bulk (for formation energies)
        dopant1.POSCAR     # dopant bulk reference
        dopant2.POSCAR     # dopant bulk reference
        dopant3.POSCAR     # dopant bulk reference
        ...

Notes:

  • All structure files may be placed inside reference_structures/.

  • base.POSCAR is the pristine crystal structure used for supercell generation.

  • The elemental POSCAR files (host.POSCAR, dopant1.POSCAR, dopant2.POSCAR …) are only required if formation energies are computed using local bulk references.

  • The exact filenames are user-defined, but must match what is specified in input.toml.

ALIGNN Model Directory (Environment Variable)

For bandgap prediction (Step 05), a trained ALIGNN model must be available.

The path must be set via environment variable:

export ALIGNN_MODEL_DIR=/path/to/alignn/model

This directory must contain:

  • config.json

  • checkpoint_*.pt

Without this variable, Step 05 will fail.

Important Notes

  • Dopant unit-cell POSCAR files are not required for structure generation. Doping is substitutional and uses the pristine structure only.

  • Dopant bulk POSCAR files are only needed if: - You compute formation energies using local references.

  • The workflow does not require separate dopant unit-cell structures for substitution.

Summary

Minimum to start:

  • input.toml

  • Pristine POSCAR

To enable full workflow including formation energies and bandgaps:

  • Reference bulk structures (or database access)

  • ALIGNN model directory