matscipy.surface_reconstruction

Classes

SurfaceReconstruction(el, a0, calc, ...[, ...])

Object for mapping and applying a surface reconstruction in simple and multi-lattices.

class matscipy.surface_reconstruction.SurfaceReconstruction(el, a0, calc, directions, surf_dir, lattice, multilattice=False)

Bases: object

Object for mapping and applying a surface reconstruction in simple and multi-lattices.

The relaxation of a given free surface of a crystal at a given orientation can be mapped and saved. This relaxation can then be applied to atoms in a different ASE atoms object. This is extremely useful in the case of fracture mechanics, where surface relaxation can be mapped to the internal crack surfaces of an atoms object.

Methods

`apply_pandey_111`(atoms, surface_coords[, ...])	Function which applies the mapped out Pandey deformation to the surface layers in a supplied atoms structure. :param atoms: Atoms object which contains surface to relax :type atoms: ASE atoms object :param surface_coords: Coordinates of a point that lies on the free surface (or within one layer distance above it) :type surface_coords: array_like :param xlim: [x lower, x upper], x range to apply relaxation :type xlim: array_like :param ylim: [y lower, y upper], y range to apply relaxation :type ylim: array_like :param zlim: [z lower, z upper], z range to apply relaxation :type zlim: array_like :param search_dir: -1: surface is below point provided, 1: surface is above point provided :type search_dir: int :param atoms_for_cb: atoms object which allows the easy identification of sub-lattices in a multi-lattice crystal using the CubicCauchyBorn set_sublattices function. The difference between this and atoms may be periodic boundary conditions, for example. :type atoms_for_cb: ASE atoms object :param read_from_atoms: Whether or not to read in the cauchy-born sublattices from the atoms structure. This can be done if the atoms object contains arrays called lattice1mask and lattice2mask :type read_from_atoms: bool :param orientation: Which of the three different orientations of the Pandey reconstructions are being applied to the surface :type orientation: 0,1 or 2.
`apply_si_110`(atoms, surface_coords[, cb, ...])	Function which applies the mapped out Si deformation to the surface layers in a supplied atoms structure. :param atoms: Atoms object which contains surface to relax :type atoms: ASE atoms object :param surface_coords: Coordinates of a point that lies on the free surface (or within one layer distance above it) :type surface_coords: array_like :param xlim: [x lower, x upper], x range to apply relaxation :type xlim: array_like :param ylim: [y lower, y upper], y range to apply relaxation :type ylim: array_like :param zlim: [z lower, z upper], z range to apply relaxation :type zlim: array_like :param search_dir: -1: surface is below point provided, 1: surface is above point provided :type search_dir: int :param atoms_for_cb: atoms object which allows the easy identification of sub-lattices in a multi-lattice crystal using the CubicCauchyBorn set_sublattices function. The difference between this and atoms may be periodic boundary conditions, for example. :type atoms_for_cb: ASE atoms object :param read_from_atoms: Whether or not to read in the cauchy-born sublattices from the atoms structure. This can be done if the atoms object contains arrays called lattice1mask and lattice2mask :type read_from_atoms: bool :param orientation: Which of the three different orientations of the Pandey reconstructions are being applied to the surface :type orientation: 0,1 or 2.
`apply_surface_shift`(atoms, surface_coords[, ...])	Function which applies the mapped out deformation to the surface layers in a supplied atoms structure. :param atoms: Atoms object which contains surface to relax :type atoms: ASE atoms object :param surface_coords: Coordinates of a point that lies on the free surface (or within one layer distance above it) :type surface_coords: array_like :param xlim: [x lower, x upper], x range to apply relaxation :type xlim: array_like :param ylim: [y lower, y upper], y range to apply relaxation :type ylim: array_like :param zlim: [z lower, z upper], z range to apply relaxation :type zlim: array_like :param search_dir: -1: surface is below point provided, 1: surface is above point provided :type search_dir: int :param atoms_for_cb: atoms object which allows the easy identification of sub-lattices in a multi-lattice crystal using the CubicCauchyBorn set_sublattices function. The difference between this and atoms may be periodic boundary conditions, for example. :type atoms_for_cb: ASE atoms object :param read_from_atoms: Whether or not to read in the cauchy-born sublattices from the atoms structure. This can be done if the atoms object contains arrays called lattice1mask and lattice2mask :type read_from_atoms: bool.
`identify_layers`(atoms, surface_coords[, ...])	Function for identifying the layers adjacent to a surface, in a supplied atoms structure. This allows a mapped relaxation to be easily applied to a surface. :param atoms: Atoms object which contains surface to relax :type atoms: ASE atoms object :param surface_coords: Coordinates of a point that lies on the free surface (or within one layer distance above it) :type surface_coords: array_like :param xlim: [x lower, x upper], x range to apply relaxation :type xlim: array_like :param ylim: [y lower, y upper], y range to apply relaxation :type ylim: array_like :param zlim: [z lower, z upper], z range to apply relaxation :type zlim: array_like :param search_dir: -1: surface is below point provided, 1: surface is above point provided :type search_dir: int :param atoms_for_cb: atoms object which allows the easy identification of sub-lattices in a multi-lattice crystal using the CubicCauchyBorn set_sublattices function. The difference between this and atoms may be periodic boundary conditions, for example. :type atoms_for_cb: ASE atoms object :param read_from_atoms: Whether or not to read in the cauchy-born sublattices from the atoms structure. This can be done if the atoms object contains arrays called lattice1mask and lattice2mask :type read_from_atoms: bool.
`identify_pandey_layers`(atoms, surface_coords)	Function for identifying the layers adjacent to a surface, in a supplied atoms structure.
`identify_si_110_layers`(atoms, surface_coords)	Function for identifying the layers adjacent to a surface, in a supplied atoms structure.
`map_pandey_111`([fmax, layers, cutoff, ...])	Map the diamond structure 111 pandey relaxation of the crystal surface a certain number of layers deep. As this relaxation breaks surface symmetry, one can map it in 3 different orientations. :param fmax: Force tolerance for relaxation :type fmax: float :param layers: Number of layers deep to map the free surface :type layers: int :param cutoff: Cutoff of the potential being used - used to decide the number of atoms beneath the mapped layers that need to be modelled :type cutoff: float :param shift: Amount to shift the bulk structure before the surface is mapped such that the top layer of surface is physically meaningful. One use case of this would be to adjust the top layer of atoms being mapped in diamond such that it matches the top layer of atoms seen on the cleavage plane. :type shift: float :param switch: Whether or not to switch the sublattices around in the mapped structure. (Essentially, the correct surface can always be found from some combination of shift and switch) :type switch: bool :param orientation: Which of the three different orientations of the Pandey reconstruction to map :type orientation: 0,1,2.
`map_si_110_3x1`([fmax, layers, cutoff, ...])	Map the silicon 110 3x1 relaxation of the crystal. :2: (WARNING/2) Title underline too short. Map the silicon 110 3x1 relaxation of the crystal. ------------------------------ fmax float Force tolerance for relaxation layers int Number of layers deep to map the free surface cutoff float Cutoff of the potential being used - used to decide the number of atoms beneath the mapped layers that need to be modelled shift float Amount to shift the bulk structure before the surface is mapped such that the top layer of surface is physically meaningful. One use case of this would be to adjust the top layer of atoms being mapped in diamond such that it matches the top layer of atoms seen on the cleavage plane. switch bool Whether or not to switch the sublattices around in the mapped structure. (Essentially, the correct surface can always be found from some combination of shift and switch) orientation int, 1 or 0 Whether to flip the reconstruction by 180 degrees. This is necessary for the lower surface.
`map_surface`([fmax, layers, cutoff, shift, ...])	Map the relaxation of the crystal surface a certain number of layers deep. :param fmax: Force tolerance for relaxation :type fmax: float :param layers: Number of layers deep to map the free surface :type layers: int :param cutoff: Cutoff of the potential being used - used to decide the number of atoms beneath the mapped layers that need to be modelled :type cutoff: float :param shift: Amount to shift the bulk structure before the surface is mapped such that the top layer of surface is physically meaningful. One use case of this would be to adjust the top layer of atoms being mapped in diamond such that it matches the top layer of atoms seen on the cleavage plane. :type shift: float :param switch: Whether or not to switch the sublattices around in the mapped structure. (Essentially, the correct surface can always be found from some combination of shift and switch) :type switch: bool :param invert_dirs: Whether to invert the components of the mapped shifts. This is useful in the case where a surface which originally has mirror symmetry in a certain plane can break this symmetry during reconstruction. This is the case for the 110 silicon reconstructed surface, where the surface breaks mirror symmetry in the {001} type plane during reconstruction. Two possible surfaces can form, related through diad symmetry. To map the other surface, one has to switch sublattices and invert the mapped displacements along the <001> type direction. :type invert_dirs: bool array.

