Thermodynamics

Free energy

free_energy

free_energy(system, potential, temperatures, *, phase='solid', pressure=0.0, timestep=0.001, equilibration=10.0, switching=50.0, scan=100.0, repeats=1, mixing=False, melt_temperature=None, barostat=None, seed=1, progress=None, cancel=None)

The free energy of a solid or a liquid, per atom, from molecular dynamics in LAMMPS, with classical atoms.

Parameters:

Name	Type	Description	Default
system	System	The atoms, with an element column, in a box periodic in every direction: for a solid at their places in the crystal (relax them first), for a liquid anywhere, as it is melted first.	required
potential	LAMMPS	The interaction. A liquid needs one pair style, not a hybrid.	required
temperatures	float64 or array_like	Temperatures in K, positive. The free energy is calculated at the first, and followed from there to the others, which must lie on one side of it, in order.	required
phase	(solid, liquid)	The phase. Default "solid".	"solid"
pressure	float64 or None	Pressure in GPa for the Gibbs energy; None for the Helmholtz energy in the box of system. Default 0.	0.0
timestep	float64	Time step in ps. Default 0.001.	0.001
equilibration	float64	Time in ps of each equilibration. Default 10.	10.0
switching	float64	Time in ps of each switching between two interactions. Default 50.	50.0
scan	float64	Time in ps of each run between the first and the last temperature. Default 100.	100.0
repeats	int32	Independent calculations at the first temperature. Default 1.	1
mixing	bool	Add the ideal entropy of mixing of a random solid solution, whose atoms do not exchange places in the dynamics. A liquid has it by itself. Default False.	False
melt_temperature	float64	Temperature in K at which a liquid is melted. Default twice the first temperature.	None
barostat	(iso, aniso, tri)	How the box of a solid changes, as in MolecularDynamics.run. Default "aniso", and "iso" for a liquid.	"iso"
seed	int32	Seed of the random numbers, positive. Default 1.	1
progress	callable	Called as progress(done, total) with the steps run.	None
cancel	CancelToken	Stops the calculation, which raises mdapy.errors.Cancelled.	None

Returns:

Type	Description
FreeEnergyResult	The free energy, enthalpy, entropy and volume per atom at each temperature. A phase that changes on the way, as a crystal melts when it is too hot, leaves out the temperatures from there on, with a warning.

Raises:

Type	Description
InvalidParameter	For invalid options, a box not periodic in every direction, a hybrid pair style for a liquid, a liquid that does not move as one, a phase that changes in every scan, or if LAMMPS fails.
MissingProperty	If the system has no element column.
Cancelled	If cancelled.

FreeEnergyResult dataclass

FreeEnergyResult(temperatures, pressure, free_energy, enthalpy, entropy, volume, phase, error, dissipation, system)

Bases: Result

The free energy of a phase, per atom.

Attributes:

Name	Type	Description
temperatures	ndarray	(T,) float64, the temperatures in K.
pressure	float64 or None	The pressure in GPa, None at constant volume.
free_energy	ndarray	(T,) float64, the Gibbs energy in eV, or at constant volume the Helmholtz energy.
enthalpy	ndarray	(T,) float64, the enthalpy in eV, or at constant volume the energy.
entropy	ndarray	(T,) float64, the entropy in eV/K.
volume	ndarray	(T,) float64, the volume in ų.
phase	str	"solid" or "liquid".
error	float64 or None	The standard error in eV of the free energy at the first temperature, from the repeats; None for one repeat.
dissipation	ndarray	(T,) float64 half the difference in eV of the work there and back: near zero when the switching and the scan are slow enough and the phase stays as it is.
system	System	The atoms in the box of the first temperature.

crossing

crossing(other)

Where this phase and another have the same free energy.

Parameters:

Name	Type	Description	Default
other	FreeEnergyResult	The other phase, at the same pressure, with temperatures that overlap these.	required

Returns:

Type	Description
PhaseCoexistence	The temperature, and the latent heat and the changes of entropy and volume from this phase to the other.

Raises:

Type	Description
InvalidParameter	If the pressures differ, the temperatures do not overlap, or the free energies do not cross between them.

PhaseCoexistence dataclass

PhaseCoexistence(temperature, latent_heat, entropy, volume)

