Multiple Oxide References and Relative Energies
===============================================

This example evaluates Sb-doped SnO2 against three separate Sb oxide references.
The workflow keeps **one candidate per row** and writes a separate column for
all energies calculated from each oxide reference.

Configuration
-------------

Add every required binary oxide to the existing ``[references].oxides_ref`` list::

   [references]
   reference_mode = "oxide"
   host = "SnO2"
   host_dir = "reference_structures/"
   supercell = [2, 2, 5]
   oxides_dir = "reference_structures/"
   oxides_ref = ["SbO2", "Sb2O3", "Sb2O5"]
   gas_ref = "O2"
   gas_dir = "reference_structures/"

   [formation]
   skip_if_done = false
   normalize = "per_dopant"
   relative_enabled = true
   endpoint_x = "auto"

Both relative-energy parameters remain directly inside the existing
``[formation]`` section. No nested configuration section is required.
``"auto"`` identifies the pure oxide endmember and is recorded as
``endpoint_x = 1.0`` in the output metadata.

Place one POSCAR file for every oxide in ``reference_structures/``:

::

   reference_structures/SbO2.POSCAR
   reference_structures/Sb2O3.POSCAR
   reference_structures/Sb2O5.POSCAR

Then rebuild the cached reference energies before calculating formation
energies::

   dopingflow refs-build -c input.toml
   dopingflow formation -c input.toml
   dopingflow collect -c input.toml

Wide output format
------------------

For one Sb-doped candidate, the output remains one row. The oxide choice is
encoded in the column suffix::

   candidate,x_dopant,E_form_eV_total__SbO2,E_form_eV_total__Sb2O3,E_form_eV_total__Sb2O5,...
   candidate_000,0.05,...,...,...,...

The following values are written for every oxide reference:

- ``E_form_eV_total__<reference>``
- ``E_form_eV_per_atom__<reference>``
- ``E_form_eV_per_cation__<reference>``
- ``E_form_eV_per_dopant__<reference>``
- ``E_mix_eV_total__<reference>``
- ``E_mix_eV_per_atom__<reference>``
- ``E_mix_eV_per_cation__<reference>``
- ``E_mix_eV_per_dopant__<reference>``
- ``E_form_rel_eV_per_cation__<reference>``
- ``E_mix_rel_eV_per_cation__<reference>``

Relative-energy definition
--------------------------

The oxide chemical potentials and atom-balanced mixing reaction already place
each candidate on the host-oxide/dopant-oxide tie-line reference. Applying a
second database-derived endpoint subtraction would double-correct the energy.
Therefore the relative per-cation columns preserve the corresponding
oxide-referenced formation and mixing values. The pure oxide endpoint energy,
the composition-weighted co-doping correction, and the reference identity are
written as separate provenance columns.

Collection and sequential merging preserve these formation-stage values. The
legacy database endpoint calculation is used only when reading an older result
database that has absolute reference-specific columns but no relative columns.

Co-doping
---------

For co-doping, dopingflow evaluates all valid combinations of the listed
binary oxide references. For example, Sb2O3 together with TiO2 is written as
one suffix::

   E_mix_eV_per_cation__Sb2O3__TiO2

The dopant order in these combined suffixes is alphabetical and deterministic.