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
-
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_collection_result(method, collection_name, based_on, **method_args)[source]¶ Function to remove a single collection_result
- Parameters:
- Parameters not completed
-
clear_description_result(aid, descriptor, **desc_args)[source]¶ Function to remove a single description_result
-
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:
-
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.Atomsobject 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).