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:
  • attr (str) – attribute to load from file; one of [‘P’, ‘R’].
  • filepath (str) – full path to the file to load.
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:
  • filename (str) – name/path to the file to save to.
  • species (str) – element name.
soap()[source]

Calculates the SOAP vector matrix for the atomic environments at the grain boundary.

Parameters:
  • subsel (str) – method for subselection of atoms to include in the SOAP descriptor. One of [“median”, “cna”].
  • subpar (str) – name of the parameter to pass to the selection routine.
  • kwargs (dict) – additional arguments to pass to the selection routine.
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 from OrderedDict). Thus keys are the gbid and values are the GrainBoundary 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 a GrainBoundary instance.
  • kwargs (dict) – keyword arguments passed to the gb method of parser. For example, see gblearn.lammps.Timestep.gb().
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