Relaxation and dynamics

Energy minimization

minimize

minimize(system, calculator, *, max_force=0.001, max_steps=1000, max_step=0.1, timestep=0.001, cell=None, pressure=0.0, max_stress=0.01, save_every=None, callback=None)

Minimizes the energy over the positions, and optionally the box, with FIRE 2.0.

Parameters:

Name	Type	Description	Default
system	System	The starting configuration, with a mass or an element column; a movable column, (N, 3) bool, keeps each atom still along the directions where it is False.	required
calculator	Calculator	Computes energies and forces, and the virial when the box relaxes.	required
max_force	float64	Convergence: the largest force on any atom, in eV/Å. Default 1e-3.	0.001
max_steps	int32	Largest number of steps. Default 1000.	1000
max_step	float64	Largest displacement of an atom along x, y or z in one step, in Å. Default 0.1.	0.1
timestep	float64	First time step of the dynamics, in ps. Default 0.001.	0.001
cell	(None, isotropic, axes, full)	How the box may change along its periodic directions: not at all (default), by one scale factor, by a scale factor along each Cartesian axis, or by any strain without rotation.	None
pressure	float64	External hydrostatic pressure in GPa when the box relaxes; the enthalpy is minimized. Default 0.	0.0
max_stress	float64	Convergence when the box relaxes: the largest deviation of a relaxed stress component from the target, in GPa. Default 0.01.	0.01
save_every	int32	Keeps the configuration every this many steps, with the first and the last, in frames of the result. Default None, keeping none.	None
callback	callable	Called after every step as callback(step, system, energy, max_force); returning True stops the minimization.	None

Returns:

Type	Description
MinimizeResult	The last configuration and whether it converged.

Raises:

Type	Description
InvalidParameter	For invalid options, or a calculator without the properties needed.
MissingProperty	If the system has neither masses nor elements.

MinimizeResult dataclass

MinimizeResult(system, converged, steps, energy, max_force, stress=None, frames=None)

Bases: Result

The outcome of minimize.

Attributes:

Name	Type	Description
system	System	The last configuration, with forces and atomic_energies columns and energy, and with a virial virial and stress, in info.
converged	bool	Whether every force fell below max_force and, when the box relaxed, every relaxed stress component came within max_stress of the target.
steps	int32	Number of steps taken.
energy	float64	Energy of the last configuration in eV.
max_force	float64	Largest force of the last configuration in eV/Å.
stress	ndarray or None	(3, 3) float64 stress of the last configuration in GPa, positive under tension; None when the calculator computes no virial.
frames	tuple of System or None	With save_every, the configurations at step 0, every save_every steps and the last step, with the columns and information of system and the step number as timestep in info; None otherwise.

Molecular dynamics

MolecularDynamics

MolecularDynamics(system, potential, *, timestep=0.001)

Molecular dynamics of a system in LAMMPS, with the interaction of a LAMMPS calculator.

Parameters:

Name	Type	Description	Default
system	System	The atoms, with an element column; their velocities, if the system has them, in Å/ps.	required
potential	LAMMPS	The interaction: its commands, the element of each atom type and the command-line arguments of LAMMPS.	required
timestep	float64	Time step in ps. Default 0.001.	0.001

Attributes:

Name	Type	Description
timestep	float64	Time step in ps.

Raises:

Type	Description
InvalidParameter	If the time step is not positive, an element has no atom type, or LAMMPS rejects the commands.
MissingProperty	If the system has no element column.
ImportError	If the LAMMPS Python module is not installed.

lammps property

lammps

The LAMMPS instance, for anything else.

step property

step

The time step number of LAMMPS: the steps run so far.

system property

system

The atoms now, with their velocities and periodic images, and the step and time in info.

thermo property

thermo

The thermodynamic state every thermo steps of the runs: step, time (ps), temperature (K), potential, kinetic and total energy (eV), pressure (GPa), volume (ų) and stress (GPa, Voigt order, positive under tension).

frames property

frames

The atoms every frames steps of the runs.

close

close()

Closes the LAMMPS instance.

command

command(commands)

Runs LAMMPS commands, one or several lines.

Parameters:

Name	Type	Description	Default
commands	str	The commands.	required

Raises:

Type	Description
InvalidParameter	If LAMMPS rejects them.

velocities

velocities(temperature, *, seed)

Gives the atoms random velocities of a temperature, with no total momentum.

Parameters:

Name	Type	Description	Default
temperature	float64	Temperature in K, not negative.	required
seed	int32	Seed of the random velocities, positive.	required

Raises:

Type	Description
InvalidParameter	For a negative temperature or a seed that is not positive.

run

run(steps, *, ensemble='nve', temperature=None, pressure=None, barostat='iso', thermostat_damping=None, barostat_damping=None, thermo=100, frames=None, progress=None, cancel=None)

Runs molecular dynamics.

Parameters:

