Modules

Functions and AtomsCollection class for interacting with collections of ASE Atoms objects

class pyrelate.collection.AtomsCollection(name, store=None, data=None)[source]

Represents a collection of ASE Atoms objects

Attributes:
  • self (dict): inherits from dictionary
  • name (str) : identifier for this collection
  • store (Store) : store to hold all the results and other information. Defaults to None, which creates a store in the current directory named ‘Store’

Warning

Make sure to have unique collection names, will be used for LER

aids()[source]

Returns sorted list of atom ID’s (aids) in collection

clear(descriptor=None, aid=None, collection_name=None, method=None, based_on=None, **kwargs)[source]

Function to delete specified results from Store.

Functionality includes:

  • remove a specific description result
  • remove all descriptions
  • remove a specific collection result
  • remove all collection results created with specific method
  • remove all results in the store
Parameters:
descriptor (str): Descriptor to be cleared or descriptor with specific results to be cleared. Defaults to None. aid (str): Aid of Atoms object who’s results you want cleared. Defaults to None, in which case all descriptor results will be cleared if descriptor is not none. collection_name (str): Name of collection that contain the results you want cleared. Defaults to None. Must be called with mothod parameter. method (str): Method to be cleared or method with specific results to be cleared. Defaults to None. based_on (str): Descriptor that specifc collection results are based on. Defaults to None. in which case all method results will be cleared if method and collection name are none. **kwargs (dict): Parameters associated with specifc descriptor or collection that will be cleared.
Example:
my_col.clear(descriptor="soap", aid="aid1", rcut=5.0, nmax=9, lmax=9) #clears single SOAP result with given parameters
my_col.clear(descriptor="soap") #clears all soap results from store
my_col.clear(collection_name="S5", method="ler", based_on="soap") #clears all collection results processed with ler from the collection named S5 and described with soap
my_col.clear(collection_name="S5". method="ler") #clears all collection results processed with ler from the collection named S5
my_col.clear() #clears all results from store
describe(descriptor, aid=None, fcn=None, override=False, **desc_args)[source]

Function to calculate and store atomic description.

User can specify a descriptor function to be used, or use those in descriptors.py. When there is a padding associated with the Atoms object, the padding atoms are deleted from the final description before being stored.

Parameters:
descriptor (str) : descriptor to be applied. aid (iterable or string) : Atoms ID’s (aid) of atomic systems to be described. Can pass in single aid string, or an iterable of aids. Defaults to None. When None, all ASE Atoms objects in AtomsCollection are described. fcn : function to apply said description. Defaults to none. When none, built in functions in descriptors.py are used. override (bool) : if True, descriptor will override any matching results in the store. Defaults to False. desc_args (dict) : Parameters associated with the description function specified. See documentation in descriptors.py for function details and parameters.

#FIXME old examples

Examples:
soap_args = {
    "rcut" : 5,
    "lmax" : 9,
    "nmax" : 9
}

my_col.describe("soap", **soap_args)

my_col.describe("my_soap", fcn=soap, **soap_args)
my_col.describe("asr", res_needed="my_soap", **soap_args)

ler_args = {
    "collection" : my_col,
    "res_needed" : "my_soap",
    "soap_fcn" : soap,
    "eps" : 0.1,
    "dissim_args" : {"gamma":4000},
    **soap_args
}

my_col.describe("ler", **ler_args)
get_collection_result(method, based_on, metadata=False, **method_args)[source]

Wrapper function to retrieve collection specific results from the store

get_description(idd, descriptor, metadata=False, **desc_args)[source]

Wrapper function to retrieve descriptor results from the store

process(method, based_on, fcn=None, override=None, **kwargs)[source]

Calculate and store collection specific results

Parameters:
method (str): string indicating the name of the descriptor to be applied based_on (str, dict): tuple holding the information necessary to get previously calculated results for use in processing. fcn (str): function to apply said processing method. Defaults to none. When none, built in functions in descriptors.py are used. override (bool): if True, results will override any matching results in the store. Defaults to False. kwargs (dict): Parameters associated with the processing function specified. See documentation in descriptors.py for function details and parameters.

Examples:

read(root, Z, f_format=None, rxid=None, prefix=None)[source]

Function to read atoms data into ASE Atoms objects and add to AtomsCollection.

Utilizes functionality in ASE to read in atomic data.

