references/model-and-validation.md
Composition basis and equilibrium validation
Original pedagogical database
assets/ideal-cu-ni.tdb was written for this skill and is released under the skill's
MIT license. Cu and Ni are labels for a hypothetical ideal binary; there are no fitted
experimental data. The file defines one substitutional sublattice in FCC_A1 and LIQUID,
with no excess mixing terms or pressure dependence. Its functions span 298.15–2000 K.
With x = X(Ni), energies in J/mol, and R in J/(mol K):
- G(FCC_A1) = R T [x ln x + (1-x) ln(1-x)].
- G(LIQUID) = G(FCC_A1) + (1-x)(10000-10T) + x(12000-10T).
At T=1100 K the liquid endmember offsets are -1000 and +1000 J/mol. Equality of both component chemical potentials gives x_liquid = 1/(1+exp(1000/(RT))) and x_solid = 1-x_liquid. The phase fraction of solid at bulk x between those endpoints is (x_bulk-x_liquid)/(x_solid-x_liquid). This is an independent analytic check of the numerical common tangent, phase compositions, and lever rule. The tests use pycalphad's R=8.3145 J/(mol K); the listed decimal values are package/model-specific regression values.
The database intentionally lacks realistic heat capacities, lattice stabilities, excess mixing, magnetic terms, and pressure effects. Its apparent transitions are synthetic. Do not fit a real experiment to it or replace an assessed database with this example.
Basis conversions
For measured elemental mass fractions w_i and molar masses M_i, calculate
x_i = (w_i/M_i) / sum_j(w_j/M_j), including the dependent element. Weight percent is
first divided by 100. Store the original composition, molar masses, and converted values
with the run. The helper accepts only the resulting mole fractions and rejects a
mass_fraction basis instead of treating weight percent as atomic fraction.
NP is a molar phase fraction at total N=1. A mass phase fraction requires each phase's
composition-weighted molar mass: w_phase = NP_phaseM_phase / sum(NP_jM_j).
Volume fractions require appropriate phase densities or molar volumes as well. Do not
compare molar fractions directly to microscopy area fractions without explaining the
conversion and sampling assumptions.
For this elemental workflow, molar energies and amounts use a mole of non-vacancy
atoms, not a mole of an arbitrary compound formula unit. Model.GM is normalized on
that basis; Model.G is formula energy and can differ with sublattice site ratios.
Site fractions v.Y(phase, sublattice_index, species) are internal degrees of freedom,
not bulk mole fractions. Sublattice indices are zero-based.
The tested conversion API is v.get_mole_fractions({v.W('NI'): 0.5}, 'CU', db);
it uses the TDB elemental masses and returns a condition mapping keyed by v.X('NI').
For the bundled masses, 50 wt% Ni is X(Ni)=0.5198487558, not 0.5. No conversion is
performed by the JSON helper itself.
Native model, property, and plotting contracts
These examples were executed with pycalphad 0.11.2. Paths below are relative to the
collection root. Database(path) parses local thermodynamic data; successful parsing
does not establish that the assessment or every model feature is suitable. Review TDB
warnings rather than suppressing all warnings. db.elements, db.phases, and each
phase's constituents, sublattices, and model_hints expose the modeled system.
Model(db, components, phase) builds a symbolic energy model, not an equilibrium.
calculate(..., output='GM', T=..., P=..., pdens=...) samples its phase-constitution
surface. Its points columns are ordered internal site fractions: use the model's
site_fractions order; do not pass overall alloy compositions as points for a
multisublattice model. In the one-sublattice teaching FCC model only, [0.5, 0.5]
coincides with 50:50 bulk composition. calculate does not minimize across phases.
Pass sampling options to equilibrium or Workspace through calc_opts, not as
top-level pdens; unused equilibrium keyword arguments merely produce a warning.
import numpy as np
from pycalphad import Database, Workspace, variables as v
db = Database('skills/pycalphad/assets/ideal-cu-ni.tdb')
components = ['CU', 'NI', 'VA']
phases = ['FCC_A1', 'LIQUID']
conditions = {v.T: [900, 1100, 1300], v.P: 101325, v.N: 1, v.X('NI'): 0.5}
wks = Workspace(db, components, phases, conditions, calc_opts={'pdens': 500})
temperature = wks.get(v.T)
phase_amounts = wks.get_dict('NP(*)')
gm = wks.get('GM') # system molar Gibbs energy, J/mol
x_solid = wks.get(v.X('FCC_A1', 'NI'))
assert np.allclose(temperature, [900, 1100, 1300])
assert np.isfinite(gm).all()
assert np.isnan(x_solid[-1]) # absent solid; NaN is not a failed equilibrium
Use get_dict when phase multiplicity can change. A request such as NP(FCC_A1)
or X(FCC_A1,NI) expands to #1, #2, ... properties for a miscibility gap; get
can consequently return a list of arrays rather than one array. Preserve those sets
and only sum their amounts when a total phase-name fraction is intended. Suffixes
identify solver composition sets, not permanent ordered/disordered identities.
Inspect compositions and site fractions before assigning physical labels. Property
arrays squeeze singleton condition axes; use wks.condition_axis_order for grids.
GM and HM are J/mol; SM and CPM are J/(mol K). A phase-qualified property,
such as GM(FCC_A1), is that stable composition set's property, whereas unqualified
GM is phase-amount-weighted. CPM differentiates the model at fixed constitution;
wks.get('HM.T') differentiates equilibrium enthalpy as temperature changes, including
phase amounts and internal relaxation. They need not agree. At 1100 K the hypothetical
two-phase example has CPM=0 but HM.T approximately 1005.08 J/(mol K), matching a
small central difference of equilibrium enthalpy. Derivatives at phase boundaries or
invariant points require special care; a finite derivative is not a latent-heat integral.
For a small binary phase diagram, the current top-level binplot uses the mapping API:
import matplotlib.pyplot as plt
from pycalphad import binplot
ax, strategy = binplot(
db, components, phases,
{v.T: (900, 1300, 100), v.P: 101325, v.N: 1, v.X('NI'): (0.3, 0.7, 0.1)},
return_strategy=True,
)
ax.set_title('Hypothetical ideal binary; not assessed Cu-Ni')
ax.figure.savefig('hypothetical-binary.png', dpi=150, bbox_inches='tight')
plt.close(ax.figure)
The default return is an Axes; return_strategy=True returns (Axes, BinaryStrategy).
Pass plot options in plot_kwargs; other keywords configure the mapper. binplot
requires one varying composition and one varying potential coordinate. A fixed-bulk
temperature sweep is better plotted directly from Workspace properties or the CSV.
For equilibrium/Workspace, a tuple is (start, stop, step) with an excluded stop;
a list is explicit values. Mapping uses tuple bounds and increments to follow phase
boundaries, not just a Cartesian equilibrium grid. A smooth plot alone does not
validate all stable fields; check representative points and refine difficult boundaries.
Official sources checked for these contracts:
- Stable Model and variables source
- Stable Workspace and composition conditions
- Stable property framework
- Stable mapping compatibility API
- Current property and ordering workflow
Phase selection and solver checks
VA supports vacancy sublattices and is omitted from overall elemental mass balance.
Select actual elements present in the database. A required vacancy or other constituent
missing from every active species in one sublattice can make a phase unavailable.
The helper rejects phase lists that pycalphad filters, including redundant coupled
order/disorder selections, so the agent can review rather than silently alter them.
Excluding a phase can lower the number of stable phases and change apparent solubility. An excluded phase list is therefore scientific provenance. Preserve each composition set in miscibility gaps: summing fractions by phase name is useful for totals but loses the two distinct tie-line endpoints. Never use a vertex index as a persistent phase ID.
Mass balance, phase-sum checks, and finite Gibbs energy are necessary but not sufficient.
Doubled pdens only tests one initialization-density change. Repeat with more density,
inspect nearby conditions, compare alternative candidate phase sets, or use a trusted
reference calculation when the result affects a scientific conclusion. Degenerate phase
fractions at invariant points may be nonunique even when Gibbs energies agree. The
helper's flags should be interpreted with that thermodynamic context.
The native regression suite also loads the small alni_dupin_2001.tdb shipped in
pycalphad 0.11.2, checks order/disorder filtering, and verifies an Al-Ni equilibrium
point at 1000 K and X(Al)=0.25. That is a release integration check, not independent
experimental validation of the database. No proprietary database is bundled or used.
Parameter uncertainty is separate from numerical sampling sensitivity. Without an
assessment's covariance/posterior or another justified uncertainty model, doubled
pdens cannot yield confidence intervals. Database coverage, omitted phases, reference
states, and extrapolation can dominate errors even when two numerical runs agree.
Preserve the actual TDB with the output under its licensing terms. A SHA-256 identifies bytes but does not document assessment quality, reference-state conventions, or the validity range. Include the database authors' citation and uncertainty/coverage limits in the final scientific report.