agentleFS
SFETNISFETNI/Deep-Matter-Chem-Skills/skills/thermodynamics-calphad/calphad-workflow/SKILL.md

calphad-workflow

Skill10 starsChanged 6 months agoMITView on GitHub

This skill covers CALPHAD workflows for computational thermodynamics and materials design: thermodynamic database selection, equilibrium and metastable calculations, binary and ternary phase diagrams, Scheil solidification, chemical potentials, activities, driving forces, parameter assessment, uncertainty, and reproducible coupling to DFT, experiments, materials databases, precipitation, solidification, diffusion, and phase-field models. Invoke this skill when an agent needs phase stability or thermodynamic inputs from assessed Gibbs-energy models rather than from a single DFT calculation or empirical rule. CALPHAD, short for CALculation of PHAse Diagrams,…

The file

Show its rules and text

We split this skill into the rules it gives an agent

22 rules. About 0 are common, 22 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈22

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use when calculating binary, ternary, or multicomponent phase equilibria from an assessed thermodynamic database.

    line 40
  2. Distinctive:

    Use when generating isothermal sections, isopleths, liquidus/solidus projections, phase-fraction maps, or metastable diagrams.

    line 41
  3. Distinctive:

    Use when extracting chemical potentials, activities, driving forces, or Gibbs energies for downstream precipitation, diffusion, …

    line 42
  4. Distinctive:

    Use when comparing DFT formation energies, experimental phase equilibria, and database predictions.

    line 43
  5. Distinctive:

    Use when selecting or auditing thermodynamic databases for a target alloy or materials system.

    line 44
  6. Distinctive:

    Use when assessing uncertainty or sensitivity in database parameters, phase descriptions, or extrapolated higher-order systems.

    line 45
  7. Distinctive:

    Read database documentation for assessed binaries, ternaries, extrapolation policy, magnetic models, and order-disorder descriptions.

    line 80
  8. Distinctive:

    Check whether the target system is assessed directly or only extrapolated.

    line 81
  9. Distinctive:

    Use pycalphad for scriptable, reproducible equilibrium calculations when the database is available in a compatible TDB format.

    line 109
  10. Distinctive:

    Verify phases are intentionally included or suppressed.

    line 143
  11. Distinctive:

    Check that the database uses the same element symbols and vacancy convention expected by the code.

    line 145
  12. Distinctive:

    Document the suppressed phase set and why the metastable state is physically meaningful.

    line 159
  13. Distinctive:

    Do not compare driving forces from two databases unless reference states and phase descriptions are compatible.

    line 169
  14. Distinctive:

    Use Scheil results as process-sensitive indicators, not final microstructure predictions:

    line 175
  15. Distinctive:

    Use consistent magnetic, ordering, and structural states.

    line 197
  16. Distinctive:

    Avoid overfitting sparse DFT data outside experimental constraints.

    line 199
  17. Distinctive:

    Keep raw data, processed data, weights, parameter files, and scripts versioned.

    line 200
  18. Distinctive:

    Use parameter covariance, Bayesian posterior samples, bootstrap fits, or sensitivity scans where available.

    line 219
  19. Distinctive:

    Treat the thermodynamic database as primary input data and version it like code.

    line 242
  20. Distinctive:

    Never publish a phase diagram without database name, version, phase list, components, conditions, and software version.

    line 243
  21. Distinctive:

    Keep metastable calculations separate from full-equilibrium calculations in filenames and figures.

    line 246
  22. Distinctive:

    Use point equilibria to verify important features from gridded diagrams.

    line 247

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

CALPHAD Workflow

Description

This skill covers CALPHAD workflows for computational thermodynamics and materials design: thermodynamic database selection, equilibrium and metastable calculations, binary and ternary phase diagrams, Scheil solidification, chemical potentials, activities, driving forces, parameter assessment, uncertainty, and reproducible coupling to DFT, experiments, materials databases, precipitation, solidification, diffusion, and phase-field models. Invoke this skill when an agent needs phase stability or thermodynamic inputs from assessed Gibbs-energy models rather than from a single DFT calculation or empirical rule.

