gblearn.io

Functions for I/O interaction of gblearn.gb.GrainBoundaryCollection objects and the many results they produce with disk storage.

Note

Whenever a new representation is added, a property getter and setter need to be added with documentation to the ResultStore. The three generic getter and setter functions for numpy arrays, aggregated arrays and dictionaries of parameterized aggregated arrays should be sufficient to handle any additional representations we may come up with.

Classes

DiskCollection(root, gbids[, restricted]) For large grain boundary collections, it may not be possible to keep all SOAP matrices and their derivatives in memory at the same time for processing.
ResultStore(gbids[, root, restricted]) Represents a collection of results for a GrainBoundaryCollection that can be cached because they are permanent for the particular collection.

API Documentation

Functions for I/O interaction of gblearn.gb.GrainBoundaryCollection objects and the many results they produce with disk storage.

Note

Whenever a new representation is added, a property getter and setter need to be added with documentation to the ResultStore. The three generic getter and setter functions for numpy arrays, aggregated arrays and dictionaries of parameterized aggregated arrays should be sufficient to handle any additional representations we may come up with.

class gblearn.io.DiskCollection(root, gbids, restricted=True)[source]

For large grain boundary collections, it may not be possible to keep all SOAP matrices and their derivatives in memory at the same time for processing. In these cases, it is preferable to read a matrix in, process it, and then delete it from memory right away.

Parameters:
  • root (str) – path to the folder where the array files are stored.
  • gbids (list) – of ids for each GB; the files should be stored as id.npy in the root directory.
  • restricted (bool) – when True, run in memory-restricted mode. Otherwise, the loaded array files are cached in memory for speedy multiple retrieval.
cache

dict – keys are GB ids in gbids; values are the corresponding numpy.ndarray files. This only has values in restricted is False.

files

dict – keys are GB ids, values are paths to the numpy array files.

class gblearn.io.ResultStore(gbids, root=None, restricted=True, **soapargs)[source]

Represents a collection of results for a GrainBoundaryCollection that can be cached because they are permanent for the particular collection.

Note

The result store creates separate sub-folders P_ for the full SOAP matrices of each GB; U_ for the unique decompositions at different epsilon values; ASR_ for the ASR representation; and LER_ for the LER representations (tied to particular epsilon values and unique decompositions).

Note

If any of the results (such as P, U, ASR or LER) are not saved in the store, None will be returned.

Note

If root=None then the results will only be cached in memory and not to disk.

Parameters:
  • gbids (list) – of identifiers for the individual members of the GB collection. The store makes sure that they match for a given directory so that results can be kept straight.
  • root (str) – path to the root directory for this result store.
  • restricted (bool) – when True, run in memory-restricted mode. Otherwise, the loaded array files are cached in memory for speedy multiple retrieval.
  • soapargs (dict) – arguments for the SOAP descriptor. See gblearn.soap.SOAPCalculator for information.
root

str – path to the root directory for this result store.

gbids

list – of identifiers for the individual members of the GB collection.

reps

list – of str representation names that will be handled by the result store.

soapargs

dict – arguments for the SOAP descriptor. See gblearn.soap.SOAPCalculator for information.

soapstr

list – of str soap arguments that are formatted to form a folder name for specific variations of the representations.

ASR

Returns the Averaged SOAP representation for this GB collection using the currently configured SOAP parameters (see SOAP).

LER

Gets the LER for the current SOAP configuration.

Returns:keys are values of epsilon, rounded to 5 decimal places; values are the Local Environment Representation for the GB collection. The keys in this dict are linked with those in U.
Return type:dict
P

SOAP Representation for each GB in the collection.

Note

The SOAP matrices returned will be for the currently configured values of lmax, nmax and rcut in the store.

Returns:keys are gbid, values are the SOAP reprentation for that particular GB.
Return type:dict
SOAP

Returns the current SOAP paramater configuration.

Returns:of SOAP arguments used to form the directory name for particular parameter sets. See soapstr.
Return type:tuple
SOAP_str

Returns the directory string for the current SOAP configuration. It is defined by nmax_lmax_rcut.

U

Gets the value of the unique decomposition in this store.

Warning

These value are dependent on the particular SOAP parameter set. They are saved accordingly.

Returns:keys are values of epsilon, rounded to 5 decimal places; values are those returned by unique().
Return type:dict