thermoatoms/calphy
Agent skills for installing, running, analysing, and troubleshooting calphy free-energy calculations with LAMMPS.
Run calphy alchemical transformations: mode: alchemy to get the free-energy difference between two interatomic potentials for the same structure (upsampling a cheap potential to an expensive one, comparing potentials), and mode: composition_scaling to get the free-energy change with composition or the cost of substitutional defects. Use when the question is a free-energy difference between two Hamiltonians or two compositions rather than an absolute free energy.
Read and interpret calphy output: report.yaml fields, temperature_sweep.dat and pressure_sweep.dat, forward/backward switching files, logs, and the calphy.postprocessing helpers (read_report, gather_results, find_transition_temperature), including how to combine runs, propagate errors, and build a melting line or phase diagram. Use when a calphy run has finished and the task is to extract, check, plot, or aggregate its numbers.
Decide which calphy calculation mode and settings answer a thermodynamics question (free energy at a state point, free energy vs temperature or pressure, melting point, solid-solid transition, phase diagram, potential comparison, composition dependence, specific heat) and whether calphy is the right tool at all. Use before writing an input file when the user states a physical goal rather than a mode.
Run a calphy mode: fe (or fe-qtb) calculation to get the absolute Helmholtz or Gibbs free energy of a solid or liquid at one temperature and pressure, and judge whether the number can be trusted. Use for single-point free energies, Einstein-crystal or Uhlenbeck-Ford reference runs, liquid melting cycles, quantum-corrected solid free energies, and for validating report.yaml from an fe run.
Write or fix a calphy input.yaml that passes calphy 2.x validation. Use when creating an input file for any calphy calculation, converting a v1 (top-level keys) file to the v2 calculations: list, or resolving a pydantic validation error such as "unknown key", "Element ordering mismatch", "legacy calphy input format", or "Input should be a valid string".
Install calphy and a LAMMPS binary that has the packages calphy needs, then verify the setup with a preflight check. Use when setting up calphy for the first time, when lmp cannot be found, when a run fails with a missing LAMMPS package or a pair_style/fix "unrecognized" error, or when enabling the optional pylammpsmpi library backend.
Compute a melting point with calphy, either automatically with mode: melting_temperature or manually from solid and liquid ts sweeps whose free-energy curves cross, and decide whether the resulting Tm is trustworthy. Use for melting temperatures of single-component or alloy potentials, melting lines at pressure, and for diagnosing "curves do not cross", "Tm is not within range", or a Tm that disagrees with the literature.
Launch, monitor, and rerun calphy calculations: calphy_kernel for one calculation in the foreground, calphy to submit every entry through the local, SLURM, or SGE scheduler, hand-written batch scripts, MPI core counts, the pylammpsmpi library backend, the in-process Python API, and reading progress from calphy.log. Use when a valid input.yaml exists and the task is to run it on a laptop or cluster, check on a running job, estimate runtime, or rerun a failed one.
Run calphy reversible scaling (mode: ts), direct temperature scaling (mode: tscale), or pressure scaling (mode: pscale) to get the free energy of one phase as a continuous function of temperature or pressure, and check the sweep for hidden phase transitions. Use for F(T) or G(P) curves, solid-solid transition temperatures, phase-diagram lines, specific heat, and for interpreting temperature_sweep.dat or pressure_sweep.dat.
Diagnose a failed, hanging, or suspicious calphy run from its error text, calphy.log, LAMMPS segment logs, and report.yaml. Covers pair_style/pair_coeff and potential-path errors, MEAM and ML potentials, Kokkos and hybrid/scaled, pressure not converging, lost atoms, melted solids and frozen liquids, spring-constant nan/inf, high dissipation, missing temperature_sweep.dat, folder-exists errors, scheduler and MPI problems, and results that changed between calphy versions. Use whenever a calphy run did not finish or its number looks wrong.