Domain Context

CALPHAD, short for CALculation of PHAse Diagrams, represents the Gibbs energy of each phase as a function of temperature, pressure, composition, and internal sublattice degrees of freedom. Equilibria are obtained by minimizing the total Gibbs energy subject to mass balance and phase constraints. A CALPHAD database is not just a table of phase boundaries; it is a set of model functions, parameters, reference states, phase descriptions, and assessed experimental or first-principles data.

The validity of a CALPHAD result is therefore the validity of the database assessment. Results are strongest inside the assessed composition, temperature, pressure, and phase-space domain. Extrapolated ternaries, quaternaries, high-temperature liquids, metastable phases, magnetic transitions, order-disorder models, and non-stoichiometric compounds can be useful but must be treated as database-dependent predictions. [EXPERT REVIEW NEEDED]

CALPHAD complements DFT rather than replacing it. DFT gives 0 K or finite-temperature free-energy contributions for specific configurations; CALPHAD integrates experimental phase equilibria, calorimetry, activities, DFT formation energies, magnetic terms, solution models, and compound-energy formalism into thermodynamic descriptions usable across composition and temperature. Combining them requires consistent reference states, phases, and provenance.

Thermodynamic outputs from CALPHAD often feed other modeling workflows: precipitation driving forces, local equilibrium in diffusion simulations, liquidus/solidus surfaces for casting, phase fractions for alloy design, chemical potentials for defect calculations, and free-energy densities for phase-field simulations. Those downstream workflows inherit every database assumption.

When to Use This Skill

  • Use when calculating binary, ternary, or multicomponent phase equilibria from an assessed thermodynamic database.
  • Use when generating isothermal sections, isopleths, liquidus/solidus projections, phase-fraction maps, or metastable diagrams.
  • Use when extracting chemical potentials, activities, driving forces, or Gibbs energies for downstream precipitation, diffusion, solidification, or phase-field models.
  • Use when comparing DFT formation energies, experimental phase equilibria, and database predictions.
  • Use when selecting or auditing thermodynamic databases for a target alloy or materials system.
  • Use when assessing uncertainty or sensitivity in database parameters, phase descriptions, or extrapolated higher-order systems.

When Not to Use This Skill

  • When no assessed database covers the system. A calculation from an unrelated database can look precise while being physically meaningless.
  • When the phase of interest is missing from the database. Suppressing or omitting a real phase changes equilibria, driving forces, and predicted stability.
  • When atomic-scale local structure is the target. CALPHAD gives thermodynamic state functions and phase amounts, not atomistic mechanisms or interface structures.
  • When the property depends on kinetics alone. Equilibrium phase fractions do not predict nucleation barriers, diffusion paths, microstructure length scales, or transformation rates without additional models.
  • When database mixing is required but reference states are incompatible. Parameters from different databases cannot usually be combined mechanically.
  • When using extrapolated high-order systems for final claims without validation. Ternary and quaternary predictions must be checked against experiments, DFT, or higher-quality assessments. [EXPERT REVIEW NEEDED]

