forked from hackingmaterials/atomate
-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathworkflow_yaml_reference.html
251 lines (240 loc) · 13.6 KB
/
workflow_yaml_reference.html
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
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Workflow YAML Reference — atomate 1.0.3 documentation</title>
<link rel="stylesheet" href="_static/nature.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/language_data.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Atomate concepts" href="concepts.html" />
<link rel="prev" title="License" href="license.html" />
<link href='https://fonts.googleapis.com/css?family=Lato:400,700' rel='stylesheet' type='text/css'>
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="concepts.html" title="Atomate concepts"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="license.html" title="License"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">atomate 1.0.3 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Workflow YAML Reference</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="workflow-yaml-reference">
<span id="id1"></span><h1>Workflow YAML Reference<a class="headerlink" href="#workflow-yaml-reference" title="Permalink to this headline">¶</a></h1>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>This document is a short reference for the features of atomate Workflows that you can control in YAML files. It aims to express all of the features that can make up a workflow. The benefit of YAML file workflows is that they are easy to understand and share, especially for non-programmers.</p>
<p>For details on the YAML format, refer to the <a class="reference external" href="http://www.yaml.org/spec/1.2/spec.html">official YAML specification</a>.</p>
</div>
<div class="section" id="yaml-files-in-atomate">
<h2>YAML Files in atomate<a class="headerlink" href="#yaml-files-in-atomate" title="Permalink to this headline">¶</a></h2>
<p>The following illustrates an example of a YAML file that can be used in atwf to run a workflow. Unless there is an existing YAML Workflow for the workflow you are trying to create, you will have to determine which required and optional parameters to set. Every Workflow in atomate is required to have a structure as the first parameter. This is implied in all of the YAML files and does not need to be included.</p>
<p>YAML format for the usual MP bandstructure workflow is given as follows:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">fireworks</span><span class="p">:</span>
<span class="p p-Indicator">-</span> <span class="nt">fw</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">atomate.vasp.fireworks.core.OptimizeFW</span>
<span class="p p-Indicator">-</span> <span class="nt">fw</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">atomate.vasp.fireworks.core.StaticFW</span>
<span class="nt">params</span><span class="p">:</span>
<span class="nt">parents</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">0</span>
<span class="p p-Indicator">-</span> <span class="nt">fw</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">atomate.vasp.fireworks.core.NonSCFUniformFW</span>
<span class="nt">params</span><span class="p">:</span>
<span class="nt">parents</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">1</span>
<span class="p p-Indicator">-</span> <span class="nt">fw</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">atomate.vasp.fireworks.core.NonSCFLineFW</span>
<span class="nt">params</span><span class="p">:</span>
<span class="nt">parents</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">1</span>
<span class="nt">common_params</span><span class="p">:</span>
<span class="nt">db_file</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">db.json</span>
<span class="nt">$vasp_cmd</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">$HOME/opt/vasp</span>
<span class="nt">name</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">bandstructure</span>
<span class="nt">metadata</span><span class="p">:</span>
<span class="nt">tag</span><span class="p">:</span> <span class="l l-Scalar l-Scalar-Plain">testing_workflow</span>
</pre></div>
</div>
<p>At the top there is often a comment (hashtag) describing the workflow (not shown here).</p>
<p>The <cite>fireworks</cite> key is a list of Fireworks; it is expected that
all such Fireworks have “structure” as the first argument and
other optional arguments following that. Each Firework is specified
via “fw”: <explicit path>.</p>
<p>You can pass arguments into the Firework constructor using the special
keyword <cite>params</cite>, which is a dict. Any param starting with a $ will
be expanded using environment variables. If multiple fireworks share
the same <cite>params</cite>, you can use <cite>common_params</cite> to specify a common
set of arguments that are passed to all fireworks. Local params
take precedent over global params.</p>
<p>Another special keyword is <cite>parents</cite>, which provides
the <em>indices</em> of the parents of that particular Firework in the
list. The indices start at zero, i.e, the first Firework in your list
has zero. Thus, if you want the second Firework in the list to be a child
of the first Firework, you should specify a parent of 0 for the Firework.
Multiple parents are allowed. This allows you to link the Fireworks into a
logical workflow.</p>
<p>In the above example, we have:
* the first Firework (OptimizeFW) will run before anything else
* the second Firework (StaticFW) will run after the OptimizeFW is complete
* the third and fourth Fireworks (NonSCFUniformFW and NonSCFLineFW) will
run after the StaticFW is complete. Note these two Fireworks can run in parallel.</p>
<p>Next, <cite>name</cite> is used to set the Workflow name (structure formula +
name) which can be helpful in record keeping.</p>
<p>Finally, one can specify a <cite>metadata</cite> key as a YAML dict/hash that will
initialize workflow metadata - this is purely optional and for bookkeeping.</p>
</div>
<div class="section" id="eos-workflow-example">
<h2>EOS Workflow Example<a class="headerlink" href="#eos-workflow-example" title="Permalink to this headline">¶</a></h2>
<p>This example shows what a more complicated workflow can look like using the YAML version of the EOS workflow described in the <a class="reference internal" href="running_workflows.html#running-workflows-tutorial"><span class="std std-ref">Running Workflows Tutorial</span></a>.</p>
<p>In order to use this example, create a file called <code class="docutils literal notranslate"><span class="pre">eos.yaml</span></code> with a text editor and enter the following text:</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span># EOS Workflow
# An optimization Firework followed by 7 deformed structures based on the optimized structure
# the deformations are +/- 10% volume of the original cell
fireworks:
- fw: atomate.vasp.fireworks.core.OptimizeFW
user_incar_settings:
SIGMA: 0.2
ISMEAR: 1
- fw: atomate.vasp.fireworks.core.TransmuterFW
params:
parents: 0
transformations:
- DeformStructureTransformation
transformation_params:
- "scaling_matrix": [[0.9655, 0, 0], [0, 0.9655, 0], [0, 0, 0.9655]]
- fw: atomate.vasp.fireworks.core.TransmuterFW
params:
parents: 0
transformations:
- DeformStructureTransformation
transformation_params:
- "scaling_matrix": [[0.9773, 0, 0], [0, 0.9773, 0], [0, 0, 0.9773]]
- fw: atomate.vasp.fireworks.core.TransmuterFW
params:
parents: 0
transformations:
- DeformStructureTransformation
transformation_params:
- "scaling_matrix": [[0.9888, 0, 0], [0, 0.9888, 0], [0, 0, 0.9888]]
- fw: atomate.vasp.fireworks.core.TransmuterFW
params:
parents: 0
transformations:
- DeformStructureTransformation
transformation_params:
- "scaling_matrix": [[1.0000, 0, 0], [0, 1.0000, 0], [0, 0, 1.0000]]
- fw: atomate.vasp.fireworks.core.TransmuterFW
params:
parents: 0
transformations:
- DeformStructureTransformation
transformation_params:
- "scaling_matrix": [[1.0110, 0, 0], [0, 1.0110, 0], [0, 0, 1.0110]]
- fw: atomate.vasp.fireworks.core.TransmuterFW
params:
parents: 0
transformations:
- DeformStructureTransformation
transformation_params:
- "scaling_matrix": [[1.0217, 0, 0], [0, 1.0217, 0], [0, 0, 1.0217]]
- fw: atomate.vasp.fireworks.core.TransmuterFW
params:
parents: 0
transformations:
- DeformStructureTransformation
transformation_params:
- "scaling_matrix": [[1.0323, 0, 0], [0, 1.0323, 0], [0, 0, 1.0323]]
common_params:
vasp_cmd: >>vasp_cmd<<
db_file: >>db_file<<
</pre></div>
</div>
<p>To add this to your LaunchPad go to the folder containing your <code class="docutils literal notranslate"><span class="pre">POSCAR</span></code> (or other structure file) and <code class="docutils literal notranslate"><span class="pre">eos.yaml</span></code>, run the following command to add the workflow to your LaunchPad:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>atwf add POSCAR -s eos.yaml
</pre></div>
</div>
<p>The YAML file format is typically considered easy to read, but it is less practical for more complicated workflows. The Python implementation of the EOS workflow is at <code class="xref py py-mod docutils literal notranslate"><span class="pre">atomate.vasp.workflows.base.bulk_modulus</span></code> and it uses the existing deformation workflow to express the same as the above YAML file in less than 20 lines of Python code, including imports. Another advantage of using Python is being able to have more control over Fireworks and create them from Firetasks in the workflow, like the <code class="docutils literal notranslate"><span class="pre">FitEOSToDb</span></code> Firetask.</p>
</div>
</div>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Workflow YAML Reference</a><ul>
<li><a class="reference internal" href="#introduction">Introduction</a></li>
<li><a class="reference internal" href="#yaml-files-in-atomate">YAML Files in atomate</a></li>
<li><a class="reference internal" href="#eos-workflow-example">EOS Workflow Example</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="license.html"
title="previous chapter">License</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="concepts.html"
title="next chapter">Atomate concepts</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/workflow_yaml_reference.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="concepts.html" title="Atomate concepts"
>next</a> |</li>
<li class="right" >
<a href="license.html" title="License"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">atomate 1.0.3 documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Workflow YAML Reference</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2015, Anubhav Jain.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.2.1.
</div>
</body>
</html>