Bases: Result

Two phases of the same free energy, per atom.

Attributes:

Name	Type	Description
temperature	float64	The temperature in K.
latent_heat	float64	The change of enthalpy in eV.
entropy	float64	The change of entropy in eV/K.
volume	float64	The change of volume in ų.

Melting point

melting_point

melting_point(crystal, potential, temperature, *, pressure=0.0, atoms=16000, repeat=None, timestep=0.001, equilibration=10.0, coexistence=500.0, tolerance=3.0, max_runs=8, barostat_damping=None, seed=1, progress=None, cancel=None)

The melting point of a crystal, from a first guess, by the two-phase method: a solid and a liquid share a box at constant enthalpy, where they reach their common temperature while the interface between them moves. A run in which one phase takes over gives a new guess, until the two last.

Parameters:

Name	Type	Description	Default
crystal	System	The crystal, relaxed, with an element column, in a box periodic in every direction; the interface between the phases is across its third vector.	required
potential	LAMMPS	The interaction.	required
temperature	float64	The first guess in K, positive.	required
pressure	float64	Pressure in GPa. Default 0.	0.0
atoms	int32	About how many atoms the box holds, three times as long along its third vector as along the others. Default 16000; fewer for a slow potential, at the price of a larger spread between runs.	16000
repeat	array_like	(3,) int32 repeats of crystal along its vectors, instead of atoms; the third is made even.	None
timestep	float64	Time step in ps. Default 0.001.	0.001
equilibration	float64	Time in ps of each stage before the two phases meet. Default 10.	10.0
coexistence	float64	Time in ps of each stretch of the two phases, of which a run has up to five while the temperature drifts. Default 500; a larger box needs longer, as heat takes longer to cross it.	500.0
tolerance	float64	How much in K the temperature may still drift, from the third quarter of a stretch of coexistence to the last, for it to be the answer; twice its statistical error, if that is larger. Default 3.	3.0
max_runs	int32	Largest number of runs. Default 8.	8
barostat_damping	float64	Damping time of the barostat in ps, as in MolecularDynamics.run. Default 1000 time steps.	None
seed	int32	Seed of the random numbers, positive. Default 1.	1
progress	callable	Called as progress(done, total) with the steps run, of a total that takes every run to be the last.	None
cancel	CancelToken	Stops the calculation, which raises mdapy.errors.Cancelled.	None

Returns:

Type	Description
MeltingPointResult	The melting point, its error, the runs, and the temperature, pressure and fraction of solid atoms along the last run.

Raises:

Type	Description
InvalidParameter	For invalid options, a box not periodic in every direction, if half of the crystal does not melt, if no run ends with two phases within max_runs, or if LAMMPS fails.
MissingProperty	If the system has no element column.
Cancelled	If cancelled.

MeltingPointResult dataclass

MeltingPointResult(temperature, error, pressure, attempts, time, temperatures, pressures, fractions, fraction_time, system)

Bases: Result

The melting point of a crystal.

Attributes:

Name	Type	Description
temperature	float64	The melting point in K: the temperature at which the two phases coexist, averaged over the second half of the last stretch.
error	float64	The standard error of that mean in K, from blocks of the run.
pressure	float64	The pressure in GPa.
attempts	tuple of MeltingAttempt	Each stretch of each run, in order.
time	ndarray	(S,) float64, the time in ps along the last stretch.
temperatures	ndarray	(S,) float64, the temperature in K along the last stretch.
pressures	ndarray	(S,) float64, the pressure in GPa along the last stretch.
fractions	ndarray	(F,) float64, the fraction of solid atoms along the last stretch.
fraction_time	ndarray	(F,) float64, the time in ps of the fractions.
system	System	The atoms at the end of the last run, with a boolean column solid.

MeltingAttempt dataclass

MeltingAttempt(start, outcome, temperature, fraction, drift)

One stretch of a solid and a liquid in one box.

Attributes:

Name	Type	Description
start	float64	The temperature in K at which the run started.
outcome	str	"melted", "frozen" or "coexisting".
temperature	float64	The mean temperature in K over its second half.
fraction	float64	The fraction of solid atoms at its end.
drift	float64	How much in K the mean temperature changed from the third quarter of the run to the last.

