ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

reformat to conform to LAMMPS writing style

Browse Source
This commit is contained in:
Axel Kohlmeyer
2023-11-29 02:11:44 -05:00
parent d39cd265ae
commit 918cddfb90
2 changed files with 96 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
doc/src/compute_slcsa_atom.rst
View File

@ -16,7 +16,7 @@ Syntax
* nclasses = number of crystal structures used in the database for the classifier SL-CSA
* db_mean_descriptor_file = file name of file containing the database mean descriptor
* lda_file = file name of file containing the linear discriminant analysis matrix for dimension reduction
* lr_decision_file = file name of file containing the scalings matrix for logistic regression classification
* lr_decision_file = file name of file containing the scaling matrix for logistic regression classification
* lr_bias_file = file name of file containing the bias vector for logistic regression classification
* maha_file = file name of file containing for each crystal structure: the Mahalanobis distance threshold for sanity check purposes, the average reduced descriptor and the inverse of the corresponding covariance matrix
* c_ID[*] = compute ID of previously required *compute sna/atom* command
@ -32,54 +32,117 @@ Examples
Description
"""""""""""
Define a computation that performs the Supervised Learning Crystal Structure Analysis (SL-CSA) from :ref:`(Lafourcade) <Lafourcade2023>` for each atom in the group. The SL-CSA tool takes as an input a per-atom descriptor (bispectrum) that is computed through the *compute sna/atom* command and then proceeds to a dimension reduction step followed by a logistic regression in order to assign a probable crystal structure to each atom in the group. The SL-CSA tool is pre-trained on a database containing :math:`C` distinct crystal structures from which a crystal structure classifier is derived and a tutorial to build such a tool is available at `SL-CSA <https://github.com/lafourcadep/SL-CSA>`_.
.. versionadded:: TBD
The first step of the SL-CSA tool consists in performing a dimension reduction of the per-atom descriptor :math:`\mathbf{B}^i \in \mathbb{R}^{D}` through the Linear Discriminant Analysis (LDA) method, leading to a new projected descriptor :math:`\mathbf{x}^i=\mathrm{P}_\mathrm{LDA}(\mathbf{B}^i):\mathbb{R}^D \rightarrow \mathbb{R}^{d=C-1}`:
Define a computation that performs the Supervised Learning Crystal
Structure Analysis (SL-CSA) from :ref:`(Lafourcade) <Lafourcade2023_1>`
for each atom in the group. The SL-CSA tool takes as an input a per-atom
descriptor (bispectrum) that is computed through the *compute sna/atom*
command and then proceeds to a dimension reduction step followed by a
logistic regression in order to assign a probable crystal structure to
each atom in the group. The SL-CSA tool is pre-trained on a database
containing :math:`C` distinct crystal structures from which a crystal
structure classifier is derived and a tutorial to build such a tool is
available at `SL-CSA <https://github.com/lafourcadep/SL-CSA>`_.
The first step of the SL-CSA tool consists in performing a dimension
reduction of the per-atom descriptor :math:`\mathbf{B}^i \in
\mathbb{R}^{D}` through the Linear Discriminant Analysis (LDA) method,
leading to a new projected descriptor
:math:`\mathbf{x}^i=\mathrm{P}_\mathrm{LDA}(\mathbf{B}^i):\mathbb{R}^D
\rightarrow \mathbb{R}^{d=C-1}`:
.. math::
\mathbf{x}^i = \mathbf{C}^T_\mathrm{LDA} \cdot (\mathbf{B}^i - \mu^\mathbf{B}_\mathrm{db})
where :math:`\mathbf{C}^T_\mathrm{LDA} \in \mathbb{R}^{D \times d}` is the reduction coefficients matrix of the LDA model read in file *lda_file*, :math:`\mathbf{B}^i \in \mathbb{R}^{D}` is the bispectrum of atom :math:`i` and :math:`\mu^\mathbf{B}_\mathrm{db} \in \mathbb{R}^{D}` is the average descriptor of the entire database. The latter is computed from the average descriptors of each crystal structure read from the file *mean_descriptors_file*.
where :math:`\mathbf{C}^T_\mathrm{LDA} \in \mathbb{R}^{D \times d}` is
the reduction coefficients matrix of the LDA model read in file
*lda_file*, :math:`\mathbf{B}^i \in \mathbb{R}^{D}` is the bispectrum of
atom :math:`i` and :math:`\mu^\mathbf{B}_\mathrm{db} \in \mathbb{R}^{D}`
is the average descriptor of the entire database. The latter is computed
from the average descriptors of each crystal structure read from the
file *mean_descriptors_file*.
The new projected descriptor with dimension :math:`d=C-1` allows for a good separation of different crystal structures fingerprints in the latent space.
The new projected descriptor with dimension :math:`d=C-1` allows for a
good separation of different crystal structures fingerprints in the
latent space.
Once the dimension reduction step is performed by means of LDA, the new descriptor :math:`\mathbf{x}^i \in \mathbb{R}^{d=C-1}` is taken as an input for performing a multinomial logistic regression (LR) which provides a score vector :math:`\mathbf{s}^i=\mathrm{P}_\mathrm{LR}(\mathbf{x}^i):\mathbb{R}^d \rightarrow \mathbb{R}^C` defined as:
Once the dimension reduction step is performed by means of LDA, the new
descriptor :math:`\mathbf{x}^i \in \mathbb{R}^{d=C-1}` is taken as an
input for performing a multinomial logistic regression (LR) which
provides a score vector
:math:`\mathbf{s}^i=\mathrm{P}_\mathrm{LR}(\mathbf{x}^i):\mathbb{R}^d
\rightarrow \mathbb{R}^C` defined as:
.. math::
\mathbf{s}^i = \mathbf{b}_\mathrm{LR} + \mathbf{D}_\mathrm{LR} \cdot {\mathbf{x}^i}^T
with :math:`\mathbf{b}_\mathrm{LR} \in \mathbb{R}^C` and :math:`\mathbf{D}_\mathrm{LR} \in \mathbb{R}^{C \times d}` the bias vector and decision matrix of the LR model after training both read in files *lr_fil1* and *lr_file2* respectively.
with :math:`\mathbf{b}_\mathrm{LR} \in \mathbb{R}^C` and
:math:`\mathbf{D}_\mathrm{LR} \in \mathbb{R}^{C \times d}` the bias
vector and decision matrix of the LR model after training both read in
files *lr_fil1* and *lr_file2* respectively.
Finally, a probability vector :math:`\mathbf{p}^i=\mathrm{P}_\mathrm{LR}(\mathbf{x}^i):\mathbb{R}^d \rightarrow \mathbb{R}^C` is defined as:
Finally, a probability vector
:math:`\mathbf{p}^i=\mathrm{P}_\mathrm{LR}(\mathbf{x}^i):\mathbb{R}^d
\rightarrow \mathbb{R}^C` is defined as:
.. math::
\mathbf{p}^i = \frac{\mathrm{exp}(\mathbf{s}^i)}{\sum\limits_{j} \mathrm{exp}(s^i_j) }
from which the crystal structure assigned to each atom with descriptor :math:`\mathbf{B}^i` and projected descriptor :math:`\mathbf{x}^i` is computed as the *argmax* of the probability vector :math:`\mathbf{p}^i`. Since the logistic regression step systematically attributes a crystal structure to each atom, a sanity check is needed to avoid misclassification. To this end, a per-atom Mahalanobis distance to each crystal structure *CS* present in the database is computed:
from which the crystal structure assigned to each atom with descriptor
:math:`\mathbf{B}^i` and projected descriptor :math:`\mathbf{x}^i` is
computed as the *argmax* of the probability vector
:math:`\mathbf{p}^i`. Since the logistic regression step systematically
attributes a crystal structure to each atom, a sanity check is needed to
avoid misclassification. To this end, a per-atom Mahalanobis distance to
each crystal structure *CS* present in the database is computed:
.. math::
d_\mathrm{Mahalanobis}^{i \rightarrow \mathrm{CS}} = \sqrt{(\mathbf{x}^i - \mathbf{\mu}^\mathbf{x}_\mathrm{CS})^\mathrm{T} \cdot \mathbf{\Sigma}^{-1}_\mathrm{CS} \cdot (\mathbf{x}^i - \mathbf{\mu}^\mathbf{x}_\mathrm{CS}) }
where :math:`\mathbf{\mu}^\mathbf{x}_\mathrm{CS} \in \mathbb{R}^{d}` is the average projected descriptor of crystal structure *CS* in the database and where :math:`\mathbf{\Sigma}_\mathrm{CS} \in \mathbb{R}^{d \times d}` is the corresponding covariance matrix. Finally, if the Mahalanobis distance to crystal structure *CS* for atom *i* is greater than the pre-determined threshold, no crystal structure is assigned to atom *i*. The Mahalanobis distance thresholds are read in file *maha_file* while the covariance matrices are read in file *covmat_file*.
where :math:`\mathbf{\mu}^\mathbf{x}_\mathrm{CS} \in \mathbb{R}^{d}` is
the average projected descriptor of crystal structure *CS* in the
database and where :math:`\mathbf{\Sigma}_\mathrm{CS} \in \mathbb{R}^{d
\times d}` is the corresponding covariance matrix. Finally, if the
Mahalanobis distance to crystal structure *CS* for atom *i* is greater
than the pre-determined threshold, no crystal structure is assigned to
atom *i*. The Mahalanobis distance thresholds are read in file
*maha_file* while the covariance matrices are read in file
*covmat_file*.
The `SL-CSA <https://github.com/lafourcadep/SL-CSA>`_ framework provides an automatic computation of the different matrices and thresholds required for a proper classification and writes down all the required files for calling the *compute slcsa/atom* command.
The `SL-CSA <https://github.com/lafourcadep/SL-CSA>`_ framework provides
an automatic computation of the different matrices and thresholds
required for a proper classification and writes down all the required
files for calling the *compute slcsa/atom* command.
The *compute slcsa/atom* command requires that the *compute sna/atom* command is called before as it takes the resulting per-atom bispectrum as an input. In addition, it is crucial that the value *twojmax* is set to the same value of the value *twojmax* used in the *compute sna/atom* command, as well as that the value *nclasses* is set to the number of crystal structures used in the database to train the SL-CSA tool.
The *compute slcsa/atom* command requires that the :doc:`compute
sna/atom <compute_sna_atom>` command is called before as it takes the
resulting per-atom bispectrum as an input. In addition, it is crucial
that the value *twojmax* is set to the same value of the value *twojmax*
used in the *compute sna/atom* command, as well as that the value
*nclasses* is set to the number of crystal structures used in the
database to train the SL-CSA tool.
Output info
"""""""""""
By default, this compute computes the Mahalanobis distances to the different crystal structures present in the database in addition to assigning a crystal structure for each atom as a per-atom vector, which can be accessed by any command that uses per-atom values from a compute as input. See the :doc:`Howto output <Howto_output>` page for an overview of LAMMPS output options.
By default, this compute computes the Mahalanobis distances to the
different crystal structures present in the database in addition to
assigning a crystal structure for each atom as a per-atom vector, which
can be accessed by any command that uses per-atom values from a compute
as input. See the :doc:`Howto output <Howto_output>` page for an
overview of LAMMPS output options.
Restrictions
""""""""""""
This compute is part of the EXTRA-COMPUTE package. It is only enabled if
LAMMPS was built with that package. See the :doc:`Build package <Build_package>` page for more info.
This compute is part of the EXTRA-COMPUTE package. It is only enabled
if LAMMPS was built with that package. See the :doc:`Build package
<Build_package>` page for more info.
Related commands
""""""""""""""""

19
doc/src/compute_sna_atom.rst
View File

@ -444,7 +444,24 @@ requires that *bikflag=1*.
The rerun script can use a :doc:`special_bonds <special_bonds>`
command that includes all pairs in the neighbor list.
The keyword *nnn* allows for the calculation of the bispectrum over a specific target number of neighbors. This option is only implemented for the compute *sna/atom*\ . An optimal cutoff radius for defining the neighborhood of the central atom is calculated by means of a dichotomy algorithm. This iterative process allows to assign weights to neighboring atoms in order to match the total sum of weights with the target number of neighbors. Depending on the radial weight function used in that process, the cutoff radius can fluctuate a lot in the presence of thermal noise. Therefore, in addition to the *nnn* keyword, the keyword *wmode* allows to choose whether a Heavyside (*wmode* = 0) function or a Hyperbolic tangent function (*wmode* = 1) should be used. If the Heavyside function is used, the cutoff radius exactly matches the distance between the central atom an its *nnn*'th neighbor. However, in the case of the hyperbolic tangent function, the dichotomy algorithm allows to span the weights over a distance *delta* in order to reduce fluctuations in the resulting local atomic environment fingerprint. The detailed formalism is given in the paper by Lafourcade et al. :ref:`(Lafourcade) <Lafourcade2023>`.
The keyword *nnn* allows for the calculation of the bispectrum over a
specific target number of neighbors. This option is only implemented for
the compute *sna/atom*\ . An optimal cutoff radius for defining the
neighborhood of the central atom is calculated by means of a dichotomy
algorithm. This iterative process allows to assign weights to
neighboring atoms in order to match the total sum of weights with the
target number of neighbors. Depending on the radial weight function
used in that process, the cutoff radius can fluctuate a lot in the
presence of thermal noise. Therefore, in addition to the *nnn* keyword,
the keyword *wmode* allows to choose whether a Heaviside (*wmode* = 0)
function or a Hyperbolic tangent function (*wmode* = 1) should be used.
If the Heaviside function is used, the cutoff radius exactly matches the
distance between the central atom an its *nnn*'th neighbor. However, in
the case of the hyperbolic tangent function, the dichotomy algorithm
allows to span the weights over a distance *delta* in order to reduce
fluctuations in the resulting local atomic environment fingerprint. The
detailed formalism is given in the paper by Lafourcade et
al. :ref:`(Lafourcade) <Lafourcade2023_2>`.
----------