Sequential Example — Gradual Sb Doping

Purpose

This example performs gradual sequential Sb doping of SnO2.

Use this mode when:

  • You want to increase the dopant concentration step by step.

  • You want each composition to start from the lowest-energy relaxed structure of the previous composition.

  • You want to improve structural optimization along a doping path.

  • You want to recompute formation and mixing energies later using different oxide references without regenerating or relaxing structures.

Workflow

Run the sequential workflow:

dopingflow sequential-run -c input.toml

In mode = "full", each composition step runs:

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

After each step, the lowest-energy relaxed structure is copied to:

sequential_structures/step_xxx_<composition>/best_relaxed/POSCAR

and used as the starting structure for the next composition.

Required Files

The working directory must contain:

input.toml
reference_structures/
    SnO2.POSCAR
    Sb2O5.POSCAR
    O2.POSCAR

  • SnO2.POSCAR: pristine host oxide structure.

  • Sb2O5.POSCAR: dopant oxide reference structure.

  • O2.POSCAR: oxygen gas reference structure.

Example input.toml

[structure]
outdir = "Sb_sequential_SnO2_mace"

[references]
reference_mode = "oxide"
skip_if_done = false
fmax = 0.02
max_steps = 300
tf_threads = 1
omp_threads = 1
device = "cpu"
gpu_id = 0
backend = "mace"
model = "small"
task = ""
optimizer = "bfgs"
host = "SnO2"
host_dir = "reference_structures/"
supercell = [2, 2, 5]
metal_ref = ["Sn", "Sb"]
metals_dir = "reference_structures/"
oxides_ref = ["Sb2O5"]
oxides_dir = "reference_structures/"
gas_ref = "O2"
gas_dir = "reference_structures/"
oxygen_mode = "O-rich"
muO_shift_ev = 0.0

[generate]
poscar_order = ["Sb", "Sn", "O"]
seed_base = 12345

[sequential]
outdir = "sequential_structures"
mode = "full"

[doping]
mode = "enumerate"
host_species = "Sn"
must_include = ["Sb"]
dopants = ["Sb"]
max_dopants_total = 1
allowed_totals = [2.5, 5.0, 7.5, 10.0]
levels = [2.5, 5.0, 7.5, 10.0]

[scan]
backend = "mace"
model = "small"
task = ""
poscar_in = "POSCAR"
topk = 20
symprec = 0.001
n_workers = 8
chunksize = 10
max_enum = 10000
max_unique = 5000
anion_species = ["O"]
skip_if_done = false
mode = "auto"
sample_budget = 10000
sample_batch_size = 20
sample_patience = 60
sample_seed = 42
sample_max_saved = 1000
device = "cpu"
gpu_id = 0

[relax]
backend = "mace"
model = "small"
task = ""
relax_mode = "full"
cell_filter = "frechet"
optimizer = "bfgs"
fmax = 0.05
max_steps = 300
n_workers = 4
tf_threads = 1
omp_threads = 1
skip_if_done = false
skip_candidate_if_done = false
device = "cpu"
gpu_id = 0

[filter]
mode = "window"
window_meV = 50.0
max_candidates = 12
skip_if_done = false

[bandgap]
enabled = false
skip_if_done = false
cutoff = 8.0
max_neighbors = 12
n_workers = 4
device = "cpu"
gpu_id = 0
batch_size = 32

[formation]
skip_if_done = false
normalize = "total"

[database]
skip_if_done = false

Recomputing Energies with a Different Reference

After the full sequential workflow has finished, the same relaxed structures can be reused to recompute formation and mixing energies with a different oxide reference.

For example, change:

oxides_ref = ["Sb2O5"]

to another reference, then rebuild references:

dopingflow refs-build -c input.toml

Then set:

[sequential]
mode = "recompute_energies"

and rerun:

dopingflow sequential-run -c input.toml

This skips:

generate -> scan -> relax -> filter -> bandgap

and reruns only:

formation -> collect

for the existing sequential structures.

Outputs

Each sequential step writes its own folder:

sequential_structures/
    step_001_Sb2p5/
    step_002_Sb5/
    step_003_Sb7p5/
    step_004_Sb10/

Each step contains:

  • input_step.json

  • random_structures/<composition>/

  • best_relaxed/POSCAR

  • results_database.csv

  • sequential_step_summary.json

The final merged database is written to the project root:

results_database.csv