Stacking faults at finite temperature

stacking_fault_free_energy

stacking_fault_free_energy(crystal, potential, direction, temperatures, *, height=None, axis=2, pressure=0.0, timestep=0.001, equilibration=10.0, switching=50.0, repeats=4, max_force=0.0001, max_steps=10000, seed=1, progress=None, cancel=None)

The free energy of a stacking fault at each temperature: the difference of the free energies of the crystal with and without it, in one box of the size the crystal has at that temperature and pressure.

Parameters:

Name	Type	Description	Default
crystal	System	The crystal, relaxed, with an element column, periodic in every direction, with the plane of the fault normal to the Cartesian axis of axis, such as fcc with z along [111]. The wider the plane the smaller the error, as the error of the free energy of the atoms grows more slowly than the area does.	required
potential	LAMMPS	The interaction.	required
direction	array_like	(3,) float64, the slip vector in Å, in the plane, such as a/6 [11-2].	required
temperatures	float64 or array_like	Temperatures in K, positive.	required
height	float64	The fault, at this fractional coordinate along the box vector of axis. Default between the two layers of atoms nearest the middle of the box.	None
axis	int32 or str	The Cartesian axis normal to the fault. Default z.	2
pressure	float64	Pressure in GPa. Default 0.	0.0
timestep	float64	Time step in ps. Default 0.001.	0.001
equilibration	float64	Time in ps of each equilibration. Default 10.	10.0
switching	float64	Time in ps of each switching between the crystal and the springs. Default 50.	50.0
repeats	int32	Independent free energies of each crystal at each temperature. Default 4.	4
max_force	float64	Convergence in eV/Å of the relaxation of the fault at each size of the box. Default 1e-4.	0.0001
max_steps	int32	Largest number of steps of each relaxation. Default 10000.	10000
seed	int32	Seed of the random numbers, positive. Default 1.	1
progress	callable	Called as progress(done, total) with the steps run.	None
cancel	CancelToken	Stops the calculation, which raises mdapy.errors.Cancelled.	None

Returns:

Type	Description
FaultFreeEnergyResult	The free energy of the fault per area, and its error.

Raises:

Type	Description
InvalidParameter	For invalid options, a plane not normal to the axis, a box not periodic in every direction, or if LAMMPS fails.
MissingProperty	If the system has no element column.
Cancelled	If cancelled.

FaultFreeEnergyResult dataclass

FaultFreeEnergyResult(temperatures, energy, error, area, volume, dissipation)

Bases: Result

The free energy of a stacking fault per area.

Attributes:

Name	Type	Description
temperatures	ndarray	(T,) float64, the temperatures in K.
energy	ndarray	(T,) float64, the free energy per area in J/m².
error	ndarray	(T,) float64, its standard error in J/m², from the repeats; zero for one repeat.
area	float64	The area of the fault at the first temperature in Ų.
volume	ndarray	(T,) float64, the volume per atom of the crystal in ų.
dissipation	ndarray	(T,) float64 half the difference in eV per atom of the work there and back, the largest over the runs: near zero when the switching is slow enough.

Phase diagrams of two elements

binary_phase_diagram

binary_phase_diagram(phases, temperatures, *, elements=('A', 'B'), points=1001, degree=4)

The phase diagram of two elements from free energies per atom, at constant pressure: at each temperature the stable phases at each composition lie on the lower convex hull of the free energies of all phases.

Parameters:

Name	Type	Description	Default
phases	mapping of str to mapping of float64	For each phase, its free energies by the fraction of the second element: each a FreeEnergyResult, or a pair of (T,) temperatures in K and (T,) free energies in eV per atom. A phase of one fraction is a compound of that composition. A phase of more is a solution between its lowest and its highest fractions: the free energy minus that of ideal mixing, at each temperature, is a polynomial of the fraction.	required
temperatures	array_like	(T,) the temperatures of the diagram in K, positive; beyond those of a free energy, it goes on along a straight line.	required
elements	sequence of 2 str	The elements, for the labels. Default ("A", "B").	('A', 'B')
points	int32	Number of fractions from 0 to 1. Default 1001.	1001
degree	int32	Largest degree of the polynomials. Default 4.	4

Returns:

