Explicit Example — Single Target Composition
=============================================

Purpose
-------

This example generates and evaluates **one explicit co-doped composition**.

Use this mode when:
- You already know the exact dopant percentages.
- You want exactly one generated structure per composition.
- You want the full workflow executed (00–07).

Workflow
--------

Run the complete pipeline:

::

   dopingflow run-all -c input.toml


Required Files
--------------

The working directory must contain:

::

   input.toml
   reference_structures/
       base.POSCAR
       Sn.POSCAR
       Sb.POSCAR
       Zr.POSCAR

- ``base.POSCAR``: pristine unit cell.
- Elemental ``*.POSCAR``: bulk reference structures for chemical potentials.


Example input.toml
------------------

::

   [structure]
   outdir = "random_structures"

   [references]
   reference_mode = "metal"
   host = "SnO2"
   host_dir = "reference_structures/"
   supercell = [ 5, 2, 1]
   metals_ref = [ "Zr","Sb","Sn"]
   oxides_dir = "reference_structures/"
   fmax = 0.02
   skip_if_done = false

   [doping]
   mode = "explicit"
   host_species = "Sn"
   compositions = [
   { Sb = 5.0, Zr = 5.0 }
   ]

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

   [scan]
   poscar_in = "POSCAR"
   topk = 10
   symprec = 1e-3
   max_enum = 10
   n_workers = 4
   chunksize = 10
   anion_species = ["O"]
   max_unique = 50000
   skip_if_done = false
   mode = "auto"
   sample_budget = 5000
   sample_batch_size = 64
   sample_patience = 1000
   sample_seed = 42
   sample_max_saved = 10000
   device = "cpu"

   [relax]
   fmax = 0.05
   n_workers = 4
   tf_threads = 1
   omp_threads = 1
   skip_if_done = true
   skip_candidate_if_done = true
   device = "cpu"

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

   [bandgap]
   skip_if_done = false
   cutoff = 8.0
   max_neighbors = 12
   n_workers = 4
   device = "cpu"

   [formation]
   skip_if_done = true
   normalize = "per_dopant"

   [database]



Outputs
-------

- ``reference_structures/reference_energies.json``
- ``random_structures/<composition>/``
  - ``ranking_scan.csv``
  - ``ranking_relax.csv``
  - ``ranking_relax_filtered.csv``
  - ``bandgap_alignn_summary.csv``
  - ``formation_energies.csv``
- ``results_database.csv``