Parameters:
root (str) : relative file path (or list of file paths) to the file, or directory of files, where the raw atomic descriptions are located. Z (int) : atomic number of the elements to be read f_format (str) : format of data file. Defaults to None. See ASE’s documentation at ‘https://wiki.fysik.dtu.dk/ase/ase/io/io.html’ rxid (:obj: str, optional) : regex pattern for extracting the aid for each Atoms object. Defaults to None. The regex should include a named group (?P<aid>…) so that the id can be extracted correctly. If any files don’t match the regex or if it is not specified, the file name is used as the aid. prefix (str): optional prefix for aid. Defaults to none.
Example:
my_col.read(["/Ni/ni.p454.out", "/Ni/ni.p453.out"], 28, "lammps-dump-text", rxid=r'ni.p(?P<aid>\d+).out', prefix="Nickel")
my_col.read("/Ni/", 28, "lammps-dump-text", rxid=r'ni.p(?P<aid>\d+).out', prefix="Nickel")
subset(aids, name=None, store=None)[source]

Return an AtomsCollection containing the specified subset of the original collection.

Parameters:
aids (list): List containing the strings of all the aids to include in the new collection. name (string): Name of the new collection, default is the name of the original collection. store (string): String representing the location of the store, default (None) sets the current store as the store for the new collection, which is probably what you want most of the time.
Returns:
pyrelate.AtomsCollection
trim(trim, dim, pad=True)[source]

Trims off excess atoms and indicates padding (specified in a mask). #FIXME store trim and pad values for the entire collection

Padding may want to be included so that atoms have a full atomic environments at the edge, some descriptors that perform better with full atomic environments. The “mask” array is attached to the Atoms object, with 1 indicating atoms to be kept in the final description, and 0 to indicate padding atoms. You may get the mask by calling ‘my_col.get_array(“mask”)’.

Parameters:
trim (float or int) : value (in Angstroms) of the furthest atoms that you want included in the calculated results dim (int) : what dimension the grain boundary is in, 0 for x, 1 for y, 2 for z pad (boolean or float or int) : ‘True’ (default) gives a padding value equal to that of the trim, ‘False’ gives no padding, or specify the amount of padding wanted (in Angstroms).

Warning

The user must keep track of what trim and pad parameters were used, as the results stored will not indicate if they have been trimmed or not

Example:
my_col.trim(trim=4, dim=0)
my_col.trim(4, 0, pad=False)
pyrelate.descriptors.asr(collection, based_on, norm_asr=False)[source]

Average SOAP representation: average vectors from SOAP matrix into a single vector

Parameters:
norm_asr (bool): Normalize ASR vector. Default is False, not normalized.
pyrelate.descriptors.gaussian_dissimilarity(lae1, lae2, gamma)[source]

Gaussian (RBF) dissimilarity metric (used with LER) that varies between 0 and 1.