Type	Description
BinaryPhaseDiagram	The stable phase at each temperature and fraction, and the tie lines.

Raises:

Type	Description
InvalidParameter	For no phases, a fraction out of range, no phase at some fraction, invalid temperatures, points or degree.

BinaryPhaseDiagram dataclass

BinaryPhaseDiagram(elements, phases, temperatures, fractions, stable, tie_lines)

Bases: Result

The stable phases of two elements against composition and temperature.

Attributes:

Name	Type	Description
elements	tuple of str	The two elements; the fraction is that of the second.
phases	tuple of str	The names of the phases.
temperatures	ndarray	(T,) float64, the temperatures in K.
fractions	ndarray	(X,) float64, the fractions of the second element.
stable	ndarray	(T, X) int64, the index in phases of the one stable phase, or -1 where two phases coexist.
tie_lines	tuple of TieLine	Each pair of phases in equilibrium, by temperature and fraction.

phases_at

phases_at(temperature, fraction)

The one or two stable phases at the nearest temperature of the diagram.

Parameters:

Name	Type	Description	Default
temperature	float64	The temperature in K.	required
fraction	float64	The fraction of the second element, from 0 to 1.	required

Returns:

Type	Description
tuple of str	The phase, or the two phases in equilibrium.

Raises:

Type	Description
InvalidParameter	For a fraction out of range.

TieLine dataclass

TieLine(temperature, first, first_fraction, second, second_fraction)

Two phases in equilibrium at a temperature.

Attributes:

Name	Type	Description
temperature	float64	The temperature in K.
first, second	str	The phases, the first at the lower fraction.
first_fraction, second_fraction	float64	The fractions of the second element in each.

Pressure-temperature diagrams

pressure_temperature_diagram

pressure_temperature_diagram(phases, *, points=1001)

The phase diagram of one element against pressure and temperature, from the free energies of its phases: at each pressure, the phase with the lowest free energy at each temperature.

Parameters:

Name	Type	Description	Default
phases	mapping	For each name of a phase, its free energies, one per pressure, each a mdapy.simulation.FreeEnergyResult of a run at that pressure.	required
points	int32	The temperatures of the diagram, from the lowest of the free energies to the highest. Default 1001.	1001

Returns:

Type	Description
PressureTemperatureDiagram	The stable phases and the boundaries between them. A boundary is found along the temperature at each pressure.

Raises:

Type	Description
InvalidParameter	For fewer than two phases, too few points, a free energy without a pressure, or two free energies of one phase at one pressure.

PressureTemperatureDiagram dataclass

PressureTemperatureDiagram(phases, pressures, temperatures, stable, boundaries)

Bases: Result

The stable phases of one element against pressure and temperature.

Attributes:

Name	Type	Description
phases	tuple of str	The names of the phases.
pressures	ndarray	(P,) float64, the pressures in GPa.
temperatures	ndarray	(T,) float64, the temperatures in K.
stable	ndarray	(P, T) int64, the index in phases of the phase with the lowest free energy of those known there, or -1 where none is.
boundaries	tuple of PhaseBoundary	Each pair of phases in equilibrium.

phase_at

phase_at(pressure, temperature)

The stable phase at the nearest pressure and temperature of the diagram.

Parameters:

Name	Type	Description	Default
pressure	float64	The pressure in GPa.	required
temperature	float64	The temperature in K.	required

Returns:

Type	Description
str or None	The phase, or None where no free energy is known.

PhaseBoundary dataclass

PhaseBoundary(first, second, pressures, temperatures, latent_heat, volume, slope)

Bases: Result

Two phases of one element in equilibrium, along the pressure.

Attributes:

Name	Type	Description
first, second	str	The phases, the first stable below the temperature of the boundary and the second above it.
pressures	ndarray	(B,) float64, the pressures in GPa.
temperatures	ndarray	(B,) float64, the temperature of the boundary at each pressure in K.
latent_heat	ndarray	(B,) float64, the change of enthalpy from the first to the second in eV per atom.
volume	ndarray	(B,) float64, the change of volume from the first to the second in ų per atom.
slope	ndarray	(B,) float64 dT/dP of the boundary in K/GPa by the Clausius-Clapeyron relation, T times the change of volume over the latent heat.