__init__(el, a0, calc, directions, surf_dir, lattice, multilattice=False)

Parameters:

el (string) – Element crystal is composed of in ASE format
a0 (float) – Lattice constant of crystal
calc (ASE calculator object) – Calculator for surface relaxation
directions (list) – The x, y and z lab frame directions expressed in the lattice frame. e.g directions=[[1,1,1], [0,-1,1], [-2,1,1]]
surf_dir (int) – Direction which is normal to the free surface. Can be 0, 1 or 2 for lab x, lab y or lab z (as defined by directions).
lattice (ASE ase.lattice.cubic function) – Callable function which can be used to generate the crystal.

map_surface(fmax=0.0001, layers=6, cutoff=10, shift=0, switch=False, invert_dirs=[False, False, False])

Map the relaxation of the crystal surface a certain number of layers deep. :param fmax: Force tolerance for relaxation :type fmax: float :param layers: Number of layers deep to map the free surface :type layers: int :param cutoff: Cutoff of the potential being used - used to decide the number of

atoms beneath the mapped layers that need to be modelled

Parameters:

shift (float) – Amount to shift the bulk structure before the surface is mapped such that the top layer of surface is physically meaningful. One use case of this would be to adjust the top layer of atoms being mapped in diamond such that it matches the top layer of atoms seen on the cleavage plane.
switch (bool) – Whether or not to switch the sublattices around in the mapped structure. (Essentially, the correct surface can always be found from some combination of shift and switch)
invert_dirs (bool array) – Whether to invert the components of the mapped shifts. This is useful in the case where a surface which originally has mirror symmetry in a certain plane can break this symmetry during reconstruction. This is the case for the 110 silicon reconstructed surface, where the surface breaks mirror symmetry in the {001} type plane during reconstruction. Two possible surfaces can form, related through diad symmetry. To map the other surface, one has to switch sublattices and invert the mapped displacements along the <001> type direction.