Core Concepts

  • Gibbs energy model: Mathematical expression for a phase Gibbs energy as a function of temperature, composition, and internal degrees of freedom.
  • Phase description: Database definition of a phase, including constituents, sublattices, model type, parameters, and validity range.
  • Sublattice model: Representation of ordered phases or solution phases with multiple crystallographic or chemical sublattices, e.g. (Al,Ni):(Va) or more complex site models.
  • Solution model: Excess Gibbs-energy description for non-ideal mixing, often using Redlich-Kister or related polynomial forms.
  • Compound-energy formalism (CEF): Framework for phases with multiple sublattices and endmembers whose site fractions are optimized during equilibrium.
  • Endmember: A limiting configuration of a sublattice model with a defined Gibbs energy contribution.
  • Reference state: The standard state used for each element and phase. Wrong reference states shift formation energies, chemical potentials, and driving forces.
  • Equilibrium calculation: Gibbs-energy minimization over allowed phases subject to mass balance and state variables.
  • Metastable equilibrium: Equilibrium calculated with selected stable phases suppressed or with constrained phase sets to inspect driving forces or transformation paths.
  • Activity and chemical potential: Thermodynamic quantities describing effective composition and partial Gibbs energy, used for diffusion, defect equilibria, and reactions.
  • Scheil solidification: Non-equilibrium solidification approximation with complete liquid mixing and no solid diffusion. Useful for casting trends but not a universal microsegregation model.
  • Parameter assessment: Optimization of model parameters against experimental, first-principles, or database-derived data with uncertainty and model-form assumptions.

Key Workflows

Workflow 1: Select and audit a thermodynamic database

Database choice is the most important scientific decision in a CALPHAD workflow. Record it as input data, not as a software detail.

Checklist:

  • Confirm the database covers every element, phase, and temperature/composition range needed.
  • Read database documentation for assessed binaries, ternaries, extrapolation policy, magnetic models, and order-disorder descriptions.
  • Check whether the target system is assessed directly or only extrapolated.
  • Identify missing phases, metastable phases, liquids, gas phases, or compound descriptions.
  • Record database name, vendor/source, version, release date, license, checksum if available, and local path.
  • Compare at least one known experimental or literature phase diagram before production calculations.

Example provenance record:

calphad_database:
  file: TCNI12.TDB
  source: Thermo-Calc nickel alloy database
  version: "12"
  checksum_sha256: "recorded-from-local-file"
  system: Ni-Al-Cr
  assessed_domain: "verify in database documentation"
  phases_enabled:
    - LIQUID
    - FCC_A1
    - BCC_A2
    - B2_BCC
    - GAMMA_PRIME
  notes:
    - "Do not combine with parameters from another database."
    - "[EXPERT REVIEW NEEDED] Confirm target alloy range is assessed."

Workflow 2: Compute an equilibrium phase diagram with pycalphad

Use pycalphad for scriptable, reproducible equilibrium calculations when the database is available in a compatible TDB format.

from pathlib import Path

import matplotlib.pyplot as plt
from pycalphad import Database, equilibrium, variables as v
from pycalphad.plot.eqplot import eqplot

db_path = Path("databases/Ni-Al-Cr_validated.tdb")
dbf = Database(str(db_path))

components = ["NI", "AL", "CR", "VA"]
phases = ["LIQUID", "FCC_A1", "BCC_A2", "B2_BCC"]

conditions = {
    v.T: (800, 1800, 10),
    v.P: 101325,
    v.X("AL"): (0.0, 0.30, 0.005),
    v.X("CR"): 0.10,
}

eq = equilibrium(dbf, components, phases, conditions)

fig = plt.figure(figsize=(7, 5))
ax = fig.add_subplot()
eqplot(eq, ax=ax)
ax.set_title("Ni-Al-Cr isopleth at X(Cr)=0.10")
fig.tight_layout()
fig.savefig("ni_al_cr_isopleth.png", dpi=300)

Before reporting:

  • Verify phases are intentionally included or suppressed.
  • Confirm compositions are mole fractions unless otherwise documented.
  • Check that the database uses the same element symbols and vacancy convention expected by the code.
  • Repeat key calculations with finer grids or point equilibria near invariant reactions.
  • Save the exact phase list and conditions used to produce the figure.

Workflow 3: Calculate metastable equilibria, driving forces, and chemical potentials

Metastable calculations are useful for nucleation, precipitation, defect, and transformation analyses. They are also easy to misuse because suppressing a stable phase changes the reference equilibrium.

