source: Tutorials/PythonScript/CommandLine.htm @ 4131

Last change on this file since 4131 was 3207, checked in by toby, 5 years ago

New command-line tutorial
  • Property svn:mime-type set to text/html
File size: 9.6 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
2<html> <head>
3<title>GSAS-II from the Command Line</title>
4</head>
5
6<body>
7<h1>Running a GSAS-II Refinement from the Command Line</h1>
8In this training example we show a unix script that duplicates the Python
9<A href="https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/PythonScript/Scripting.htm"
10target="_blank">Scripting GSAS-II</A> tutorial
11(which shows how to script the <A
12href="https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/CWCombined/Combined%20refinement.htm"
13target="_blank">GSAS-II CW Combined Refinement</A>
14tutorial refinement.)
15
16<h2>Prerequisites</h2>
17This exercise assumes that the reader has reviewed
18the software documentation on the
19<A href="http://gsas-ii.readthedocs.io/en/latest/GSASIIscripts.html"
20target="_blank"> 
21GSASIIscriptable module</A> (http://gsas-ii.readthedocs.io/en/latest/GSASIIscripts.html)
22with special attention to the
23<A
24href="http://gsas-ii.readthedocs.io/en/latest/GSASIIscriptable.html#gsasiiscriptable-command-line-interface">Command-line
25Interface</A> section. Note that this tutorial duplicates the
26<A href="https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/PythonScript/Scripting.htm#SingleStep"
27target="_blank">Single Step Approach</A> section of the Scripting
28GSAS-II tutorial, which should be reviewed before this tutorial is
29read. It may also be useful to review the <A href="https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/CWCombined/Combined%20refinement.htm"
30target="_blank">GSAS-II CW Combined Refinement</A> tutorial that this
31exercise is modeled upon, which explains why each refinement step is
32being used.
33<P>
34The exercise can be performed by placing all of the shell commands
35into a script, (which can also be
36<A href="https://subversion.xray.aps.anl.gov/trac/pyGSAS/export/3131/Tutorials/PythonScript/data/example.sh">
37downloaded here</A>),
38but it is also possible to use copy and paste to execute the commands
39into a terminal window on a Mac or Linux computer (this likely works
40but has not been tried with <A
41href="https://docs.microsoft.com/en-us/windows/wsl/install-win10">Windows
42Subsystem for Linux</a>).
43<P>
44Finally, download from
45<A href="https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/PythonScript/data/">
46https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/PythonScript/data/</A> 
47the following files: "PBSO4.XRA", "INST_XRY.PRM", "PBSO4.CWN",
48"inst_d1a.prm" and "PbSO4-Wyckoff.cif" and make a note of their
49location for the next step.
50
51<h4>0: Create variables for paths</H4>
52<blockquote>
53To simplify the subsequent commands, let's define variables with the path of the
54data files and the path to where GSAS-II is installed:
55<blockquote><textarea rows="3" cols="70" readonly>
56datadir="/Users/toby/software/G2/Tutorials/PythonScript/data"
57gsaspath="/Users/toby/GSASII"
58</textarea></blockquote>
59
60Note that we will run the Python found in the path. If Python needs to be
61executed from a different location, it might be useful to also define
62a variable that points to that.
63</blockquote>
64<h4>1: Create a GSAS-II project and add a phase and histogram</H4>
65<blockquote> 
66The first step in this exercise is to create the GSAS-II project and
67then add this two powder datasets and a phase to the project. Note
68that in this example, it is possible to do all this in a single step,
69but this is done here with two commands, in part to demonstrate command options only
70available with the "add" command (<tt>-hf</tt>, <tt>-pf</tt> and <tt>-l</tt>, which
71select formats for the histogram and phase files, as well as, designate
72which histograms are linked to the phase, respectively.)
73
74<blockquote><textarea rows="6" cols="70" readonly>
75python $gsaspath/GSASIIscriptable.py create test.gpx
76python $gsaspath/GSASIIscriptable.py add test.gpx \
77    -d $datadir/PBSO4.XRA $datadir/PBSO4.CWN -hf GSAS \
78    -i $datadir/INST_XRY.PRM $datadir/inst_d1a.prm \
79    -p $datadir/PbSO4-Wyckoff.cif -pf CIF -l 0 1
80</textarea></blockquote>
81
82Note since the "add" command offers the "-l" (or "--histlist")
83option and "create" does not, if the added phase(s) will be linked to
84only some histograms, the "add" command is required.
85</blockquote>
86
87<h4>2: Create a JSON file to conduct the refinement</H4>
88<blockquote> 
89The following single command creates a JSON file. This contains a
90representation of Python dict structure. <A
91href="http://json.org/">JSON syntax</A> is quite close to Python,
92except that the boolean key words (true and false) are all lower case
93and that while use of extra commas at ends of dicts and lists is
94allowed in Python, it is not in JSON.
95<blockquote><textarea rows="42" cols="70" readonly>
96cat > example.json <<EOF
97{"refinements": 
98  [
99    {"skip":true, "call":"SetParams"},
100    { "set": {"Background": {"no. coeffs": 3, "refine": true}}, 
101      "call":"HistStats", "output": "step4.gpx"}, 
102    { "set": {"Cell": true}, "call":"HistStats", "output": "step5.gpx"}, 
103    { "set": {"HStrain": true}, 
104      "histograms": [0], "phases": [0], "call":"HistStats", "output": "step6.gpx"}, 
105    { "set": {"Mustrain": {"type": "isotropic", "refine": true}, 
106             "Size": {"type": "isotropic", "refine": true}}, 
107      "histograms": [0], "call":"HistStats", "output": "step7.gpx"}, 
108    { "set": {"Sample Parameters": ["Shift"]}, 
109      "histograms": [0], "skip": true}, 
110    { "set": {"Atoms": {"all": "XU"}, 
111             "Sample Parameters": ["DisplaceX", "DisplaceY"]}, 
112      "histograms": [1], "call":"HistStats", "output": "step8.gpx"}, 
113    { "set": {"Limits": [16.0, 158.4]}, 
114      "histograms": [0], "skip": true}, 
115    { "set": {"Limits": [19.0, 153.0]}, 
116      "histograms": [1], "skip": true}, 
117    { "set": {"Instrument Parameters": ["U", "V", "W"]}, 
118      "call":"HistStats", "output": "step9.gpx"}
119  ],
120"code":
121  ["global HistStats",
122   "def HistStats(gpx):",
123   "    '''prints profile rfactors for all histograms'''",
124   "    print(u'*** profile Rwp, '+os.path.split(gpx.filename)[1])",
125   "    for hist in gpx.histograms():",
126   "        print('\t{:20s}: {:.2f}'.format(hist.name,hist.get_wR()))",
127   "    print()",
128   "proj.data['Controls']['data']['max cyc'] = 8 # not in API",
129   "proj.histogram(1).data['Sample Parameters']['Gonio. radius'] = 650. # not in API"
130  ]
131}
132EOF
133</textarea></blockquote>
134
135This code example requires a fair amount of explaination. Note that
136the first and last lines (<tt>cat</tt> and <tt>EOF</tt>) are used to
137create the file (<tt>example.json</tt>)
138from the shell and could be eliminated if the file were to be created
139directly in an editor.
140<P>
141There are two entries in the dict, <tt>refinements</tt>, which defines
142the steps to be followed in the refinement, and
143<tt>code</tt>, which defines Python code to be executed after the
144GSAS-II project is read in, but before the refinement is performed.
145<P>
146<DL><DT><tt>refinements</tt></DT>
147<DD>Performs the same actions as are described in steps 5-10 in the
148  <A href="https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/PythonScript/Scripting.htm"
149target="_blank">Scripting GSAS-II</A> tutorial. The
150<A href="https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/PythonScript/Scripting.htm#SingleStep"
151target="_blank">Single Step</A> section shows these steps collapsed to
152  a list of dicts.
153</DD>
154<DT><tt>code</tt></DT>
155<DD>Note that since JSON does not offer a method to quote multiline
156  strings, this dict entry is defined as a list of strings, which are
157  concatenated as separate Python lines. This Python code will be
158  evaluated [using expr()] inside function
159  <A href="http://gsas-ii.readthedocs.io/en/latest/GSASIIscriptable.html#GSASIIscriptable.refine">
160  <tt>refine</tt></a> where variable <tt>proj</tt> is defined as the current
161  G2Project.
162<P>
163In this example, the function <tt>HistStats</tt> is defined as before,
164  but now a global statement is needed so that this function is
165  visible where it will be used. Note that the two statements used to
166  set GSAS-II parameters directly (from steps 4 and 9 in the
167  <A href="https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/PythonScript/Scripting.htm"
168target="_blank">Scripting GSAS-II</A> tutorial) are moved here and are
169  referenced with the variable <tt>proj</tt> rather than <tt>gpx</tt>.
170</DD></DL>
171</blockquote>
172
173<h4>3: Execute the refinement</H4>
174<blockquote> 
175The final command executes the contents of the JSON file:
176
177<blockquote><textarea rows="1" cols="70" readonly>
178python $gsaspath/GSASIIscriptable.py refine test.gpx example.json
179</textarea></blockquote>
180
181</blockquote>
182
183<h2>Command Line Scripts in Windows</h2>
184
185While scripting is more commonly done in unix-type environments (Mac
186and Linux), it is also possible to use the GSASIIscriptable capability
187from a Windows batch (.bat) file. Note that the syntax is slightly
188different, but follows the same general rules. The following commands
189reproduce the above exercise in Windows.
190
191<blockquote><textarea rows="10" cols="70" readonly>
192@REM example script that uses cmd.exe to run a GSAS-II script
193set datadir=C:\Users\toby.WIN10-VM\temp\
194set gsaspath=c:\GSASII\
195set python=C:\conda3\python.exe
196%python% %gsaspath%GSASIIscriptable.py create test.gpx
197%python% %gsaspath%GSASIIscriptable.py add test.gpx ^
198    -d %datadir%PBSO4.XRA %datadir%PBSO4.CWN ^
199        -i %datadir%INST_XRY.PRM %datadir%inst_d1a.prm -hf GSAS ^
200    -p %datadir%PbSO4-Wyckoff.cif -pf CIF -l 0 1
201%python% %gsaspath%GSASIIscriptable.py refine test.gpx example.json
202</textarea></blockquote>
203
204Note that for simplicity, it is assumed
205that the <tt>example.JSON</tt> file has been created in a text editor
206or has been downloaded along with the required data files
207(<A href="https://subversion.xray.aps.anl.gov/trac/pyGSAS/browser/Tutorials/PythonScript/data/example.JSON?format=txt">download link</A>).
208<hr>
209<address></address>
210<!-- hhmts start -->Last modified: Tue Dec 26 16:54:48 CST 2017 <!-- hhmts end -->
211</body> </html>
Note: See TracBrowser for help on using the repository browser.