-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathLinear.html
More file actions
241 lines (226 loc) · 16.5 KB
/
Linear.html
File metadata and controls
241 lines (226 loc) · 16.5 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
<!DOCTYPE html>
<html class="writer-html5" lang="en" >
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>4. Linear Models — FitSNAP documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/css/theme.css" type="text/css" />
<!--[if lt IE 9]>
<script src="_static/js/html5shiv.min.js"></script>
<![endif]-->
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<script async="async" src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
<script src="_static/js/theme.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="5. PyTorch Models" href="Pytorch.html" />
<link rel="prev" title="3.4. Running as library" href="Run/Run_library.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="index.html">
<img src="_static/FitSNAP.png" class="logo" alt="Logo"/>
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">User Guide</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="Introduction.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="Installation.html">2. Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="Run/index.html">3. Run FitSNAP</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">4. Linear Models</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#outputs">4.1. Outputs</a></li>
<li class="toctree-l2"><a class="reference internal" href="#uncertainty-quantification-uq">4.2. Uncertainty Quantification (UQ)</a></li>
<li class="toctree-l2"><a class="reference internal" href="#in-development-uq-solvers">4.3. In development UQ solvers</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#opt">4.3.1. OPT</a></li>
<li class="toctree-l3"><a class="reference internal" href="#mcmc">4.3.2. MCMC</a></li>
<li class="toctree-l3"><a class="reference internal" href="#merr">4.3.3. MERR</a></li>
<li class="toctree-l3"><a class="reference internal" href="#bcs">4.3.4. BCS</a></li>
</ul>
</li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Pytorch.html">5. PyTorch Models</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Programmer Guide</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="Contributing.html">1. Contributing</a></li>
<li class="toctree-l1"><a class="reference internal" href="Executable.html">2. Executable</a></li>
<li class="toctree-l1"><a class="reference internal" href="Lib/index.html">3. Library</a></li>
<li class="toctree-l1"><a class="reference internal" href="Tests.html">4. Tests</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="index.html">FitSNAP</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="index.html" class="icon icon-home"></a> »</li>
<li><span class="section-number">4. </span>Linear Models</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/Linear.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="linear-models">
<h1><span class="section-number">4. </span>Linear Models<a class="headerlink" href="#linear-models" title="Permalink to this heading"></a></h1>
<p>FitSNAP can perform linear regression to obtain models of the form</p>
<div class="math notranslate nohighlight">
\[E_s = \sum_i^{N_s}{ \boldsymbol{\beta}_i \cdot \boldsymbol{B}_i }\]</div>
<p>where</p>
<ul class="simple">
<li><p><span class="math notranslate nohighlight">\(s\)</span> indexes a particular configuration of atoms</p></li>
<li><p><span class="math notranslate nohighlight">\(E_s\)</span> is the potential energy of configuration <span class="math notranslate nohighlight">\(s\)</span></p></li>
<li><p><span class="math notranslate nohighlight">\(i\)</span> indexes a particular atom</p></li>
<li><p><span class="math notranslate nohighlight">\(N_s\)</span> is the number of atoms in configuration <span class="math notranslate nohighlight">\(s\)</span></p></li>
<li><p><span class="math notranslate nohighlight">\(\boldsymbol{\beta}_i\)</span> is a vector of fitting coefficients for atom <span class="math notranslate nohighlight">\(i\)</span></p></li>
<li><p><span class="math notranslate nohighlight">\(\boldsymbol{B}_i\)</span> is a vector of atomic environment descriptors for atom <span class="math notranslate nohighlight">\(i\)</span></p></li>
</ul>
<p>The settings for SNAP descriptors are explained in the <a class="reference external" href="Run.html#bispectrum">[BISPECTRUM] section</a>.</p>
<p>For this linear regression problem we solve the following matrix problem as explained in <a class="reference external" href="https://www.sciencedirect.com/science/article/pii/S0021999114008353">Thompson et. al.</a></p>
<figure class="align-default">
<a class="reference internal image-reference" href="_images/fitting_matrix.png"><img alt="_images/fitting_matrix.png" src="_images/fitting_matrix.png" style="width: 542.4px; height: 300.0px;" /></a>
</figure>
<p>where</p>
<ul class="simple">
<li><p><span class="math notranslate nohighlight">\(\frac{\boldsymbol{B}_i}{r_j^{\alpha}}\)</span> is the gradient of descriptor <span class="math notranslate nohighlight">\(\boldsymbol{B}_i\)</span>
with respect to <span class="math notranslate nohighlight">\(r_j^{\alpha}\)</span>, the <span class="math notranslate nohighlight">\(\alpha\)</span> Cartesian direction of atom <span class="math notranslate nohighlight">\(j\)</span>.</p></li>
<li><p><span class="math notranslate nohighlight">\(E^{qm}_s\)</span> is the quantum mechanical target energy for configuration <span class="math notranslate nohighlight">\(s\)</span></p></li>
<li><p><span class="math notranslate nohighlight">\(E^{ref}_s\)</span> is the reference energy of a potential that is overlayed on the linear regression
model, as declared in the <a class="reference external" href="Run.html#reference">[REFERENCE] section</a></p></li>
<li><p><span class="math notranslate nohighlight">\(F^{qm}_{j,\alpha}\)</span> is the quantum mechanical target force for atom <span class="math notranslate nohighlight">\(j\)</span> in the
<span class="math notranslate nohighlight">\(\alpha\)</span> direction.</p></li>
<li><p><span class="math notranslate nohighlight">\(F^{qm}_{j,\alpha}\)</span> is the reference force for atom <span class="math notranslate nohighlight">\(j\)</span> in the <span class="math notranslate nohighlight">\(\alpha\)</span>
direction, from a potential that is overlayed on the linear regression model, as declared in
the <a class="reference external" href="Run.html#reference">[REFERENCE] section</a>.</p></li>
<li><p><span class="math notranslate nohighlight">\(W_{\alpha \beta, s}\)</span> is virial in the <span class="math notranslate nohighlight">\(\alpha\)</span> and <span class="math notranslate nohighlight">\(\beta\)</span> directions for
configuration <span class="math notranslate nohighlight">\(s\)</span>, where both quantum mechanical target and reference virials are included
on the right-hand side of the matrix equation.</p></li>
</ul>
<p>FitSNAP solves this matrix problem using SVD and supports other solvers as well. For more details on
settings used for descriptors and solvers, please see the docs on
<a class="reference external" href="Run.html#input-scripts">FitSNAP Input Scripts</a>.</p>
<section id="outputs">
<h2><span class="section-number">4.1. </span>Outputs<a class="headerlink" href="#outputs" title="Permalink to this heading"></a></h2>
<p>The outputs for linear models are explained here. For nonlinear models, please see the
<a class="reference external" href="Pytorch.html#outputs-and-error-calculation">PyTorch models output section</a>. After running a
linear model fit, the following outputs will be produced:</p>
<ul class="simple">
<li><p><code class="code docutils literal notranslate"><span class="pre">FitSNAP.df</span></code> is a Pandas dataframe with rows corresponding to the linear fitting matrix as
shown above. We have interactive examples of examining this dataframe and calculating detailed
errors from it in our <a class="reference external" href="https://colab.research.google.com/github/FitSNAP/FitSNAP/blob/master/tutorial.ipynb">Colab Python notebook tutorial</a>.</p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">*_metrics.md</span></code> is a markdown file containing mean absolute errors and RMSEs for your dataset.
If using LAMMPS metal units, energy errors are in eV, and force errors are in eV/Angstrom. The prefix name
of this file depends on the <code class="code docutils literal notranslate"><span class="pre">metrics</span></code> parameter declared in the <a class="reference external" href="Run.html#outfile">[OUTFILE] section</a>.</p></li>
<li><p><strong>LAMMPS-ready potential files</strong>. For example if fitting with SNAP descriptors, this will create
<code class="code docutils literal notranslate"><span class="pre">*_pot.snapparam</span></code> and <code class="code docutils literal notranslate"><span class="pre">*_pot.snapcoeff</span></code> files with prefix names depending on the <code class="code docutils literal notranslate"><span class="pre">potential</span></code>
parameter declared in the <a class="reference external" href="Run.html#outfile">[OUTFILE] section</a>. To use these files with LAMMPS,
please refer to the LAMMPS documentation.</p></li>
</ul>
</section>
<section id="uncertainty-quantification-uq">
<h2><span class="section-number">4.2. </span>Uncertainty Quantification (UQ)<a class="headerlink" href="#uncertainty-quantification-uq" title="Permalink to this heading"></a></h2>
<p>Linear models have uncertainty quantification (UQ) capabilitiies in the form of extra solvers, which
are explain here. UQ solvers output a <code class="code docutils literal notranslate"><span class="pre">covariance.npy</span></code> file in addition to performing a fit.</p>
<p>We incorporate an analytical Bayesian UQ solver denoted by <code class="code docutils literal notranslate"><span class="pre">solver</span> <span class="pre">=</span> <span class="pre">ANL</span></code> in the input script. This
is declared like:</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">solver = ANL</span>
<span class="go">nsam = 133 #this is the number of sample fits requested to be drawn from the distribution</span>
<span class="go">cov_nugget = 1.e-10 #this is the small number to be added to the matrix inverse for better conditioning</span>
</pre></div>
</div>
</section>
<section id="in-development-uq-solvers">
<h2><span class="section-number">4.3. </span>In development UQ solvers<a class="headerlink" href="#in-development-uq-solvers" title="Permalink to this heading"></a></h2>
<p>In general we recommend the use of the <code class="code docutils literal notranslate"><span class="pre">ANL</span></code> solver. The following UQ solvers, however, are
experimental and in development.</p>
<section id="opt">
<h3><span class="section-number">4.3.1. </span>OPT<a class="headerlink" href="#opt" title="Permalink to this heading"></a></h3>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">solver = OPT</span>
</pre></div>
</div>
<p>The standard least-squares fit, but solving the optimization problem instead of SVD or matrix
inversions. Can be useful when matrices are ill-conditioned, or when we add regularization.</p>
</section>
<section id="mcmc">
<h3><span class="section-number">4.3.2. </span>MCMC<a class="headerlink" href="#mcmc" title="Permalink to this heading"></a></h3>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">solver = MCMC</span>
<span class="go">nsam = 133 #this is the number of sample fits requested to be drawn from the distribution</span>
<span class="go">mcmc_num = 1000 #this is the number of total MCMC steps requested</span>
<span class="go">mcmc_gamma = 0.01 #this is the MCMC proposal jump size (smaller gamma increases the acceptance rate)</span>
</pre></div>
</div>
<p>MCMC sampling, currently assuming constant noise size, but unlike the ANL case, there is flexibility
if one plays with the log-post function.</p>
</section>
<section id="merr">
<h3><span class="section-number">4.3.3. </span>MERR<a class="headerlink" href="#merr" title="Permalink to this heading"></a></h3>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">solver = MERR</span>
<span class="go">nsam = 133 #this is the number of sample fits requested to be drawn from the distribution</span>
<span class="go">merr_method = iid #specific liklihood model: options are iid, independent identically distributed, and abc, approximate bayesian computation, and full (too heavy and degenerate, not intended to be used yet)</span>
<span class="go">merr_mult = 0 #0 is additive model error, 1 is multiplicative</span>
<span class="go">merr_cfs = 5 44 3 49 10 33 4 39 38 23 #can provide either a list of coefficient indices to embed on, or "all"</span>
<span class="go">cov_nugget = 1.e-10 #this is the small number to be added to the matrix inverse for better conditioning</span>
</pre></div>
</div>
<p>Model error embedding approach - powerful but very slow. Requires an optimization that does not run
in parallel currently, and is not guaranteed to converge.</p>
</section>
<section id="bcs">
<h3><span class="section-number">4.3.4. </span>BCS<a class="headerlink" href="#bcs" title="Permalink to this heading"></a></h3>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">solver = BCS</span>
</pre></div>
</div>
<p>Fitting with Bayesian compressive sensing, need to learn how to prune bispectrum bases in order for
this to be useful. Not working properly yet.</p>
</section>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="Run/Run_library.html" class="btn btn-neutral float-left" title="3.4. Running as library" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="Pytorch.html" class="btn btn-neutral float-right" title="5. PyTorch Models" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>© Copyright 2022, Sandia Corporation.</p>
</div>
Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
<a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>