Research workflow:

  1. Compute the full equilibrium with all relevant stable phases enabled.
  2. Identify the phase or phases whose metastable driving force is needed.
  3. Recompute with selected phases suppressed or with only selected phases enabled.
  4. Extract chemical potentials, activities, phase fractions, or driving forces.
  5. Document the suppressed phase set and why the metastable state is physically meaningful.

Typical outputs:

  • Chemical potentials for elements or species.
  • Activities relative to database reference states.
  • Gibbs energy difference between parent and product phases.
  • Precipitation driving force as a function of temperature and composition.
  • Phase amount sensitivity to a suppressed phase.

Do not compare driving forces from two databases unless reference states and phase descriptions are compatible.

Workflow 4: Scheil solidification and liquidus/solidus analysis

Scheil calculations approximate non-equilibrium solidification with complete liquid mixing and no diffusion in the solid. They are useful for alloy screening, segregation trends, liquidus/solidus estimates, and identifying possible terminal phases.

Use Scheil results as process-sensitive indicators, not final microstructure predictions:

  • Back diffusion, dendrite arm spacing, convection, nucleation undercooling, and phase coarsening are not included in the basic Scheil approximation.
  • The result depends strongly on liquid and solid phase descriptions.
  • Small terminal liquid fractions can produce noisy or unrealistic low-temperature phases.
  • Experimental solidification paths may require kinetic or process models beyond CALPHAD.

For publication or design decisions, compare Scheil predictions against equilibrium solidification, experimental thermal analysis, or process simulation when available. [EXPERT REVIEW NEEDED]

Workflow 5: Couple CALPHAD with DFT, experiments, and databases

CALPHAD assessment and validation often combine:

  • Experimental phase boundaries, invariant reactions, calorimetry, activities, and heat capacities.
  • DFT formation energies for stable and metastable compounds.
  • DFT phonons or thermodynamic integration for finite-temperature free-energy contributions.
  • Materials database structures and energies after compatibility checks.
  • Bayesian or Gaussian-process surrogates for parameter sensitivity and uncertainty analysis.

DFT coupling checklist:

  • Match reference states between DFT formation energies and CALPHAD endmembers.
  • Use consistent magnetic, ordering, and structural states.
  • Include uncertainty or quality flags for DFT convergence and finite-temperature corrections.
  • Avoid overfitting sparse DFT data outside experimental constraints.
  • Keep raw data, processed data, weights, parameter files, and scripts versioned.

Workflow 6: Validate parameter assessments and database predictions

Validation should be external to the data used for assessment whenever possible.

Validation targets:

  • Binary and ternary phase boundaries.
  • Invariant reaction temperatures and compositions.
  • Liquidus/solidus curves.
  • Activities and chemical potentials.
  • Enthalpies of mixing and formation.
  • Phase fractions from heat treatment experiments.
  • DFT formation energies of compounds not used in fitting.

Uncertainty practices:

  • Report which parameters were varied and which were fixed.
  • Use parameter covariance, Bayesian posterior samples, bootstrap fits, or sensitivity scans where available.
  • Propagate parameter samples to phase boundaries, phase fractions, and driving forces.
  • Identify regions where phase equilibria change discontinuously across plausible parameter sets.

Parameter uncertainty is often strongly model-form dependent. A narrow parameter posterior does not prove the phase model is correct. [EXPERT REVIEW NEEDED]

Common Failure Modes

