pycalphad: TDB equilibrium calculations

When to use

Use for equilibrium phase fractions and compositions at a fixed bulk elemental mole composition, specified pressure, and a list of finite temperatures. The bundled helper executes real pycalphad equilibria, checks mass balance, repeats at greater sampling density, and exports each stable composition set separately.

Equilibrium is constrained by the selected database, components, phases, and conditions. It does not predict precipitation rates, retained metastable microstructures, or properties of phases missing from the database. Successful numerical checks do not establish the database's experimental accuracy.

Workflow

1. Identify the TDB's source, license, assessment/publication, valid temperature/pressure and composition range, and required elements. Use the user's database for real alloys. The bundled assets/ideal-cu-ni.tdb is an original hypothetical teaching model, not an assessed Cu-Ni database.
2. Inspect database elements and phases. Select the relevant phases deliberately; record exclusions because they can turn the calculation into a metastable constrained result. Include VA where required by sublattice models. Vacancies are not an independent bulk mole fraction. Keep coupled order/disorder definitions in the TDB, but do not select both partners as separate candidates when the ordered model already includes the disordered contribution; the helper rejects such filtered candidate lists.
3. Copy assets/equilibrium.json. Specify exactly N-1 elemental mole fractions and one dependent non-vacancy element. The dependent fraction is 1 - sum(independent fractions); fractions are not silently normalized. Set K and Pa. Convert weight percentages or mass fractions before using this helper.
4. Declare the database temperature interval from its assessment if known, or set database_temperature_range_k to null if unknown. This is user-supplied evidence, not a range automatically inferred from every TDB function. Requests outside a declared interval fail. Check pressure and composition validity separately.
5. Run the calculation. Check finite Gibbs energies, phase fractions summing to one, reconstructed bulk composition, and stability to doubled pdens (phase-constitution sampling density). Near transitions, refine temperatures and sampling density further.
6. Deliver phase fractions with their molar basis, phase compositions, database hash, conditions, excluded phases, and any numerical or assessment limitations.

Read references/model-and-validation.md for the analytic example, basis conversion, native Model/Workspace/property/plot contracts, miscibility-gap handling, and convergence limits.

Execute the tested example

From the collection root:

uv run --no-project --python 3.12 --with pycalphad==0.11.2 --with numpy==2.5.3 \
  python skills/pycalphad/scripts/equilibrate.py \
  skills/pycalphad/assets/ideal-cu-ni.tdb \
  skills/pycalphad/assets/equilibrium.json equilibrium-result

Tested on Python 3.12, pycalphad 0.11.2, and NumPy 2.5.3. Use a new output directory. All thermodynamic calculations are local; the script does not upload a TDB.

For the supplied hypothetical model at X(Ni)=0.5 and 101325 Pa:

The suite verifies analytic common-tangent compositions, a noncentral lever-rule case, Gibbs energy, mass balance, both single-phase limits, and actual same-phase miscibility gap vertices. These validate the computational workflow, not real Cu-Ni metallurgy.

Outputs and acceptance

• report.json: settings and versions, TDB/settings SHA-256, excluded database phases, requested, solver-imposed, and reconstructed bulk compositions, per-temperature baseline/refined results, and checks. Experimental validity is not evaluated by the helper.
• phase-equilibria.csv: one row per stable vertex per temperature and sampling run, including phase name, molar phase fraction, and elemental mole fractions. Its Gibbs energy column is the whole-system molar Gibbs energy, repeated for each vertex; it is not the individual phase energy.

…