7. Examples
7.1. Fe_Linear_NPJ2021
See examples/Fe_Linear_NPJ2021/ for details.
7.2. Fe_Pytorch_NN
PyTorch neural network force fitting example.
Fit a NN with
python -m fitsnap3 Fe-example.in --overwrite # use --overwrite to overwrite existing fitsnap files.
The following python scripts help analyze fitting progress and results:
python plot_error_vs_epochs.py
python plot_energy_comparison.py
python plot_force_comparison.py
7.3. InP_JPCA2020
FitSnap3 Indium Phosphide example
This example will generate a potential for InP as published in
Cusentino, M.A. et. al, J. Chem. Phys. (2020). This version
of the Indium Phosphide potential uses the linear version of SNAP.
This particular example demostrates the Explicit Multi-Element (EME-SNAP)
version of SNAP where the weighted densities are now broken into
partial densities based on atom type leading to a better description
of chemically complex systems. This option is denoted by "alloyflag"
in the FitSNAP input file.
#### Running this example:
To run this example, use the following command in this directory:
mpirun -n 4 python3 -m fitsnap3 InP-example.in
#### Files in this Directory
InP-example.in
Input file containing parameters to run FitSNAP and generate
the Indium Phosphide potential
JSON/
Directory that contains all the training configurations which are organized
into different groups.
#### Files generated by example:
InP_pot.snapcoeff
SNAP potential coefficient file that contains all the beta coefficients for
this potential. This is one of two files needed to use this potential in LAMMPS
InP_pot.snapparam
SNAP potential parameters file that contains the hyperparameters and options used during
the fit for this potential. This is one of two files needed to use this potential in LAMMPS
InP_metrics.csv
Contains a variety of error metrics for all the training groups for this fit.
Note that the 20May21_Standard/ directory contains sample output for this example
#### Important input parameters for this example
rcutfac = 1 : Radial cutoff (hyperparameter) chosen for this potential
wj1 = 1.0 : Elemental weight on Indium for density expansion
wj2 = 9.293160905266721e-01 : : Elemental weight on Phosphide for density expansion
radelem1 = 3.812045629514403e : Indium per-element cutoff
radelem2 = 3.829453817954964e : Phospide per-element cutoff
type1 = In : Chemical symbol for element which should match training files in JSON
type2 = P : Chemical symbol for element which should match training files in JSON
eshift = In : -1.65967588701534 : Per atom training data energy shift for In
eshift = P : 4.38159549501534 : Per atom training data energy shift for P
quadraticflag = 0 : Quadratic SNAP is turned off, using linear SNAP
chemflag = 1 : Flag to turn on EME-SNAP
bnormflag = 1 : Flag to turn on normalization of j indices (speeds up MD runs)
wselfallflag = 1 : Adds wself contribution to the density
See docs/TEMPLATE.in for further information on input parameters
#### Indium Phosphide data from:
The JSON configurations and hyperparameters used for this example are published in:
- Thompson, A.P., et. al.,, Automated algorithms for quantum-level accuracy in
atomistic simulations: LDRD final report, Technical Report SAND 2014-17862, Sandia
National Laboratories, Albuquerque, NM, 2014.
- Cusentino, M.A., Wood, M.A., and Thompson, A.P., Explicit Multi-element Extension of
the Spectral Neighbor Analysis Potential for Chemically Complex Systems, J. Chem.
Phys. (2020).
**Note to Developers: Make sure this example still reproduces the same results when modifying code**
7.4. InP_PACE
FitSnap3 Indium Phosphide example with ACE
## Important Notes
Multi-element ACE fit with reference energies (bzeroflag=1).
The 'erefs' variable in the ACE section may be used to set
the intercept manually in the .yace potential file, but by
default, the intercept for bzeroflag=1 should be 0.0 for all
elements.
### Energy and forces only
Input file and expected output in 30Mar23_Standard.
Example of multielement ACE fit from FitSNAP. This example
requires that sklearn is installed for the ARD solver. The
priors are chosen based on variance in the (weighted)
training energies and forces. The default example in the
top directory is this fit.
### With stresses
Input file and expected output in 30Mar23_Standard_Stress.
Example of multielement ACE fit from FitSNAP. This example
requires that sklearn is installed for the ARD solver. The
priors are chosen based on variance in the (weighted)
training energies, forces, and stresses.
7.5. InP_VASP
See examples/InP_VASP/ for details.
7.6. MSD-Fe
See examples/MSD-Fe/ for details.
7.7. N2_ReaxFF
See examples/N2_ReaxFF/ for details.
7.8. Ta_JAX_NN
See examples/Ta_JAX_NN/ for details.
7.9. Ta_Linear_JCP2014
FitSnap3 Tantalum example
This example will generate a potential for tantalum as published in
Thompson, A.P. et. al, J. Comp. Phys. 285 (2015) 316-330. This version
of the tantalum potential uses the linear version of SNAP.
#### Running this example:
To run this example, use the following command in this directory:
python -m fitsnap3 Ta-example.in
#### Files in this Directory
`Ta-example.in`
Input file containing parameters to run FitSNAP and generate
the tantalum potential
`JSON/`
Directory that contains all the training configurations which are organized
into different groups.
#### Files generated by example:
`Ta_pot.snapcoeff`
SNAP potential coefficient file that contains all the beta coefficients for
this potential. This is one of two files needed to use this potential in LAMMPS
`Ta_pot.snapparam`
SNAP potential parameters file that contains the hyperparameters and options used during
the fit for this potential. This is one of two files needed to use this potential in LAMMPS
`Ta_metrics.md`
Contains a variety of error metrics for all the training groups for this fit.
Note that the `20May21_Standard/` directory contains sample output for this example
`FitSNAP.df`
Pickled pandas dataframe whose columns contain various quantities associated with the fit. For those unfamiliar with pandas dataframes, this file can be loaded in python with:
import pandas as pd
data = pd.read_pickle("FitSNAP.df")
and we can extract data using typical pandas dataframe attributes, for example:
print(data.columns) # see which columns we have
print(data["Row_Type"].values) # print the values of row types in the A matrix
#### Important input parameters for this example
rcutfac = 4.67637 : Radial cutoff (hyperparameters) chosen for this potential
wj1 = 1.0 : Elemental weight on tantalum for density expansion
radelem1 = 0.5 : Tantalum per-element cutoff
type1 = Ta : Chemical symbol for element which should match training files in JSON
quadraticflag = 0 : Quadratic SNAP is turned off, using linear SNAP
See docs/TEMPLATE.in for further information on input parameters
#### Tantalum data from:
The JSON configurations and hyperparameters used for this example are published in:
Thompson, A. P., Swiler, L. P., Trott, C. R., Foiles, S. M., & Tucker, G. J. (2015).
Spectral neighbor analysis method for automated generation of quantum-accurate interatomic
potentials. Journal of Computational Physics, 285, 316-330
**Note to Developers: Make sure this example still reproduces the same results when modifying code**
After running the example, use `python compare_snapcoeff.py` to calculate the max absolute difference in SNAP coefficients from the standard.
The values should agree within a near zero amount (machine precision or close).
7.10. Ta_PACE
FitSnap3 Ta example with ACE
## Important Note
As with other ACE fits, regularization is highly
recommended. Please see Ta_PACE_Ridge and the TA_PACE_ARD
examples for practical use cases. This is an example using
SVD to obtain ACE coefficients, with group weights from
an optimized SNAP potential of Ta.
7.11. Ta_PACE_ARD
FitSnap3 Ta example with ACE
## Important Note
As with other ACE fits, regularization is highly
recommended. These Ta potentials are minimally tested and
are here for demonstration purposes. This example uses ARD
a.k.a relevance vector learning to both apply
regularization as well as obtain a sparse solution to the
linear ACE model.
### ARD regression for sparse linear ACE
ARD is the recommended regressor for linear ACE models.
The use of this method requires the installation of
sklearn, which can be easily installed with python pip.
In the 29Mar23_ARD example directory, the input for an ARD
fit may be found. This method assumes an elliptical
gaussian prior for all of the ACE weights. This prior is
adaptively scaled to the variance of the <i>weighted</i>
training data set. This allows for sparse solutions to
the ACE weights, and for the use of fewer descriptors in a
potential. <b>This example requires the installation of
external libraries (sklearn).</b> More info about
this method can be found in the documentation for sklearn
<a>https://scikit-learn.org/stable/modules/generated/sklearn.linear_model.ARDRegression.html</a>.
### ARD Hyperparameters
directmethod : (bool) flag to use the hyperparameter scheme
from sklearn, without using training data to help choose
the hyperparameters (default is off)
<br>
<b> Hyperparameters if <u>not</u> using the directmethod </b>
<br>
scap : (float) scaling factor for the prior distribution
of the linear model coefficients (to be rescaled based on
training data variance)
<br>
scai : (float) scaling factor for the prior distribution
of the uncertainty of the linear model coefficients. (to be
rescaled based on training data variance) Simultaneously
increasing or decreasing scap and scai will change the
absolute scale of model coefficients.
<br>
logcut : (float) log<sub>10</sub> value of the cutoff
threshhold for pruning descriptors. Increasing this value
will add descriptors into the model, lowest uncertainty
first. Decreasing this value will prune descriptors from
the model, highest uncertainty first.
<br>
<b> Hyperparameters if using the directmethod </b>
<br>
alpha_big : (float) primary parameter for a gamma dist.
prior for the linear model coefficients
<br>
alpha_small : (float) secondary parameter for the gamma
distribution for the linear model coefficients
<br>
lambda_big : (float) primary parameter for a gamma dist.
prior for the uncertainties of the linear model
coefficients.
<br>
lambda_small : (float) secondary parameter for the gamma
distribution for the uncertainties of the linear model
coefficients.
<br>
threshold_lambda : (int) threshold for pruning descriptors/
(via setting the linear model coefficients to 0)
7.12. Ta_PACE_PyTorch_NN
See examples/Ta_PACE_PyTorch_NN/ for details.
7.13. Ta_PACE_RIDGE
FitSnap3 Ta example with ACE
## Important Note
As with other ACE fits, regularization is highly
recommended. These Ta potentials are minimally tested and
are here for demonstration purposes. This example uses
the RIDGE regression technique to apply a penalty to ACE
coefficients that are too large via the L2 norm penalty.
### RIDGE regression
This is the default example provided for the linear ACE fit
of Ta. The ridge regressor may be used from sklearn, or
through internal solvers. No additional installation of
sklearn is required for this example. The default input in
this top directory, and in 30Mar23_RIDGE, uses a ridge
regressor from FitSNAP by default. Otherwise, this is a
copy of the ARD example but with a different regressor.
RIDGE regression is one of the more simple ways to obtain
a regularized solution to the least squares problem. An L2
penalty ( <b>w</b> <sup>T</sup> (α <b>I</b>) <b>w</b> ) is added
to the least squares cost function to penalize model
weights that get too large. While this can reduce
overfitting and stabilize models, it does little for
sparsification/feature selection.
### RIDGE hyperparameters
alpha : (float) regularization hyperparameter that scales
the penalty for the linear model coefficients. Increasing
this value will result in models with linear model
coefficients with lower absolute values.
local_solver : (bool) flag to use the RIDGE regressor from
the FitSNAP library (default) or to use the sklearn RIDGE
regressor
7.14. Ta_PyTorch_NN
PyTorch neural network force fitting example.
Fit a NN with
python -m fitsnap3 Ta-example.in --overwrite # use --overwrite if you want to overwrite existing
fitsnap files.
This also creates corresponding plots of errors vs. epochs and target force vs. model force.
To check that the model forces match those calculated with finite difference, do
`python fd_force_check.py`, which creates a `fd_force_check.png` plot.
This finite difference script uses the same force calculation routine that we use in
`fitsnap3lib/lib/neural_networks/pytorch.py`
When fitting forces AND energies, it was found to best have `energy_weight=1e-2` and
`force_weight=1.0` or some similar ratio.
### Calculating fitting errors.
FitSNAP produces output files that we can use to calculate error ourselves. To do this, run
python plot_comparison.py
which will calculate errors and plot comparisons with the detailed fitting data.
### Running MD with NN potential.
Refer to folder "MD" for instructions to run MD simulations with the potential.
### Evaluating energies/forces in Python.
Sometimes you want to calculate energies/forces on another set using an already fitted model. In this
case it is wasteful to re-calculate the descriptors. We can therefore load a pickled list of
Configuration objects which are used by FitSNAP for NN fitting. First generate the pickled list
of Configuration objects `configs.pickle` by performing a fit, then use the script
`evaluate_configs.py` which will load this pickled list and calculate energies/forces for all
configs.
7.15. Ta_Quadratic_JCP2018
FitSnap3 Tantalum quadratic example
This example will generate a potential for tantalum as published in
Wood, M. A., & Thompson, A. P. (2018) J. Chem. Phys. 24 (2018) 241721. This version
of the tantalum potential uses the quadratic version of SNAP.
#### Running this example:
To run this example, use the following command in this directory:
mpirun -n 4 python3 -m fitsnap3 Ta-example.in
#### Files in this Directory
Ta-example.in
Input file containing parameters to run FitSNAP and generate
the tantalum quadratic potential
JSON/
Directory that contains all the training configurations which are organized
into different groups.
#### Files generated by example:
Ta_pot.snapcoeff
SNAP potential coefficient file that contains all the beta coefficients for
this potential. This is one of two files needed to use this potential in LAMMPS
Ta_pot.snapparam
SNAP potential parameters file that contains the hyperparameters and options used during
the fit for this potential. This is one of two files needed to use this potential in LAMMPS
Ta_metrics.csv
Contains a variety of error metrics for all the training groups for this fit.
Note that the 20May21_Standard/ directory contains sample output for this example for comparison
#### Important input parameters for this example
rcutfac = 5.594 : Radial cutoff (hyperparameters) chosen for this potential (different from linear example)
wj1 = 1.0 : Elemental weight on tantalum for density expansion
radelem1 = 0.5 : Tantalum per-element cutoff
type1 = Ta : Chemical symbol for element which should match training files in JSON
bzeroflag = 1 : Forces Bspec to 0 when atoms are non-interacting (different from linear example)
quadraticflag = 1 : Quadratic SNAP is turned on, using quadratic SNAP (different from linear example)
See docs/TEMPLATE.in for further information on input parameters
#### Tantalum data from:
The JSON configurations and hyperparameters used for this example are published in:
Wood, M. A., & Thompson, A. P. (2018). Extending the accuracy of
the SNAP interatomic potential form. The Journal of chemical
physics, 148(24), 241721.
**Note to Developers: Make sure this example still reproduces the same results when modifying code**
7.16. Ta_XYZ
FitSnap3 Tantalum example
This example will generate a potential for tantalum as published in
Thompson, A.P. et. al, J. Comp. Phys. 285 (2015) 316-330. This version
of the tantalum potential uses the linear version of SNAP.
#### Running this example:
To run this example, use the following command in this directory:
python3 -m fitsnap3 Ta-example.in
#### Files in this Directory
Ta-example.in
Input file containing parameters to run FitSNAP and generate
the tantalum potential
grouplist.in
File that lists all the training groups in the JSON directory,
the number of files in each group, and the energy, force, and virial training
weights on each group.
XYZ/
Directory that contains all the training configurations which are organized
into different groups.
#### Files generated by example:
Ta_pot.snapcoeff
SNAP potential coefficient file that contains all the beta coefficients for
this potential. This is one of two files needed to use this potential in LAMMPS
Ta_pot.snapparam
SNAP potential parameters file that contains the hyperparameters and options used during
the fit for this potential. This is one of two files needed to use this potential in LAMMPS
Ta_metrics.csv
Contains a variety of error metrics for all the training groups for this fit.
Note that the 19Nov19_Standard/ directory contains sample output for this example
#### Important input parameters for this example
rcutfac = 4.67637 : Radial cutoff (hyperparameters) chosen for this potential
wj1 = 1.0 : Elemental weight on tantalum for density expansion
radelem1 = 0.5 : Tantalum per-element cutoff
type1 = Ta : Chemical symbol for element which should match training files in JSON
quadraticflag = 0 : Quadratic SNAP is turned off, using linear SNAP
See docs/TEMPLATE.in for further information on input parameters
#### Tantalum data from:
The XYZ configurations and hyperparameters used for this example are published in:
Thompson, A. P., Swiler, L. P., Trott, C. R., Foiles, S. M., & Tucker, G. J. (2015).
Spectral neighbor analysis method for automated generation of quantum-accurate interatomic
potentials. Journal of Computational Physics, 285, 316-330
**Note to Developers: Make sure this example still reproduces the same results when modifying code**
7.17. Ta_pytorch_custom_NN
PyTorch neural network force fitting example.
Fit a NN with
# use --overwrite if you want to overwrite existing fitsnap files
python -m fitsnap3 Ta-example.in --overwrite
This also creates corresponding plots of errors vs. epochs and target force vs. model force.
To check that the model forces match those calculated with finite difference, do
`python fd_force_check.py`, which creates a `fd_force_check.png` plot.
This finite difference script uses the same force calculation routine that we use in
`fitsnap3lib/lib/neural_networks/pytorch.py`
When fitting forces AND energies, it was found to best have `energy_weight=1e-2` and
`force_weight=1.0` or some similar ratio.
### Calculating fitting errors.
FitSNAP produces output files that we can use to calculate error ourselves. To do this, run
python calculate_fitting_errors.py
which will calculate mean absolute errors for energy and forces, as well as plot a distribution of
force errors, for the training and validation sets.
### Running MD with NN potential.
Refer to folder "MD" for instructions to run MD simulations with the potential.
7.18. WBe_PRB2019
FitSnap3 Tungten - Beryllium example
This example will generate a potential for tungsten and beryllium as published in
Wood, M. A., et. al. Phys. Rev. B 99 (2019) 184305. This potential was developed
for the purpose of studying plasma material interactions in fusion reactors.
#### Running this example:
To run this example, use the following command in this directory:
mpirun -n 4 python3 -m fitsnap3 WBe-example.in
#### Files in this Directory
WBe-example.in
Input file containing parameters to run FitSNAP and generate
the W-Be potential
JSON/
Directory that contains all the training configurations which are organized
into different groups.
#### Files generated by example:
WBe_pot.snapcoeff
SNAP potential coefficient file that contains all the beta coefficients for
this potential. This is one of two files needed to use this potential in LAMMPS
WBe_pot.snapparam
SNAP potential parameters file that contains the hyperparameters and options used during
the fit for this potential. This is one of two files needed to use this potential in LAMMPS
WBe_metrics.csv
Contains a variety of error metrics for all the training groups for this fit.
Note that the 20May21_Standard/ directory contains sample output for this example for comparison
#### Important input parameters for this example
numTypes = 2 : Two atom types for this example
rcutfac = 4.812302818 : Radial cutoff (hyperparameter) chosen for this potential
wj1 = 1.0 : Elemental weight on tungsten for density expansion
wj2 = 0.9590493408 : Elemental weight on beryllium for density expansion
radelem1 = 0.5 : Tungsten per-element cutoff
radelem2 = 0.417932464 : Beryllium per-element cutoff
type1 = W : Chemical symbol for first element which should match training files in JSON
type2 = Be : Chemical symbol for second element which should match training files in JSON
bzeroflag = 1 : Forces Bspec to 0 when atoms are non-interacting (different from linear example)
quadraticflag = 0 : Quadratic SNAP is turned off, using linear SNAP
See docs/TEMPLATE.in for further information on input parameters
#### Tungsten-Beryllium data from:
The JSON configurations and hyperparameters used for this example are published in:
Wood, Mitchell A., et al. "Data-driven material models for
atomistic simulation." Physical Review B 99.18 (2019): 184305.
**Note to Developers: Make sure this example still reproduces the same results when modifying code**
7.19. WBe_PyTorch_NN
FitSnap3 NN Tungten - Beryllium example
This example will generate a NN potential for WBe using the `WBe_PRB2019` dataset.
#### Running this example:
To run this example, use the following command in this directory:
python3 -m fitsnap3 WBe-example.in --overwrite # use --overwrite if you already have fitsnap files
saved.
#### Files in this Directory
WBe-example.in
Input file containing parameters to run FitSNAP and generate a SNAP-NN potential
MD/
Directory that contains an example with running MD in LAMMPS using the PyTorch model from FitSNAP.
7.20. library
Examples using FitSNAP library
This directory houses Python scripts that do various things with the fitsnap library.