Changeset 3202 for Tutorials/PythonScript

Timestamp:

Dec 22, 2017 7:56:50 PM (5 years ago)

Author:

toby

Message:

make scriptable Py3 ready and add new features; minor fix for new G2 installation

File:

• Tutorials/PythonScript/Scripting.htm (modified) (18 diffs)

Tutorials/PythonScript/Scripting.htm

@@ -20 +20 @@
 This exercise assumes that the reader has reasonable familiarity with
 the Python language. 
-Before beginning this exercise, the documentation on the
+Also, the documentation on the
 <A href="http://gsas-ii.readthedocs.io/en/latest/GSASIIscripts.html"
 target="_blank">
@@ -39 +39 @@
 Python will make this a more pleasant experience. 
 
+<h2>Multi-step Script Approach</h2>
+
 <h4>0: Load the GSASIIscriptable module</H4>
 <blockquote>
@@ -48 +50 @@
 script as is done in the example below. Note that a common location
 for this will be
-<TT>os.path.expanduser("~/g2conda/GSASII/")</TT>. Thus the script will
-begin with:
+<TT>os.path.expanduser("~/g2conda/GSASII/")</TT> or
+<tt>'/Users/toby/software/GSASII'</tt>, etc. 
+Thus the script will begin with something like this:
 
 <blockquote><textarea rows="3" cols="60" readonly>
 import os,sys
-sys.path.insert(0,'/Users/toby/software/G2/GSASII')
+sys.path.insert(0,os.path.expanduser("~/g2conda/GSASII/"))
 import GSASIIscriptable as G2sc</textarea></blockquote>
 
@@ -96 +99 @@
 access a GSAS-II project, which is done with a call to
 <TT>GSASIIscriptable.G2Project()</tt>. This can be done in one of two
-ways, a call with <tt>G2sc.G2Project(filename=</tt><I>file</I><tt>)</tt> creates a new
+ways: a call with <tt>G2sc.G2Project(filename=</tt><I>file</I><tt>)</tt> creates a new
 (empty) project, while a call with
 <tt>G2sc.G2Project(gpxfile=</tt><I>file</I><tt>)</tt> opens and
-reads an existing project (.gpx) file. Both return a Project wrapper
+reads an existing project (.gpx) file. Both return a <tt>G2Project</tt> wrapper
 object that is used to access a number of methods and variables. 
 Note that <TT>GSASIIscriptable.G2Project()</tt> can read .gpx files
@@ -106 +109 @@
 <P>
 In this example, we create a new project by using the
-<tt>filename=</tt><I>file</I> argument. Note that this will not
-actually create a file until a save operation is done. 
+<tt>filename=</tt><I>file</I> argument with this code:
     
 <blockquote><textarea rows="3" cols="70" readonly>
@@ -113 +115 @@
 gpx = G2sc.G2Project(filename='PbSO4.gpx')</textarea></blockquote>
 
-</blockquote>
+Note that the file will not actually be created until an operation
+that saves the project is called.
+</blockquote>
+
 <h4>3: Add Histograms and Phase to the GSAS-II project</H4>
 <blockquote>
-To add two powder diffraction datasets (histograms) to the
-project we use the <I>project</I><tt>.add_powder_histogram()</tt> method in
-the <TT>GSASIIscriptable</tt> class. The two arguments to
+To add two powder diffraction datasets (histograms) and a phase to the
+project using this code:
+
+<blockquote><textarea rows="10" cols="70" readonly>
+# setup step 1: add two histograms to the project
+hist1 = gpx.add_powder_histogram(os.path.join(datadir,"PBSO4.XRA"),
+                          os.path.join(datadir,"INST_XRY.PRM"))
+hist2 = gpx.add_powder_histogram(os.path.join(datadir,"PBSO4.CWN"),
+                          os.path.join(datadir,"inst_d1a.prm"))
+# setup step 2: add a phase and link it to the previous histograms
+phase0 = gpx.add_phase(os.path.join(datadir,"PbSO4-Wyckoff.cif"),
+                      phasename="PbSO4",
+                      histograms=[hist1,hist2])</textarea></blockquote>
+
+  
+We use the <I>project</I><tt>.add_powder_histogram()</tt> method in
+the <TT>GSASIIscriptable</tt> class to read in the powder data.
+The two arguments to
 <tt>.add_powder_histogram()</tt> are the powder dataset and the
-  instrument parameter file. While neither powder data file uses a
-  standard extension, the importer is able to determine the file
-  format anyway. This will not be true for all file formats.
+  instrument parameter file. Note that these files are both "GSAS
+  powder data" files and the importer for this format (and many
+  others) allows files with arbitrary extensions to be read.
+All importers that allow for extensions .XRA and .CWN will be
+used to attempt to read the file, producing a number of warning
+messages. To specify that only the GSAS powder data importer be
+used, include a third argument, <tt>fmthint="GSAS powder"</tt> or
+something similar (<tt>fmthint="GSAS"</tt> is also fine, but will
+cause both the "GSAS powder data" and the "GSAS-II .gpx" importer to be considered.) 
 <UL><LI>
   Note that <I>project</I><tt>.add_powder_histogram()</tt> returns a
-  powder histogram objects which are saved for later reference. It is
+  powder histogram objects, which here are saved for later reference. It is
   also possible to obtain these using <tt>gpx.histograms()</tt>, which
   returns a list of defined histograms. 
@@ -133 +159 @@
   <I>project</I><tt>.add_phase()</tt>. This specifies a CIF containing the
   structural information, a name for the phase and specifies that the
-  two histograms are "added" (linked) to the phase.
+  two histograms are "added" (linked) to the phase. The
+<tt>fmthint="CIF"</tt> parameter can also optionally be specified to limit the
+importers that will be tried.
+
   <UL><LI>
   Note that <I>project</I><tt>.add_phase()</tt>
@@ -145 +174 @@
   These three ways to use the <tt>histograms</tt> parameter produce
   the same result.
+</blockquote>
     
-<blockquote><textarea rows="10" cols="70" readonly>
-# setup step 1: add two histograms to the project
-hist1 = gpx.add_powder_histogram(os.path.join(datadir,"PBSO4.XRA"),
-                          os.path.join(datadir,"INST_XRY.PRM"))
-hist2 = gpx.add_powder_histogram(os.path.join(datadir,"PBSO4.CWN"),
-                          os.path.join(datadir,"inst_d1a.prm"))
-# setup step 2: add a phase and link it to the previous histograms
-phase0 = gpx.add_phase(os.path.join(datadir,"PbSO4-Wyckoff.cif"),
-                      phasename="PbSO4",
-                      histograms=[hist1,hist2])</textarea></blockquote>
-
-  
-</blockquote>
 <A name="ChangeCycles">
 <h4>4: Change the number of refinement cycles</H4>
@@ -166 +183 @@
   without converging the refinement (or at least coming close to
   convergence) at each refinement step. This is best accomplished by
-  increasing the number of least-squares cycles. There at present is
-  no method in the project object that allows this parameter to be
-  set, so this must be done by finding appropriate parameter
-  dictionary entry.
+  increasing the number of least-squares cycles. No supplied method (at
+  present) allows this parameter to be set straightforwardly, but this
+  code will do this:
+  
+ <blockquote><textarea rows="3" cols="70" readonly>
+# not in tutorial: increase # of cycles to improve convergence
+gpx.data['Controls']['data']['max cyc'] = 8 # not in API </textarea></blockquote>
+
 <P>
-  At this point, the Python command <tt>gpx.data.keys()</tt> shows the names of the
-  entries in the GSAS-II tree; 'Controls' is the tree item
+  To find this parameter in the GSAS-II data structure, I followed
+  these steps: In the GUI, Controls is the tree item
   corresponding to the section where Least Squares cycles are
-  set. Command <tt>gpx.data['Controls'].keys()</tt> shows that all
+  set. Executing the command <tt>gpx.data.keys()</tt> shows the names of the
+  entries in the dictionary corresponding to the GSAS-II tree and
+  indeed one entry is 'Controls'.
+  Command <tt>gpx.data['Controls'].keys()</tt> shows that all
   values are located in an entry labeled 'data' and
   <tt>gpx.data['Controls']['data'].keys()</tt> shows the entries in
 this section. Examination of
-<BR><tt>gpx.data['Controls']['data']['max cyc']</tt>shows the value 3,
+<tt>gpx.data['Controls']['data']['max cyc']</tt> shows the value 3,
 which is default number of cycles. Thus, 
-the number of cycles is changed with this Python command:
-
-<blockquote><textarea rows="3" cols="70" readonly>
-# not in tutorial: increase # of cycles to improve convergence
-gpx.data['Controls']['data']['max cyc'] = 8 # not in API </textarea></blockquote>
-
-</blockquote>
+the number of cycles is changed with the Python command above.
+
+</blockquote>
+
 <h4>5: Set initial variables and refine</H4>
 <blockquote>
@@ -196 +217 @@
 refinement flags are not turned on by default, so a dictionary must be
 created to set these histogram variables. This code:
+<blockquote><textarea rows="5" cols="75" readonly>
+# tutorial step 4: turn on background refinement (Hist)
+refdict0 = {"set": {"Background": { "no. coeffs": 3, "refine": True }}}
+gpx.save('step4.gpx')
+gpx.do_refinements([refdict0])
+HistStats(gpx)</textarea></blockquote>
 <UL>
 <LI>defines a dictionary (refdict0) that will be used to set the number of background coefficients (not really
@@ -216 +243 @@
 prints them. The function also writes the final refinement results
 into the current project file. </A>
-
-<blockquote><textarea rows="5" cols="75" readonly>
-# tutorial step 4: turn on background refinement (Hist)
-refdict0 = {"set": {"Background": { "no. coeffs": 3, "refine": True }}}
-gpx.save('step4.gpx')
-gpx.do_refinements([refdict0])
-HistStats(gpx)</textarea></blockquote>
 
 The output from this will be:<blockquote><pre>
@@ -249 +269 @@
 <tt>my_project.do_refinements()</tt>, as
 <A href="http://gsas-ii.readthedocs.io/en/latest/GSASIIscripts.html#refinement-parameters">
-described here</A>. The <tt>gpx.do_refinements([refdict0])</tt>
+described here</A>. Thus, the <tt>gpx.do_refinements([refdict0])</tt>
 statement above could be replaced with:
 <blockquote><pre>
@@ -295 +315 @@
 
 In Step 6 of the original tutorial, the refinement is performed again
-after adding Histogram/Phase (HAP) parameters that allow different
-lattice constants for the first histogram only.
+after adding Histogram/Phase (HAP) parameters so that the lattice
+constants for the first histogram (only) can vary. This is done with
+this code:
 
 <blockquote><textarea rows="6" cols="75" readonly>
@@ -306 +327 @@
 HistStats(gpx)</textarea></blockquote>
 
-Here we cannot use <tt>gpx.do_refinements([refdict2])</tt> because
-that would turn on refinement of the Hstrain terms for both histograms
-(if there were more than one phase, it would be all phases and all
-histograms), but in the above the <tt>gpx.set_refinement(...)</tt>
-statement alternately can be replaced with this:
+Here we cannot use <tt>gpx.do_refinements([refdict2])</tt> with
+<tt>refdict2</tt> defined as above because
+that would turn on refinement of the Hstrain terms for all histograms
+and all phases. There are several ways to restrict the parameter
+changes to specified histogram(s) and phase(s). One is to call a
+method in the phase object(s) directly, such as 
+replacing the <tt>gpx.set_refinement(...)</tt>
+statement with this:
 <blockquote><pre>
 phase0.set_HAP_refinements({"HStrain": True},histograms=[hist1])
 </pre></blockquote>
 
-</blockquote>
+It is also possible to add "histograms" and/or "phases" values into
+the <tt>refdict2</tt> dict, as will be <a href="#SingeStep">described below.</a>
+</blockquote>
+
 <h4>8: Add X-ray Sample broadening terms</h4>
 <blockquote>
@@ -328 +355 @@
 existing default. Again, since these parameters are being set only for
 one histogram, either <tt>phase0.set_HAP_refinements()</tt> or
-<tt>gpx.set_refinement()</tt> must be used. 
+<tt>gpx.set_refinement()</tt> must be called or to use
+<tt>gpx.do_refinements([refdict3])</tt> the "histograms" element must be
+included inside <tt>refdict3</tt>.
 
 <blockquote><textarea rows="8" cols="75" readonly>
 # tutorial step 7: add size & strain broadening (HAP) for histogram 1 only 
 gpx.save('step7.gpx')
-refdict2 = {"set": {"Mustrain": {"type":"isotropic","refine":True},
+refdict3 = {"set": {"Mustrain": {"type":"isotropic","refine":True},
                     "Size":{"type":"isotropic","refine":True},
                     }}
-gpx.set_refinement(refdict2,phase=phase0,histogram=[hist1])
+gpx.set_refinement(refdict3,phase=phase0,histogram=[hist1])
 gpx.do_refinements([{}]) # refine after setting
 HistStats(gpx)</textarea></blockquote>
@@ -348 +377 @@
 sample parameters using <tt>phase0.set_refinements()</tt> to set the
 "X" (coordinate) and "U" (displacement) refinement flags for all
-atoms. The original tutorial
-calls for the diffractometer radius to be changed. This parameter
-cannot be set from any GSASIIscriptable routines, but following a
-similar
-<A href="#ChangeCycles">process, as before</A>, the location for this
-setting can be located in the histogram's 'Sample Parameters' section
-(<tt>hist2.data['Sample Parameters']['Gonio. radius']</tt>).
+atoms. This is done with this code: 
 
 <blockquote><textarea rows="9" cols="75" readonly>
@@ -366 +389 @@
 HistStats(gpx)</textarea></blockquote>
 
-Note that the settings provided in the
-<tt>phase0.set_refinements()</tt> statement could have been done using
-the <tt>gpx.do_refinements()</tt> call, but not those in the
-<tt>hist</tt><I>X</I><tt>.set_refinements()</tt> calls, since they
-must be different for each histogram. 
+Note that the original tutorial
+calls for the diffractometer radius to be changed to the correct value
+so that the displacement value is in the correct units. This parameter
+cannot be set from any GSASIIscriptable routines, but following a
+similar process, 
+<A href="#ChangeCycles">as before</A>, the location for this
+setting can be located in the histogram's 'Sample Parameters' section
+(as <tt>hist2.data['Sample Parameters']['Gonio. radius']</tt>).
+
+Also note that the settings provided in the
+<tt>phase0.set_refinements()</tt> and statements
+<tt>gpx.do_refinements()</tt> could have
+been combined into this single statement:
+<blockquote><pre>
+gpx.do_refinements({"set":{"Atoms":{"all":"XU"}})
+</pre></blockquote>
 
 </blockquote>
@@ -402 +436 @@
 </pre></blockquote>
 
-
-</blockquote><hr>
+</blockquote>
+<a name="SingeStep"><h2>Single Step Approach</h2></a>
+<blockquote>
+
+As is noted in the
+<A href="http://gsas-ii.readthedocs.io/en/latest/GSASIIscripts.html" target="_blank">
+GSASIIscriptable module documentation</A>,
+the <I>project</i><tt>.do_refinements()</tt> method can be used to
+perform multiple refinement steps. To duplicate the above steps into a
+single call a more complex set of dicts must be created, as shown
+below: 
+
+<blockquote><textarea rows="39" cols="75" readonly>
+# tutorial step 4: turn on background refinement (Hist)
+refdict0 = {"set": {"Background": { "no. coeffs": 3, "refine": True }},
+            "output":'step4.gpx',
+            "call":HistStats,"callargs":[gpx]} # callargs actually unneeded
+                                               # as [gpx] is the default
+# tutorial step 5: add unit cell refinement (Phase)
+refdict1 = {"set": {"Cell": True},    # set the cell flag (for all phases)
+            "output":'step5.gpx', "call":HistStats}
+# tutorial step 6: add Dij terms (HAP) for phase 1 only
+refdict2 = {"set": {"HStrain": True},  # set HAP parameters
+            "histograms":[hist1],      # histogram 1 only
+            "phases":[phase0],         # unneeded (default is all
+                                       # phases) included as a example
+            "output":'step6.gpx', "call":HistStats}
+# tutorial step 7: add size & strain broadening (HAP) for histogram 1 only 
+refdict3 = {"set": {"Mustrain": {"type":"isotropic","refine":True},
+                    "Size":{"type":"isotropic","refine":True},},
+            "histograms":[hist1],      # histogram 1 only
+            "output":'step7.gpx', "call":HistStats}
+# tutorial step 8: add sample parameters & set radius (Hist); refine
+#                  atom parameters (phase)
+refdict4a = {"set": {'Sample Parameters': ['Shift']},
+            "histograms":[hist1],      # histogram 1 only
+             "skip": True}
+refdict4b = {"set": {"Atoms":{"all":"XU"}, # not affected by histograms
+             'Sample Parameters': ['DisplaceX', 'DisplaceY']},
+            "histograms":[hist2],      # histogram 2 only 
+            "output":'step8.gpx', "call":HistStats}
+# tutorial step 9: change data limits & inst. parm refinements (Hist) 
+refdict5a = {"set": {'Limits': [16.,158.4]},
+            "histograms":[hist1],      # histogram 1 only
+             "skip": True,}
+refdict5b = {"set": {'Limits': [19.,153.]},
+            "histograms":[hist2],      # histogram 2 only
+             "skip": True}
+refdict5c = {"set": {'Instrument Parameters': ['U', 'V', 'W']},
+            "output":'step9.gpx', "call":HistStats}
+</textarea></blockquote>
+
+Note that above the "call" and "callargs" dict entries are
+defined to run <tt>HistStats</tt> and "output" is used to designate
+the .gpx file that will be needed. When parameters should be changed
+in specific histograms, the entries <tt>"histograms":[hist1]</tt> and
+<tt>"histograms":[hist2]</tt> are used
+(equivalent would be <tt>"histograms":[0]</tt> and
+<tt>"histograms":[1]</tt>).
+Since there is only one phase present, use of <tt>"phase":[0]</tt> is
+superfluous, but in a more complex refinement, this could be needed. 
+<p>
+A list of dicts is then prepared here:
+<blockquote><textarea rows="3" cols="75" readonly>
+dictList = [refdict0,refdict1,refdict2,refdict3,
+            refdict4a,refdict4b,
+            refdict5a,refdict5b,refdict5c]
+</textarea></blockquote>
+Steps 4 through 10, above then can be performed with these few commands:
+<blockquote><textarea rows="4" cols="75" readonly>
+# Change number of cycles and radius
+gpx.data['Controls']['data']['max cyc'] = 8 # not in API
+hist2.data['Sample Parameters']['Gonio. radius'] = 650. # not in API
+gpx.do_refinements(dictList)
+</textarea></blockquote>
+
+</blockquote>
+
+<hr>
 <address></address>
-<!-- hhmts start -->Last modified: Thu Oct 12 10:45:51 CDT 2017 <!-- hhmts end -->
+<!-- hhmts start -->Last modified: Fri Dec 22 16:24:53 CST 2017 <!-- hhmts end -->
 </body> </html>