dopingflow

High-throughput ML-driven doping workflow for materials screening.

dopingflow is a modular CLI pipeline for automated generation, screening, relaxation, and evaluation of doped crystal structures using machine-learning interatomic potentials and graph neural networks.

Designed for reproducible, scalable materials discovery workflows.

---

📘 Documentation

The full documentation is available in multiple formats:

• 🌐 Online HTML (auto-deployed via GitHub Actions):
  https://kazemzh.github.io/dopingflow/

• 📄 User Guide (PDF):
  Download dopingflow User Guide

---

Installation

Clone repository

git clone https://github.com/KazemZh/dopingflow.git
cd ml-doping-workflow

Create environment

conda create -n dopingflow python=3.11
conda activate dopingflow

Install Packages

⚠️ Choose only one backend between M3GNet and UMA. They require incompatible versions of numpy and ase. Do not install both in the same environment!

MACE backend:

pip install -e ".[mace]"

GRACE backend:

pip install -e ".[grace]"

M3GNet backend:

pip install -e ".[m3gnet]"

UMA backend:

pip install -e ".[uma]"

Requires Hugging Face access (see setup below).

UMA Backend Setup

The UMA backend is provided through FAIR-Chem and requires access to the pretrained UMA models hosted on Hugging Face.

1. Request access to the UMA model repository
   https://huggingface.co/facebook/UMA

2. Log in to Hugging Face

After access is granted, authenticate in your UMA environment:

hf auth login

ALIGNN Backend:

pip install -e ".[alignn]"

GUI:

pip install -e ".[gui]"

Material Project API:

pip install -e ".[mp]"

Development tools:

pip install -e ".[dev]"

---

Required Environment Variables

ALIGNN model directory (required for bandgap step)

export ALIGNN_MODEL_DIR=/path/to/alignn/model

Materials Project API (optional)

export MP_API_KEY=your_api_key

---

Workflow Commands

Each stage can be run individually:

dopingflow refs-build -c input.toml
dopingflow generate -c input.toml
dopingflow scan -c input.toml
dopingflow relax -c input.toml
dopingflow filter -c input.toml
dopingflow bandgap -c input.toml
dopingflow formation -c input.toml
dopingflow collect -c input.toml
dopingflow alloy-hull -c input.toml
dopingflow phase-diagram -c input.toml
dopingflow surface -c input.toml

Or run the complete pipeline:

dopingflow run-all -c input.toml

For gradual composition-by-composition doping, use sequential-run. This reuses the lowest-energy relaxed structure from each composition as the base for the next composition:

dopingflow sequential-run -c input.toml

---

Logging

Logs are written to:

logs/dopingflow.log

Use --verbose for detailed output.

---

Graphical User Interface (Streamlit)

dopingflow provides an optional Streamlit-based graphical user interface for interactive workflow configuration, execution, and results analysis.

The GUI allows you to:

• Build and edit input.toml
• Run workflow stages interactively
• Visualize generated structures
• Explore results_database.csv and per-system phase-diagram CSVs with Plotly

Relative-energy controls remain inside the existing [formation] section:

[formation]
relative_enabled = true
endpoint_x = "auto"

Launch the GUI

From the project root directory:

streamlit run gui/app.py

After launching, a local browser window will open automatically.

---

Project Structure

.
├── CHANGELOG.md
├── docs
│   ├── make.bat
│   ├── Makefile
│   └── source
│       ├── api
│       │   ├── dopingflow.rst
│       │   └── modules.rst
│       ├── conf.py
│       ├── examples
│       │   ├── enumerate_screening.rst
│       │   ├── explicit_batch.rst
│       │   ├── explicit_single_oxides.rst
│       │   ├── explicit_single.rst
│       │   ├── smoke_test.rst
│       │   └── sequential_workflow.rst
│       ├── index.rst
│       ├── input_file.rst
│       ├── installation_and_usage.rst
│       ├── methods
│       │   ├── bandgap.rst
│       │   ├── database.rst
│       │   ├── filtering.rst
│       │   ├── formation_energy.rst
│       │   ├── generation.rst
│       │   ├── phase_diagram.rst
│       │   ├── references.rst
│       │   ├── relaxation.rst
│       │   ├── sequential.rst
│       │   ├── scanning.rst
│       │   └── surfaces.rst
│       ├── required_inputs.rst
│       ├── _static
│       │   ├── .gitkeep
│       │   └── logo.png
│       ├── _templates
│       └── workflow_overview.rst
├── dopingflow-user-guide.pdf
├── examples
│   ├── enumerate_screening
│   ├── explicit_batch
│   ├── explicit_single_composition
│   ├── explicit_single_composition_oxide_reference
│   ├── smoke_test
│   └── surface_creation
├── .github
│   └── workflows
│       └── docs.yml
├── .gitignore
├── gui
│   ├── app.py
│   ├── gui_config.py
│   ├── io_project.py
│   ├── README.md
│   └── view_structure.py
├── input.toml
├── LICENSE
├── logo.png
├── pyproject.toml
├── README.md
├── src
│   └── dopingflow
│       ├── bandgap.py
│       ├── cli.py
│       ├── collect.py
│       ├── filtering.py
│       ├── formation.py
│       ├── generate.py
│       ├── hardware.py
│       ├── __init__.py
│       ├── logging.py
│       ├── ml_backends.py
│       ├── ml_relaxation.py
│       ├── phase_diagram.py
│       ├── refs.py
│       ├── relax.py
│       ├── scan.py
│       ├── sequential.py
│       ├── surface.py
│       └── utils
│           ├── io.py
│           ├── parallel.py
│           └── pymatgen_helpers.py
└── tests
    ├── test_cli_help.py
    ├── test_cli.py
    ├── test_generate_minimal.py
    └── test_imports.py

---

License

Proprietary and confidential.

© 2026 Kazem Zhour
RWTH Aachen University

Unauthorized use, modification, or distribution is prohibited.

---

Author

Kazem Zhour
RWTH Aachen University