GMP-featurizer

This package is used to efficiently and accurately compute the GMP features and their derivatives for any chemical systems. The computation is also parallelized via Ray.

The details of the theory behind the Gaussian Multipole descriptors can be found in the original paper or in its arxiv version

Part of the code of this package is based on the AmpTorch package

Installation

To install this package, simply clone this repo, git clone https://github.com/TRI-AMDD/GMP-featurizer cd GMP-featurizer

Then install the requirements and the package itself pip install -r requirements.txt pip install -e .

Basic usage

Please refer to the example notebooks for better and detailed tutorials

An example "cif" file is provided in the "examples" directory

Import modules and load data

``` import numpy as np from GMPFeaturizer import GMPFeaturizer, ASEAtomsConverter, PymatgenStructureConverter from ase.io import read as aseread

Loading cif file as a ase atoms object

image = aseread("./examples/test.cif")

The input to the featurizer should be a non-empty list

images = [image]

initialize the converter, in this case it's the converter for ASE atoms objects

There is also a pre-existing converter for pymatgen Structure objects as well

converter = ASEAtomsConverter()

converter = PymatgenStructureConverter()

```

Setup the featurizer

The list of features is the Cartesian product of orders and sigams (except for order -1, which correspond just local electron density, so different simgas does not matter. Thus, there is only one feature for order -1).

With this setting, the list of features are

[(-1, 0), (0, 0.1), (0, 0.2), (0, 0.3), (1, 0.1), (1, 0.2), (1, 0.3), (2, 0.1), (2, 0.2), (2, 0.3)]

where the first number is the order of the MCSH angular probe, and the second number is the sigma of the Gaussian radial probe ``` GMPs = { "GMPs": {
"orders": [-1, 0, 1, 2], "sigmas": [0.1, 0.2, 0.3]
}, # path to the pseudo potential file "psppath": "/NC-SR.gpsp", # basically the accuracy of the resulting features "overlapthreshold": 1e-16, # whether the features are squared, #no need to change if you are not considering the feature derivatives # "square": False, }

featurizer = GMPFeaturizer(GMPs=GMPs, converter=converter, calcderivatives=True, verbose=True) ``` Set calcderivatives=True if you want to get the feature derivatives w.r.t. atom positions, which are stored in the form of sparse matrices.

Calculate features and access data

Use the "cores" argument to change the number of cores for parallelization. Also converted needed to be specified, ``` result = featurizer.prepare_features(images, cores=5)

features = [entry["features"] for entry in result] featureprimes = [entry["featureprimes"] for entry in result] ```

Specifying the list of GMP features

It's also possible to manually specify the list of GMP features to be computed, instead of specifying orders and sigmas. GMPs = { "GMPs_detailed_list": [(-1,0), (0, 0.1), (0, 0.2), (0, 0.3), (1, 0.2), (1, 0.3), (2, 0.3)], "psp_path": "./NC-SR.gpsp", # path to the pseudo potential file "overlap_threshold": 1e-16, # basically the accuracy of the resulting features # "square": False, # whether the features are squared, no need to change if you are not get the feature derivatives }

Whole Script

``` import numpy as np from GMPFeaturizer import GMPFeaturizer, ASEAtomsConverter, PymatgenStructureConverter

load data

from ase.io import read as aseread image = aseread("./examples/test.cif") images = [image]

converter = ASEAtomsConverter()

converter = PymatgenStructureConverter()

setup featurizer

GMPs = { "GMPs": {
"orders": [-1, 0, 1, 2], "sigmas": [0.1, 0.2, 0.3]
}, # path to the pseudo potential file "psppath": "/NC-SR.gpsp", # basically the accuracy of the resulting features "overlapthreshold": 1e-16, # whether the features are squared, #no need to change if you are not considering the feature derivatives # "square": False, } featurizer = GMPFeaturizer(GMPs=GMPs, converter=converter, calc_derivatives=True, verbose=True)

calculate features

result = featurizer.prepare_features(images, cores=5)

access data

features = [entry["features"] for entry in result] featureprimes = [entry["featureprimes"] for entry in result] ```

Save calculated feature to / load calculated feature from local folder

Simply set "savefeatures=True" when calling the preparefeatures function.

The path to the local database is set when initializing the featurizer featurizer = GMPFeaturizer(GMPs=GMPs, converter=converter, calc_derivatives=False, feature_database="cache/features/") features = featurizer.prepare_features(images, cores=5, save_features=True)

License

Apache 2.0

Copyright 2023 Toyota Research Institute