Name	Type	Description	Default
steps	int32	Number of steps.	required
ensemble	(nve, nvt, npt, nph)	Constant energy, or a Nosé-Hoover thermostat, and barostat, or a barostat alone. Default "nve".	"nve"
temperature	float64 or (float64, float64)	Temperature in K of the thermostat, or its values at the start and the end of the run; needed for "nvt" and "npt".	None
pressure	float64 or (float64, float64)	Pressure in GPa of the barostat, or its values at the start and the end; needed for "npt" and "nph".	None
barostat	(iso, aniso, tri, xy)	The box changes alike in every direction, along each axis, in any way, or alike along its first two vectors with the third kept. Default "iso".	"iso"
thermostat_damping	float64	Damping time of the thermostat in ps. Default 100 time steps.	None
barostat_damping	float64	Damping time of the barostat in ps. Default 1000 time steps.	None
thermo	int32	Records the thermodynamic state every this many steps, and at the start and the end. Default 100.	100
frames	int32	Keeps the atoms every this many steps. Default None, keeping none.	None
progress	callable	Called as progress(done, total) with the steps run.	None
cancel	CancelToken	Stops the run, which raises mdapy.errors.Cancelled.	None

Raises:

Type	Description
InvalidParameter	For invalid options, or if LAMMPS fails.
Cancelled	If cancelled.

Defect energies

vacancy_formation_energy

vacancy_formation_energy(crystal, calculator, *, atom=0, cell=None, max_force=0.0001, max_steps=10000)

The energy to form a vacancy in a perfect crystal.

Parameters:

Name	Type	Description	Default
crystal	System	The perfect crystal, periodic, large enough that the vacancy does not meet its images.	required
calculator	Calculator	The potential.	required
atom	int32	The atom removed. Default 0.	0
cell	(None, isotropic, axes, full)	How the box relaxes, for both crystals, as in mdapy.simulation.minimize. Default None, a fixed box.	None
max_force	float64	Convergence of the minimizations in eV/Å. Default 1e-4.	0.0001
max_steps	int32	Largest number of steps of each minimization. Default 10000.	10000

Returns:

Type	Description
VacancyResult	The formation energy, the two energies and the relaxed defect.

VacancyResult dataclass

VacancyResult(energy, perfect, defect, system)

Bases: Result

The formation energy of a vacancy.

Attributes:

Name	Type	Description
energy	float64	The formation energy in eV.
perfect	float64	The energy of the perfect crystal in eV.
defect	float64	The energy of the crystal with the vacancy in eV.
system	System	The crystal with the vacancy, relaxed.

surface_energy

surface_energy(crystal, calculator, *, axis=2, vacuum=15.0, max_force=0.0001, max_steps=10000)

The energy of the surface of a crystal normal to a box vector.

Parameters:

Name	Type	Description	Default
crystal	System	The periodic crystal; the slab is this crystal between two surfaces normal to the box vector of axis, thick enough not to feel each other.	required
calculator	Calculator	The potential.	required
axis	int32 or str	The box vector across the slab, 0, 1, 2 or x, y, z. Default z.	2
vacuum	float64	Thickness in Å of the vacuum between the slab and its image, beyond the cutoff of the potential. Default 15.	15.0
max_force	float64	Convergence of the minimizations in eV/Å. Default 1e-4.	0.0001
max_steps	int32	Largest number of steps of each minimization. Default 10000.	10000

Returns:

Type	Description
SurfaceResult	The surface energy, the two energies, the area and the relaxed slab.

SurfaceResult dataclass

SurfaceResult(energy, bulk, slab, area, system)

Bases: Result

The energy of a surface.

Attributes:

Name	Type	Description
energy	float64	The surface energy in J/m².
bulk	float64	The energy of the periodic crystal in eV.
slab	float64	The energy of the slab in eV.
area	float64	The area of one surface in Ų.
system	System	The slab, relaxed.

stacking_fault_energy

stacking_fault_energy(crystal, calculator, direction, *, points=21, height=None, axis=2, relax=True, max_force=0.0001, max_steps=10000)

The generalized stacking fault energy along a slip vector.

Parameters:

Name	Type	Description	Default
crystal	System	The crystal, with the plane of the fault normal to the Cartesian axis of axis, such as fcc with z along [111]; periodic along that axis for a single fault, else between two free surfaces.	required
calculator	Calculator	The potential.	required
direction	array_like	(3,) float64, the slip vector in Å, in the plane, such as a/2 [1-10].	required
points	int32	Number of displacements from 0 to the whole slip vector, at least 2. Default 21.	21
height	float64	The fault, at this fractional coordinate along the box vector of axis. Default 0.5.	None
axis	int32 or str	The Cartesian axis normal to the fault. Default z.	2
relax	bool	Relax the atoms along the normal only, as is usual, or not at all. Default True.	True
max_force	float64	Convergence of the minimizations in eV/Å. Default 1e-4.	0.0001
max_steps	int32	Largest number of steps of each minimization. Default 10000.	10000

Returns:

Type	Description
StackingFaultResult	The energy per area for each fraction of the slip vector.

StackingFaultResult dataclass

StackingFaultResult(fraction, displacement, energy, area)

Bases: Result

A generalized stacking fault energy curve.

Attributes:

Name	Type	Description
fraction	ndarray	(P,) float64 fraction of the slip vector of each point.
displacement	ndarray	(P, 3) float64 displacement in Å of the upper half of each point.
energy	ndarray	(P,) float64 energy per area of the fault in J/m², 0 for no slip.
area	float64	The area of the fault in Ų.