identify_layers(atoms, surface_coords, xlim=None, ylim=None, zlim=None, search_dir=-1, atoms_for_cb=None, read_from_atoms=False)

Function for identifying the layers adjacent to a surface, in a supplied atoms structure. This allows a mapped relaxation to be easily applied to a surface. :param atoms: Atoms object which contains surface to relax :type atoms: ASE atoms object :param surface_coords: Coordinates of a point that lies on the free surface (or within one layer distance above it) :type surface_coords: array_like :param xlim: [x lower, x upper], x range to apply relaxation :type xlim: array_like :param ylim: [y lower, y upper], y range to apply relaxation :type ylim: array_like :param zlim: [z lower, z upper], z range to apply relaxation :type zlim: array_like :param search_dir: -1: surface is below point provided, 1: surface is above point provided :type search_dir: int :param atoms_for_cb: atoms object which allows the easy identification of sub-lattices in a multi-lattice

crystal using the CubicCauchyBorn set_sublattices function. The difference between this and atoms may be periodic boundary conditions, for example.

Parameters:: read_from_atoms (bool) – Whether or not to read in the cauchy-born sublattices from the atoms structure. This can be done if the atoms object contains arrays called lattice1mask and lattice2mask
Returns:: layer_mask_set – A 2D array dimensions [nlayers,natoms] where a row i is a mask for ‘atoms’ corresponding to a layer i deep from the surface. In the case of a multi-lattice, two masks are returned, one for each of the sublattices on each layer.
Return type:: array_like, bool

apply_surface_shift(atoms, surface_coords, cb=None, xlim=None, ylim=None, zlim=None, search_dir=-1, atoms_for_cb=None, read_from_atoms=False)

Function which applies the mapped out deformation to the surface layers in a supplied atoms structure. :param atoms: Atoms object which contains surface to relax :type atoms: ASE atoms object :param surface_coords: Coordinates of a point that lies on the free surface (or within one layer distance above it) :type surface_coords: array_like :param xlim: [x lower, x upper], x range to apply relaxation :type xlim: array_like :param ylim: [y lower, y upper], y range to apply relaxation :type ylim: array_like :param zlim: [z lower, z upper], z range to apply relaxation :type zlim: array_like :param search_dir: -1: surface is below point provided, 1: surface is above point provided :type search_dir: int :param atoms_for_cb: atoms object which allows the easy identification of sub-lattices in a multi-lattice

crystal using the CubicCauchyBorn set_sublattices function. The difference between this and atoms may be periodic boundary conditions, for example.

Parameters:: read_from_atoms (bool) – Whether or not to read in the cauchy-born sublattices from the atoms structure. This can be done if the atoms object contains arrays called lattice1mask and lattice2mask

map_pandey_111(fmax=0.0001, layers=6, cutoff=10, orientation=0, shift=0, switch=False)

Map the diamond structure 111 pandey relaxation of the crystal surface a certain number of layers deep. As this relaxation breaks surface symmetry, one can map it in 3 different orientations. :param fmax: Force tolerance for relaxation :type fmax: float :param layers: Number of layers deep to map the free surface :type layers: int :param cutoff: Cutoff of the potential being used - used to decide the number of

atoms beneath the mapped layers that need to be modelled

Parameters:

shift (float) – Amount to shift the bulk structure before the surface is mapped such that the top layer of surface is physically meaningful. One use case of this would be to adjust the top layer of atoms being mapped in diamond such that it matches the top layer of atoms seen on the cleavage plane.
switch (bool) – Whether or not to switch the sublattices around in the mapped structure. (Essentially, the correct surface can always be found from some combination of shift and switch)
orientation (0,1,2) – Which of the three different orientations of the Pandey reconstruction to map

identify_pandey_layers(atoms, surface_coords, xlim=None, ylim=None, zlim=None, search_dir=-1, atoms_for_cb=None, read_from_atoms=False, frame_dirs=None, orientation=0)

Function for identifying the layers adjacent to a surface, in a supplied atoms structure. This allows a mapped relaxation to be easily applied to a surface. This implementation is specific to the 111 Pandey reconstruction, as more atoms need to be identified due to the breaking of surface symmetry.

Parameters:

atoms (ASE atoms object) – Atoms object which contains surface to relax
surface_coords (array_like) – Coordinates of a point that lies on the free surface (or within one layer distance above it)
xlim (array_like) – [x lower, x upper], x range to apply relaxation
ylim (array_like) – [y lower, y upper], y range to apply relaxation
zlim (array_like) – [z lower, z upper], z range to apply relaxation
search_dir (int) – -1: surface is below point provided, 1: surface is above point provided
atoms_for_cb (ASE atoms object) – atoms object which allows the easy identification of sub-lattices in a multi-lattice crystal using the CubicCauchyBorn set_sublattices function. The difference between this and atoms may be periodic boundary conditions, for example.
read_from_atoms (bool) – Whether or not to read in the cauchy-born sublattices from the atoms structure. This can be done if the atoms object contains arrays called lattice1mask and lattice2mask
frame_dirs – The frame in which the Pandey reconstruction was mapped out - the atoms in the supplied frame will need to be rotated to this frame before the reconstruction can be applied
orientation (0,1 or 2) – Which of the three different orientations of the Pandey reconstructions are being applied to the surface

Returns:

layer_mask_set – A 2D array dimensions [nlayers,natoms] where a row i is a mask for ‘atoms’ corresponding to a layer i deep from the surface. In the case of a multi-lattice, two masks are returned, one for each of the sublattices on each layer.

Return type:

array_like, bool

apply_pandey_111(atoms, surface_coords, cb=None, xlim=None, ylim=None, zlim=None, search_dir=-1, atoms_for_cb=None, read_from_atoms=False, orientation=0)

Function which applies the mapped out Pandey deformation to the surface layers in a supplied atoms structure. :param atoms: Atoms object which contains surface to relax :type atoms: ASE atoms object :param surface_coords: Coordinates of a point that lies on the free surface (or within one layer distance above it) :type surface_coords: array_like :param xlim: [x lower, x upper], x range to apply relaxation :type xlim: array_like :param ylim: [y lower, y upper], y range to apply relaxation :type ylim: array_like :param zlim: [z lower, z upper], z range to apply relaxation :type zlim: array_like :param search_dir: -1: surface is below point provided, 1: surface is above point provided :type search_dir: int :param atoms_for_cb: atoms object which allows the easy identification of sub-lattices in a multi-lattice

crystal using the CubicCauchyBorn set_sublattices function. The difference between this and atoms may be periodic boundary conditions, for example.

Parameters:

