Context Navigation

source: trunk/docs/source/GSASIIscriptable.rst @ 5572

Last change on this file since 5572 was 5572, checked in by toby, 5 months ago
partial refactor of ReST comments for better formatting on ReadTheDocs?; more work needed for GSASIIGUI.rst & GSASIIstruc.rst
File size: 62.3 KB

Line
1	=======================================
2	GSASIIscriptable: Scripting Interface
3	=======================================
4
5
6	Summary/Contents
7	==================================================
8
9	Routines to use an increasing amount of GSAS-II's capabilities from scripts,
10	without use of the graphical user interface (GUI). GSASIIscriptable can create and access
11	GSAS-II project (.gpx) files and can directly perform image handling and refinements.
12	The module defines wrapper classes (inheriting from :class:`G2ObjectWrapper`) for a growing number
13	of data tree items.
14
15	GSASIIscriptable can be used in two ways. It offers a command-line mode, but
16	the more widely used and more powerful mode of GSASIIscriptable is
17	used is via Python scripts that
18	call the module's application interface (API), see API summary that follows or the :ref:`API`
19	section. The command-line mode
20	provides access a number of features without writing Python scripts
21	via shell/batch commands (see :ref:`CommandlineInterface`) but this
22	is no longer being developed and its use is discouraged.
23
24	.. contents:: Section Contents
25
26
27	Application Interface (API) Summary
28	==================================================
29	This section of the documentation provides an overview to API, with full documentation
30	in the :ref:`API` section. The typical API use will be with a Python script, such as
31	what is found in :ref:`CodeExamples`. Most functionality is provided via the objects and methods
32	summarized below.
33
34	Overview of Classes
35	---------------------
36
37	.. tabularcolumns:: \|l\|p{4in}\|
38
39	=============================== ===============================================================================================================
40	class Encapsulates
41	=============================== ===============================================================================================================
42	:class:`G2Project` A GSAS-II project file, provides references to objects below,
43	each corresponding to a tree item
44	(exception is :class:`G2AtomRecord`)
45	:class:`G2Phase` Provides phase information access
46	(also provides access to atom info via :class:`G2AtomRecord`)
47	:class:`G2AtomRecord` Access to an atom within a phase
48	:class:`G2PwdrData` Access to powder histogram info
49	:class:`G2Image` Access to image info
50	:class:`G2PDF` PDF histogram info
51	:class:`G2SeqRefRes` The sequential results table
52	=============================== ===============================================================================================================
53
54	Functions
55	---------------------
56
57	A small amount of the Scriptable code does not require use of objects.
58
59	.. tabularcolumns:: \|l\|p{4in}\|
60
61	================================================== ===============================================================================================================
62	method Use
63	================================================== ===============================================================================================================
64	:func:`GenerateReflections` Generates a list of unique powder reflections
65	:func:`SetPrintLevel` Sets the amout of output generated when running a script
66	================================================== ===============================================================================================================
67
68	Class :class:`G2Project`
69	---------------------------------
70
71	All GSASIIscriptable scripts will need to create a :class:`G2Project` object
72	either for a new GSAS-II project or to read in an existing project (.gpx) file.
73	The most commonly used routines in this object are:
74
75	.. tabularcolumns:: \|l\|p{3.in}\|
76
77	================================================== ===============================================================================================================
78	method Use
79	================================================== ===============================================================================================================
80	:meth:`G2Project.save` Writes the current project to disk.
81
82	:meth:`G2Project.add_powder_histogram` Used to read in powder diffraction data into a project file.
83
84	:meth:`G2Project.add_simulated_powder_histogram` Defines a "dummy" powder diffraction data that will be simulated after a refinement step.
85
86	:meth:`G2Project.add_image` Reads in an image into a project.
87
88	:meth:`G2Project.add_phase` Adds a phase to a project
89
90	:meth:`G2Project.add_PDF` Adds a PDF entry to a project (does not compute it)
91
92	:meth:`G2Project.histograms` Provides a list of histograms in the current project, as :class:`G2PwdrData` objects
93
94	:meth:`G2Project.phases` Provides a list of phases defined in the current project, as :class:`G2Phase` objects
95
96	:meth:`G2Project.images` Provides a list of images in the current project, as :class:`G2Image` objects
97
98	:meth:`G2Project.pdfs` Provides a list of PDFs in the current project, as :class:`G2PDF` objects
99
100	:meth:`G2Project.seqref` Returns a :class:`G2SeqRefRes` object if there are Sequential Refinement results
101
102	:meth:`G2Project.do_refinements` This is passed a list of dictionaries, where each dict defines a refinement step.
103	Passing a list with a single empty dict initiates a refinement with the current
104	parameters and flags. A refinement dict sets up a single refinement step
105	(as described in :ref:`Project_dicts`). Also see :ref:`Refinement_recipe`.
106
107	:meth:`G2Project.set_refinement` This is passed a single dict which is used to set parameters and flags.
108	These actions can be performed also in :meth:`G2Project.do_refinements`.
109	:meth:`G2Project.get_Variable` Retrieves the value and esd for a parameter
110	:meth:`G2Project.get_Covariance` Retrieves values and covariance for a set of refined parameters
111	:meth:`G2Project.set_Controls` Set overall GSAS-II control settings such as number of cycles and to set up a sequential
112	fit. (Also see :meth:`G2Project.get_Controls` to read values.)
113	:meth:`G2Project.imageMultiDistCalib` Performs a global calibration fit with images at multiple distance settings.
114	:meth:`G2Project.get_Constraints` Retrieves :ref:`constraint definition <Constraint_definitions_table>` entries.
115	:meth:`G2Project.add_HoldConstr` Adds a hold constraint on one or more variables
116	:meth:`G2Project.add_EquivConstr` Adds an equivalence constraint on two or more variables
117	:meth:`G2Project.add_EqnConstr` Adds an equation-type constraint on two or more variables
118	:meth:`G2Project.add_NewVarConstr` Adds an new variable as a constraint on two or more variables
119	================================================== ===============================================================================================================
120
121	Class :class:`G2Phase`
122	---------------------------------
123
124
125	Another common object in GSASIIscriptable scripts is :class:`G2Phase`, used to encapsulate each phase in a project, with commonly used methods:
126
127	.. tabularcolumns:: \|l\|p{3.5in}\|
128
129	================================================== ===============================================================================================================
130	method Use
131	================================================== ===============================================================================================================
132	:meth:`G2Phase.set_refinements` Provides a mechanism to set values and refinement flags for the phase. See :ref:`Phase_parameters_table`
133	for more details. This information also can be supplied within a call to :meth:`G2Project.do_refinements`
134	or :meth:`G2Project.set_refinement`.
135	:meth:`G2Phase.clear_refinements` Unsets refinement flags for the phase.
136	:meth:`G2Phase.set_HAP_refinements` Provides a mechanism to set values and refinement flags for parameters specific to both this phase and
137	one of its histograms. See :ref:`HAP_parameters_table`. This information also can be supplied within
138	a call to :meth:`G2Project.do_refinements` or :meth:`G2Project.set_refinement`.
139	:meth:`G2Phase.clear_HAP_refinements` Clears refinement flags specific to both this phase and one of its histograms.
140	:meth:`G2Phase.getHAPvalues` Returns values of parameters specific to both this phase and one of its histograms.
141	:meth:`G2Phase.copyHAPvalues` Copies HAP settings between from one phase/histogram and to other histograms in same phase.
142	:meth:`G2Phase.atoms` Returns a list of atoms in the phase
143	:meth:`G2Phase.atom` Returns an atom from its label
144	:meth:`G2Phase.histograms` Returns a list of histograms linked to the phase
145	:meth:`G2Phase.get_cell` Returns unit cell parameters (also see :meth:`G2Phase.get_cell_and_esd`)
146	:meth:`G2Phase.export_CIF` Writes a CIF for the phase
147	:meth:`G2Phase.setSampleProfile` Sets sample broadening parameters
148	:meth:`G2Phase.clearDistRestraint` Clears any previously defined bond distance restraint(s) for the selected phase
149	:meth:`G2Phase.addDistRestraint` Finds and defines new bond distance restraint(s) for the selected phase
150	:meth:`G2Phase.setDistRestraintWeight` Sets the weighting factor for the bond distance restraints
151
152	================================================== ===============================================================================================================
153
154	Class :class:`G2PwdrData`
155	---------------------------------
156
157	Another common object in GSASIIscriptable scripts is :class:`G2PwdrData`, which encapsulate each powder diffraction histogram in a project, with commonly used methods:
158
159	.. tabularcolumns:: \|l\|p{3.5in}\|
160
161	================================================== ===============================================================================================================
162	method Use
163	================================================== ===============================================================================================================
164	:meth:`G2PwdrData.set_refinements` Provides a mechanism to set values and refinement flags for the powder histogram. See
165	:ref:`Histogram_parameters_table` for details.
166	:meth:`G2PwdrData.clear_refinements` Unsets refinement flags for the the powder histogram.
167	:meth:`G2PwdrData.residuals` Reports R-factors etc. for the the powder histogram (also see :meth:`G2PwdrData.get_wR`)
168	:meth:`G2PwdrData.add_back_peak` Adds a background peak to the histogram. Also see :meth:`G2PwdrData.del_back_peak` and
169	:meth:`G2PwdrData.ref_back_peak`.
170	:meth:`G2PwdrData.fit_fixed_points` Fits background to the specified fixed points.
171	:meth:`G2PwdrData.getdata` Provides access to the diffraction data associated with the histogram.
172	:meth:`G2PwdrData.reflections` Provides access to the reflection lists for the histogram.
173	:meth:`G2PwdrData.Export` Writes the diffraction data or reflection list into a file
174	:meth:`G2PwdrData.add_peak` Adds a peak to the peak list. Also see :ref:`PeakRefine`.
175	:meth:`G2PwdrData.set_peakFlags` Sets refinement flags for peaks
176	:meth:`G2PwdrData.refine_peaks` Starts a peak/background fitting cycle, returns refinement results
177	:attr:`G2PwdrData.Peaks` Provides access to the peak list data structure
178	:attr:`G2PwdrData.PeakList` Provides the peak list parameter values
179	:meth:`G2PwdrData.Export_peaks` Writes the peak parameters to a text file
180	:meth:`G2PwdrData.set_background` Sets a background histogram that will be subtracted (point by point) from the current histogram.
181	================================================== ===============================================================================================================
182
183	Class :class:`G2Image`
184	---------------------------------
185
186	When working with images, there will be a :class:`G2Image` object for each image (also see :meth:`G2Project.add_image` and :meth:`G2Project.images`).
187
188	.. tabularcolumns:: \|l\|p{3.5in}\|
189
190	================================================== ===============================================================================================================
191	method Use
192	================================================== ===============================================================================================================
193	:meth:`G2Image.Recalibrate` Invokes a recalibration fit starting from the current Image Controls calibration coefficients.
194	:meth:`G2Image.Integrate` Invokes an image integration All parameters Image Controls will have previously been set.
195	:meth:`G2Image.setControl` Set an Image Controls parameter in the current image.
196	:meth:`G2Image.getControl` Return an Image Controls parameter in the current image.
197	:meth:`G2Image.findControl` Get the names of Image Controls parameters.
198	:meth:`G2Image.loadControls` Load controls from a .imctrl file (also see :meth:`G2Image.saveControls`).
199	:meth:`G2Image.loadMasks` Load masks from a .immask file.
200	:meth:`G2Image.setVary` Set a refinement flag for Image Controls parameter in the current image. (Also see :meth:`G2Image.getVary`)
201	:meth:`G2Image.setCalibrant` Set a calibrant type (or show choices) for the current image.
202	:meth:`G2Image.setControlFile` Set a image to be used as a background/dark/gain map image.
203	================================================== ===============================================================================================================
204
205
206	Class :class:`G2PDF`
207	---------------------------------
208
209	To work with PDF entries, object :class:`G2PDF`, encapsulates a PDF entry with methods:
210
211	.. tabularcolumns:: \|l\|p{3.5in}\|
212
213	================================================== ===============================================================================================================
214	method Use
215	================================================== ===============================================================================================================
216	:meth:`G2PDF.export` Used to write G(r), etc. as a file
217	:meth:`G2PDF.calculate` Computes the PDF using parameters in the object
218	:meth:`G2PDF.optimize` Optimizes selected PDF parameters
219	:meth:`G2PDF.set_background` Sets the histograms used for sample background, container, etc.
220	:meth:`G2PDF.set_formula` Sets the chemical formula for the sample
221	================================================== ===============================================================================================================
222
223	Class :class:`G2SeqRefRes`
224	---------------------------------
225
226	To work with Sequential Refinement results, object :class:`G2SeqRefRes`, encapsulates the sequential refinement table with methods:
227
228	.. tabularcolumns:: \|l\|p{3.5in}\|
229
230	================================================== ===============================================================================================================
231	method Use
232	================================================== ===============================================================================================================
233	:meth:`G2SeqRefRes.histograms` Provides a list of histograms used in the Sequential Refinement
234	:meth:`G2SeqRefRes.get_cell_and_esd` Returns cell dimensions and standard uncertainies for a phase and histogram from the Sequential Refinement
235	:meth:`G2SeqRefRes.get_Variable` Retrieves the value and esd for a parameter from a particular histogram in the Sequential Refinement
236	:meth:`G2SeqRefRes.get_Covariance` Retrieves values and covariance for a set of refined parameters for a particular histogram
237	================================================== ===============================================================================================================
238
239	Class :class:`G2AtomRecord`
240	---------------------------------
241
242	When working with phases, :class:`G2AtomRecord` objects provide access to the contents of each atom in a phase. This provides access to "properties" that can be
243	used to get values of much of the atoms associated settings: label, type, refinement_flags, coordinates, occupancy, ranId, adp_flag, and uiso. In addition,
244	refinement_flags, occupancy and uiso can be used to set values. See the :class:`G2AtomRecord` docs and source code.
245
246	.. _Refinement_dicts:
247
248
249	Refinement parameters
250	=====================
251	While scripts can be written that setup refinements by changing individual parameters
252	through calls to the methods associated with objects that wrap each data tree item,
253	many of these actions can be combined into fairly complex dict structures to conduct refinement
254	steps. Use of these dicts is required with the :ref:`CommandlineInterface`. This section of the
255	documentation describes these dicts.
256
257	.. _Project_dicts:
258
259	Project-level Parameter Dict
260	-----------------------------
261
262	As noted below (:ref:`Refinement_parameters_kinds`), there are three types of refinement parameters,
263	which can be accessed individually by the objects that encapsulate individual phases and histograms
264	but it will often be simplest to create a composite dictionary
265	that is used at the project-level. A dict is created with keys
266	"set" and "clear" that can be supplied to :meth:`G2Project.set_refinement`
267	(or :meth:`G2Project.do_refinements`, see :ref:`Refinement_recipe` below) that will
268	determine parameter values and will determine which parameters will be refined.
269
270	The specific keys and subkeys that can be used are defined in tables
271	:ref:`Histogram_parameters_table`, :ref:`Phase_parameters_table` and :ref:`HAP_parameters_table`.
272
273	Note that optionally a list of histograms and/or phases can be supplied in the call to
274	:meth:`G2Project.set_refinement`, but if not specified, the default is to use all defined
275	phases and histograms.
276
277	As an example:
278
279	.. code-block:: python
280
281	pardict = {'set': { 'Limits': [0.8, 12.0],
282	'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
283	'Background': {'type': 'chebyschev-1', 'refine': True,
284	'peaks':[[0,True],[1,1,1]] }},
285	'clear': {'Instrument Parameters': ['U', 'V', 'W']}}
286	my_project.set_refinement(pardict)
287
288	.. _Refinement_recipe:
289
290	Refinement recipe
291	------------------------
292
293	Building on the :ref:`Project_dicts`,
294	it is possible to specify a sequence of refinement actions as a list of
295	these dicts and supplying this list
296	as an argument to :meth:`G2Project.do_refinements`.
297
298	As an example, this code performs the same actions as in the example in the section above:
299
300	.. code-block:: python
301
302	pardict = {'set': { 'Limits': [0.8, 12.0],
303	'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
304	'Background': {'type': 'chebyschev-1', 'refine': True}},
305	'clear': {'Instrument Parameters': ['U', 'V', 'W']}}
306	my_project.do_refinements([pardict])
307
308	However, in addition to setting a number of parameters, this example will perform a refinement as well,
309	after setting the parameters. More than one refinement can be performed by including more
310	than one dict in the list.
311
312	In this example, two refinement steps will be performed:
313
314	.. code-block:: python
315
316	my_project.do_refinements([pardict,pardict1])
317
318
319	The keys defined in the following table
320	may be used in a dict supplied to :meth:`G2Project.do_refinements`. Note that keys ``histograms``
321	and ``phases`` are used to limit actions to specific sets of parameters within the project.
322
323	.. tabularcolumns:: \|l\|p{4in}\|
324
325	========== ============================================================================
326	key explanation
327	========== ============================================================================
328	set Specifies a dict with keys and subkeys as described in the
329	:ref:`Refinement_parameters_fmt` section. Items listed here
330	will be set to be refined.
331	clear Specifies a dict, as above for set, except that parameters are
332	cleared and thus will not be refined.
333	once Specifies a dict as above for set, except that parameters are
334	set for the next cycle of refinement and are cleared once the
335	refinement step is completed.
336	skip Normally, once parameters are processed with a set/clear/once
337	action(s), a refinement is started. If skip is defined as True
338	(or any other value) the refinement step is not performed.
339	output If a file name is specified for output is will be used to save
340	the current refinement.
341	histograms Should contain a list of histogram(s) to be used for the
342	set/clear/once action(s) on :ref:`Histogram_parameters_table` or
343	:ref:`HAP_parameters_table`. Note that this will be
344	ignored for :ref:`Phase_parameters_table`. Histograms may be
345	specified as a list of strings [('PWDR ...'),...], indices
346	[0,1,2] or as list of objects [hist1, hist2].
347	phases Should contain a list of phase(s) to be used for the
348	set/clear/once action(s) on :ref:`Phase_parameters_table` or
349	:ref:`HAP_parameters_table`. Note that this will be
350	ignored for :ref:`Histogram_parameters_table`.
351	Phases may be specified as a list of strings
352	[('Phase name'),...], indices [0,1,2] or as list of objects
353	[phase0, phase2].
354	call Specifies a function to call after a refinement is completed.
355	The value supplied can be the object (typically a function)
356	that will be called or a string that will evaluate (in the
357	namespace inside :meth:`G2Project.iter_refinements` where
358	``self`` references the project.)
359	Nothing is called if this is not specified.
360	callargs Provides a list of arguments that will be passed to the function
361	in call (if any). If call is defined and callargs is not, the
362	current <tt>G2Project</tt> is passed as a single argument.
363	========== ============================================================================
364
365	An example that performs a series of refinement steps follows:
366
367	.. code-block:: python
368
369	reflist = [
370	{"set": { "Limits": { "low": 0.7 },
371	"Background": { "no. coeffs": 3,
372	"refine": True }}},
373	{"set": { "LeBail": True,
374	"Cell": True }},
375	{"set": { "Sample Parameters": ["DisplaceX"]}},
376	{"set": { "Instrument Parameters": ["U", "V", "W", "X", "Y"]}},
377	{"set": { "Mustrain": { "type": "uniaxial",
378	"refine": "equatorial",
379	"direction": [0, 0, 1]}}},
380	{"set": { "Mustrain": { "type": "uniaxial",
381	"refine": "axial"}}},
382	{"clear": { "LeBail": True},
383	"set": { "Atoms": { "Mn": "X" }}},
384	{"set": { "Atoms": { "O1": "X", "O2": "X" }}},]
385	my_project.do_refinements(reflist)
386
387
388	In this example, a separate refinement step will be performed for each dict in the list. The keyword
389	"skip" can be used to specify a dict that should not include a refinement.
390	Note that in the second from last refinement step, parameters are both set and cleared.
391
392	.. _Refinement_parameters_kinds:
393
394	Refinement parameter types
395	----------------------------
396
397	Note that parameters and refinement flags used in GSAS-II fall into three classes:
398
399	* Histogram: There will be a set of these for each dataset loaded into a
400	project file. The parameters available depend on the type of histogram
401	(Bragg-Brentano, Single-Crystal, TOF,...). Typical Histogram parameters
402	include the overall scale factor, background, instrument and sample parameters;
403	see the :ref:`Histogram_parameters_table` table for a list of the histogram
404	parameters where access has been provided.
405
406	* Phase: There will be a set of these for each phase loaded into a
407	project file. While some parameters are found in all types of phases,
408	others are only found in certain types (modulated, magnetic, protein...).
409	Typical phase parameters include unit cell lengths and atomic positions; see the
410	:ref:`Phase_parameters_table` table for a list of the phase
411	parameters where access has been provided.
412
413	* Histogram-and-phase (HAP): There is a set of these for every histogram
414	that is associated with each phase, so that if there are ``N`` phases and ``M``
415	histograms, there can be ``N*M`` total sets of "HAP" parameters sets (fewer if all
416	histograms are not linked to all phases.) Typical HAP parameters include the
417	phase fractions, sample microstrain and crystallite size broadening terms,
418	hydrostatic strain perturbations of the unit cell and preferred orientation
419	values.
420	See the :ref:`HAP_parameters_table` table for the HAP parameters where access has
421	been provided.
422
423	.. _Refinement_parameters_fmt:
424
425
426	Specifying Refinement Parameters
427	=================================
428
429	Refinement parameter values and flags to turn refinement on and off are specified within dictionaries,
430	where the details of these dicts are organized depends on the
431	type of parameter (see :ref:`Refinement_parameters_kinds`), with a different set
432	of keys (as described below) for each of the three types of parameters.
433
434	.. _Histogram_parameters_table:
435
436	Histogram parameters
437	--------------------
438
439	This table describes the dictionaries supplied to :func:`G2PwdrData.set_refinements`
440	and :func:`G2PwdrData.clear_refinements`. As an example,
441
442	.. code-block:: python
443
444	hist.set_refinements({"Background": {"no.coeffs": 3, "refine": True},
445	"Sample Parameters": ["Scale"],
446	"Limits": [10000, 40000]})
447
448	With :meth:`G2Project.do_refinements`, these parameters should be placed inside a dict with a key
449	``set``, ``clear``, or ``once``. Values will be set for all histograms, unless the ``histograms``
450	key is used to define specific histograms. As an example:
451
452	.. code-block:: python
453
454	gsas_proj.do_refinements([
455	{'set': {
456	'Background': {'no.coeffs': 3, 'refine': True},
457	'Sample Parameters': ['Scale'],
458	'Limits': [10000, 40000]},
459	'histograms': [1,2]}
460	])
461
462	Note that below in the Instrument Parameters section,
463	related profile parameters (such as U and V) are grouped together but
464	separated by commas to save space in the table.
465
466	.. tabularcolumns:: \|l\|l\|p{3.5in}\|
467
468	===================== ==================== =================================================
469	key subkey explanation
470	===================== ==================== =================================================
471	Limits The range of 2-theta (degrees) or TOF (in
472	microsec) range of values to use. Can
473	be either a dictionary of 'low' and/or 'high',
474	or a list of 2 items [low, high]
475	\ low Sets the low limit
476	\ high Sets the high limit
477
478	Sample Parameters Should be provided as a list of subkeys
479	to set or clear,\e.g. ['DisplaceX', 'Scale']
480	\ Absorption
481	\ Contrast
482	\ DisplaceX Sample displacement along the X direction
483	\ DisplaceY Sample displacement along the Y direction
484	\ Scale Histogram Scale factor
485
486	Background Sample background. Value will be a dict or
487	a boolean. If True or False, the refine
488	parameter for background is set to that.
489	Note that background peaks are not handled
490	via this; see
491	:meth:`G2PwdrData.ref_back_peak` instead.
492	When value is a dict,
493	supply any of the following keys:
494	\ type The background model, e.g. 'chebyschev-1'
495	\ refine The value of the refine flag, boolean
496	\ 'no. coeffs' Number of coefficients to use, integer
497	\ coeffs List of floats, literal values for background
498	\ FixedPoints List of (2-theta, intensity) values for fixed points
499	\ 'fit fixed points' If True, triggers a fit to the fixed points to
500	be calculated. It is calculated when this key is
501	detected, regardless of calls to refine.
502	\ peaks Specifies a set of flags for refining
503	background peaks as a nested list. There may
504	be an item for each defined background peak
505	(or fewer) and each item is a list with the flag
506	values for pos,int,sig & gam (fewer than 4 values
507	are allowed).
508
509	Instrument Parameters As in Sample Paramters, provide as a list of
510	subkeys to
511	set or clear, e.g. ['X', 'Y', 'Zero', 'SH/L']
512	\ U, V, W Gaussian peak profile terms
513	\ X, Y, Z Lorentzian peak profile terms
514	\ alpha, beta-0, TOF profile terms
515	beta-1, beta-q,
516	\ sig-0, sig-1, TOF profile terms
517	sig-2, sig-q
518	\ difA, difB, difC TOF Calibration constants
519	\ Zero Zero shift
520	\ SH/L Finger-Cox-Jephcoat low-angle peak asymmetry
521	\ Polariz. Polarization parameter
522	\ Lam Lambda, the incident wavelength
523	===================== ==================== =================================================
524
525	.. _Phase_parameters_table:
526
527	Phase parameters
528	----------------
529
530	This table describes the dictionaries supplied to :func:`G2Phase.set_refinements`
531	and :func:`G2Phase.clear_refinements`. With :meth:`G2Project.do_refinements`,
532	these parameters should be placed inside a dict with a key
533	``set``, ``clear``, or ``once``. Values will be set for all phases, unless the ``phases``
534	key is used to define specific phase(s).
535
536
537	.. tabularcolumns:: \|l\|p{4.5in}\|
538
539	======= ==========================================================
540	key explanation
541	======= ==========================================================
542	Cell Whether or not to refine the unit cell.
543	Atoms Dictionary of atoms and refinement flags.
544	Each key should be an atom label, e.g.
545	'O3', 'Mn5', and each value should be
546	a string defining what values to refine.
547	Values can be any combination of 'F'
548	for site fraction, 'X' for position,
549	and 'U' for Debye-Waller factor
550	LeBail Enables LeBail intensity extraction.
551	======= ==========================================================
552
553
554	.. _HAP_parameters_table:
555
556
557	Histogram-and-phase parameters
558	------------------------------
559
560	This table describes the dictionaries supplied to :func:`G2Phase.set_HAP_refinements`
561	and :func:`G2Phase.clear_HAP_refinements`. When supplied to
562	:meth:`G2Project.do_refinements`, these parameters should be placed inside a dict with a key
563	``set``, ``clear``, or ``once``. Values will be set for all histograms used in each phase,
564	unless the ``histograms`` and ``phases`` keys are used to define specific phases and histograms.
565
566	.. tabularcolumns:: \|l\|l\|p{3.5in}\|
567
568	============= ========== ============================================================
569	key subkey explanation
570	============= ========== ============================================================
571	Babinet Should be a list of the following
572	subkeys. If not, assumes both
573	BabA and BabU
574	\ BabA
575	\ BabU
576	Extinction Boolean, True to refine.
577	HStrain Boolean or list/tuple, True to refine all
578	appropriate D\ :sub:`ij` terms or False
579	to not refine any. If a list/tuple, will
580	be a set of True & False values for each
581	D\ :sub:`ij` term; number of items must
582	match number of terms.
583	Mustrain
584	\ type Mustrain model. One of 'isotropic',
585	'uniaxial', or 'generalized'. **Should always
586	be included when Mustrain is used.**
587	\ direction For uniaxial only. A list of three
588	integers,
589	the [hkl] direction of the axis.
590	\ refine Usually boolean, set to True to refine.
591	or False to clear.
592	For uniaxial model, can specify a value
593	of 'axial' or 'equatorial' to set that flag
594	to True or a single
595	boolean sets both axial and equatorial.
596	Size
597	\ type Size broadening model. One of 'isotropic',
598	'uniaxial', or 'ellipsoid'. **Should always
599	be specified when Size is used.**
600	\ direction For uniaxial only. A list of three
601	integers,
602	the [hkl] direction of the axis.
603	\ refine Boolean, True to refine.
604	\ value float, size value in microns
605	Pref.Ori. Boolean, True to refine
606	Show Boolean, True to refine
607	Use Boolean, True to refine
608	Scale Phase fraction; Boolean, True to refine
609	============= ========== ============================================================
610
611	Histogram/Phase objects
612	------------------------
613	Each phase and powder histogram in a :class:`G2Project` object has an associated
614	object. Parameters within each individual object can be turned on and off by calling
615	:meth:`G2PwdrData.set_refinements` or :meth:`G2PwdrData.clear_refinements`
616	for histogram parameters;
617	:meth:`G2Phase.set_refinements` or :meth:`G2Phase.clear_refinements`
618	for phase parameters; and :meth:`G2Phase.set_HAP_refinements` or
619	:meth:`G2Phase.clear_HAP_refinements`. As an example, if some_histogram is a histogram object (of type :class:`G2PwdrData`), use this to set parameters in that histogram:
620
621	.. code-block:: python
622
623	params = { 'Limits': [0.8, 12.0],
624	'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
625	'Background': {'type': 'chebyschev-1', 'refine': True}}
626	some_histogram.set_refinements(params)
627
628	Likewise to turn refinement flags on, use code such as this:
629
630	.. code-block:: python
631
632	params = { 'Instrument Parameters': ['U', 'V', 'W']}
633	some_histogram.set_refinements(params)
634
635	and to turn these refinement flags, off use this (Note that the
636	``.clear_refinements()`` methods will usually will turn off refinement even
637	if a refinement parameter is set in the dict to True.):
638
639	.. code-block:: python
640
641	params = { 'Instrument Parameters': ['U', 'V', 'W']}
642	some_histogram.clear_refinements(params)
643
644	For phase parameters, use code such as this:
645
646	.. code-block:: python
647
648	params = { 'LeBail': True, 'Cell': True,
649	'Atoms': { 'Mn1': 'X',
650	'O3': 'XU',
651	'V4': 'FXU'}}
652	some_histogram.set_refinements(params)
653
654	and here is an example for HAP parameters:
655
656	.. code-block:: python
657
658	params = { 'Babinet': 'BabA',
659	'Extinction': True,
660	'Mustrain': { 'type': 'uniaxial',
661	'direction': [0, 0, 1],
662	'refine': True}}
663	some_phase.set_HAP_refinements(params)
664
665	Note that the parameters must match the object type and method (phase vs. histogram vs. HAP).
666
667	.. _AccessingOtherItems:
668
669	Access to other parameter settings
670	===================================
671
672	There are several hundred different types of values that can be stored in a
673	GSAS-II project (.gpx) file. All can be changed from the GUI but only a
674	subset have direct mechanism implemented for change from the GSASIIscriptable
675	API. In practice all parameters in a .gpx file can be edited via scripting,
676	but sometimes determining what should be set to implement a parameter
677	change can be complex.
678	Several routines, :meth:`G2Phase.getHAPentryList`,
679	:meth:`G2Phase.getPhaseEntryList` and :meth:`G2PwdrData.getHistEntryList`
680	(and their related get...Value and set.Value entries),
681	provide a mechanism to discover what the GUI is changing inside a .gpx file.
682
683	As an example, a user in changing the data type for a histogram from Debye-Scherrer
684	mode to Bragg-Brentano. This capability is not directly exposed in the API. To
685	find out what changes when the histogram type is changed we can create a short script
686	that displays the contents of all the histogram settings:
687
688	.. code-block:: python
689
690	from __future__ import division, print_function
691	import os,sys
692	sys.path.insert(0,'/Users/toby/software/G2/GSASII')
693	import GSASIIscriptable as G2sc
694	gpx = G2sc.G2Project('/tmp/test.gpx')
695	h = gpx.histograms()[0]
696	for h in h.getHistEntryList():
697	print(h)
698
699	This can be run with a command like this::
700
701	python test.py > before.txt
702
703	(This will create file ``before.txt``, which will contain hundreds of lines.)
704
705	At this point open the project file, ``test.gpx`` in the GSAS-II GUI and
706	change in Histogram/Sample Parameters the diffractometer type from Debye-Scherrer
707	mode to Bragg-Brentano and then save the file.
708
709	Rerun the previous script creating a new file::
710
711	python test.py > after.txt
712
713	Finally look for the differences between files ``before.txt`` and ``after.txt`` using a tool
714	such as diff (on Linux/OS X) or fc (in Windows).
715
716	in Windows::
717
718	Z:\>fc before.txt after.txt
719	Comparing files before.txt and after.txt
720	***** before.txt
721	fill_value = 1e+20)
722	, 'PWDR Co_PCP_Act_d900-00030.fxye Bank 1', 'PWDR Co_PCP_Act_d900-00030.fxye Ban
723	k 1'])
724	(['Comments'], <class 'list'>, ['Co_PCP_Act_d900-00030.tif #0001 Azm= 180.00'])
725	***** AFTER.TXT
726	fill_value = 1e+20)
727	, 'PWDR Co_PCP_Act_d900-00030.fxye Bank 1', 'PWDR Co_PCP_Act_d900-00030.fxye Ban
728	k 1', 'PWDR Co_PCP_Act_d900-00030.fxye Bank 1']
729
730	(['Comments'], <class 'list'>, ['Co_PCP_Act_d900-00030.tif #0001 Azm= 180.00'])
731	*****
732
733	***** before.txt
734	(['Sample Parameters', 'Scale'], <class 'list'>, [1.276313196832068, True])
735	(['Sample Parameters', 'Type'], <class 'str'>, 'Debye-Scherrer')
736	(['Sample Parameters', 'Absorption'], <class 'list'>, [0.0, False])
737	***** AFTER.TXT
738	(['Sample Parameters', 'Scale'], <class 'list'>, [1.276313196832068, True])
739	(['Sample Parameters', 'Type'], <class 'str'>, 'Bragg-Brentano')
740	(['Sample Parameters', 'Absorption'], <class 'list'>, [0.0, False])
741	*****
742
743	in Linux/Mac::
744
745	bht14: toby$ diff before.txt after.txt
746	103c103
747	< , 'PWDR Co_PCP_Act_d900-00030.fxye Bank 1', 'PWDR Co_PCP_Act_d900-00030.fxye Bank 1'])
748	---
749	> , 'PWDR Co_PCP_Act_d900-00030.fxye Bank 1', 'PWDR Co_PCP_Act_d900-00030.fxye Bank 1', 'PWDR Co_PCP_Act_d900-00030.fxye Bank 1'])
750	111c111
751	< (['Sample Parameters', 'Type'], <class 'str'>, 'Debye-Scherrer')
752	---
753	> (['Sample Parameters', 'Type'], <class 'str'>, 'Bragg-Brentano')
754
755	From this we can see there are two changes that took place. One is fairly obscure,
756	where the histogram name is added to a list, which can be ignored, but the second change
757	occurs in a straight-forward way and we discover that a simple call::
758
759	h.setHistEntryValue(['Sample Parameters', 'Type'], 'Bragg-Brentano')
760
761	can be used to change the histogram type.
762
763	.. _CodeExamples:
764
765	Code Examples
766	=================================
767
768	.. _PeakRefine:
769
770	Peak Fitting
771	--------------------
772
773	Peak refinement is performed with routines
774	:meth:`G2PwdrData.add_peak`, :meth:`G2PwdrData.set_peakFlags` and
775	:meth:`G2PwdrData.refine_peaks`. Method :meth:`G2PwdrData.Export_peaks` and
776	properties :attr:`G2PwdrData.Peaks` and :attr:`G2PwdrData.PeakList`
777	provide ways to access the results. Note that when peak parameters are
778	refined with :meth:`~G2PwdrData.refine_peaks`, the background may also
779	be refined. Use :meth:`G2PwdrData.set_refinements` to change background
780	settings and the range of data used in the fit. See below for an example
781	peak refinement script, where the data files are taken from the
782	"Rietveld refinement with CuKa lab Bragg-Brentano powder data" tutorial
783	(in https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/LabData/data/).
784
785	.. code-block:: python
786
787	from __future__ import division, print_function
788	import os,sys
789	sys.path.insert(0,'/Users/toby/software/G2/GSASII') # needed to "find" GSAS-II modules
790	import GSASIIscriptable as G2sc
791	datadir = os.path.expanduser("~/Scratch/peakfit")
792	PathWrap = lambda fil: os.path.join(datadir,fil)
793	gpx = G2sc.G2Project(newgpx=PathWrap('pkfit.gpx'))
794	hist = gpx.add_powder_histogram(PathWrap('FAP.XRA'), PathWrap('INST_XRY.PRM'),
795	fmthint='GSAS powder')
796	hist.set_refinements({'Limits': [16.,24.],
797	'Background': {"no. coeffs": 2,'type': 'chebyschev-1', 'refine': True}
798	})
799	peak1 = hist.add_peak(1, ttheta=16.8)
800	peak2 = hist.add_peak(1, ttheta=18.9)
801	peak3 = hist.add_peak(1, ttheta=21.8)
802	peak4 = hist.add_peak(1, ttheta=22.9)
803	hist.set_peakFlags(area=True)
804	hist.refine_peaks()
805	hist.set_peakFlags(area=True,pos=True)
806	hist.refine_peaks()
807	hist.set_peakFlags(area=True, pos=True, sig=True, gam=True)
808	res = hist.refine_peaks()
809	print('peak positions: ',[i[0] for i in hist.PeakList])
810	for i in range(len(hist.Peaks['peaks'])):
811	print('peak',i,'pos=',hist.Peaks['peaks'][i][0],'sig=',hist.Peaks['sigDict']['pos'+str(i)])
812	hist.Export_peaks('pkfit.txt')
813	#gpx.save() # gpx file is not written without this
814
815	Pattern Simulation
816	-----------------------
817
818	This shows two examples where a structure is read from a CIF, a
819	pattern is computed using a instrument parameter file to specify the
820	probe type (neutrons here) and wavelength.
821
822	The first example uses a CW neutron instrument parameter file.
823	The pattern is computed over a 2Îž range of 5 to 120 degrees
824	with 1000 points.
825	The pattern and reflection list are written into files.
826	Data files are found in the
827	`Scripting Tutorial <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/PythonScript/data/>`_.
828
829	.. code-block:: python
830
831	import os,sys
832	sys.path.insert(0,'/Users/toby/software/G2/GSASII')
833	import GSASIIscriptable as G2sc
834	datadir = "/Users/toby/software/G2/Tutorials/PythonScript/data"
835	PathWrap = lambda fil: os.path.join(datadir,fil)
836	gpx = G2sc.G2Project(newgpx='PbSO4sim.gpx') # create a project
837	phase0 = gpx.add_phase(PathWrap("PbSO4-Wyckoff.cif"),
838	phasename="PbSO4",fmthint='CIF') # add a phase to the project
839	# add a simulated histogram and link it to the previous phase(s)
840	hist1 = gpx.add_simulated_powder_histogram("PbSO4 simulation",
841	PathWrap("inst_d1a.prm"),5.,120.,Npoints=1000,
842	phases=gpx.phases(),scale=500000.)
843	gpx.do_refinements() # calculate pattern
844	gpx.save()
845	# save results
846	gpx.histogram(0).Export('PbSO4data','.csv','hist') # data
847	gpx.histogram(0).Export('PbSO4refl','.csv','refl') # reflections
848
849	This example uses bank#2 from a TOF neutron instrument parameter file.
850	The pattern is computed over a TOF range of 14 to 35 milliseconds with
851	the default of 2500 points.
852	This uses the same CIF as in the example before, but the instrument is found in the
853	`TOF-CW Joint Refinement Tutorial <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/TOF-CW Joint Refinement/data>`_
854	tutorial.
855
856	.. code-block:: python
857
858	import os,sys
859	sys.path.insert(0,'/Users/toby/software/G2/GSASII')
860	import GSASIIscriptable as G2sc
861	cifdir = "/Users/toby/software/G2/Tutorials/PythonScript/data"
862	datadir = "/Users/toby/software/G2/Tutorials/TOF-CW Joint Refinement/data"
863	gpx = G2sc.G2Project(newgpx='/tmp/PbSO4simT.gpx') # create a project
864	phase0 = gpx.add_phase(os.path.join(cifdir,"PbSO4-Wyckoff.cif"),
865	phasename="PbSO4",fmthint='CIF') # add a phase to the project
866	hist1 = gpx.add_simulated_powder_histogram("PbSO4 simulation",
867	os.path.join(datadir,"POWGEN_1066.instprm"),14.,35.,
868	phases=gpx.phases(),ibank=2)
869	gpx.do_refinements([{}])
870	gpx.save()
871
872	Simple Refinement
873	----------------------
874
875	GSASIIscriptable can be used to setup and perform simple refinements.
876	This example reads in an existing project (.gpx) file, adds a background
877	peak, changes some refinement flags and performs a refinement.
878
879	.. code-block:: python
880
881	from __future__ import division, print_function
882	import os,sys
883	sys.path.insert(0,'/Users/toby/software/G2/GSASII') # needed to "find" GSAS-II modules
884	import GSASIIscriptable as G2sc
885	datadir = "/Users/Scratch/"
886	gpx = G2sc.G2Project(os.path.join(datadir,'test2.gpx'))
887	gpx.histogram(0).add_back_peak(4.5,30000,5000,0)
888	pardict = {'set': {'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
889	'Background': {'type': 'chebyschev-1', 'refine': True,
890	'peaks':[[0,True]]}}}
891	gpx.set_refinement(pardict)
892
893	Sequential Refinement
894	----------------------
895
896	GSASIIscriptable can be used to setup and perform sequential refinements. This example script
897	is used to take the single-dataset fit at the end of Step 1 of the
898	`Sequential Refinement tutorial <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/SeqRefine/SequentialTutorial.htm>`_
899	and turn on and off refinement flags, add histograms and setup the sequential fit, which is then run:
900
901	.. code-block:: python
902
903	import os,sys,glob
904	sys.path.insert(0,'/Users/toby/software/G2/GSASII')
905	import GSASIIscriptable as G2sc
906	datadir = os.path.expanduser("~/Scratch/SeqTut2019Mar")
907	PathWrap = lambda fil: os.path.join(datadir,fil)
908	# load and rename project
909	gpx = G2sc.G2Project(PathWrap('7Konly.gpx'))
910	gpx.save(PathWrap('SeqRef.gpx'))
911	# turn off some variables; turn on Dijs
912	for p in gpx.phases():
913	p.set_refinements({"Cell": False})
914	gpx.phase(0).set_HAP_refinements(
915	{'Scale': False,
916	"Size": {'type':'isotropic', 'refine': False},
917	"Mustrain": {'type':'uniaxial', 'refine': False},
918	"HStrain":True,})
919	gpx.phase(1).set_HAP_refinements({'Scale': False})
920	gpx.histogram(0).clear_refinements({'Background':False,
921	'Sample Parameters':['DisplaceX'],})
922	gpx.histogram(0).ref_back_peak(0,[])
923	gpx.phase(1).set_HAP_refinements({"HStrain":(1,1,1,0)})
924	for fil in sorted(glob.glob(PathWrap('*.fxye'))): # load in remaining fxye files
925	if '00' in fil: continue
926	gpx.add_powder_histogram(fil, PathWrap('OH_00.prm'), fmthint="GSAS powder",phases='all')
927	# copy HAP values, background, instrument params. & limits, not sample params.
928	gpx.copyHistParms(0,'all',['b','i','l'])
929	for p in gpx.phases(): p.copyHAPvalues(0,'all')
930	# setup and launch sequential fit
931	gpx.set_Controls('sequential',gpx.histograms())
932	gpx.set_Controls('cycles',10)
933	gpx.set_Controls('seqCopy',True)
934	gpx.refine()
935
936	.. _ImageProc:
937
938	Image Processing
939	----------------------
940
941	A sample script where an image is read, assigned calibration values from a file
942	and then integrated follows.
943	The data files are found in the
944	`Scripting Tutorial <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/PythonScript/data/>`_.
945
946	.. code-block:: python
947
948	import os,sys
949	sys.path.insert(0,'/Users/toby/software/G2/GSASII')
950	import GSASIIscriptable as G2sc
951	datadir = "/tmp"
952	PathWrap = lambda fil: os.path.join(datadir,fil)
953
954	gpx = G2sc.G2Project(newgpx=PathWrap('inttest.gpx'))
955	imlst = gpx.add_image(PathWrap('Si_free_dc800_1-00000.tif'),fmthint="TIF")
956	imlst[0].loadControls(PathWrap('Si_free_dc800_1-00000.imctrl'))
957	pwdrList = imlst[0].Integrate()
958	gpx.save()
959
960	This example shows a computation similar to what is done in tutorial
961	`Area Detector Calibration with Multiple Distances <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/DeterminingWavelength/DeterminingWavelength.html>`_
962
963	.. code-block:: python
964
965	import os,sys,glob
966	sys.path.insert(0,'/Users/toby/software/G2/GSASII')
967	import GSASIIscriptable as G2sc
968	PathWrap = lambda fil: os.path.join(
969	"/Users/toby/wp/Active/MultidistanceCalibration/multimg",
970	fil)
971
972	gpx = G2sc.G2Project(newgpx='/tmp/img.gpx')
973	for f in glob.glob(PathWrap('*.tif')):
974	im = gpx.add_image(f,fmthint="TIF")
975	# image parameter settings
976	defImgVals = {'wavelength': 0.24152, 'center': [206., 205.],
977	'pixLimit': 2, 'cutoff': 5.0, 'DetDepth': 0.055,'calibdmin': 1.,}
978	# set controls and vary options, then fit
979	for img in gpx.images():
980	img.setCalibrant('Si SRM640c')
981	img.setVary('*',False)
982	img.setVary(['det-X', 'det-Y', 'phi', 'tilt', 'wave'], True)
983	img.setControls(defImgVals)
984	img.Recalibrate()
985	img.Recalibrate() # 2nd run better insures convergence
986	gpx.save()
987	# make dict of images for sorting
988	images = {img.getControl('setdist'):img for img in gpx.images()}
989	# show values
990	for key in sorted(images.keys()):
991	img = images[key]
992	c = img.getControls()
993	print(c['distance'],c['wavelength'])
994
995	.. _MultiDist_Example:
996
997	Image Calibration
998	----------------------
999
1000	This example performs a number of cycles of constrained fitting.
1001	A project is created with the images found in a directory, setting initial
1002	parameters as the images are read. The initial values
1003	for the calibration are not very good, so a :meth:`G2Image.Recalibrate` is done
1004	to quickly improve the fit. Once that is done, a fit of all images is performed
1005	where the wavelength, an offset and detector orientation are constrained to
1006	be the same for all images. The detector penetration correction is then added.
1007	Note that as the calibration values improve, the algorithm is able to find more
1008	points on diffraction rings to use for calibration and the number of "ring picks"
1009	increase. The calibration is repeated until that stops increasing significantly (<10%).
1010	Detector control files are then created.
1011	The files used for this exercise are found in the
1012	`Area Detector Calibration Tutorial <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/DeterminingWavelength/data/>`_
1013	(see
1014	`Area Detector Calibration with Multiple Distances <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/DeterminingWavelength/DeterminingWavelength.html>`_ ).
1015
1016	.. code-block:: python
1017
1018	import os,sys,glob
1019	sys.path.insert(0,'/Users/toby/software/G2/GSASII')
1020	import GSASIIscriptable as G2sc
1021	PathWrap = lambda fil: os.path.join(
1022	"/Users/toby/wp/Active/MultidistanceCalibration/multimg",
1023	fil)
1024
1025	gpx = G2sc.G2Project(newgpx='/tmp/calib.gpx')
1026	for f in glob.glob(PathWrap('*.tif')):
1027	im = gpx.add_image(f,fmthint="TIF")
1028	# starting image parameter settings
1029	defImgVals = {'wavelength': 0.240, 'center': [206., 205.],
1030	'pixLimit': 2, 'cutoff': 5.0, 'DetDepth': 0.03,'calibdmin': 0.5,}
1031	# set controls and vary options, then initial fit
1032	for img in gpx.images():
1033	img.setCalibrant('Si SRM640c')
1034	img.setVary('*',False)
1035	img.setVary(['det-X', 'det-Y', 'phi', 'tilt', 'wave'], True)
1036	img.setControls(defImgVals)
1037	if img.getControl('setdist') > 900:
1038	img.setControls({'calibdmin': 1.,})
1039	img.Recalibrate()
1040	G2sc.SetPrintLevel('warn') # cut down on output
1041	result,covData = gpx.imageMultiDistCalib()
1042	print('1st global fit: initial ring picks',covData['obs'])
1043	print({i:result[i] for i in result if '-' not in i})
1044	# add parameter to all images & refit multiple times
1045	for img in gpx.images(): img.setVary('dep',True)
1046	ringpicks = covData['obs']
1047	delta = ringpicks
1048	while delta > ringpicks/10:
1049	result,covData = gpx.imageMultiDistCalib(verbose=False)
1050	delta = covData['obs'] - ringpicks
1051	print('ring picks went from',ringpicks,'to',covData['obs'])
1052	print({i:result[i] for i in result if '-' not in i})
1053	ringpicks = covData['obs']
1054	# once more for good measure & printout
1055	result,covData = gpx.imageMultiDistCalib(verbose=True)
1056	# create image control files
1057	for img in gpx.images():
1058	img.saveControls(os.path.splitext(img.name)[0]+'.imctrl')
1059	gpx.save()
1060
1061	.. _HistExport:
1062
1063	Histogram Export
1064	--------------------
1065
1066	This example shows how to export a series of histograms from a collection of
1067	.gpx (project) files. The Python ``glob()`` function is used to find all files
1068	matching a wildcard in the specified directory (``dataloc``). For each file
1069	there is a loop over histograms in that project and for each histogram
1070	:meth:`G2PwdrData.Export` is called to write out the contents of that histogram
1071	as CSV (comma-separated variable) file that contains data positions,
1072	observed, computed and backgroun intensities as well as weighting for each
1073	point and Q. Note that for the Export call, there is more than one choice of
1074	exporter that can write ``.csv`` extension files, so the export hint must
1075	be specified.
1076
1077	.. code-block:: python
1078
1079	import os,sys,glob
1080	sys.path.insert(0,'/Users/toby/software/G2/GSASII') # change this
1081	import GSASIIscriptable as G2sc
1082
1083	dataloc = "/Users/toby/Scratch/" # where to find data
1084	PathWrap = lambda fil: os.path.join(dataloc,fil) # EZ way 2 add dir to filename
1085
1086	for f in glob.glob(PathWrap('bkg*.gpx')): # put filename prefix here
1087	print(f)
1088	gpx = G2sc.G2Project(f)
1089	for i,h in enumerate(gpx.histograms()):
1090	hfil = os.path.splitext(f)[0]+'_'+str(i) # file to write
1091	print('\t',h.name,hfil+'.csv')
1092	h.Export(hfil,'.csv','histogram CSV')
1093
1094	.. _CommandlineInterface:
1095
1096
1097	Installation of GSASIIscriptable
1098	=======================================
1099
1100	It is assumed that most people using GSASIIscriptable will also want to use the GUI, for this the standard
1101	`installation instructions <https://subversion.xray.aps.anl.gov/trac/pyGSAS#Installationinstructions>`_ should be followed. The GUI includes all files needed to run scriptable.
1102	Noting that not all GSAS-II capabilities are not available
1103	by scripting -- yet. Even if the scripting API were to be fully completed,
1104	there will still be some things that GSAS-II does
1105	with the GUI would be almost impossible to implement without a
1106	interactive graphical view of the data.
1107
1108	Nonetheless, there may be times where it does make sense to install GSAS-II without all of the GUI components, for example on a compute server. As `described here
1109	<https://gsas-ii.readthedocs.io/en/latest/packages.html#scripting-requirements>`_ the minimal python requirements are only numpy and scipy. It is assumed that
1110	anyone able to use scripting is well posed to install from the command line.
1111	Below are example commands to install GSAS-II for use for scripting only.
1112
1113	Installing a minimal Python configuration: Note I have chosen below
1114	to use the free
1115	miniconda installer from Anaconda, Inc., but there are also plenty of
1116	other ways to install Python, Numpy and Scipy on Linux, Windows and MacOS.
1117	For Linux a reasonable alternative is to install these packages
1118	(and perhaps others as below) using the Linux dist (``apt-get`` etc.).
1119
1120	.. code-block:: bash
1121
1122	bash ~/Downloads/Miniconda3-latest-<platform>-x86_64.sh -b -p /loc/pyg2script
1123	source /loc/pyg2script/bin/activate
1124	conda install numpy scipy matplotlib pillow h5py hdf5 svn
1125
1126	Some discussion on these commands follows:
1127
1128	* the 1st command (bash) assumes that the appropriate version of Miniconda has been downloaded from https://docs.conda.io/en/latest/miniconda.html and ``/loc/pyg2script`` is where I have selected for python to be installed. You might want to use something like ``~/pyg2script``.
1129	* the 2nd command (source) is needed to access Python with miniconda.
1130	* the 3rd command (conda) installs all possible packages that might be used by scripting, but matplotlib, pillow, and hdf5 are not commonly needed and could be omitted. The svn package is not needed (for example on Linux) where this has been installed in another way.
1131
1132	Once svn and Python has been installed and is in the path, use these commands to install GSAS-II:
1133
1134	.. code-block:: bash
1135
1136	svn co https://subversion.xray.aps.anl.gov/pyGSAS/trunk /loc/GSASII
1137	python /loc/GSASII/GSASIIscriptable.py
1138
1139	Notes on these commands:
1140
1141	* the 1st command (svn) is used to download the GSAS-II software. ``/loc/GSASII`` is the location where I decided to install the software. You can select something different.
1142	* the 2nd command (python) is used to invoke GSAS-II scriptable for the first time, which is needed to load the binary files from the server.
1143
1144	GSASIIscriptable Command-line Interface
1145	=======================================
1146
1147	The routines described above are intended to be called from a Python script, but an
1148	alternate way to access some of the same functionality is to
1149	invoke the ``GSASIIscriptable.py`` script from
1150	the command line usually from within a shell script or batch file.
1151	This mode of accessing GSAS-II scripting does not appear to get much use and
1152	is no longer being developed. Please do communicate to the developers if
1153	keeping this mode of access would be of value in your work.
1154
1155	To use the command-line mode is done with a command like this::
1156
1157	python <path/>GSASIIscriptable.py <subcommand> <file.gpx> <options>
1158
1159	The following subcommands are defined:
1160
1161	* create, see :func:`create`
1162	* add, see :func:`add`
1163	* dump, see :func:`dump`
1164	* refine, see :func:`refine`
1165	* export, :func:`export`
1166	* browse, see :func:`IPyBrowse`
1167
1168	Run::
1169
1170	python GSASIIscriptable.py --help
1171
1172	to show the available subcommands, and inspect each subcommand with
1173	`python GSASIIscriptable.py <subcommand> --help` or see the documentation for each of the above routines.
1174
1175	.. _JsonFormat:
1176
1177	Parameters in JSON files
1178	-------------------------
1179
1180	The refine command requires two inputs: an existing GSAS-II project (.gpx) file and
1181	a JSON format file
1182	(see `Introducing JSON <http://json.org/>`_) that contains a single dict.
1183	This dict may have two keys:
1184
1185	refinements:
1186	This defines the a set of refinement steps in a JSON representation of a
1187	:ref:`Refinement_recipe` list.
1188
1189	code:
1190	This optionally defines Python code that will be executed after the project is loaded,
1191	but before the refinement is started. This can be used to execute Python code to change
1192	parameters that are not accessible via a :ref:`Refinement_recipe` dict (note that the
1193	project object is accessed with variable ``proj``) or to define code that will be called
1194	later (see key ``call`` in the :ref:`Refinement_recipe` section.)
1195
1196	JSON website: `Introducing JSON <http://json.org/>`_.
1197
1198	.. _API:
1199
1200	API: Complete Documentation
1201	============================================================
1202
1203	.. automodule:: GSASIIscriptable
1204	:members:
1205

Note: See TracBrowser for help on using the repository browser.

Download in other formats: