source: Tutorials/PythonScript/CommandLine.htm @ 4575

Last change on this file since 4575 was 4457, checked in by toby, 18 months ago

add data link to tutorials

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