read_from_atoms (bool) – Whether or not to read in the cauchy-born sublattices from the atoms structure. This can be done if the atoms object contains arrays called lattice1mask and lattice2mask
orientation (0,1 or 2) – Which of the three different orientations of the Pandey reconstructions are being applied to the surface

map_si_110_3x1(fmax=0.0001, layers=6, cutoff=10, switch=False, orientation=0, shift=0, permute=False)

Map the silicon 110 3x1 relaxation of the crystal.

fmaxfloat: Force tolerance for relaxation
layersint: Number of layers deep to map the free surface
cutofffloat: Cutoff of the potential being used - used to decide the number of atoms beneath the mapped layers that need to be modelled
shiftfloat: Amount to shift the bulk structure before the surface is mapped such that the top layer of surface is physically meaningful. One use case of this would be to adjust the top layer of atoms being mapped in diamond such that it matches the top layer of atoms seen on the cleavage plane.
switchbool: Whether or not to switch the sublattices around in the mapped structure. (Essentially, the correct surface can always be found from some combination of shift and switch)
orientationint, 1 or 0: Whether to flip the reconstruction by 180 degrees. This is necessary for the lower surface.

identify_si_110_layers(atoms, surface_coords, xlim=None, ylim=None, zlim=None, search_dir=-1, atoms_for_cb=None, read_from_atoms=False, frame_dirs=None, orientation=0, switch=False)

Function for identifying the layers adjacent to a surface, in a supplied atoms structure. This allows a mapped relaxation to be easily applied to a surface. This implementation is specific to the 111 Pandey reconstruction, as more atoms need to be identified due to the breaking of surface symmetry.

Parameters:

atoms (ASE atoms object) – Atoms object which contains surface to relax
surface_coords (array_like) – Coordinates of a point that lies on the free surface (or within one layer distance above it)
xlim (array_like) – [x lower, x upper], x range to apply relaxation
ylim (array_like) – [y lower, y upper], y range to apply relaxation
zlim (array_like) – [z lower, z upper], z range to apply relaxation
search_dir (int) – -1: surface is below point provided, 1: surface is above point provided
atoms_for_cb (ASE atoms object) – atoms object which allows the easy identification of sub-lattices in a multi-lattice crystal using the CubicCauchyBorn set_sublattices function. The difference between this and atoms may be periodic boundary conditions, for example.
read_from_atoms (bool) – Whether or not to read in the cauchy-born sublattices from the atoms structure. This can be done if the atoms object contains arrays called lattice1mask and lattice2mask
frame_dirs – The frame in which the Pandey reconstruction was mapped out - the atoms in the supplied frame will need to be rotated to this frame before the reconstruction can be applied
orientation (0,1 or 2) – Which of the three different orientations of the Pandey reconstructions are being applied to the surface

Returns:

layer_mask_set – A 2D array dimensions [nlayers,natoms] where a row i is a mask for ‘atoms’ corresponding to a layer i deep from the surface. In the case of a multi-lattice, two masks are returned, one for each of the sublattices on each layer.

Return type:

array_like, bool

apply_si_110(atoms, surface_coords, cb=None, xlim=None, ylim=None, zlim=None, search_dir=-1, atoms_for_cb=None, read_from_atoms=False, orientation=0, switch=False)

Function which applies the mapped out Si deformation to the surface layers in a supplied atoms structure. :param atoms: Atoms object which contains surface to relax :type atoms: ASE atoms object :param surface_coords: Coordinates of a point that lies on the free surface (or within one layer distance above it) :type surface_coords: array_like :param xlim: [x lower, x upper], x range to apply relaxation :type xlim: array_like :param ylim: [y lower, y upper], y range to apply relaxation :type ylim: array_like :param zlim: [z lower, z upper], z range to apply relaxation :type zlim: array_like :param search_dir: -1: surface is below point provided, 1: surface is above point provided :type search_dir: int :param atoms_for_cb: atoms object which allows the easy identification of sub-lattices in a multi-lattice

crystal using the CubicCauchyBorn set_sublattices function. The difference between this and atoms may be periodic boundary conditions, for example.

Parameters:

read_from_atoms (bool) – Whether or not to read in the cauchy-born sublattices from the atoms structure. This can be done if the atoms object contains arrays called lattice1mask and lattice2mask
orientation (0,1 or 2) – Which of the three different orientations of the Pandey reconstructions are being applied to the surface