"""Python module for running PTM on an Asap list of atoms.
This module runs Polyhedral Template Matching on an Atoms object from ASE/Asap.
It requires that both ASE and Asap are installed.
This module can also be used as inspiration for how to use Polyhedral Template
Matching in other codes.
"""
import asap3
from asap3.Internal.Subject import Subject
from asap3.Internal.NeighborLocators import _decide_minimumimage
import numpy as np
import sys
[docs]
def PTM(atoms, cutoff=10.0, rmsd_max=None, **kwargs):
"""Run Polyhedral Template Matching on an Atoms object.
Parameters
----------
atoms : ase.Atoms
The atoms object.
cutoff : float, optional
A cutoff used for the neighbor list. It must be large enough that
all nearest neighbors are returned (second-nearest for BCC). Using
too large a value may impact performance, but not results. The
default is 10.0.
rmsd_max : float, optional
If set, matches with an RMSD above this threshold are reclassified as
unknown structure (type 0). This is done as post-processing, and is
completely equivalent to ``data['structure'][data['rmsd'] >
rmsd_max] = 0``.
target_structures : tuple of str, optional
The structures to be investigated. Defaults to
``('sc', 'fcc', 'hcp', 'ico', 'bcc')``. It MUST be a tuple, not a
list or other sequence.
calculate_strains : bool, optional
Set to ``True`` to calculate strains. The default is ``False``.
quick : bool, optional
Set to ``True`` to skip topological ordering of neighbors. It gives
a factor of two in speed, but more misclassified atoms at high
temperatures. The default is ``False``.
return_nblist : bool, optional
Return the neighbor list object used internally. This may be used
for preprocessing. Do not enable unless you need it, as this object
can use a lot of memory. The default is ``False``.
return_mappings : bool or tuple of str, optional
Return the mapping of neighbors to the template used internally. Set
to ``True`` to get mappings for all structures, or to a tuple of
structures to get them for some (see ``target_structures``).
Returns
-------
dict
A dictionary of NumPy arrays, each of the same length as the number
of atoms. In the descriptions below, ``i`` is the first index of the
array and identifies the atom.
``'structure'``
The local crystal structure around atom ``i``, if any.
0 = none; 1 = SC; 2 = FCC; 3 = HCP; 4 = Icosahedral; 5 = BCC.
``'alloytype'``
The alloy structure identified. 0 = unidentified; 1 = pure
element; 2 = L1_0; 3 = L1_2 majority atom; 4 = L1_2 minority
atom. 0 is returned if ``structure != 2`` or if no known alloy
structure is recognized.
``'rmsd'``
The RMSD error in the fitting to the template, or ``inf`` if no
structure was identified.
``'scale'``
The average distance to the nearest neighbors for structures 1-4;
or the average distance to nearest and next-nearest neighbors for
structure 5 (BCC); or ``inf`` if no structure was identified.
``'orientation'``
The orientation of the crystal lattice, expressed as a unit
quaternion. If no structure was found, the illegal value
``(0, 0, 0, 0)`` is returned.
``'strain'``
The strain tensor as a symmetric 3x3 matrix. Only present if
``calculate_strains=True``. The trace of the matrix is 1.0,
since a hydrostatic component of the strain cannot be determined
without a-priori knowledge of the reference lattice parameter.
If such knowledge is available, the hydrostatic component of the
strain can be calculated from ``scale[i]``.
``'info'``
A tuple of two integers: the number of atoms analyzed by PTM, and
the number of atoms skipped due to insufficient neighbors.
``'nblist'``
A neighbor list object. Only present if ``return_nblist=True``.
"""
for argument in ('target_structures', 'return_mappings'):
if argument in kwargs:
# The C++ code only accepts tuples of bytes (str in Python 2),
# we need more flexibility.
structs = kwargs[argument]
if structs is None:
continue
if isinstance(structs, tuple):
structs = list(structs) # Make mutable
for i, s in enumerate(structs):
if isinstance(s, str):
structs[i] = s.encode() # Convert to bytes
kwargs[argument] = tuple(structs)
minimum_image = _decide_minimumimage(cutoff, atoms)
data = asap3._asap.PTM_allatoms(atoms, cutoff, minimum_image=minimum_image, **kwargs)
if rmsd_max:
data['structure'][data['rmsd'] > rmsd_max] = 0
return data
[docs]
class PTMobserver(Subject):
"""Polyhedral Template Matching observer object.
By default, sets the tags of the atoms according to their local crystal
structure. 0 = none; 1 = FCC; 2 = HCP; 3 = BCC; 4 = Icosahedral; 5 = SC.
This class is intended for use as an observer, so its ``analyze`` method
is called automatically by e.g. the dynamics. It can itself act as a
subject, so a Plotter or a Trajectory can be called just after the
calculations. The ``get_data`` method returns the full dictionary of PTM
data from the last calculation.
Parameters
----------
atoms : ase.Atoms
The atoms object.
cutoff : float, optional
A cutoff used for the neighbor list. It must be large enough that
all nearest neighbors are returned (second-nearest for BCC). Using
too large a value may impact performance, but not results. The
default is 10.0.
rmsd_max : float, optional
If set, matches with an RMSD above this threshold are reclassified as
unknown structure (type 0). This is done as post-processing, and is
completely equivalent to ``data['structure'][data['rmsd'] >
rmsd_max] = 0``.
target_structures : tuple of str, optional
The structures to be investigated. Defaults to
``('sc', 'fcc', 'hcp', 'ico', 'bcc')``. It MUST be a tuple, not a
list or other sequence.
calculate_strains : bool, optional
Set to ``True`` to calculate strains. The default is ``False``.
quick : bool, optional
Set to ``True`` to skip topological ordering of neighbors. It gives
a factor of two in speed, but more misclassified atoms at high
temperatures. The default is ``False``.
quantity : str or None, optional
The quantity used to set the tags, either ``'structure'`` (the
default) or ``'alloytype'``. If ``None``, the tags are not set.
analyze_first : bool, optional
Whether an analysis should be made as soon as this object is created.
Leave as ``True`` if you plan to attach a Trajectory as an observer
to this object, and the Trajectory will save the initial state.
See Also
--------
PTM : The function performing the analysis.
"""
def __init__(self, atoms, cutoff=10.0, rmsd_max=None, target_structures=None,
calculate_strains=False, quick=False, quantity='structure',
analyze_first=True):
Subject.__init__(self)
self.atoms = atoms
self.cutoff = cutoff
self.rmsd_max = rmsd_max
self.target_structures = target_structures
self.strains = calculate_strains
self.quick = quick
self.quantity = quantity
if analyze_first:
self.analyze() # There will not be any observers yet.
[docs]
def analyze(self):
"Runs the PTM analysis."
self.data = PTM(self.atoms, cutoff=self.cutoff, rmsd_max=self.rmsd_max,
target_structures=self.target_structures,
calculate_strains=self.strains,
quick=self.quick)
if self.quantity:
self.atoms.set_tags(self.data[self.quantity])
self.call_observers()
update = analyze
def get_data(self):
return self.data
[docs]
class PTMdislocations(PTMobserver):
"""Polyhedral Template Matching observer detecting dislocations.
Sets the tags of the atoms according to their local crystal structure,
after postprocessing of the HCP atoms for dislocation detection. The
dislocation detection assumes that the majority of the system is in the
FCC structure.
Tags are set to 0 = none; 1 = FCC; 2 = HCP; 3 = BCC; 4 = Icosahedral;
5 = SC; 6 = Twin boundary; 7 = Stacking fault; 8 = Partial dislocation
line.
Otherwise, this object is like :class:`PTMobserver`; refer to it for
further documentation and parameters, with the exception that the
``quantity`` parameter is ignored.
"""
# For HCP atoms, which neighbors are in the same basal plane, and
# which are in the planes above and below? The neighbors are located
# like this.
#
# (x) Basal plane atom [y] Atom in plane above
#
# (7)
#
#
# (11) [5] (8)
#
#
# (@) [3]
#
#
# (12) [1] (9)
#
#
# (10)
#
# 6 below 5; 4 below 3; 2 below 1.
# In this numbering, the central atom(@) is number 0, but that is not returned
# by the PTM code, so all indices must be one less than the number above.
hcp_inplane = np.array((7, 8, 9, 10, 12, 11)) - 1
hcp_above = np.array((5, 3, 1)) - 1
hcp_below = np.array((6, 4, 2)) - 1
[docs]
def analyze(self):
"Runs the PTM analysis."
self.data = PTM(self.atoms, cutoff=self.cutoff, rmsd_max=self.rmsd_max,
target_structures=self.target_structures,
calculate_strains=self.strains,
quick=self.quick, return_mappings=('hcp',))
new_s = self.data['structure']
s = np.array(new_s) # A copy so we can change the original.
mappings = self.data['mappings']
hcpatoms = (s == 2).nonzero()[0]
if getattr(self.atoms, "parallel", False):
# Parallel simulation - we need to communicate the structures
nghosts = len(self.atoms.ghosts['positions'])
label = '_ptm_disloc_analysis_internal'
self.atoms.arrays[label] = s
self.atoms.ghosts[label] = np.zeros(nghosts, dtype=s.dtype)
del s # Suppress a warning from asap - no extra references are allowed
self.atoms.calc.update_ghost_data(self.atoms)
s = self.atoms.arrays[label] # Restore s - same as before.
ghost_structs = self.atoms.ghosts[label]
del self.atoms.ghosts[label]
del self.atoms.arrays[label]
s = np.concatenate((s, ghost_structs))
for i in hcpatoms:
mapping = mappings[i]
nhcp = 0
nfcc = 0
nbsum = np.zeros(3)
# Atom types of the neighbors
inplane = s[mapping[self.hcp_inplane]] == 2
inplanesum = inplane.sum()
above = s[mapping[self.hcp_above]] == 2
abovesum = above.sum()
below = s[mapping[self.hcp_below]] == 2
belowsum = below.sum()
fccsum = (s[mapping] == 1).sum()
# Heuristic for finding typical structures of HCP atoms
if inplanesum == 6 and abovesum == 0 and belowsum == 0:
# A single basal plane of HCP atoms: Twin boundary
new_s[i] = 6
elif inplanesum == 6 and ((abovesum == 3 and belowsum == 0) or
(abovesum == 0 and belowsum == 3)):
# Looks like two parallel planes of HCP atoms: Stacking fault.
new_s[i] = 7
elif (3 <= inplanesum <= 5
and inplanesum + abovesum + belowsum + fccsum >= 11
and (bool(abovesum) ^ bool(belowsum))):
# A partial basal plane, with a possibly partial plane either
# above or below, but not both. At most one non-HCP/FCC atom.
#
# This could be the edge of a SF ribbon (i.e. a partial dislocation
# core) if the atoms in the plane are on the same side. Check that
# there are only two boundaries between HCP and non-HCP atoms
rolled = np.roll(inplane, 1)
if np.logical_xor(inplane, rolled).sum() == 2:
new_s[i] = 8
# Kill the mappings dictionary to save memory
del mappings, self.data['mappings']
self.atoms.set_tags(new_s)
self.atoms.set_array("rmsd", self.data['rmsd'])
self.call_observers()
update = analyze