3. Candidate Relaxation

Implementation

This stage is implemented in:

src/dopingflow/relax.py

The public entry point is:

run_relax(...)

Purpose

This stage performs full structural relaxation of the low-energy candidates selected during the scanning stage.

For each candidate structure:

  • atomic positions are relaxed

  • lattice vectors are relaxed

  • the final total energy is extracted

  • relaxed structures are written to disk

  • a relaxation ranking is generated

This stage refines the single-point screening results by allowing full geometry optimization.

Inputs

This stage uses settings from the following sections of input.toml:

  • [structure]: provides the output directory containing structure folders.

  • [generate]: provides the species ordering used when writing POSCAR files.

  • [relax]: controls convergence tolerance, parallelism, and skipping logic.

The relaxation stage processes:

<outdir>/<structure_folder>/candidate_*/01_scan/POSCAR

Method Summary

For each structure folder inside [structure].outdir:

  1. Detect all candidate_* subfolders.

  2. For each candidate: a. Read 01_scan/POSCAR. b. Perform full structural relaxation. c. Write relaxed structure to 02_relax/POSCAR. d. Write relaxation metadata.

  3. Rank candidates by relaxed total energy.

  4. Write ranking_relax.csv per structure folder.

Relaxation Model

Structural relaxation is performed using:

  • Interatomic potential: M3GNet (pretrained)

  • Optimizer: internal Relaxer (FIRE-based)

  • Convergence criterion: maximum force below [relax].fmax

Both:

  • atomic coordinates

  • lattice parameters

are allowed to relax.

Parallel Execution

Relaxation is parallelized over candidates using multiprocessing.

Each worker process:

  • initializes its own M3GNet Relaxer instance

  • sets thread limits to control TensorFlow and OpenMP usage

  • runs independently

The number of parallel workers is controlled by:

[relax]
n_workers = ...

Additional thread control parameters:

tf_threads
omp_threads

These settings allow tuning CPU usage on workstations or HPC systems.

Ranking Logic

After all candidates are processed within a structure folder:

  • Only successfully relaxed candidates (status ok) are ranked.

  • Ranking is based on ascending relaxed total energy.

The resulting CSV file:

ranking_relax.csv

contains:

  • candidate name

  • relaxed rank

  • relaxed energy

  • original single-point rank

  • original single-point energy

  • signature

  • status

  • walltime

  • error message (if any)

Reproducibility and Skipping

Two levels of skipping are supported:

Folder-level skipping

If:

[relax].skip_if_done = true

and ranking_relax.csv already exists in a structure folder, the entire folder is skipped.

Candidate-level skipping

If:

[relax].skip_candidate_if_done = true

and:

candidate_*/02_relax/meta.json
candidate_*/02_relax/POSCAR

already exist, that individual candidate is skipped.

This enables safe restart of interrupted runs.

Outputs

For each candidate:

candidate_###/
    01_scan/
    02_relax/
        POSCAR
        meta.json

The relaxation metadata includes:

  • relaxed total energy

  • walltime

  • species counts

  • convergence target (fmax)

  • link to original scan metadata

For each structure folder:

ranking_relax.csv

which ranks relaxed candidates by energy.

Error Handling

If relaxation fails:

  • an error is written to 02_relax/meta.json

  • the candidate is marked with status fail

  • ranking proceeds with remaining successful candidates

Failures do not abort the entire structure folder.

Notes and Limitations

  • Relaxation uses a pretrained ML potential (not DFT-level relaxation).

  • No charge states or external fields are included.

  • No temperature or vibrational effects are considered.

  • Energies are total energies from the ML model.

  • Convergence depends on the chosen fmax threshold.

  • Parallel performance depends on CPU availability and thread configuration.