This metric is given by \(1 - \exp{(-\gamma*||x - x'||^2)}\). A dissimilarity value closer to 0 means the LAEs are more similar, while closer to 1 means more dissimilar.

Parameters:
lae1 (np.array): first lae to compare lae2 (np.array): second lae to compare gamma (float): gamma value
pyrelate.descriptors.ler(collection, based_on, eps, dissimilarity=<function gaussian_dissimilarity>, dissim_args={}, soap_fcn=None, seed=None, metric='euclidean', n_trees=10, search_k=-1, **kwargs)[source]

Local Environment Representation

Parameters:
atoms (‘ase.atoms.Atoms’): ASE atoms object to perform description on store (pyrelate.store.Store) : store to access previously computed SOAP matrix (automatically passed in with AtomsCollection.describe()) collection (pyrelate.collection.AtomsCollection): LER is collection specific, needed for computation eps (float): epsilon value indicating that any LAE’s outside this value are considered dissimilar. Descriptor and dissimilarity metric specific. res_needed (str): name of description whose results are needed to compute the LER. Defaults to ‘soap’. dissimilarity (function): dissimilarity metric function that has the first 2 parameters as the 2 LAE’s to be compared. dissim_args (dict): dictionary with any additional hyperparameter arguments for the given dissimilarity metric. soap_fcn (function): optional parameter for a function to compute SOAP matrix for the element’s perfect crystal on the fly. Defaults to None. When None, ‘soap’ function in descriptors.py will be used. seed(np.ndarray or list): perfect seed for the element being considered. Defaults to None. When None, seed will be generated on the fly. metric(str): For approximate nearest neighbor calculation. See Annoy’s documentation for more details. n_trees(int): For approximate nearest neighbor calculation. See Annoy’s documentation for more details. search_k(int): For approximate nearest neighbor calculation. See Annoy’s documentation for more details. soapargs (dict): Parameters associated with the SOAP description being used. Annoy’s documentation.
pyrelate.descriptors.soap(atoms, rcut, nmax, lmax, **kwargs)[source]

Smooth Overlap of Atomic Positions– pycsoap implementation

Parameters:
atoms (‘ase.atoms.Atoms’): ASE atoms object to perform description on nmax (int): bandwidth limits for the SOAP descriptor radial basis functions. lmax (int): bandwidth limits for the SOAP descriptor spherical harmonics. rcut (float): local environment finite cutoff parameter. kwargs (dict): Parameters associated with the description function

To see pycsoap’s documentation.

pyrelate.descriptors.sum(collection, based_on)[source]

Sum all rows of a descriptor matrix into a single vector

Parameters:

Functions and Store class for storing atomic descriptions

class pyrelate.store.Store(store_path=None)[source]

Class for efficient storing of description of the AtomsCollection

check_exists(store_section, level1, level2, based_on=None, explicit=False, **kwargs)[source]

Function to check if correct file structure is in place and if a result file exists for these parameters

Parameters:
store_section (str): corresponds to the store section being considered, the string “Descriptions” or “Collections”. level1 (str): First level of directory in store. In “Descriptions” section, corresponds to the aid. In the “Collections” section, corresponds to the method name. level2 (str): Second level of directory in store. In “Descriptions” section, corresponds to the descriptor name. In the “Collections” section, corresponds to the collection name. based_on (string, dict): If based_on is None, considered an atomic description. If not, considered a collection processing result.
clear_all()[source]

Function to remove all results from the Store

clear_collection_result(method, collection_name, based_on, **method_args)[source]

Function to remove a single collection_result

Parameters:
Parameters not completed
clear_description(aid, descriptor)[source]

Function to remove a description directory

clear_description_result(aid, descriptor, **desc_args)[source]

Function to remove a single description_result

clear_method(method, collection_name)[source]

Function to remove a method directory

get_collection_result(method, collection_name, based_on, metadata=False, **method_args)[source]

Function to retrieve collection specific results from the store for the given atoms id and parameters.

Parameters:
method (str): method name used to generate results collection_name (str): collection name based_on (Tuple of types (str, dict)): tuple holding the name of the descriptor the method uses the results of, and the parameters used in generating the results. **method_args: additional arguments to used in generating the method result metadata (bool): If True, return info dictionary with the result. Default is False. **method_args: arguments used in generating the result

Returns:

get_description(aid, descriptor, metadata=False, **desc_args)[source]

Function to retrieve description results from the store for the given atoms id and parameters.

Parameters:
aid (str): atoms id descriptor (str): descriptor name metadata (bool): If True, return info dictionary with the result. Default is False. **desc_args: arguments used in generating the result

Returns:

list_store_results()[source]

Print results currently stored in the Store

store_additional(result, store_as, info=None)[source]

Function to store any arbitrary results specified by the user

store_collection_result(result, info, method, collection_name, based_on, **method_args)[source]

Store collection specific results generated.

Parameters:
result: result to be stored info (dict): additional info dict to be stored simultaneously and used in result retrieval method (str): string giving the method used in generating results collection_name (str): name of the collection based_on (tuple of type (str, dict)): tuple containting a) the name of the descriptor the method is based on, and b) a dictionary holding the arguments used in the calculation of the descriptor results **method_args: additional arguments to used in generating the method result, any function arguments will be converted to a string of the function name before storing in the info dict
store_description(result, info, aid, descriptor, **desc_args)[source]

Function to store information into result store

Parameters:
result (pickle): computed result aid (str): atoms id descriptor (str): name of descriptor info (dict): dictionary holding additional information to be stored, including the parameters used in calculation kwargs (dict): arguments for computing descriptor, will be used to generate file names

Crystal definitions and SOAP vector calculations for simple elements.

pyrelate.elements.atoms(element)[source]

Returns an ase.Atoms object for the given element, using the tabulated lattice parameters.

Parameters:
element (str): name of the element.
pyrelate.elements.elements = {'Al': ('FaceCenteredCubic', 4.05, 13, [0]), 'Cr': ('BodyCenteredCubic', 2.91, 24, [0, 1]), 'Mg': ('HexagonalClosedPacked', {'a': 3.21, 'c/a': 1.633}, 12, [0, 1]), 'Ni': ('FaceCenteredCubic', 3.52, 28, [0])}

dict: keys are element names, values are a tuple of (str lattice, float lattice parameter, int element number, list basis indices).

pyrelate.elements.seed(element, soap_fcn, **soapargs)[source]

Computes the \(P\) matrix for the given element.

Parameters:
element (str): name of the element. soap_fcn (function): function to compute SOAP matrix. soapargs (dict): Parameters associated with the SOAP description being used.