surface_energy_static.py

Calculation functions

relax_system(lammps_command: str, system: System, potential: Potential, mpi_command: str | None = None, etol: float = 0.0, ftol: float = 0.0, maxiter: int = 10000, maxeval: int = 100000, dmax: float = 0.01, lammps_date: date | None = None) → dict

Sets up and runs the min.in LAMMPS script for performing an energy/force minimization to relax a system.

Parameters:

  • lammps_command (str) – Command for running LAMMPS.

  • system (atomman.System) – The system to perform the calculation on.

  • potential (atomman.lammps.Potential) – The LAMMPS implemented potential to use.

  • mpi_command (str, optional) – The MPI command for running LAMMPS in parallel. If not given, LAMMPS will run serially.

  • etol (float, optional) – The energy tolerance for the structure minimization. This value is unitless. (Default is 0.0).

  • ftol (float, optional) – The force tolerance for the structure minimization. This value is in units of force. (Default is 0.0).

  • maxiter (int, optional) – The maximum number of minimization iterations to use (default is 10000).

  • maxeval (int, optional) – The maximum number of minimization evaluations to use (default is 100000).

  • dmax (float, optional) – The maximum distance in length units that any atom is allowed to relax in any direction during a single minimization iteration (default is 0.01 Angstroms).

  • lammps_date (datetime.date or None, optional) – The date version of the LAMMPS executable. If None, will be identified from the lammps_command (default is None).

Returns:

Dictionary of results consisting of keys:

  • ’logfile’ (str) - The name of the LAMMPS log file.

  • ’initialdatafile’ (str) - The name of the LAMMPS data file used to import an inital configuration.

  • ’initialdumpfile’ (str) - The name of the LAMMPS dump file corresponding to the inital configuration.

  • ’finaldumpfile’ (str) - The name of the LAMMPS dump file corresponding to the relaxed configuration.

  • ’potentialenergy’ (float) - The total potential energy of the relaxed system.

Return type:

dict

surface_energy_static(lammps_command: str, ucell: System, potential: Potential, hkl: list | ndarray, mpi_command: str | None = None, sizemults: list | tuple | None = None, minwidth: float = None, even: bool = False, conventional_setting: str = 'p', cutboxvector: str = 'c', atomshift: list | ndarray | None = None, shiftindex: int | None = None, etol: float = 0.0, ftol: float = 0.0, maxiter: int = 10000, maxeval: int = 100000, dmax: float = 0.01) → dict

Evaluates surface formation energies by slicing along one periodic boundary of a bulk system.

Parameters:

  • lammps_command (str) – Command for running LAMMPS.

  • ucell (atomman.System) – The crystal unit cell to use as the basis of the stacking fault configurations.

  • potential (atomman.lammps.Potential) – The LAMMPS implemented potential to use.

  • hkl (array-like object) – The Miller(-Bravais) crystal fault plane relative to ucell.

  • mpi_command (str, optional) – The MPI command for running LAMMPS in parallel. If not given, LAMMPS will run serially.

  • sizemults (list or tuple, optional) – The three System.supersize multipliers [a_mult, b_mult, c_mult] to use on the rotated cell to build the final system. Note that the cutboxvector sizemult must be an integer and not a tuple. Default value is [1, 1, 1].

  • minwidth (float, optional) – If given, the sizemult along the cutboxvector will be selected such that the width of the resulting final system in that direction will be at least this value. If both sizemults and minwidth are given, then the larger of the two in the cutboxvector direction will be used.

  • even (bool, optional) – A True value means that the sizemult for cutboxvector will be made an even number by adding 1 if it is odd. Default value is False.

  • conventional_setting (str, optional) – Allows for rotations of a primitive unit cell to be determined from (hkl) indices specified relative to a conventional unit cell. Allowed settings: ‘p’ for primitive (no conversion), ‘f’ for face-centered, ‘i’ for body-centered, and ‘a’, ‘b’, or ‘c’ for side-centered. Default behavior is to perform no conversion, i.e. take (hkl) relative to the given ucell.

  • cutboxvector (str, optional) – Indicates which of the three system box vectors, ‘a’, ‘b’, or ‘c’, to cut with a non-periodic boundary (default is ‘c’).

  • atomshift (array-like object, optional) – A Cartesian vector shift to apply to all atoms. Can be used to shift atoms perpendicular to the fault plane to allow different termination planes to be cut. Cannot be given with shiftindex.

  • shiftindex (int, optional) – Allows for selection of different termination planes based on the preferred shift values determined by the underlying fault generation. Cannot be given with atomshift. If neither atomshift nor shiftindex given, then shiftindex will be set to 0.

  • etol (float, optional) – The energy tolerance for the structure minimization. This value is unitless. (Default is 0.0).

  • ftol (float, optional) – The force tolerance for the structure minimization. This value is in units of force. (Default is 0.0).

  • maxiter (int, optional) – The maximum number of minimization iterations to use (default is 10000).

  • maxeval (int, optional) – The maximum number of minimization evaluations to use (default is 100000).

  • dmax (float, optional) – The maximum distance in length units that any atom is allowed to relax in any direction during a single minimization iteration (default is 0.01 Angstroms).

Returns:

Dictionary of results consisting of keys:

  • ’dumpfile_base’ (str) - The filename of the LAMMPS dump file of the relaxed bulk system.

  • ’dumpfile_surf’ (str) - The filename of the LAMMPS dump file of the relaxed system containing the free surfaces.

  • ’E_total_base’ (float) - The total potential energy of the relaxed bulk system.

  • ’E_total_surf’ (float) - The total potential energy of the relaxed system containing the free surfaces.

  • ’A_surf’ (float) - The area of the free surface.

  • ’E_pot’ (float) - The per-atom potential energy of the relaxed bulk system.

  • ’E_surf_f’ (float) - The computed surface formation energy.

Return type:

dict

Raises:

ValueError – For invalid cutboxvectors