FailureSymptomLikely CauseDiagnosticFix
Database outside assessed rangeSmooth but wrong phase diagramExtrapolated composition or temperature domainCheck database documentation and assessed systemsRestrict domain or validate against data
Incompatible databases mixedDiscontinuous or nonsensical equilibriaDifferent reference states and phase modelsCompare element references and phase definitionsUse one database or reassess parameters consistently
Missing metastable phaseDriving forces look too large or phase path is wrongPhase absent or suppressed unintentionallyList enabled and disabled phasesAdd/enable phase or document suppression
Extrapolated ternary trustedTernary predictions fail experimentsBinary-only or sparse ternary assessmentCheck assessed ternaries and residualsTreat as hypothesis and validate
Wrong reference stateChemical potentials or formation energies shiftedElement or phase reference mismatchReproduce pure-element and binary limitsConvert references or rederive inputs
Missing magnetic modelTransition temperatures and phase boundaries biasedMagnetic contribution absent or invalidInspect database model termsUse database with magnetic assessment
Order-disorder mishandledOrdered phase fraction missing or duplicatedWrong phase selection or sublattice interpretationCompare ordered/disordered phase descriptionsUse documented phase set and constraints
Poor grid resolutionMissed invariant reactions or narrow phase fieldsCoarse temperature/composition gridRefine around boundaries and run point equilibriaUse adaptive refinement or targeted points
No provenancePhase diagram cannot be reproducedMissing database version, phase list, or conditionsAudit figure metadataStore database/version/conditions with outputs
Activities misreportedDiffusion or defect coupling gives wrong trendsWrong standard state or component conventionCompare limiting behavior and documentationState reference state and units explicitly

Best Practices

  • Treat the thermodynamic database as primary input data and version it like code.
  • Never publish a phase diagram without database name, version, phase list, components, conditions, and software version.
  • Validate the database on a simpler subsystem before using high-order extrapolations.
  • Save both the plotting script and the raw equilibrium result object or table.
  • Keep metastable calculations separate from full-equilibrium calculations in filenames and figures.
  • Use point equilibria to verify important features from gridded diagrams.
  • Record suppressed phases, fixed activities, reference states, and composition basis.
  • Cross-check thermodynamic predictions with DFT or experiments for new compositions.
  • Propagate parameter uncertainty when phase-boundary location or driving force magnitude controls a conclusion.
  • Mention useful future couplings, such as phase-field or precipitation modeling, in prose until the corresponding repository skills exist.

Integration with Other Skills

  • materials-databases-access: Supplies database-derived structures, energies, provenance, and compatibility checks before thermodynamic comparison or assessment.
  • pymatgen-analysis: Supports composition handling, phase diagram concepts, structure parsing, and formation-energy analysis around CALPHAD workflows.
  • materials-featurization: Provides descriptors for thermodynamic surrogate models and composition-space analysis.
  • high-throughput-dft: Generates DFT data that can validate or inform CALPHAD assessments.
  • dft-convergence: Ensures DFT formation energies and finite-temperature inputs are converged enough for thermodynamic use.
  • scientific-visualization: Produces phase diagrams, uncertainty bands, residual plots, and publication-ready thermodynamic figures.
  • reproducibility-workflow: Tracks database versions, scripts, results, checksums, and figure provenance.
  • gaussian-process-materials: Models thermodynamic residuals, parameter sensitivities, or surrogate response surfaces for composition screening.
  • bayesian-optimization: Guides alloy composition search using CALPHAD outputs and uncertainty-aware acquisition.
  • surrogate-validation: Validates surrogate models trained on CALPHAD-derived phase stability or driving-force targets.
  • small-data-ml: Provides validation strategies for sparse experimental and thermodynamic datasets.

Key References

  1. Saunders, N. and Miodownik, A. P. (1998). CALPHAD: Calculation of Phase Diagrams: A Comprehensive Guide. Pergamon.
  2. Lukas, H. L., Fries, S. G., and Sundman, B. (2007). Computational Thermodynamics: The Calphad Method. Cambridge University Press.
  3. Andersson, J. O. et al. (2002). Thermo-Calc and DICTRA, computational tools for materials science. Calphad. https://doi.org/10.1016/S0364-5916(02)00037-8
  4. Otis, R. and Liu, Z.-K. (2017). pycalphad: CALPHAD-based computational thermodynamics in Python. Journal of Open Research Software. https://doi.org/10.5334/jors.140
  5. Bocklund, B. et al. (2019). ESPEI for efficient thermodynamic database development, modification, and uncertainty quantification: application to Cu-Mg. MRS Communications. https://doi.org/10.1557/mrc.2019.59

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.