-
Notifications
You must be signed in to change notification settings - Fork 2
Expand file tree
/
Copy pathRun.html
More file actions
460 lines (434 loc) · 37.8 KB
/
Run.html
File metadata and controls
460 lines (434 loc) · 37.8 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
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
<!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>3. Run FitSNAP — 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 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="4. Linear Models" href="Linear.html" />
<link rel="prev" title="2. Installation" href="Installation.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 current"><a class="current reference internal" href="#">3. Run FitSNAP</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#executable">3.1. Executable</a></li>
<li class="toctree-l2"><a class="reference internal" href="#input-scripts">3.2. Input Scripts</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#bispectrum">3.2.1. [BISPECTRUM]</a></li>
<li class="toctree-l3"><a class="reference internal" href="#calculator">3.2.2. [CALCULATOR]</a></li>
<li class="toctree-l3"><a class="reference internal" href="#eshift">3.2.3. [ESHIFT]</a></li>
<li class="toctree-l3"><a class="reference internal" href="#solver">3.2.4. [SOLVER]</a></li>
<li class="toctree-l3"><a class="reference internal" href="#scraper">3.2.5. [SCRAPER]</a></li>
<li class="toctree-l3"><a class="reference internal" href="#path">3.2.6. [PATH]</a></li>
<li class="toctree-l3"><a class="reference internal" href="#outfile">3.2.7. [OUTFILE]</a></li>
<li class="toctree-l3"><a class="reference internal" href="#reference">3.2.8. [REFERENCE]</a></li>
<li class="toctree-l3"><a class="reference internal" href="#groups">3.2.9. [GROUPS]</a></li>
<li class="toctree-l3"><a class="reference internal" href="#extras">3.2.10. [EXTRAS]</a></li>
<li class="toctree-l3"><a class="reference internal" href="#memory">3.2.11. [MEMORY]</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="#outputs">3.3. Outputs</a></li>
<li class="toctree-l2"><a class="reference internal" href="#library">3.4. Library</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="Linear.html">4. Linear Models</a></li>
<li class="toctree-l1"><a class="reference internal" href="Pytorch.html">5. PyTorch Models</a></li>
<li class="toctree-l1"><a class="reference internal" href="Uncertainty%20Quantification.html">6. Uncertainty Quantification</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="Library.html">3. Library</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 class="breadcrumb-item active"><span class="section-number">3. </span>Run FitSNAP</li>
<li class="wy-breadcrumbs-aside">
<a href="_sources/Run.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="run-fitsnap">
<h1><span class="section-number">3. </span>Run FitSNAP<a class="headerlink" href="#run-fitsnap" title="Permalink to this heading"></a></h1>
<p><strong>If you want to get started immediately with interactive examples</strong>, please see our
<a class="reference external" href="https://colab.research.google.com/github/FitSNAP/FitSNAP/blob/master/tutorial.ipynb">Colab Python notebook tutorial</a></p>
<p>There are two ways to run FitSNAP: (1) the python executable or (2) as a python library. The
executable version is reserved for the most basic operation of fitting on a dataset, where data
is scraped from a directory, configurations are input to LAMMPS to calculate descriptors, and the
machine learning problem is solved. The python library provides more flexibility and allows one to
modify the steps in that fitting process.</p>
<section id="executable">
<span id="run-executable"></span><h2><span class="section-number">3.1. </span>Executable<a class="headerlink" href="#executable" title="Permalink to this heading"></a></h2>
<p>Before using the executable, you must set the path to your FitSNAP directoy in your
<code class="code docutils literal notranslate"><span class="pre">PYTHONPATH</span></code> environment variable, e.g.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">export PYTHONPATH="path/to/FitSNAP:$PYTHONPATH"</span>
</pre></div>
</div>
<p>which is conveniently placed in a <code class="code docutils literal notranslate"><span class="pre">~/.bashrc</span></code> or <code class="code docutils literal notranslate"><span class="pre">~/.bash_profile</span></code> file. Then fits
can be performed with the executable by doing</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="go">python -m fitsnap3 input.in</span>
</pre></div>
</div>
<p>where <code class="code docutils literal notranslate"><span class="pre">input.in</span></code> is a FitSNAP input script, which is explained in the next section.</p>
</section>
<section id="input-scripts">
<h2><span class="section-number">3.2. </span>Input Scripts<a class="headerlink" href="#input-scripts" title="Permalink to this heading"></a></h2>
<p>Input scripts contain settings that tell FitSNAP how to perform a fit. Our input scripts take the
form of configuration files with a format explained by
<a class="reference external" href="https://docs.python.org/3/library/configparser.html">Python’s native ConfigParser class</a>. These configuration files are composed of
sections, each of which contains keys with values, e.g. like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">SECTION1</span><span class="p">]</span>
<span class="n">key1</span> <span class="o">=</span> <span class="n">value1</span>
<span class="n">key2</span> <span class="o">=</span> <span class="n">value2</span>
<span class="p">[</span><span class="n">SECTION2</span><span class="p">]</span>
<span class="n">key3</span> <span class="o">=</span> <span class="n">value3</span>
<span class="n">key4</span> <span class="o">=</span> <span class="n">value4</span>
<span class="n">key5</span> <span class="o">=</span> <span class="n">value5</span>
</pre></div>
</div>
<p>In FitSNAP, each section declares a setting for a certain aspect of the machine learning problem.
For example we have a <code class="code docutils literal notranslate"><span class="pre">BISPECTRUM</span></code> section whose keys determine settings for the bispectrum
descriptors that describe interatomic geometry, a <code class="code docutils literal notranslate"><span class="pre">CALCULATOR</span></code> section whose keys determine
which LAMMPS computes to use for calculating the descriptors, a <code class="code docutils literal notranslate"><span class="pre">SOLVER</span></code> section whose keys
determine which numerical solver to use for performing the fit, and so forth.</p>
<p>There are many examples on the GitHub repo, for example the linear SNAP tantalum example has the
following input script:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">BISPECTRUM</span><span class="p">]</span>
<span class="n">numTypes</span> <span class="o">=</span> <span class="mi">1</span>
<span class="n">twojmax</span> <span class="o">=</span> <span class="mi">6</span>
<span class="n">rcutfac</span> <span class="o">=</span> <span class="mf">4.67637</span>
<span class="n">rfac0</span> <span class="o">=</span> <span class="mf">0.99363</span>
<span class="n">rmin0</span> <span class="o">=</span> <span class="mf">0.0</span>
<span class="n">wj</span> <span class="o">=</span> <span class="mf">1.0</span>
<span class="n">radelem</span> <span class="o">=</span> <span class="mf">0.5</span>
<span class="nb">type</span> <span class="o">=</span> <span class="n">Ta</span>
<span class="n">wselfallflag</span> <span class="o">=</span> <span class="mi">0</span>
<span class="n">chemflag</span> <span class="o">=</span> <span class="mi">0</span>
<span class="n">bzeroflag</span> <span class="o">=</span> <span class="mi">0</span>
<span class="n">quadraticflag</span> <span class="o">=</span> <span class="mi">0</span>
<span class="p">[</span><span class="n">CALCULATOR</span><span class="p">]</span>
<span class="n">calculator</span> <span class="o">=</span> <span class="n">LAMMPSSNAP</span>
<span class="n">energy</span> <span class="o">=</span> <span class="mi">1</span>
<span class="n">force</span> <span class="o">=</span> <span class="mi">1</span>
<span class="n">stress</span> <span class="o">=</span> <span class="mi">1</span>
<span class="p">[</span><span class="n">ESHIFT</span><span class="p">]</span>
<span class="n">Ta</span> <span class="o">=</span> <span class="mf">0.0</span>
<span class="p">[</span><span class="n">SOLVER</span><span class="p">]</span>
<span class="n">solver</span> <span class="o">=</span> <span class="n">SVD</span>
<span class="n">compute_testerrs</span> <span class="o">=</span> <span class="mi">1</span>
<span class="n">detailed_errors</span> <span class="o">=</span> <span class="mi">1</span>
<span class="p">[</span><span class="n">SCRAPER</span><span class="p">]</span>
<span class="n">scraper</span> <span class="o">=</span> <span class="n">JSON</span>
<span class="p">[</span><span class="n">PATH</span><span class="p">]</span>
<span class="n">dataPath</span> <span class="o">=</span> <span class="n">JSON</span>
<span class="p">[</span><span class="n">OUTFILE</span><span class="p">]</span>
<span class="n">metrics</span> <span class="o">=</span> <span class="n">Ta_metrics</span><span class="o">.</span><span class="n">md</span>
<span class="n">potential</span> <span class="o">=</span> <span class="n">Ta_pot</span>
<span class="p">[</span><span class="n">REFERENCE</span><span class="p">]</span>
<span class="n">units</span> <span class="o">=</span> <span class="n">metal</span>
<span class="n">atom_style</span> <span class="o">=</span> <span class="n">atomic</span>
<span class="n">pair_style</span> <span class="o">=</span> <span class="n">hybrid</span><span class="o">/</span><span class="n">overlay</span> <span class="n">zero</span> <span class="mf">10.0</span> <span class="n">zbl</span> <span class="mf">4.0</span> <span class="mf">4.8</span>
<span class="n">pair_coeff1</span> <span class="o">=</span> <span class="o">*</span> <span class="o">*</span> <span class="n">zero</span>
<span class="n">pair_coeff2</span> <span class="o">=</span> <span class="o">*</span> <span class="o">*</span> <span class="n">zbl</span> <span class="mi">73</span> <span class="mi">73</span>
<span class="p">[</span><span class="n">GROUPS</span><span class="p">]</span>
<span class="c1"># name size eweight fweight vweight</span>
<span class="n">group_sections</span> <span class="o">=</span> <span class="n">name</span> <span class="n">training_size</span> <span class="n">testing_size</span> <span class="n">eweight</span> <span class="n">fweight</span> <span class="n">vweight</span>
<span class="n">group_types</span> <span class="o">=</span> <span class="nb">str</span> <span class="nb">float</span> <span class="nb">float</span> <span class="nb">float</span> <span class="nb">float</span> <span class="nb">float</span>
<span class="n">smartweights</span> <span class="o">=</span> <span class="mi">0</span>
<span class="n">random_sampling</span> <span class="o">=</span> <span class="mi">0</span>
<span class="n">Displaced_A15</span> <span class="o">=</span> <span class="mf">1.0</span> <span class="mf">0.0</span> <span class="mi">100</span> <span class="mi">1</span> <span class="mf">1.00E-08</span>
<span class="n">Displaced_BCC</span> <span class="o">=</span> <span class="mf">1.0</span> <span class="mf">0.0</span> <span class="mi">100</span> <span class="mi">1</span> <span class="mf">1.00E-08</span>
<span class="n">Displaced_FCC</span> <span class="o">=</span> <span class="mf">1.0</span> <span class="mf">0.0</span> <span class="mi">100</span> <span class="mi">1</span> <span class="mf">1.00E-08</span>
<span class="n">Elastic_BCC</span> <span class="o">=</span> <span class="mf">1.0</span> <span class="mf">0.0</span> <span class="mf">1.00E-08</span> <span class="mf">1.00E-08</span> <span class="mf">0.0001</span>
<span class="n">Elastic_FCC</span> <span class="o">=</span> <span class="mf">1.0</span> <span class="mf">0.0</span> <span class="mf">1.00E-09</span> <span class="mf">1.00E-09</span> <span class="mf">1.00E-09</span>
<span class="n">GSF_110</span> <span class="o">=</span> <span class="mf">1.0</span> <span class="mf">0.0</span> <span class="mi">100</span> <span class="mi">1</span> <span class="mf">1.00E-08</span>
<span class="n">GSF_112</span> <span class="o">=</span> <span class="mf">1.0</span> <span class="mf">0.0</span> <span class="mi">100</span> <span class="mi">1</span> <span class="mf">1.00E-08</span>
<span class="n">Liquid</span> <span class="o">=</span> <span class="mf">1.0</span> <span class="mf">0.0</span> <span class="mf">4.67E+02</span> <span class="mi">1</span> <span class="mf">1.00E-08</span>
<span class="n">Surface</span> <span class="o">=</span> <span class="mf">1.0</span> <span class="mf">0.0</span> <span class="mi">100</span> <span class="mi">1</span> <span class="mf">1.00E-08</span>
<span class="n">Volume_A15</span> <span class="o">=</span> <span class="mf">1.0</span> <span class="mf">0.0</span> <span class="mf">1.00E+00</span> <span class="mf">1.00E-09</span> <span class="mf">1.00E-09</span>
<span class="n">Volume_BCC</span> <span class="o">=</span> <span class="mf">1.0</span> <span class="mf">0.0</span> <span class="mf">1.00E+00</span> <span class="mf">1.00E-09</span> <span class="mf">1.00E-09</span>
<span class="n">Volume_FCC</span> <span class="o">=</span> <span class="mf">1.0</span> <span class="mf">0.0</span> <span class="mf">1.00E+00</span> <span class="mf">1.00E-09</span> <span class="mf">1.00E-09</span>
<span class="p">[</span><span class="n">EXTRAS</span><span class="p">]</span>
<span class="n">dump_descriptors</span> <span class="o">=</span> <span class="mi">1</span>
<span class="n">dump_truth</span> <span class="o">=</span> <span class="mi">1</span>
<span class="n">dump_weights</span> <span class="o">=</span> <span class="mi">1</span>
<span class="n">dump_dataframe</span> <span class="o">=</span> <span class="mi">1</span>
<span class="p">[</span><span class="n">MEMORY</span><span class="p">]</span>
<span class="n">override</span> <span class="o">=</span> <span class="mi">0</span>
</pre></div>
</div>
<p>We explain the sections and their keys in more detail below.</p>
<section id="bispectrum">
<h3><span class="section-number">3.2.1. </span>[BISPECTRUM]<a class="headerlink" href="#bispectrum" title="Permalink to this heading"></a></h3>
<p>This section contains settings for the SNAP bispectrum descriptors from <a class="reference external" href="https://www.sciencedirect.com/science/article/pii/S0021999114008353">Thompson et. al.</a></p>
<ul class="simple">
<li><p><code class="code docutils literal notranslate"><span class="pre">numTypes</span></code> number of atom types in your set of configurations located in <a class="reference external" href="Run.html#path">the [PATH] section</a></p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">type</span></code> contains a list of element type symbols, one for each type. Make sure these are
ordered correctly, e.g. if you have a LAMMPS type 1 atom that is <code class="code docutils literal notranslate"><span class="pre">Ga</span></code>, and LAMMPS type 2
atoms are <code class="code docutils literal notranslate"><span class="pre">N</span></code>, list this as <code class="code docutils literal notranslate"><span class="pre">Ga</span> <span class="pre">N</span></code>.</p></li>
</ul>
<p>The remaining keywords are thoroughly explained in the <a class="reference external" href="https://docs.lammps.org/compute_sna_atom.html">LAMMPS docs on computing SNAP descriptors</a>
but we will give an overview here. <strong>These are hyperparameters that *could* be optimized for your
specific system, but this is not a requirement. You may also use the default values, or values used
in our examples, which are often well behaved for other systems.</strong></p>
<ul class="simple">
<li><p><code class="code docutils literal notranslate"><span class="pre">twojmax</span></code> determines the number of bispectrum coefficients for each element type. Give an
argument for each element type, e.g. for two element types we may use <code class="code docutils literal notranslate"><span class="pre">6</span> <span class="pre">6</span></code> declaring
<code class="code docutils literal notranslate"><span class="pre">twojmax</span> <span class="pre">=</span> <span class="pre">6</span></code> for each type. Higher <code class="code docutils literal notranslate"><span class="pre">twojmax</span></code> increases the number of bispectrum
components for each atom, thus potentially giving more accuracy at an increased cost. We recommend
using a <code class="code docutils literal notranslate"><span class="pre">twojmax</span></code> of 4, 6, or 8. This corresponds to 14, 30, and 55 bispectrum components,
respectively. Default value is 6.</p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">rcutfac</span></code> is a cutoff radius parameter. One value is used for all element types. We recommend
a cutoff between 4 and 5 Angstroms for most systems. Default value is 4.67 Angstroms.</p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">rfac0</span></code> is a parameter used in distance to angle conversion, between 0 and 1. Default value
is 0.99363.</p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">rmin0</span></code> another parameter used in distance to angle conversion, between 0 and 1. Default value
is 0.</p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">wj</span></code> list of neighbor weights. Give one argument for each element types, e.g. for two element
types we may use <code class="code docutils literal notranslate"><span class="pre">1.0</span> <span class="pre">0.5</span></code> declaring a weight of 1.0 for neighbors of type 1, and 0.5 for
neighbors of type 2. We recommend taking values from the existing multi-element examples.</p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">radelem</span></code> list of cutoff radii, one for each element type. These values get multiplied by
<code class="code docutils literal notranslate"><span class="pre">rcutfac</span></code> to determine the effective cutoff of a particular type.</p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">wselfallflag</span></code> is 0 or 1, determining whether self-contribution is for elements of a central
atom or for all elements, respectively.</p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">chemflag</span></code> is 0 or 1, determining whether to use explicit multi-element SNAP descriptors as
explained in <a class="reference external" href="https://www.sciencedirect.com/science/article/pii/S0021999114008353">Cusentino et. al.</a>, and used in the InP example. This
increases the number of SNAP descriptors to resolve multi-element environment descriptions, and
therefore comes at an increase in cost but higher accuracy. This option is not required
for multi-element systems; the default value is 0.</p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">bzeroflag</span></code> is 0 or 1, determining whether or not B0, the bispectrum components of an atom
with no neighbors, are subtracted from the calculated bispectrum components.</p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">quadraticflag</span></code> is 0 or 1, determining whether or not to use quadratic descriptors in a
linear model, as done by <a class="reference external" href="https://aip.scitation.org/doi/full/10.1063/1.5017641">Wood and Thompson</a>, and illusrated in the
<code class="code docutils literal notranslate"><span class="pre">Ta_Quadratic</span></code> example.</p></li>
</ul>
<p>The following keywords are necessary for extracting per-atom descriptors and individual derivatives
of bispectrum components with respect to neighbors, required for neural network potentials. See more
info in <a class="reference external" href="Pytorch.html">PyTorch Models</a></p>
<ul class="simple">
<li><p><code class="code docutils literal notranslate"><span class="pre">bikflag</span></code> is 0 or 1, determining whether to compute per-atom bispectrum descriptors instead
of sums of components for each atom. We do the latter for linear fitting because of the nature of
the linear problem, which saves memory, but per-atom descriptors are required for neural networks.</p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">dgradflag</span></code> is 0 or 1, determining whether to compute individual derivatives of descriptors
with respect to neighboring atoms, which is required for neural networks.</p></li>
</ul>
</section>
<section id="calculator">
<h3><span class="section-number">3.2.2. </span>[CALCULATOR]<a class="headerlink" href="#calculator" title="Permalink to this heading"></a></h3>
<p>This section houses keywords determining which calculator to use, i.e. which descriptors to
calculate.</p>
<ul class="simple">
<li><p><code class="code docutils literal notranslate"><span class="pre">calculator</span></code> is the name of the LAMMPS connection for getting descriptors, e.g. for SNAP
descriptors use <code class="code docutils literal notranslate"><span class="pre">LAMMPSSNAP</span></code>.</p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">energy</span></code> is 0 or 1, determining whether to calculate descriptors associated with
energies.</p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">force</span></code> is 0 or 1, determining whether to calculate descriptor gradients
associated with forces.</p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">stress</span></code> is 0 or 1, determining whether to calculate descriptors gradients associated with
virial terms for calculating and fitting to stresses.</p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">per_atom_energy</span></code> is 0 or 1, determining whether to use per-atom energy descriptors in
association with <code class="code docutils literal notranslate"><span class="pre">bikflag</span> <span class="pre">=</span> <span class="pre">1</span></code></p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">nonlinear</span></code> is 0 or 1, and should be 1 if using nonlinear solvers such as PyTorch models.</p></li>
</ul>
</section>
<section id="eshift">
<h3><span class="section-number">3.2.3. </span>[ESHIFT]<a class="headerlink" href="#eshift" title="Permalink to this heading"></a></h3>
<p>This section declares an energy shift applied to each atom type.</p>
</section>
<section id="solver">
<h3><span class="section-number">3.2.4. </span>[SOLVER]<a class="headerlink" href="#solver" title="Permalink to this heading"></a></h3>
<p>This section contains keywords associated with specific machine learning solvers.</p>
<ul class="simple">
<li><p><code class="code docutils literal notranslate"><span class="pre">solver</span></code> name of the solver. We recommend using <code class="code docutils literal notranslate"><span class="pre">SVD</span></code> for linear solvers and
<code class="code docutils literal notranslate"><span class="pre">PYTORCH</span></code> for neural networks.</p></li>
</ul>
</section>
<section id="scraper">
<h3><span class="section-number">3.2.5. </span>[SCRAPER]<a class="headerlink" href="#scraper" title="Permalink to this heading"></a></h3>
<p>This section declares which file scraper to use for gathering training data.</p>
<ul class="simple">
<li><p><code class="code docutils literal notranslate"><span class="pre">scraper</span></code> is either <code class="code docutils literal notranslate"><span class="pre">JSON</span></code> or <code class="code docutils literal notranslate"><span class="pre">XYZ.</span></code></p></li>
</ul>
<p>If using the XYZ scraper, each <a class="reference external" href="Run.html#groups">Group</a> of configurations has its own XYZ file
containing configurations of atoms concatenated together, in extended XYZ format. Follow the example
in <code class="code docutils literal notranslate"><span class="pre">examples/Ta_XYZ</span></code>.</p>
<p>If using the JSON scraper, each <a class="reference external" href="Run.html#groups">Group</a> may have its own directory containing
separate JSON files for each configuration. Guarantee compatibility with FitSNAP by using our
<code class="code docutils literal notranslate"><span class="pre">tools/VASP2JSON.py</span></code> conversion script; this requires that your DFT training data be in VASP
OUTCAR format. Likewise for <code class="code docutils literal notranslate"><span class="pre">tools/VASPxml2JSON.py</span></code>.</p>
<p>We are also working on a scraper that directly reads VASP output; more documentation on this coming
soon.</p>
</section>
<section id="path">
<h3><span class="section-number">3.2.6. </span>[PATH]<a class="headerlink" href="#path" title="Permalink to this heading"></a></h3>
<p>This section contains a <code class="code docutils literal notranslate"><span class="pre">dataPath</span></code> keyword that locates the directory of the training data.
For example if the training data is in a file called <code class="code docutils literal notranslate"><span class="pre">JSON</span></code> in the previous directory relative
to where we run the FitSNAP executable, this section looks like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">PATH</span><span class="p">]</span>
<span class="n">dataPath</span> <span class="o">=</span> <span class="o">../</span><span class="n">JSON</span>
</pre></div>
</div>
</section>
<section id="outfile">
<h3><span class="section-number">3.2.7. </span>[OUTFILE]<a class="headerlink" href="#outfile" title="Permalink to this heading"></a></h3>
<p>This section declares the names of output files.</p>
<ul class="simple">
<li><p><code class="code docutils literal notranslate"><span class="pre">metrics</span></code> gives the name of the error metrics markdown file. If using LAMMPS metal units,
energy mean absolute errors are in eV and force errors are in eV/Angstrom.</p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">potential</span></code> gives the prefix of the LAMMPS-ready potential files to dump.</p></li>
</ul>
</section>
<section id="reference">
<h3><span class="section-number">3.2.8. </span>[REFERENCE]<a class="headerlink" href="#reference" title="Permalink to this heading"></a></h3>
<p>This section includes settings for an <em>optional</em> potential to overlay our machine learned potential
with. We call this a “reference potential”, which is a pair style defined in LAMMPS. If you choose
to use a reference potential, the energies and forces from the reference potential will be subtracted
from the target <em>ab initio</em> training data. We also declare units in this section.</p>
<ul class="simple">
<li><p><code class="code docutils literal notranslate"><span class="pre">units</span></code> declares units used by LAMMPS, see <a class="reference external" href="https://docs.lammps.org/units.html">LAMMPS units docs</a> for more
info.</p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">atom_style</span></code> the atom style used by the LAMMPS pair style you wish to overlay, see
<a class="reference external" href="https://docs.lammps.org/atom_style.html">LAMMPS atom style docs</a> for more info.</p></li>
</ul>
<p>The minimum working reference potential setup involves not using a reference potential at all, where
the reference section would look like (using metal units):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span><span class="n">REFERENCE</span><span class="p">]</span>
<span class="n">units</span> <span class="o">=</span> <span class="n">metal</span>
<span class="n">pair_style</span> <span class="o">=</span> <span class="n">zero</span> <span class="mf">10.0</span>
<span class="n">pair_coeff</span> <span class="o">=</span> <span class="o">*</span> <span class="o">*</span>
</pre></div>
</div>
<p>The rest of the keywords are associated with the particular LAMMPS pair style you wish to use.</p>
</section>
<section id="groups">
<h3><span class="section-number">3.2.9. </span>[GROUPS]<a class="headerlink" href="#groups" title="Permalink to this heading"></a></h3>
<p>Each group should be its own sub-directory in the directory given by the <code class="code docutils literal notranslate"><span class="pre">dataPath/</span></code> keyword in
<a class="reference external" href="Run.html#path">the [PATH] section</a>. There are a few different allowed syntaxes; subdirectory
names in the first column is common to all options.</p>
<p><code class="code docutils literal notranslate"><span class="pre">group_sections</span></code> declares which parameters you want to set for each group of configurations.</p>
<p>For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">group_sections</span> <span class="o">=</span> <span class="n">name</span> <span class="n">training_size</span> <span class="n">testing_size</span> <span class="n">eweight</span> <span class="n">fweight</span> <span class="n">vweight</span>
</pre></div>
</div>
<p>means you will supply group names, training size as a decimal fraction, testing size as a decimal
fraction, energy weight, force weight, and virial weight, respectively. We must also declare the
data types associated with these variables, given by</p>
<blockquote>
<div><p>group_types = str float float float float float</p>
</div></blockquote>
<p>Then we may declare the group names and parameters associated with them. For a particular group
called <code class="code docutils literal notranslate"><span class="pre">Liquid</span></code> for example, this looks like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Liquid</span> <span class="o">=</span> <span class="mf">1.0</span> <span class="mf">0.0</span> <span class="mf">4.67E+02</span> <span class="mi">1</span> <span class="mf">1.00E-08</span>
</pre></div>
</div>
<p>where <code class="code docutils literal notranslate"><span class="pre">Liquid</span></code> is the name of the group, <code class="code docutils literal notranslate"><span class="pre">1.0</span></code> is the training fraction, <code class="code docutils literal notranslate"><span class="pre">0.0</span></code> is
the testing fraction, <code class="code docutils literal notranslate"><span class="pre">6.47E+02</span></code> is the energy weight, <code class="code docutils literal notranslate"><span class="pre">1</span></code> is the force weight, and
<code class="code docutils literal notranslate"><span class="pre">1.00E-8</span></code> is the virial weight.</p>
<p>Other available keywords are</p>
<ul class="simple">
<li><p><code class="code docutils literal notranslate"><span class="pre">random_sampling</span></code> is 0 or 1. If 1, configurations in the groups are randomly sampled between
their training and testing fractions.</p></li>
<li><p><code class="code docutils literal notranslate"><span class="pre">smartweights`</span></code> is 0 or 1. If 1, we declare statistically distributed weights given your
supplied weights.</p></li>
</ul>
<p>A few examples are found in the examples directory.</p>
</section>
<section id="extras">
<h3><span class="section-number">3.2.10. </span>[EXTRAS]<a class="headerlink" href="#extras" title="Permalink to this heading"></a></h3>
<p>This section contains keywords on optional info to dump. By default, linear models output error
metric markdown files that should be sufficient in most cases. If more detailed errors are required,
please see the output Pandas dataframe <code class="code docutils literal notranslate"><span class="pre">FitSNAP.df</span></code> used by linear models. Examples and
library tools for analyzing this dataframe are found 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>
</section>
<section id="memory">
<h3><span class="section-number">3.2.11. </span>[MEMORY]<a class="headerlink" href="#memory" title="Permalink to this heading"></a></h3>
<p>This section contains keywords for dealing with memory. We recommend using defaults.</p>
</section>
</section>
<section id="outputs">
<h2><span class="section-number">3.3. </span>Outputs<a class="headerlink" href="#outputs" title="Permalink to this heading"></a></h2>
<p>FitSNAP outputs include error metrics, detailed errors for each atom, configuration, or groups of
configurations, and LAMMPS-ready files for running MD simulations.</p>
<p>Outputs are different for linear and nonlinear models.</p>
<p>For linear models, please see the <a class="reference external" href="Linear.html#outputs">Linear models output section</a></p>
<p>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>
</section>
<section id="library">
<h2><span class="section-number">3.4. </span>Library<a class="headerlink" href="#library" title="Permalink to this heading"></a></h2>
<p>FitSNAP may also be run through the library interface. The <a class="reference external" href="https://github.com/FitSNAP/FitSNAP/tree/master/examples/library">GitHub repo examples</a>
may help set up scripts for your needs. More useful library functionality is found 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>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="Installation.html" class="btn btn-neutral float-left" title="2. Installation" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="Linear.html" class="btn btn-neutral float-right" title="4. Linear 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>