Installation, Usage, and Outputs

This page explains how to install dopingflow and how to run the workflow either step-by-step or using the single orchestration command.

Installation

Clone the repository and install in editable mode:

git clone KazemZh/dopingflow
cd dopingflow
python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .

Verify the CLI is available:

dopingflow --help

Required Inputs

Refer to Required Input Files page.

Running the Workflow

All commands accept -c/--config to specify the TOML file. If omitted, input.toml in the current directory is used.

Run the full pipeline with one command

To run the complete workflow in order:

dopingflow run-all -c input.toml

This executes:

refs -> generate -> scan -> relax -> filter -> bandgap -> formation -> collect

Resuming and partial runs (run-all)

You can resume from a given stage:

dopingflow run-all -c input.toml --from relax

You can stop at a stage (inclusive). This is useful if you do not want to run bandgap yet:

dopingflow run-all -c input.toml --until filter

You can print the planned steps without running them:

dopingflow run-all -c input.toml --dry-run

You can run only a subset of steps inside a selected range:

dopingflow run-all -c input.toml --from refs --until collect --only refs,generate,scan

Filtering controls inside run-all

The filter stage supports optional overrides (passed through by run-all):

  • Restrict filtering to a single composition folder:

    dopingflow run-all -c input.toml --from relax --until filter --filter-only Sb5_Zr5

  • Force re-filtering even if outputs exist:

    dopingflow run-all -c input.toml --from filter --until filter --force

  • Override filtering mode by specifying one of:

    dopingflow run-all -c input.toml --from filter --until filter --window-mev 50
dopingflow run-all -c input.toml --from filter --until filter --topn 12

Step-by-step execution

Step 00: reference energies:

dopingflow refs-build -c input.toml

Step 01: structure generation:

dopingflow generate -c input.toml

Step 02: scan (symmetry-unique enumeration + M3GNet single-point energies):

dopingflow scan -c input.toml

Step 03: relax scanned candidates (M3GNet Relaxer):

dopingflow relax -c input.toml

Step 04: filter relaxed candidates:

dopingflow filter -c input.toml

Optional Step 05: predict bandgap (ALIGNN):

Before running bandgap, set the model path:

export ALIGNN_MODEL_DIR=/path/to/your/alignn/model_root
dopingflow bandgap -c input.toml

Step 06: formation energies:

dopingflow formation -c input.toml

Step 07: collect results into one CSV database:

dopingflow collect -c input.toml

Outputs Overview

This section summarizes the main outputs created by each stage.

Step 00 (refs-build)

Writes:

  • reference_structures/reference_energies.json

This file contains:

  • the relaxed pristine supercell energy

  • per-atom chemical potentials for host and dopant species

  • metadata about reference structures and relaxation settings

Step 01 (generate)

Writes a structure folder per composition under [structure].outdir (default: random_structures):

  • <outdir>/<composition_tag>/POSCAR

  • <outdir>/<composition_tag>/metadata.json

Step 02 (scan)

Inside each <composition_tag>/ folder, writes:

  • ranking_scan.csv (top-k single-point energies)

  • scan_summary.txt (human-readable summary)

  • candidate structures:

    <composition_tag>/candidate_###/01_scan/POSCAR
<composition_tag>/candidate_###/01_scan/meta.json

Step 03 (relax)

For each candidate:

  • candidate_###/02_relax/POSCAR

  • candidate_###/02_relax/meta.json

Also writes per composition folder:

  • ranking_relax.csv

Step 04 (filter)

Writes per composition folder:

  • ranking_relax_filtered.csv (filtered candidate table)

  • selected_candidates.txt (names of kept candidates)

Step 05 (bandgap)

Writes per composition folder:

  • bandgap_alignn_summary.csv

Writes per candidate:

  • candidate_###/03_band/meta.json

Step 06 (formation)

Writes per composition folder:

  • formation_energies.csv

Writes per candidate:

  • candidate_###/04_formation/meta.json

Step 07 (collect)

Writes one flat CSV in the workflow root:

  • results_database.csv

This file is a compact “database view” across compositions and selected candidates, combining scan/relax/filter/bandgap/formation results where available.

Tips

  • Use --verbose with any command for more detailed logs:

    dopingflow run-all -c input.toml --verbose

  • If bandgap is not configured yet (no ALIGNN_MODEL_DIR), stop before bandgap:

    dopingflow run-all -c input.toml --until filter