Restricted One-Dimensional Alloy Hull

The alloy-hull stage builds a restricted one-dimensional convex hull for a single substitutional alloy path. For example, for Sb substitution in SnO2 it uses the fixed-composition line:

\[\mathrm{Sn}_{1-x}\mathrm{Sb}_x\mathrm{O}_2.\]

This stage is different from phase-diagram:

  • alloy-hull compares only SnO2-type host, the selected Sb substitutional candidates, and an optional stoichiometrically compatible endpoint such as SbO2.

  • phase-diagram is the full multicomponent Sn-Sb-O stability calculation; it may decompose a candidate into phases outside the Sn_(1-x)Sb_xO2 line.

Energy used for the hull

The stage uses direct relaxed total energies, normalized per cation:

\[e_\sigma = \frac{E_\sigma}{N_{\mathrm{Sn}} + N_{\mathrm{Sb}}}.\]

At each composition, only the lowest-energy candidate is retained. The lower convex envelope is then constructed from these minima, the relaxed host at x = 0, and the endpoint reference at x = 1 when one is available.

For a candidate at x lying between two neighbouring hull vertices (x_1, e_1) and (x_2, e_2), the stage computes:

\[e_{\mathrm{hull}}(x) = e_1 + \frac{x-x_1}{x_2-x_1}(e_2-e_1),\]

and reports:

\[E_{\mathrm{above\ 1D\ hull}}(x) = e_\sigma(x)-e_{\mathrm{hull}}(x).\]

This is reference-independent for a fixed alloy line: adding any term linear in x to every energy, such as the oxide-reference or oxygen-chemical- potential contribution, changes the energy zero and slopes but does not change the hull vertices or energy above the restricted 1D hull.

Configuration

The section is optional. The defaults are appropriate for a single-dopant workflow:

[alloy_hull]
dopant = "auto"
endpoint_reference = "auto"

dopant = "auto" detects the unique dopant in the result database. When multiple dopants are present, specify one explicitly, for example:

[alloy_hull]
dopant = "Sb"
endpoint_reference = "SbO2"

endpoint_reference = "auto" searches the cached oxide references for a binary dopant oxide with the same anion-to-cation ratio as the host line. For SnO2 doped with Sb, it selects SbO2. Set endpoint_reference = "none" to build a hull only over the sampled range; this is useful when no physical x = 1 endpoint has been calculated or cached.

Run

Run after collection:

dopingflow collect -c input.toml
dopingflow alloy-hull -c input.toml

The run-all command also includes this stage between collect and phase-diagram.

Outputs

The stage writes:

  • alloy_hull_results.csv: one row per relaxed candidate, including energy_per_cation_eV, hull_energy_1d_eV_per_cation, energy_above_1d_hull_eV_per_cation, on_1d_hull, and the predicted 1D decomposition between neighbouring hull vertices.

  • alloy_hull_vertices.csv: the actual lower-hull vertices, including host and endpoint reference points.

  • alloy_hull_summary.json: stage metadata and selected endpoint reference.

The same 1D hull fields are also appended to results_database.csv so they can be used directly in Jupyter plotting scripts.