| 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 | |
|---|
| 14 | In 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" |
|---|
| 16 | target="_blank">Scripting GSAS-II</A> tutorial |
|---|
| 17 | (which shows how to script the <A |
|---|
| 18 | href="https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/CWCombined/Combined%20refinement.htm" |
|---|
| 19 | target="_blank">GSAS-II CW Combined Refinement</A> |
|---|
| 20 | tutorial refinement.) |
|---|
| 21 | |
|---|
| 22 | <h2>Prerequisites</h2> |
|---|
| 23 | This exercise assumes that the reader has reviewed |
|---|
| 24 | the software documentation on the |
|---|
| 25 | <A href="http://gsas-ii.readthedocs.io/en/latest/GSASIIscripts.html" |
|---|
| 26 | target="_blank"> |
|---|
| 27 | GSASIIscriptable module</A> (http://gsas-ii.readthedocs.io/en/latest/GSASIIscripts.html) |
|---|
| 28 | with special attention to the |
|---|
| 29 | <A |
|---|
| 30 | href="http://gsas-ii.readthedocs.io/en/latest/GSASIIscriptable.html#gsasiiscriptable-command-line-interface">Command-line |
|---|
| 31 | Interface</A> section. Note that this tutorial duplicates the |
|---|
| 32 | <A href="https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/PythonScript/Scripting.htm#SingleStep" |
|---|
| 33 | target="_blank">Single Step Approach</A> section of the Scripting |
|---|
| 34 | GSAS-II tutorial, which should be reviewed before this tutorial is |
|---|
| 35 | read. It may also be useful to review the <A href="https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/CWCombined/Combined%20refinement.htm" |
|---|
| 36 | target="_blank">GSAS-II CW Combined Refinement</A> tutorial that this |
|---|
| 37 | exercise is modeled upon, which explains why each refinement step is |
|---|
| 38 | being used. |
|---|
| 39 | <P> |
|---|
| 40 | The exercise can be performed by placing all of the shell commands |
|---|
| 41 | into a script, (which can also be |
|---|
| 42 | <A href="https://subversion.xray.aps.anl.gov/trac/pyGSAS/export/3131/Tutorials/PythonScript/data/example.sh"> |
|---|
| 43 | downloaded here</A>), |
|---|
| 44 | but it is also possible to use copy and paste to execute the commands |
|---|
| 45 | into a terminal window on a Mac or Linux computer (this likely works |
|---|
| 46 | but has not been tried with <A |
|---|
| 47 | href="https://docs.microsoft.com/en-us/windows/wsl/install-win10">Windows |
|---|
| 48 | Subsystem for Linux</a>). |
|---|
| 49 | <P> |
|---|
| 50 | Finally, download from |
|---|
| 51 | <A href="https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/PythonScript/data/"> |
|---|
| 52 | https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/PythonScript/data/</A> |
|---|
| 53 | the following files: "PBSO4.XRA", "INST_XRY.PRM", "PBSO4.CWN", |
|---|
| 54 | "inst_d1a.prm" and "PbSO4-Wyckoff.cif" and make a note of their |
|---|
| 55 | location for the next step. |
|---|
| 56 | |
|---|
| 57 | <h4>0: Create variables for paths</H4> |
|---|
| 58 | <blockquote> |
|---|
| 59 | To simplify the subsequent commands, let's define variables with the path of the |
|---|
| 60 | data files and the path to where GSAS-II is installed: |
|---|
| 61 | <blockquote><textarea rows="3" cols="70" readonly> |
|---|
| 62 | datadir="/Users/toby/software/G2/Tutorials/PythonScript/data" |
|---|
| 63 | gsaspath="/Users/toby/GSASII" |
|---|
| 64 | </textarea></blockquote> |
|---|
| 65 | |
|---|
| 66 | Note that we will run the Python found in the path. If Python needs to be |
|---|
| 67 | executed from a different location, it might be useful to also define |
|---|
| 68 | a variable that points to that. |
|---|
| 69 | </blockquote> |
|---|
| 70 | <h4>1: Create a GSAS-II project and add a phase and histogram</H4> |
|---|
| 71 | <blockquote> |
|---|
| 72 | The first step in this exercise is to create the GSAS-II project and |
|---|
| 73 | then add this two powder datasets and a phase to the project. Note |
|---|
| 74 | that in this example, it is possible to do all this in a single step, |
|---|
| 75 | but this is done here with two commands, in part to demonstrate command options only |
|---|
| 76 | available with the "add" command (<tt>-hf</tt>, <tt>-pf</tt> and <tt>-l</tt>, which |
|---|
| 77 | select formats for the histogram and phase files, as well as, designate |
|---|
| 78 | which histograms are linked to the phase, respectively.) |
|---|
| 79 | |
|---|
| 80 | <blockquote><textarea rows="6" cols="70" readonly> |
|---|
| 81 | python $gsaspath/GSASIIscriptable.py create test.gpx |
|---|
| 82 | python $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 | |
|---|
| 88 | Note since the "add" command offers the "-l" (or "--histlist") |
|---|
| 89 | option and "create" does not, if the added phase(s) will be linked to |
|---|
| 90 | only some histograms, the "add" command is required. |
|---|
| 91 | </blockquote> |
|---|
| 92 | |
|---|
| 93 | <h4>2: Create a JSON file to conduct the refinement</H4> |
|---|
| 94 | <blockquote> |
|---|
| 95 | The following single command creates a JSON file. This contains a |
|---|
| 96 | representation of Python dict structure. <A |
|---|
| 97 | href="http://json.org/">JSON syntax</A> is quite close to Python, |
|---|
| 98 | except that the boolean key words (true and false) are all lower case |
|---|
| 99 | and that while use of extra commas at ends of dicts and lists is |
|---|
| 100 | allowed in Python, it is not in JSON. |
|---|
| 101 | <blockquote><textarea rows="42" cols="70" readonly> |
|---|
| 102 | cat > 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 | } |
|---|
| 138 | EOF |
|---|
| 139 | </textarea></blockquote> |
|---|
| 140 | |
|---|
| 141 | This code example requires a fair amount of explaination. Note that |
|---|
| 142 | the first and last lines (<tt>cat</tt> and <tt>EOF</tt>) are used to |
|---|
| 143 | create the file (<tt>example.json</tt>) |
|---|
| 144 | from the shell and could be eliminated if the file were to be created |
|---|
| 145 | directly in an editor. |
|---|
| 146 | <P> |
|---|
| 147 | There are two entries in the dict, <tt>refinements</tt>, which defines |
|---|
| 148 | the steps to be followed in the refinement, and |
|---|
| 149 | <tt>code</tt>, which defines Python code to be executed after the |
|---|
| 150 | GSAS-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" |
|---|
| 155 | target="_blank">Scripting GSAS-II</A> tutorial. The |
|---|
| 156 | <A href="https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/PythonScript/Scripting.htm#SingleStep" |
|---|
| 157 | target="_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> |
|---|
| 169 | In 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" |
|---|
| 174 | target="_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> |
|---|
| 181 | The final command executes the contents of the JSON file: |
|---|
| 182 | |
|---|
| 183 | <blockquote><textarea rows="1" cols="70" readonly> |
|---|
| 184 | python $gsaspath/GSASIIscriptable.py refine test.gpx example.json |
|---|
| 185 | </textarea></blockquote> |
|---|
| 186 | |
|---|
| 187 | </blockquote> |
|---|
| 188 | |
|---|
| 189 | <h2>Command Line Scripts in Windows</h2> |
|---|
| 190 | |
|---|
| 191 | While scripting is more commonly done in unix-type environments (Mac |
|---|
| 192 | and Linux), it is also possible to use the GSASIIscriptable capability |
|---|
| 193 | from a Windows batch (.bat) file. Note that the syntax is slightly |
|---|
| 194 | different, but follows the same general rules. The following commands |
|---|
| 195 | reproduce 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 |
|---|
| 199 | set datadir=C:\Users\toby.WIN10-VM\temp\ |
|---|
| 200 | set gsaspath=c:\GSASII\ |
|---|
| 201 | set 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 | |
|---|
| 210 | Note that for simplicity, it is assumed |
|---|
| 211 | that the <tt>example.JSON</tt> file has been created in a text editor |
|---|
| 212 | or 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> |
|---|
