gblearn.gb¶
Functions and classes for interacting with grain boundaries.
Classes
GrainBoundary (xyz, types, box, Z[, extras, …]) |
Represents a grain boundary that is defined by a list of atomic positions. |
GrainBoundaryCollection (name, root[, store, …]) |
Represents a collection of grain boundaries and the unique environments between them. |
API Documentation¶
Functions and classes for interacting with grain boundaries.
-
class
gblearn.gb.
GrainBoundary
(xyz, types, box, Z, extras=None, selectargs=None, **soapargs)[source] Represents a grain boundary that is defined by a list of atomic positions.
Parameters: - xyz (numpy.ndarray) – cartesian position of the atoms at the boundary. Shape is (N, 3).
- types (numpy.ndarray) – of int atom types for each atom in the xyz list.
- box (numpy.ndarray) – box dimensions in cartesian directions in format lo hi. Shape (3, 2). Also supports tricilinic boxes when shape (3, 3) is specified.
- Z (int or list) – element code(s) for the atomic species.
- extras (dict) – keys are additional atomic attributes; values are lists of attribute values. Value arrays must have same length as xyz.
- selectargs (dict) – keyword arguments passed to the selection routine that sliced the GB atoms in the first place. Needed to ensure consistency when SOAP matrix is constructed.
- soapargs (dict) – keyword arguments to pass to the constructor of the
SOAPCalculator
that will be used to calculate the P matrix for this GB.
-
lattice
¶ numpy.ndarray – array of lattice vector for the grain boundary box; this includes padding in the x-direction to allow a “surface” for the outermost atoms of the GB slice.
-
calculator
¶ ~gblearn.soap.SOAPCalculator – calculator for getting the SOAP vector matrix for this GB.
-
Z
¶ int or list – element code(s) for the atomic species.
-
P
¶ numpy.ndarray – SOAP vector matrix; shape (N, S), where N is the number of atoms at the boundary and S is the dimensionality of the SOAP vector space (which varies with SOAP parameters).
-
LAEs
¶ list – of tuple with (PID, VID) corresponding to the unique LAE number in the collection’s global unique set.
-
K
Returns the kernel similarity matrix between for the P matrix of this grain boundary.
-
NP
Returns the normalized P matrix where each row is normalized by its norm.
-
atoms
Returns an atoms object for the boundary that can be used for calculating the SOAP vectors.
Parameters: Z (int) – element code for the atomic species.
-
gbids
Calculates the set of atom ids that fall within the padding/cutoff parameters used for initial atom selection.
Returns: of ids in this GBs atoms list that fall within the padding constraints of the selection. Return type: numpy.ndarray
-
load
(attr, filepath)[source] Loads a SOAP matrix P for this GB from serialized file.
Parameters:
-
save_xyz
(filename, species=None, vacuum=False)[source] Writes the grain boundary atoms to extended XYZ file format that can be used with QUIP.
Parameters:
-
soap
()[source] Calculates the SOAP vector matrix for the atomic environments at the grain boundary.
Parameters:
-
trim
(ids=None)[source] Trims the atoms list, types list and any extras in this GB object so that it only includes atoms that fall within the cutoff constraints of the selection.
Parameters: ids (numpy.ndarray) – of atom ids in the list that should be kept. If not provided, it will be calculated from gbids
.
-
class
gblearn.gb.
GrainBoundaryCollection
(name, root, store=None, rxgbid=None, sortkey=None, reverse=False, seed=None, **soapargs)[source] Represents a collection of grain boundaries and the unique environments between them.
Warning
If you don’t specify a path for store, any results (such as SOAP matrices, ASR, LER, etc. will not be saved to disk. Also, they won’t be loaded from disk if they already exist.
Parameters: - name (str) – identifier for this collection.
- root (str) – path to the directory where the raw GB atomic descriptions are located.
- store (str) – path to the
ResultStore
root directory that this collection’s results are stored in. To use a memory-only store, leave this as None. - rxgbid (str) – regex pattern for extracting the gbid for each GB. Any files that don’t match the regex are automatically excluded. The regex should include a named group (?P<gbid>…) so that the GB id can be extracted correctly. If not specified, the file name is used as the gbid.
- sortkey (function) – when root is investigated to load GBs, the file names are first sorted; here you can specify a custom sorting function.
- reverse (bool) – for GB file name sorting (see sortkey), whether to reverse the order.
- seed (numpy.ndarray) – seed SOAP vector for calculating unique LAEs. This is usually the SOAP vector of the perfect bulk crystal in the GB.
- soapargs (dict) – key-value pairs for constructing the SOAP descriptor.
-
name
¶ str – identifier for this collection.
-
root
¶ str – path to the directory where the raw GB atomic descriptions are located.
-
store
¶ gblearn.io.ResultStore – storage manager for all the intermediate results generated by this collection.
-
unique
¶ dict – keys are float values of epsilon for comparing environments; values are themselves dictionaries that have keys as tuple of (gbid, aid) with aid the id of the atom (row id) in the SOAP vector for the GB; value is the SOAP vector already found to be unique for that value of epsilon.
-
equivalent
¶ dict – keys are float values of epsilon for comparing environments; values are themselves dictionaries that have gbid keys values are a dict having linked keys with
unique
and values a list of aid in the GB whose LAEs that are equivalent to the unique LAE represented by the key.
-
soapargs
¶ dict – key-value pairs for constructing the SOAP descriptor.
-
ASR
Returns the ASR for the GB collection.
-
LER
(eps)[source] Produces the LAE fingerprint for each GB in the system. The LAE figerprint is the percentage of the GBs local environments that belong to each unique LAE type.
Parameters: eps (float) – cutoff value for deciding whether two vectors are unique. Returns: - rows represent GBs; columns are the percentage of unique
- local environments of each type in each GB.
Return type: numpy.ndarray
-
P
Returns the computed SOAP matrices for each GB in the collection.
-
U
(eps)[source] Returns the uniquified set of environments for the GB collection and current soapargs.
Parameters: eps (float) – similarity threshlod parameter.
-
load
(parser=None, **kwargs)[source] Loads the GBs from their files to create
GrainBoundary
objects.Note
The
GrainBoundary
objects are stored in this objects dictionary (it inherits fromOrderedDict
). Thuskeys
are the gbid andvalues
are theGrainBoundary
instances, in the sorted order that they were discovered.Parameters: - parser – object used to parse the raw GB file. Defaults to
gblearn.lammps.Timestep
. Class should have a method gb that constructs aGrainBoundary
instance. - kwargs (dict) – keyword arguments passed to the gb method of
parser. For example, see
gblearn.lammps.Timestep.gb()
.
- parser – object used to parse the raw GB file. Defaults to
-
soap
()[source] Calculates the SOAP vector matrix for the atomic environments at each grain boundary.
-
uniquify
(eps)[source] Extracts all the unique LAEs in the entire GB system using the specified epsilon similarity value.
Warning
This method does not verify the completion status of any previous
uniquify()
attempts. It just re-runs everything and clobbers any existing results for the specified value of epsilon.Parameters: eps (float) – similarity scores below this value are considered identical. Two actually identical GBs will have a similarity score of 0 by this metric, so smaller is more similar. Returns: with keys U and GBs. The U key has a dictionary of (PID, VID) identifiers for the unique LAEs in the GB collection. The values are the corresponding SOAP vectors. GBs is a dictionary with gbid keys and values being a dict keyed by unique LAEs with values a list of (PID, VID) identifiers from the global GB collection. Return type: dict