Context Navigation

source: trunk/GSASIIobj.py @ 4333

Last change on this file since 4333 was 4327, checked in by toby, 5 years ago
misc doc updates
Property svn:eol-style set to `native` Property svn:keywords set to `Date Author Revision URL Id`
File size: 141.8 KB

Line
1	# -- coding: utf-8 --
2	#GSASIIobj - data objects for GSAS-II
3	########### SVN repository information ###################
4	# $Date: 2020-02-24 22:38:19 +0000 (Mon, 24 Feb 2020) $
5	# $Author: vondreele $
6	# $Revision: 4327 $
7	# $URL: trunk/GSASIIobj.py $
8	# $Id: GSASIIobj.py 4327 2020-02-24 22:38:19Z vondreele $
9	########### SVN repository information ###################
10
11	'''
12	GSASIIobj: Data objects
13	=========================
14
15	This module defines and/or documents the data structures used in GSAS-II, as well
16	as provides misc. support routines.
17
18	.. Next command allows \AA to be used in HTML
19
20	.. only:: html
21
22	:math:`\\require{mediawiki-texvc}`
23
24	.. _Constraints_table:
25
26	.. index::
27	single: Constraints object description
28	single: Data object descriptions; Constraints
29
30	Constraints Tree Item
31	----------------------
32
33	Constraints are stored in a dict, separated into groups.
34	Note that parameter are named in the following pattern,
35	p:h:<var>:n, where p is the phase number, h is the histogram number
36	<var> is a variable name and n is the parameter number.
37	If a parameter does not depend on a histogram or phase or is unnumbered, that
38	number is omitted.
39	Note that the contents of each dict item is a List where each element in the
40	list is a :ref:`constraint definition objects <Constraint_definitions_table>`.
41	The constraints in this form are converted in
42	:func:`GSASIIstrIO.ProcessConstraints` to the form used in :mod:`GSASIImapvars`
43
44	The keys in the Constraints dict are:
45
46	.. tabularcolumns:: \|l\|p{4.5in}\|
47
48	========== ====================================================
49	key explanation
50	========== ====================================================
51	Hist This specifies a list of constraints on
52	histogram-related parameters,
53	which will be of form :h:<var>:n.
54	HAP This specifies a list of constraints on parameters
55	that are defined for every histogram in each phase
56	and are of form p:h:<var>:n.
57	Phase This specifies a list of constraints on phase
58	parameters,
59	which will be of form p::<var>:n.
60	Global This specifies a list of constraints on parameters
61	that are not tied to a histogram or phase and
62	are of form ::<var>:n
63	========== ====================================================
64
65	.. _Constraint_definitions_table:
66
67	.. index::
68	single: Constraint definition object description
69	single: Data object descriptions; Constraint Definition
70
71	Each constraint is defined as an item in a list. Each constraint is of form::
72
73	[[<mult1>, <var1>], [<mult2>, <var2>],..., <fixedval>, <varyflag>, <constype>]
74
75	Where the variable pair list item containing two values [<mult>, <var>], where:
76
77	* <mult> is a multiplier for the constraint (float)
78	* <var> a :class:`G2VarObj` object (previously a str variable name of form
79	'p:h:name[:at]')
80
81	Note that the last three items in the list play a special role:
82
83	* <fixedval> is the fixed value for a `constant equation` (``constype=c``)
84	constraint or is None. For a `New variable` (``constype=f``) constraint,
85	a variable name can be specified as a str (used for externally
86	generated constraints)
87	* <varyflag> is True or False for `New variable` (``constype=f``) constraints
88	or is None. This indicates if this variable should be refined.
89	* <constype> is one of four letters, 'e', 'c', 'h', 'f' that determines the type of constraint:
90
91	* 'e' defines a set of equivalent variables. Only the first variable is refined (if the
92	appropriate refine flag is set) and and all other equivalent variables in the list
93	are generated from that variable, using the appropriate multipliers.
94	* 'c' defines a constraint equation of form,
95	:math:`m_1 \\times var_1 + m_2 \\times var_2 + ... = c`
96	* 'h' defines a variable to hold (not vary). Any variable on this list is not varied,
97	even if its refinement flag is set. Only one [mult,var] pair is allowed in a hold
98	constraint and the mult value is ignored.
99	This is of particular value when needing to hold one or more variables where a
100	single flag controls a set of variables such as, coordinates,
101	the reciprocal metric tensor or anisotropic displacement parameter.
102	* 'f' defines a new variable (function) according to relationship
103	:math:`newvar = m_1 \\times var_1 + m_2 \\times var_2 + ...`
104
105	.. _Covariance_table:
106
107	.. index::
108	single: Covariance description
109	single: Data object descriptions; Covariance
110
111	Covariance Tree Item
112	--------------------
113
114	The Covariance tree item has results from the last least-squares run. They
115	are stored in a dict with these keys:
116
117	.. tabularcolumns:: \|l\|l\|p{4in}\|
118
119	============= =============== ====================================================
120	key sub-key explanation
121	============= =============== ====================================================
122	newCellDict \ (dict) ith lattice parameters computed by
123	:func:`GSASIIstrMath.GetNewCellParms`
124	title \ (str) Name of gpx file(?)
125	variables \ (list) Values for all N refined variables
126	(list of float values, length N,
127	ordered to match varyList)
128	sig \ (list) Uncertainty values for all N refined variables
129	(list of float values, length N,
130	ordered to match varyList)
131	varyList \ (list of str values, length N) List of directly refined variables
132
133	newAtomDict \ (dict) atom position values computed in
134	:func:`GSASIIstrMath.ApplyXYZshifts`
135	Rvals \ (dict) R-factors, GOF, Marquardt value for last
136	refinement cycle
137	\ Nobs (int) Number of observed data points
138	\ Rwp (float) overall weighted profile R-factor (%)
139	\ chisq (float) :math:`\sum w*(I_{obs}-I_{calc})^2`
140	for all data.
141	Note: this is not the reduced :math:`\chi^2`.
142	\ lamMax (float) Marquardt value applied to Hessian diagonal
143	\ GOF (float) The goodness-of-fit, aka square root of
144	the reduced chi squared.
145	covMatrix \ (np.array) The (NxN) covVariance matrix
146	============= =============== ====================================================
147
148	.. _Phase_table:
149
150	.. index::
151	single: Phase object description
152	single: Data object descriptions; Phase
153
154	Phase Tree Items
155	----------------
156
157	Phase information is stored in the GSAS-II data tree as children of the
158	Phases item in a dict with keys:
159
160	.. tabularcolumns:: \|l\|l\|p{4in}\|
161
162	========== =============== =====================================================================================================
163	key sub-key explanation
164	========== =============== =====================================================================================================
165	General \ (dict) Overall information for the phase
166	\ 3Dproj (list of str) projections for 3D pole distribution plots
167	\ AngleRadii (list of floats) Default radius for each atom used to compute
168	interatomic angles
169	\ AtomMass (list of floats) Masses for atoms
170	\ AtomPtrs (list of int) four locations (cx,ct,cs & cu) to use to pull info
171	from the atom records
172	\ AtomTypes (llist of str) Atom types
173	\ BondRadii (list of floats) Default radius for each atom used to compute
174	interatomic distances
175	\ Cell Unit cell parameters & ref. flag
176	(list with 8 items. All but first item are float.)
177
178	0: cell refinement flag (True/False),
179	1-3: a, b, c, (:math:`\\AA`)
180	4-6: alpha, beta & gamma, (degrees)
181	7: volume (:math:`\\AA^3`)
182	\ Color (list of (r,b,g) triplets) Colors for atoms
183	\ Compare (dict) Polygon comparison parameters
184	\ Data plot type (str) data plot type ('Mustrain', 'Size' or
185	'Preferred orientation') for powder data
186	\ DisAglCtls (dDict) with distance/angle search controls,
187	which has keys 'Name', 'AtomTypes',
188	'BondRadii', 'AngleRadii' which are as above
189	except are possibly edited. Also contains
190	'Factors', which is a 2 element list with
191	a multiplier for bond and angle search range
192	[typically (0.85,0.85)].
193	\ F000X (float) x-ray F(000) intensity
194	\ F000N (float) neutron F(000) intensity
195	\ Flip (dict) Charge flip controls
196	\ HydIds (dict) geometrically generated hydrogen atoms
197	\ Isotope (dict) Isotopes for each atom type
198	\ Isotopes (dict) Scattering lengths for each isotope
199	combination for each element in phase
200	\ MCSA controls (dict) Monte Carlo-Simulated Annealing controls
201	\ Map (dict) Map parameters
202	\ Mass (float) Mass of unit cell contents in g/mol
203	\ Modulated (bool) True if phase modulated
204	\ Mydir (str) Directory of current .gpx file
205	\ Name (str) Phase name
206	\ NoAtoms (dict) Number of atoms per unit cell of each type
207	\ POhkl (list) March-Dollase preferred orientation direction
208	\ Pawley dmin (float) maximum Q (as d-space) to use for Pawley extraction
209	\ Pawley dmax (float) minimum Q (as d-space) to use for Pawley extraction
210	\ Pawley neg wt (float) Restraint value for negative Pawley intensities
211	\ SGData (object) Space group details as a
212	:ref:`space group (SGData) <SGData_table>`
213	object, as defined in :func:`GSASIIspc.SpcGroup`.
214	\ SH Texture (dict) Spherical harmonic preferred orientation parameters
215	\ Super (int) dimension of super group (0,1 only)
216	\ Type (str) phase type (e.g. 'nuclear')
217	\ Z (dict) Atomic numbers for each atom type
218	\ doDysnomia (bool) flag for max ent map modification via Dysnomia
219	\ doPawley (bool) Flag for Pawley intensity extraction
220	\ vdWRadii (dict) Van der Waals radii for each atom type
221	ranId \ (int) unique random number Id for phase
222	pId \ (int) Phase Id number for current project.
223	Atoms \ (list of lists) Atoms in phase as a list of lists. The outer list
224	is for each atom, the inner list contains varying
225	items depending on the type of phase, see
226	the :ref:`Atom Records <Atoms_table>` description.
227	Drawing \ (dict) Display parameters
228	\ Atoms (list of lists) with an entry for each atom that is drawn
229	\ Plane (list) Controls for contour density plane display
230	\ Quaternion (4 element np.array) Viewing quaternion
231	\ Zclip (float) clipping distance in :math:`\\AA`
232	\ Zstep (float) Step to de/increase Z-clip
233	\ atomPtrs (list) positions of x, type, site sym, ADP flag in Draw Atoms
234	\ backColor (list) background for plot as and R,G,B triplet
235	(default = [0, 0, 0], black).
236	\ ballScale (float) Radius of spheres in ball-and-stick display
237	\ bondList (dict) Bonds
238	\ bondRadius (float) Radius of binds in :math:`\\AA`
239	\ cameraPos (float) Viewing position in :math:`\\AA` for plot
240	\ contourLevel (float) map contour level in :math:`e/\\AA^3`
241	\ contourMax (float) map contour maximum
242	\ depthFog (bool) True if use depthFog on plot - set currently as False
243	\ ellipseProb (float) Probability limit for display of thermal
244	ellipsoids in % .
245	\ magMult (float) multiplier for magnetic moment arrows
246	\ mapSize (float) x & y dimensions of contourmap (fixed internally)
247	\ modelView (4,4 array) from openGL drawing transofmation matrix
248	\ oldxy (list with two floats) previous view point
249	\ radiusFactor (float) Distance ratio for searching for bonds. Bonds
250	are located that are within r(Ra+Rb) and (Ra+Rb)/r
251	where Ra and Rb are the atomic radii.
252	\ selectedAtoms (list of int values) List of selected atoms
253	\ showABC (bool) Flag to show view point triplet. True=show.
254	\ showHydrogen (bool) Flag to control plotting of H atoms.
255	\ showRigidBodies (bool) Flag to highlight rigid body placement
256	\ showSlice (bool) flag to show contour map
257	\ sizeH (float) Size ratio for H atoms
258	\ unitCellBox (bool) Flag to control display of the unit cell.
259	\ vdwScale (float) Multiplier of van der Waals radius for display of vdW spheres.
260	\ viewDir (np.array with three floats) cartesian viewing direction
261	\ viewPoint (list of lists) First item in list is [x,y,z]
262	in fractional coordinates for the center of
263	the plot. Second item list of previous & current
264	atom number viewed (may be [0,0])
265	RBModels \ Rigid body assignments (note Rigid body definitions
266	are stored in their own main top-level tree entry.)
267	RMC \ (dict) RMCProfile & rmcfull controls
268	Pawley ref \ (list) Pawley reflections
269	Histograms \ (dict of dicts) The key for the outer dict is
270	the histograms tied to this phase. The inner
271	dict contains the combined phase/histogram
272	parameters for items such as scale factors,
273	size and strain parameters. The following are the
274	keys to the inner dict. (dict)
275	\ Babinet (dict) For protein crystallography. Dictionary with two
276	entries, 'BabA', 'BabU'
277	\ Extinction (list of float, bool) Extinction parameter
278	\ HStrain (list of two lists) Hydrostatic strain. The first is
279	a list of the HStrain parameters (1, 2, 3, 4, or 6
280	depending on unit cell), the second is a list of boolean
281	refinement parameters (same length)
282	\ Histogram (str) The name of the associated histogram
283	\ LeBail (bool) Flag for LeBail extraction
284	\ Mustrain (list) Microstrain parameters, in order:
285
286	0. Type, one of u'isotropic', u'uniaxial', u'generalized'
287	1. Isotropic/uniaxial parameters - list of 3 floats
288	2. Refinement flags - list of 3 bools
289	3. Microstrain axis - list of 3 ints, [h, k, l]
290	4. Generalized mustrain parameters - list of 2-6 floats, depending on space group
291	5. Generalized refinement flags - list of bools, corresponding to the parameters of (4)
292	\ Pref.Ori. (list) Preferred Orientation. List of eight parameters.
293	Items marked SH are only used for Spherical Harmonics.
294
295	0. (str) Type, 'MD' for March-Dollase or 'SH' for Spherical Harmonics
296	1. (float) Value
297	2. (bool) Refinement flag
298	3. (list) Preferred direction, list of ints, [h, k, l]
299	4. (int) SH - number of terms
300	5. (dict) SH -
301	6. (list) SH
302	7. (float) SH
303	\ Scale (list of [float, bool]) Phase fraction & refine flag
304	\ Size List of crystallite size parameters, in order:
305
306	0. (str) Type, one of u'isotropic', u'uniaxial', u'ellipsoidal'
307	1. (list) Isotropic/uniaxial parameters - list of 3 floats
308	2. (list) Refinement flags - list of 3 bools
309	3. (list) Size axis - list of 3 ints, [h, k, l]
310	4. (list) Ellipsoidal size parameters - list of 6 floats
311	5. (list) Ellipsoidal refinement flags - list of bools, corresponding to the parameters of (4)
312	\ Use (bool) True if this histogram is to be used in refinement
313	\ newLeBail (bool) Whether to perform a new LeBail extraction
314	MCSA \ (dict) Monte-Carlo simulated annealing parameters
315	========== =============== =====================================================================================================
316
317	.. _RBData_table:
318
319	.. index::
320	single: Rigid Body Data description
321	single: Data object descriptions; Rigid Body Data
322
323	Rigid Body Objects
324	------------------
325
326	Rigid body descriptions are available for two types of rigid bodies: 'Vector'
327	and 'Residue'. Vector rigid bodies are developed by a sequence of translations each
328	with a refinable magnitude and Residue rigid bodies are described as Cartesian coordinates
329	with defined refinable torsion angles.
330
331	.. tabularcolumns:: \|l\|l\|p{4in}\|
332
333	========== =============== ====================================================
334	key sub-key explanation
335	========== =============== ====================================================
336	Vector RBId (dict of dict) vector rigid bodies
337	\ AtInfo (dict) Drad, Color: atom drawing radius & color for each atom type
338	\ RBname (str) Name assigned by user to rigid body
339	\ VectMag (list) vector magnitudes in :math:`\\AA`
340	\ rbXYZ (list of 3 float Cartesian coordinates for Vector rigid body )
341	\ rbRef (list of 3 int & 1 bool) 3 assigned reference atom nos. in rigid body for origin
342	definition, use center of atoms flag
343	\ VectRef (list of bool refinement flags for VectMag values )
344	\ rbTypes (list of str) Atom types for each atom in rigid body
345	\ rbVect (list of lists) Cartesian vectors for each translation used to build rigid body
346	\ useCount (int) Number of times rigid body is used in any structure
347	Residue RBId (dict of dict) residue rigid bodies
348	\ AtInfo (dict) Drad, Color: atom drawing radius & color for each atom type
349	\ RBname (str) Name assigned by user to rigid body
350	\ rbXYZ (list of 3 float) Cartesian coordinates for Residue rigid body
351	\ rbTypes (list of str) Atom types for each atom in rigid body
352	\ atNames (list of str) Names of each atom in rigid body (e.g. C1,N2...)
353	\ rbRef (list of 3 int & 1 bool) 3 assigned reference atom nos. in rigid body for origin
354	definition, use center of atoms flag
355	\ rbSeq (list) Orig,Piv,angle,Riding : definition of internal rigid body
356	torsion; origin atom (int), pivot atom (int), torsion angle (float),
357	riding atoms (list of int)
358	\ SelSeq (int,int) used by SeqSizer to identify objects
359	\ useCount (int)Number of times rigid body is used in any structure
360	RBIds \ (dict) unique Ids generated upon creation of each rigid body
361	\ Vector (list) Ids for each Vector rigid body
362	\ Residue (list) Ids for each Residue rigid body
363	========== =============== ====================================================
364
365	.. _SGData_table:
366
367	.. index::
368	single: Space Group Data description
369	single: Data object descriptions; Space Group Data
370
371	Space Group Objects
372	-------------------
373
374	Space groups are interpreted by :func:`GSASIIspc.SpcGroup`
375	and the information is placed in a SGdata object
376	which is a dict with these keys. Magnetic ones are marked "mag"
377
378	.. tabularcolumns:: \|l\|p{4.5in}\|
379
380	========== ========================================================================================
381	key explanation
382	========== ========================================================================================
383	BNSlattsym mag - (str) BNS magnetic space group symbol and centering vector
384	GenFlg mag - (list) symmetry generators indices
385	GenSym mag - (list) names for each generator
386	MagMom mag - (list) "time reversals" for each magnetic operator
387	MagPtGp mag - (str) Magnetic point group symbol
388	MagSpGrp mag - (str) Magnetic space group symbol
389	OprNames mag - (list) names for each space group operation
390	SGCen (np.array) Symmetry cell centering vectors. A (n,3) np.array
391	of centers. Will always have at least one row: ``np.array([[0, 0, 0]])``
392	SGFixed (bool) Only True if phase mported from a magnetic cif file
393	then the space group can not be changed by the user because
394	operator set from cif may be nonstandard
395	SGGen (list) generators
396	SGGray (bool) True if space group is a gray group (incommensurate magnetic structures)
397	SGInv (bool) True if centrosymmetric, False if not
398	SGLatt (str)Lattice centering type. Will be one of
399	P, A, B, C, I, F, R
400	SGLaue (str) one of the following 14 Laue classes:
401	-1, 2/m, mmm, 4/m, 4/mmm, 3R,
402	3mR, 3, 3m1, 31m, 6/m, 6/mmm, m3, m3m
403	SGOps (list) symmetry operations as a list of form
404	``[[M1,T1], [M2,T2],...]``
405	where :math:`M_n` is a 3x3 np.array
406	and :math:`T_n` is a length 3 np.array.
407	Atom coordinates are transformed where the
408	Asymmetric unit coordinates [X is (x,y,z)]
409	are transformed using
410	:math:`X^\prime = M_n*X+T_n`
411	SGPolax (str) Axes for space group polarity. Will be one of
412	'', 'x', 'y', 'x y', 'z', 'x z', 'y z',
413	'xyz'. In the case where axes are arbitrary
414	'111' is used (P 1, and ?).
415	SGPtGrp (str) Point group of the space group
416	SGUniq unique axis if monoclinic. Will be
417	a, b, or c for monoclinic space groups.
418	Will be blank for non-monoclinic.
419	SGSpin mag - (list) of spin flip operatiors (+1 or -1) for the space group operations
420	SGSys (str) symmetry unit cell: type one of
421	'triclinic', 'monoclinic', 'orthorhombic',
422	'tetragonal', 'rhombohedral', 'trigonal',
423	'hexagonal', 'cubic'
424	SSGK1 (list) Superspace multipliers
425	SpGrp (str) space group symbol
426	SpnFlp mag - (list) Magnetic spin flips for every magnetic space group operator
427	========== ========================================================================================
428
429	.. _SSGData_table:
430
431	.. index::
432	single: Superspace Group Data description
433	single: Data object descriptions; Superspace Group Data
434
435	Superspace groups [3+1] are interpreted by :func:`GSASIIspc.SSpcGroup`
436	and the information is placed in a SSGdata object
437	which is a dict with these keys:
438
439	.. tabularcolumns:: \|l\|p{4.5in}\|
440
441	========== ====================================================
442	key explanation
443	========== ====================================================
444	SSGCen (list) 4D cell centering vectors [0,0,0,0] at least
445	SSGK1 (list) Superspace multipliers
446	SSGOps (list) 4D symmetry operations as [M,T] so that M*x+T = x'
447	SSpGrp (str) superspace group symbol extension to space group
448	symbol, accidental spaces removed
449	modQ (list) modulation/propagation vector
450	modSymb (list of str) Modulation symbols
451	========== ====================================================
452
453
454	.. _Atoms_table:
455
456	.. index::
457	single: Atoms record description
458	single: Data object descriptions; Atoms record
459
460	Atom Records
461	------------
462
463	If ``phasedict`` points to the phase information in the data tree, then
464	atoms are contained in a list of atom records (list) in
465	``phasedict['Atoms']``. Also needed to read atom information
466	are four pointers, ``cx,ct,cs,cia = phasedict['General']['AtomPtrs']``,
467	which define locations in the atom record, as shown below. Items shown are
468	always present; additional ones for macromolecular phases are marked 'mm',
469	and those for magnetic structures are marked 'mg'
470
471	.. tabularcolumns:: \|l\|p{4.5in}\|
472
473	============== ====================================================
474	location explanation
475	============== ====================================================
476	ct-4 mm - (str) residue number
477	ct-3 mm - (str) residue name (e.g. ALA)
478	ct-2 mm - (str) chain label
479	ct-1 (str) atom label
480	ct (str) atom type
481	ct+1 (str) refinement flags; combination of 'F', 'X', 'U', 'M'
482	cx,cx+1,cx+2 (3 floats) the x,y and z coordinates
483	cx+3 (float) site occupancy
484	cx+4,cx+5,cx+6 mg - (list) atom magnetic moment along a,b,c in Bohr magnetons
485	cs (str) site symmetry
486	cs+1 (int) site multiplicity
487	cia (str) ADP flag: Isotropic ('I') or Anisotropic ('A')
488	cia+1 (float) Uiso
489	cia+2...cia+7 (6 floats) U11, U22, U33, U12, U13, U23
490	atom[cia+8] (int) unique atom identifier
491
492	============== ====================================================
493
494	.. _Drawing_atoms_table:
495
496	.. index::
497	single: Drawing atoms record description
498	single: Data object descriptions; Drawing atoms record
499
500	Drawing Atom Records
501	--------------------
502
503	If ``phasedict`` points to the phase information in the data tree, then
504	drawing atoms are contained in a list of drawing atom records (list) in
505	``phasedict['Drawing']['Atoms']``. Also needed to read atom information
506	are four pointers, ``cx,ct,cs,ci = phasedict['Drawing']['AtomPtrs']``,
507	which define locations in the atom record, as shown below. Items shown are
508	always present; additional ones for macromolecular phases are marked 'mm',
509	and those for magnetic structures are marked 'mg'
510
511	.. tabularcolumns:: \|l\|p{4.5in}\|
512
513	============== ===================================================================================
514	location explanation
515	============== ===================================================================================
516	ct-4 mm - (str) residue number
517	ct-3 mm - (str) residue name (e.g. ALA)
518	ct-2 mm - (str) chain label
519	ct-1 (str) atom label
520	ct (str) atom type
521	cx,cx+1,cx+2 (3 floats) the x,y and z coordinates
522	cx+3,cx+4,cx+5 mg - (3 floats) atom magnetic moment along a,b,c in Bohr magnetons
523	cs-1 (str) Sym Op symbol; sym. op number + unit cell id (e.g. '1,0,-1')
524	cs (str) atom drawing style; e.g. 'balls & sticks'
525	cs+1 (str) atom label style (e.g. 'name')
526	cs+2 (int) atom color (RBG triplet)
527	cs+3 (str) ADP flag: Isotropic ('I') or Anisotropic ('A')
528	cs+4 (float) Uiso
529	cs+5...cs+11 (6 floats) U11, U22, U33, U12, U13, U23
530	ci (int) unique atom identifier; matches source atom Id in Atom Records
531	============== ===================================================================================
532
533	.. _Powder_table:
534
535	.. index::
536	single: Powder data object description
537	single: Data object descriptions; Powder Data
538
539	Powder Diffraction Tree Items
540	-----------------------------
541
542	Every powder diffraction histogram is stored in the GSAS-II data tree
543	with a top-level entry named beginning with the string "PWDR ". The
544	diffraction data for that information are directly associated with
545	that tree item and there are a series of children to that item. The
546	routines :func:`GSASIIdataGUI.GSASII.GetUsedHistogramsAndPhasesfromTree`
547	and :func:`GSASIIstrIO.GetUsedHistogramsAndPhases` will
548	load this information into a dictionary where the child tree name is
549	used as a key, and the information in the main entry is assigned
550	a key of ``Data``, as outlined below.
551
552	.. tabularcolumns:: \|p{1in}\|p{1in}\|p{4in}\|
553
554	====================== =============== ===========================================================
555	key sub-key explanation
556	====================== =============== ===========================================================
557	Comments \ (list of str) Text strings extracted from the original powder
558	data header. These cannot be changed by the user;
559	it may be empty.
560	Limits \ (list) two two element lists, as [[Ld,Hd],[L,H]]
561	where L and Ld are the current and default lowest
562	two-theta value to be used and
563	where H and Hd are the current and default highest
564	two-theta value to be used.
565	Reflection Lists \ (dict of dicts) with an entry for each phase in the
566	histogram. The contents of each dict item
567	is a dict containing reflections, as described in
568	the :ref:`Powder Reflections <PowderRefl_table>`
569	description.
570	Instrument Parameters \ (dict) The instrument parameters uses different dicts
571	for the constant wavelength (CW) and time-of-flight (TOF)
572	cases. See below for the descriptions of each.
573	wtFactor \ (float) A weighting factor to increase or decrease
574	the leverage of data in the histogram .
575	A value of 1.0 weights the data with their
576	standard uncertainties and a larger value
577	increases the weighting of the data (equivalent
578	to decreasing the uncertainties).
579	Sample Parameters \ (dict) Parameters that describe how
580	the data were collected, as listed
581	below. Refinable parameters are a list containing
582	a float and a bool, where the second value
583	specifies if the value is refined, otherwise
584	the value is a float unless otherwise noted.
585	\ Scale The histogram scale factor (refinable)
586	\ Absorption The sample absorption coefficient as
587	:math:`\\mu r` where r is the radius
588	(refinable). Only valid for Debye-Scherrer geometry.
589	\ SurfaceRoughA Surface roughness parameter A as defined by
590	Surotti, J. Appl. Cryst, 5, 325-331, 1972.
591	(refinable - only valid for Bragg-Brentano geometry)
592	\ SurfaceRoughB Surface roughness parameter B (refinable -
593	only valid for Bragg-Brentano geometry)
594	\ DisplaceX, Sample displacement from goniometer center
595	DisplaceY where Y is along the beam direction and
596	X is perpendicular. Units are :math:`\\mu m`
597	(refinable).
598	\ Phi, Chi, Goniometer sample setting angles, in degrees.
599	Omega
600	\ Gonio. radius Radius of the diffractometer in mm
601	\ InstrName (str) A name for the instrument, used in preparing
602	a CIF .
603	\ Force, Variables that describe how the measurement
604	Temperature, was performed. Not used directly in
605	Humidity, any computations.
606	Pressure,
607	Voltage
608	\ ranId (int) The random-number Id for the histogram
609	(same value as where top-level key is ranId)
610	\ Type (str) Type of diffraction data, may be 'Debye-Scherrer'
611	or 'Bragg-Brentano' .
612	hId \ (int) The number assigned to the histogram when
613	the project is loaded or edited (can change)
614	ranId \ (int) A random number id for the histogram
615	that does not change
616	Background \ (list) The background is stored as a list with where
617	the first item in the list is list and the second
618	item is a dict. The list contains the background
619	function and its coefficients; the dict contains
620	Debye diffuse terms and background peaks.
621	(TODO: this needs to be expanded.)
622	Data \ (list) The data consist of a list of 6 np.arrays
623	containing in order:
624
625	0. the x-postions (two-theta in degrees),
626	1. the intensity values (Yobs),
627	2. the weights for each Yobs value
628	3. the computed intensity values (Ycalc)
629	4. the background values
630	5. Yobs-Ycalc
631	====================== =============== ===========================================================
632
633	.. _CWPowder_table:
634
635	.. index::
636	single: Powder data CW Instrument Parameters
637
638	-----------------------------
639	CW Instrument Parameters
640	-----------------------------
641
642	Instrument Parameters are placed in a list of two dicts,
643	where the keys in the first dict are listed below. Note that the dict contents are different for
644	constant wavelength (CW) vs. time-of-flight (TOF) histograms.
645	The value for each item is a list containing three values: the initial value, the current value
646	and a refinement flag which can have a value of True, False or 0 where 0 indicates a value that
647	cannot be refined. The first and second values are floats unless otherwise noted.
648	Items not refined are noted as [*]
649
650	.. tabularcolumns:: \|l\|p{1in}\|p{4in}\|
651
652	======================== =============== ===========================================================
653	key sub-key explanation
654	======================== =============== ===========================================================
655	Instrument Parameters[0] Type [*] (str) Histogram type:
656	* 'PXC' for constant wavelength x-ray
657	* 'PNC' for constant wavelength neutron
658	\ Bank [*] (int) Data set number in a multidata file (usually 1)
659	\ Lam (float) Specifies a wavelength in :math:`\\AA`
660	\ Lam1 [*] (float) Specifies the primary wavelength in
661	:math:`\\AA`, used in place of Lam
662	when an :math:`\\alpha_1, \\alpha_2`
663	source is used.
664	\ Lam2 [*] (float) Specifies the secondary wavelength in
665	:math:`\\AA`, used with Lam1
666	\ I(L2)/I(L1) (float) Ratio of Lam2 to Lam1, used with Lam1
667	\ Zero (float) Two-theta zero correction in degrees
668	\ Azimuth [*] (float) Azimuthal setting angle for data recorded with differing setting angles
669	\ U, V, W (float) Cagliotti profile coefficients
670	for Gaussian instrumental broadening, where the
671	FWHM goes as
672	:math:`U \\tan^2\\theta + V \\tan\\theta + W`
673	\ X, Y, Z (float) Cauchy (Lorentzian) instrumental broadening coefficients
674	\ SH/L (float) Variant of the Finger-Cox-Jephcoat asymmetric
675	peak broadening ratio. Note that this is the
676	sum of S/L and H/L where S is
677	sample height, H is the slit height and
678	L is the goniometer diameter.
679	\ Polariz. (float) Polarization coefficient.
680	Instrument Parameters[1] (empty dict)
681	======================== =============== ===========================================================
682
683	.. _TOFPowder_table:
684
685	.. index::
686	single: Powder data TOF Instrument Parameters
687
688	-----------------------------
689	TOF Instrument Parameters
690	-----------------------------
691
692	Instrument Parameters are also placed in a list of two dicts,
693	where the keys in each dict listed below, but here for
694	time-of-flight (TOF) histograms.
695	The value for each item is a list containing three values: the initial value, the current value
696	and a refinement flag which can have a value of True, False or 0 where 0 indicates a value that
697	cannot be refined. The first and second values are floats unless otherwise noted.
698	Items not refined are noted as [*]
699
700	.. tabularcolumns:: \|l\|p{1.5in}\|p{4in}\|
701
702	======================== =============== ===========================================================
703	key sub-key explanation
704	======================== =============== ===========================================================
705	Instrument Parameters[0] Type [*] (str) Histogram type:
706	* 'PNT' for time of flight neutron
707	\ Bank (int) Data set number in a multidata file
708	\ 2-theta [*] (float) Nominal scattering angle for the detector
709	\ fltPath [*] (float) Total flight path source-sample-detector
710	\ Azimuth [*] (float) Azimuth angle for detector right hand rotation
711	from horizontal away from source
712	\ difC,difA, (float) Diffractometer constants for conversion of d-spacing to TOF
713	difB in microseconds
714	\ Zero (float) Zero point offset (microseconds)
715	\ alpha (float) Exponential rise profile coefficients
716	\ beta-0 (float) Exponential decay profile coefficients
717	beta-1
718	beta-q
719	\ sig-0 (float) Gaussian profile coefficients
720	sig-1
721	sig-2
722	sig-q
723	\ X,Y,Z (float) Lorentzian profile coefficients
724	Instrument Parameters[1] Pdabc (list of 4 float lists) Originally created for use in gsas as optional tables
725	of d, alp, bet, d-true; for a reflection alpha & beta are obtained via interpolation
726	from the d-spacing and these tables. The d-true column is apparently unused.
727	======================== =============== ===========================================================
728
729
730	.. _PowderRefl_table:
731
732	.. index::
733	single: Powder reflection object description
734	single: Data object descriptions; Powder Reflections
735
736	Powder Reflection Data Structure
737	--------------------------------
738
739	For every phase in a histogram, the ``Reflection Lists`` value is a dict
740	one element of which is `'RefList'`, which is a np.array containing
741	reflections. The columns in that array are documented below.
742
743	========== ====================================================
744	index explanation
745	========== ====================================================
746	0,1,2 h,k,l (float)
747	3 (int) multiplicity
748	4 (float) d-space, :math:`\\AA`
749	5 (float) pos, two-theta
750	6 (float) sig, Gaussian width
751	7 (float) gam, Lorenzian width
752	8 (float) :math:`F_{obs}^2`
753	9 (float) :math:`F_{calc}^2`
754	10 (float) reflection phase, in degrees
755	11 (float) intensity correction for reflection, this times
756	:math:`F_{obs}^2` or :math:`F_{calc}^2` gives Iobs or Icalc
757	12 (float) Preferred orientation correction
758	13 (float) Transmission (absorption correction)
759	14 (float) Extinction correction
760	========== ====================================================
761
762	.. _Xtal_table:
763
764	.. index::
765	single: Single Crystal data object description
766	single: Data object descriptions; Single crystal data
767
768	Single Crystal Tree Items
769	-------------------------
770
771	Every single crystal diffraction histogram is stored in the GSAS-II data tree
772	with a top-level entry named beginning with the string "HKLF ". The
773	diffraction data for that information are directly associated with
774	that tree item and there are a series of children to that item. The
775	routines :func:`GSASIIdataGUI.GSASII.GetUsedHistogramsAndPhasesfromTree`
776	and :func:`GSASIIstrIO.GetUsedHistogramsAndPhases` will
777	load this information into a dictionary where the child tree name is
778	used as a key, and the information in the main entry is assigned
779	a key of ``Data``, as outlined below.
780
781	.. tabularcolumns:: \|l\|l\|p{4in}\|
782
783	====================== =============== ====================================================
784	key sub-key explanation
785	====================== =============== ====================================================
786	Data \ (dict) that contains the
787	reflection table,
788	as described in the
789	:ref:`Single Crystal Reflections
790	<XtalRefl_table>`
791	description.
792
793	Instrument Parameters \ (list) containing two dicts where the possible
794	keys in each dict are listed below. The value
795	for most items is a list containing two values:
796	the initial value, the current value.
797	The first and second
798	values are floats unless otherwise noted.
799	\ Lam (two floats) Specifies a wavelength in :math:`\\AA`
800	\ Type (two str values) Histogram type :
801	* 'SXC' for constant wavelength x-ray
802	* 'SNC' for constant wavelength neutron
803	* 'SNT' for time of flight neutron
804	\ InstrName (str) A name for the instrument, used in preparing a CIF
805	wtFactor \ (float) A weighting factor to increase or decrease
806	the leverage of data in the histogram.
807	A value of 1.0 weights the data with their
808	standard uncertainties and a larger value
809	increases the weighting of the data (equivalent
810	to decreasing the uncertainties).
811
812	hId \ (int) The number assigned to the histogram when
813	the project is loaded or edited (can change)
814	ranId \ (int) A random number id for the histogram
815	that does not change
816	====================== =============== ====================================================
817
818	.. _XtalRefl_table:
819
820	.. index::
821	single: Single Crystal reflection object description
822	single: Data object descriptions; Single Crystal Reflections
823
824	Single Crystal Reflection Data Structure
825	----------------------------------------
826
827	For every single crystal a histogram, the ``'Data'`` item contains
828	the structure factors as an np.array in item `'RefList'`.
829	The columns in that array are documented below.
830
831	.. tabularcolumns:: \|l\|p{4in}\|
832
833	========== ====================================================
834	index explanation
835	========== ====================================================
836	0,1,2 (float) h,k,l
837	3 (int) multiplicity
838	4 (float) d-space, :math:`\\AA`
839	5 (float) :math:`F_{obs}^2`
840	6 (float) :math:`\sigma(F_{obs}^2)`
841	7 (float) :math:`F_{calc}^2`
842	8 (float) :math:`F_{obs}^2T`
843	9 (float) :math:`F_{calc}^2T`
844	10 (float) reflection phase, in degrees
845	11 (float) intensity correction for reflection, this times
846	:math:`F_{obs}^2` or :math:`F_{calc}^2`
847	gives Iobs or Icalc
848	========== ====================================================
849
850	.. _Image_table:
851
852	.. index::
853	image: Image data object description
854	image: Image object descriptions
855
856	Image Data Structure
857	--------------------
858
859	Every 2-dimensional image is stored in the GSAS-II data tree
860	with a top-level entry named beginning with the string "IMG ". The
861	image data are directly associated with that tree item and there
862	are a series of children to that item. The routines :func:`GSASIIdataGUI.GSASII.GetUsedHistogramsAndPhasesfromTree`
863	and :func:`GSASIIstrIO.GetUsedHistogramsAndPhases` will
864	load this information into a dictionary where the child tree name is
865	used as a key, and the information in the main entry is assigned
866	a key of ``Data``, as outlined below.
867
868	.. tabularcolumns:: \|l\|l\|p{4in}\|
869
870	====================== ====================== ====================================================
871	key sub-key explanation
872	====================== ====================== ====================================================
873	Comments \ (list of str) Text strings extracted from the original image data
874	header or a metafile. These cannot be changed by
875	the user; it may be empty.
876	Image Controls azmthOff (float) The offset to be applied to an azimuthal
877	value. Accomodates
878	detector orientations other than with the detector
879	X-axis
880	horizontal.
881	\ background image (list:str,float) The name of a tree item ("IMG ...") that is to be subtracted
882	during image integration multiplied by value. It must have the same size/shape as
883	the integrated image. NB: value < 0 for subtraction.
884	\ calibrant (str) The material used for determining the position/orientation
885	of the image. The data is obtained from :func:`ImageCalibrants`
886	and UserCalibrants.py (supplied by user).
887	\ calibdmin (float) The minimum d-spacing used during the last calibration run.
888	\ calibskip (int) The number of expected diffraction lines skipped during the last
889	calibration run.
890	\ center (list:floats) The [X,Y] point in detector coordinates (mm) where the direct beam
891	strikes the detector plane as determined by calibration. This point
892	does not have to be within the limits of the detector boundaries.
893	\ centerAzm (bool) If True then the azimuth reported for the integrated slice
894	of the image is at the center line otherwise it is at the leading edge.
895	\ color (str) The name of the colormap used to display the image. Default = 'Paired'.
896	\ cutoff (float) The minimum value of I/Ib for a point selected in a diffraction ring for
897	calibration calculations. See pixLimit for details as how point is found.
898	\ DetDepth (float) Coefficient for penetration correction to distance; accounts for diffraction
899	ring offset at higher angles. Optionally determined by calibration.
900	\ DetDepthRef (bool) If True then refine DetDepth during calibration/recalibration calculation.
901	\ distance (float) The distance (mm) from sample to detector plane.
902	\ ellipses (list:lists) Each object in ellipses is a list [center,phi,radii,color] where
903	center (list) is location (mm) of the ellipse center on the detector plane, phi is the
904	rotation of the ellipse minor axis from the x-axis, and radii are the minor & major
905	radii of the ellipse. If radii[0] is negative then parameters describe a hyperbola. Color
906	is the selected drawing color (one of 'b', 'g' ,'r') for the ellipse/hyperbola.
907	\ edgemin (float) Not used; parameter in EdgeFinder code.
908	\ fullIntegrate (bool) If True then integrate over full 360 deg azimuthal range.
909	\ GonioAngles (list:floats) The 'Omega','Chi','Phi' goniometer angles used for this image.
910	Required for texture calculations.
911	\ invert_x (bool) If True display the image with the x-axis inverted.
912	\ invert_y (bool) If True display the image with the y-axis inverted.
913	\ IOtth (list:floats) The minimum and maximum 2-theta values to be used for integration.
914	\ LRazimuth (list:floats) The minimum and maximum azimuth values to be used for integration.
915	\ Oblique (list:float,bool) If True apply a detector absorption correction using the value to the
916	intensities obtained during integration.
917	\ outAzimuths (int) The number of azimuth pie slices.
918	\ outChannels (int) The number of 2-theta steps.
919	\ pixelSize (list:ints) The X,Y dimensions (microns) of each pixel.
920	\ pixLimit (int) A box in the image with 2*pixLimit+1 edges is searched to find the maximum.
921	This value (I) along with the minimum (Ib) in the box is reported by :func:`GSASIIimage.ImageLocalMax`
922	and subject to cutoff in :func:`GSASIIimage.makeRing`.
923	Locations are used to construct rings of points for calibration calcualtions.
924	\ PolaVal (list:float,bool) If type='SASD' and if True, apply polarization correction to intensities from
925	integration using value.
926	\ rings (list:lists) Each entry is [X,Y,dsp] where X & Y are lists of x,y coordinates around a
927	diffraction ring with the same d-spacing (dsp)
928	\ ring (list) The x,y coordinates of the >5 points on an inner ring
929	selected by the user,
930	\ Range (list) The minimum & maximum values of the image
931	\ rotation (float) The angle between the x-axis and the vector about which the
932	detector is tilted. Constrained to -180 to 180 deg.
933	\ SampleShape (str) Currently only 'Cylinder'. Sample shape for Debye-Scherrer experiments; used for absorption
934	calculations.
935	\ SampleAbs (list: float,bool) Value of absorption coefficient for Debye-Scherrer experimnents, flag if True
936	to cause correction to be applied.
937	\ setDefault (bool) If True the use the image controls values for all new images to be read. (might be removed)
938	\ setRings (bool) If True then display all the selected x,y ring positions (vida supra rings) used in the calibration.
939	\ showLines (bool) If True then isplay the integration limits to be used.
940	\ size (list:int) The number of pixels on the image x & y axes
941	\ type (str) One of 'PWDR', 'SASD' or 'REFL' for powder, small angle or reflectometry data, respectively.
942	\ tilt (float) The angle the detector normal makes with the incident beam; range -90 to 90.
943	\ wavelength (float) The radiation wavelength (:math:`\\AA`) as entered by the user
944	(or someday obtained from the image header).
945	Masks Arcs (list: lists) Each entry [2-theta,[azimuth[0],azimuth[1]],thickness] describes an arc mask
946	to be excluded from integration
947	\ Frames (list:lists) Each entry describes the x,y points (3 or more - mm) that describe a frame outside
948	of which is excluded from recalibration and integration. Only one frame is allowed.
949	\ Points (list:lists) Each entry [x,y,radius] (mm) describes an excluded spot on the image to be excluded
950	from integration.
951	\ Polygons (list:lists) Each entry is a list of 3+ [x,y] points (mm) that describe a polygon on the image
952	to be excluded from integration.
953	\ Rings (list: lists) Each entry [2-theta,thickness] describes a ring mask
954	to be excluded from integration.
955	\ Thresholds (list:[tuple,list]) [(Imin,Imax),[Imin,Imax]] This gives lower and upper limits for points on the image to be included
956	in integrsation. The tuple is the image intensity limits and the list are those set by the user.
957	\ SpotMask (dict: int & array)
958	'esdMul'(int) number of standard deviations above mean ring intensity to mask
959	'spotMask' (bool array) the spot mask for every pixel in image
960
961	Stress/Strain Sample phi (float) Sample rotation about vertical axis.
962	\ Sample z (float) Sample translation from the calibration sample position (for Sample phi = 0)
963	These will be restricted by space group symmetry; result of strain fit refinement.
964	\ Type (str) 'True' or 'Conventional': The strain model used for the calculation.
965	\ d-zero (list:dict) Each item is for a diffraction ring on the image; all items are from the same phase
966	and are used to determine the strain tensor.
967	The dictionary items are:
968	'Dset': (float) True d-spacing for the diffraction ring; entered by the user.
969	'Dcalc': (float) Average calculated d-spacing determined from strain coeff.
970	'Emat': (list: float) The strain tensor elements e11, e12 & e22 (e21=e12, rest are 0)
971	'Esig': (list: float) Esds for Emat from fitting.
972	'pixLimit': (int) Search range to find highest point on ring for each data point
973	'cutoff': (float) I/Ib cutoff for searching.
974	'ImxyObs': (list: lists) [[X],[Y]] observed points to be used for strain calculations.
975	'ImtaObs': (list: lists) [[d],[azm]] transformed via detector calibration from ImxyObs.
976	'ImtaCalc': (list: lists [[d],[azm]] calculated d-spacing & azimuth from fit.
977
978	====================== ====================== ====================================================
979
980	.. _parmDict_table:
981
982	.. index::
983	single: Parameter dictionary
984
985	Parameter Dictionary
986	-------------------------
987
988	The parameter dictionary contains all of the variable parameters for the refinement.
989	The dictionary keys are the name of the parameter (<phase>:<hist>:<name>:<atom>).
990	It is prepared in two ways. When loaded from the tree
991	(in :meth:`GSASIIdataGUI.GSASII.MakeLSParmDict` and
992	:meth:`GSASIIIO.ExportBaseclass.loadParmDict`),
993	the values are lists with two elements: ``[value, refine flag]``
994
995	When loaded from the GPX file (in
996	:func:`GSASIIstrMain.Refine` and :func:`GSASIIstrMain.SeqRefine`), the value in the
997	dict is the actual parameter value (usually a float, but sometimes a
998	letter or string flag value (such as I or A for iso/anisotropic).
999
1000
1001	Classes and routines
1002	----------------------
1003
1004	'''
1005	from __future__ import division, print_function
1006	import platform
1007	import re
1008	import imp
1009	import random as ran
1010	import sys
1011	import os.path as ospath
1012	if '2' in platform.python_version_tuple()[0]:
1013	import cPickle
1014	else:
1015	import pickle as cPickle
1016	import GSASIIpath
1017	import GSASIImath as G2mth
1018	import GSASIIspc as G2spc
1019	import numpy as np
1020
1021	GSASIIpath.SetVersionNumber("$Revision: 4327 $")
1022
1023	DefaultControls = {
1024	'deriv type':'analytic Hessian',
1025	'min dM/M':0.001,'shift factor':1.,'max cyc':3,'F**2':False,'SVDtol':1.e-6,
1026	'UsrReject':{'minF/sig':0.,'MinExt':0.01,'MaxDF/F':100.,'MaxD':500.,'MinD':0.05},
1027	'Copy2Next':False,'Reverse Seq':False,'HatomFix':False,
1028	'Author':'no name',
1029	'FreePrm1':'Sample humidity (%)',
1030	'FreePrm2':'Sample voltage (V)',
1031	'FreePrm3':'Applied load (MN)',
1032	'ShowCell':False,
1033	}
1034	'''Values to be used as defaults for the initial contents of the ``Controls``
1035	data tree item.
1036	'''
1037	def StripUnicode(string,subs='.'):
1038	'''Strip non-ASCII characters from strings
1039
1040	:param str string: string to strip Unicode characters from
1041	:param str subs: character(s) to place into string in place of each
1042	Unicode character. Defaults to '.'
1043
1044	:returns: a new string with only ASCII characters
1045	'''
1046	s = ''
1047	for c in string:
1048	if ord(c) < 128:
1049	s += c
1050	else:
1051	s += subs
1052	return s
1053	# return s.encode('ascii','replace')
1054
1055	def MakeUniqueLabel(lbl,labellist):
1056	'''Make sure that every a label is unique against a list by adding
1057	digits at the end until it is not found in list.
1058
1059	:param str lbl: the input label
1060	:param list labellist: the labels that have already been encountered
1061	:returns: lbl if not found in labellist or lbl with ``_1-9`` (or
1062	``_10-99``, etc.) appended at the end
1063	'''
1064	lbl = StripUnicode(lbl.strip(),'_')
1065	if not lbl: # deal with a blank label
1066	lbl = '_1'
1067	if lbl not in labellist:
1068	labellist.append(lbl)
1069	return lbl
1070	i = 1
1071	prefix = lbl
1072	if '_' in lbl:
1073	prefix = lbl[:lbl.rfind('_')]
1074	suffix = lbl[lbl.rfind('_')+1:]
1075	try:
1076	i = int(suffix)+1
1077	except: # suffix could not be parsed
1078	i = 1
1079	prefix = lbl
1080	while prefix+'_'+str(i) in labellist:
1081	i += 1
1082	else:
1083	lbl = prefix+'_'+str(i)
1084	labellist.append(lbl)
1085	return lbl
1086
1087	PhaseIdLookup = {}
1088	'''dict listing phase name and random Id keyed by sequential phase index as a str;
1089	best to access this using :func:`LookupPhaseName`
1090	'''
1091	PhaseRanIdLookup = {}
1092	'''dict listing phase sequential index keyed by phase random Id;
1093	best to access this using :func:`LookupPhaseId`
1094	'''
1095	HistIdLookup = {}
1096	'''dict listing histogram name and random Id, keyed by sequential histogram index as a str;
1097	best to access this using :func:`LookupHistName`
1098	'''
1099	HistRanIdLookup = {}
1100	'''dict listing histogram sequential index keyed by histogram random Id;
1101	best to access this using :func:`LookupHistId`
1102	'''
1103	AtomIdLookup = {}
1104	'''dict listing for each phase index as a str, the atom label and atom random Id,
1105	keyed by atom sequential index as a str;
1106	best to access this using :func:`LookupAtomLabel`
1107	'''
1108	AtomRanIdLookup = {}
1109	'''dict listing for each phase the atom sequential index keyed by atom random Id;
1110	best to access this using :func:`LookupAtomId`
1111	'''
1112	ShortPhaseNames = {}
1113	'''a dict containing a possibly shortened and when non-unique numbered
1114	version of the phase name. Keyed by the phase sequential index.
1115	'''
1116	ShortHistNames = {}
1117	'''a dict containing a possibly shortened and when non-unique numbered
1118	version of the histogram name. Keyed by the histogram sequential index.
1119	'''
1120
1121	#VarDesc = {} # removed 1/30/19 BHT as no longer needed (I think)
1122	#''' This dictionary lists descriptions for GSAS-II variables,
1123	#as set in :func:`CompileVarDesc`. See that function for a description
1124	#for how keys and values are written.
1125	#'''
1126
1127	reVarDesc = {}
1128	''' This dictionary lists descriptions for GSAS-II variables where
1129	keys are compiled regular expressions that will match the name portion
1130	of a parameter name. Initialized in :func:`CompileVarDesc`.
1131	'''
1132
1133	reVarStep = {}
1134	''' This dictionary lists the preferred step size for numerical
1135	derivative computation w/r to a GSAS-II variable. Keys are compiled
1136	regular expressions and values are the step size for that parameter.
1137	Initialized in :func:`CompileVarDesc`.
1138	'''
1139	# create a default space group object for P1; N.B. fails when building documentation
1140	try:
1141	P1SGData = G2spc.SpcGroup('P 1')[1] # data structure for default space group
1142	except:
1143	pass
1144
1145	def GetPhaseNames(fl):
1146	''' Returns a list of phase names found under 'Phases' in GSASII gpx file
1147	NB: there is another one of these in GSASIIstrIO.py that uses the gpx filename
1148
1149	:param file fl: opened .gpx file
1150	:return: list of phase names
1151	'''
1152	PhaseNames = []
1153	while True:
1154	try:
1155	data = cPickle.load(fl)
1156	except EOFError:
1157	break
1158	datum = data[0]
1159	if 'Phases' == datum[0]:
1160	for datus in data[1:]:
1161	PhaseNames.append(datus[0])
1162	fl.seek(0) #reposition file
1163	return PhaseNames
1164
1165	def SetNewPhase(Name='New Phase',SGData=None,cell=None,Super=None):
1166	'''Create a new phase dict with default values for various parameters
1167
1168	:param str Name: Name for new Phase
1169
1170	:param dict SGData: space group data from :func:`GSASIIspc:SpcGroup`;
1171	defaults to data for P 1
1172
1173	:param list cell: unit cell parameter list; defaults to
1174	[1.0,1.0,1.0,90.,90,90.,1.]
1175
1176	'''
1177	if SGData is None: SGData = P1SGData
1178	if cell is None: cell=[1.0,1.0,1.0,90.,90.,90.,1.]
1179	phaseData = {
1180	'ranId':ran.randint(0,sys.maxsize),
1181	'General':{
1182	'Name':Name,
1183	'Type':'nuclear',
1184	'Modulated':False,
1185	'AtomPtrs':[3,1,7,9],
1186	'SGData':SGData,
1187	'Cell':[False,]+cell,
1188	'Pawley dmin':1.0,
1189	'Data plot type':'None',
1190	'SH Texture':{
1191	'Order':0,
1192	'Model':'cylindrical',
1193	'Sample omega':[False,0.0],
1194	'Sample chi':[False,0.0],
1195	'Sample phi':[False,0.0],
1196	'SH Coeff':[False,{}],
1197	'SHShow':False,
1198	'PFhkl':[0,0,1],
1199	'PFxyz':[0,0,1],
1200	'PlotType':'Pole figure',
1201	'Penalty':[['',],0.1,False,1.0]}},
1202	'Atoms':[],
1203	'Drawing':{},
1204	'Histograms':{},
1205	'Pawley ref':[],
1206	'RBModels':{},
1207	}
1208	if Super and Super.get('Use',False):
1209	phaseData['General'].update({'Modulated':True,'Super':True,'SuperSg':Super['ssSymb']})
1210	phaseData['General']['SSGData'] = G2spc.SSpcGroup(SGData,Super['ssSymb'])[1]
1211	phaseData['General']['SuperVec'] = [Super['ModVec'],False,Super['maxH']]
1212
1213	return phaseData
1214
1215	def ReadCIF(URLorFile):
1216	'''Open a CIF, which may be specified as a file name or as a URL using PyCifRW
1217	(from James Hester).
1218	The open routine gets confused with DOS names that begin with a letter and colon
1219	"C:\dir\" so this routine will try to open the passed name as a file and if that
1220	fails, try it as a URL
1221
1222	:param str URLorFile: string containing a URL or a file name. Code will try first
1223	to open it as a file and then as a URL.
1224
1225	:returns: a PyCifRW CIF object.
1226	'''
1227	import CifFile as cif # PyCifRW from James Hester
1228
1229	# alternate approach:
1230	#import urllib
1231	#ciffile = 'file:'+urllib.pathname2url(filename)
1232
1233	try:
1234	fp = open(URLorFile,'r')
1235	cf = cif.ReadCif(fp)
1236	fp.close()
1237	return cf
1238	except IOError:
1239	return cif.ReadCif(URLorFile)
1240
1241	def IndexAllIds(Histograms,Phases):
1242	'''Scan through the used phases & histograms and create an index
1243	to the random numbers of phases, histograms and atoms. While doing this,
1244	confirm that assigned random numbers are unique -- just in case lightning
1245	strikes twice in the same place.
1246
1247	Note: this code assumes that the atom random Id (ranId) is the last
1248	element each atom record.
1249
1250	This is called in three places (only): :func:`GSASIIstrIO.GetUsedHistogramsAndPhases`
1251	(which loads the histograms and phases from a GPX file),
1252	:meth:`~GSASIIdataGUI.GSASII.GetUsedHistogramsAndPhasesfromTree`
1253	(which loads the histograms and phases from the data tree.) and
1254	:meth:`GSASIIconstrGUI.UpdateConstraints`
1255	(which displays & edits the constraints in a GUI)
1256
1257	TODO: do we need a lookup for rigid body variables?
1258	'''
1259	# process phases and atoms
1260	PhaseIdLookup.clear()
1261	PhaseRanIdLookup.clear()
1262	AtomIdLookup.clear()
1263	AtomRanIdLookup.clear()
1264	ShortPhaseNames.clear()
1265	for ph in Phases:
1266	cx,ct,cs,cia = Phases[ph]['General']['AtomPtrs']
1267	ranId = Phases[ph]['ranId']
1268	while ranId in PhaseRanIdLookup:
1269	# Found duplicate random Id! note and reassign
1270	print ("\n\n*** Phase "+str(ph)+" has repeated ranId. Fixing.\n")
1271	Phases[ph]['ranId'] = ranId = ran.randint(0,sys.maxsize)
1272	pId = str(Phases[ph]['pId'])
1273	PhaseIdLookup[pId] = (ph,ranId)
1274	PhaseRanIdLookup[ranId] = pId
1275	shortname = ph #[:10]
1276	while shortname in ShortPhaseNames.values():
1277	shortname = ph[:8] + ' ('+ pId + ')'
1278	ShortPhaseNames[pId] = shortname
1279	AtomIdLookup[pId] = {}
1280	AtomRanIdLookup[pId] = {}
1281	for iatm,at in enumerate(Phases[ph]['Atoms']):
1282	ranId = at[cia+8]
1283	while ranId in AtomRanIdLookup[pId]: # check for dups
1284	print ("\n\n*** Phase "+str(ph)+" atom "+str(iatm)+" has repeated ranId. Fixing.\n")
1285	at[cia+8] = ranId = ran.randint(0,sys.maxsize)
1286	AtomRanIdLookup[pId][ranId] = str(iatm)
1287	if Phases[ph]['General']['Type'] == 'macromolecular':
1288	label = '%s_%s_%s_%s'%(at[ct-1],at[ct-3],at[ct-4],at[ct-2])
1289	else:
1290	label = at[ct-1]
1291	AtomIdLookup[pId][str(iatm)] = (label,ranId)
1292	# process histograms
1293	HistIdLookup.clear()
1294	HistRanIdLookup.clear()
1295	ShortHistNames.clear()
1296	for hist in Histograms:
1297	ranId = Histograms[hist]['ranId']
1298	while ranId in HistRanIdLookup:
1299	# Found duplicate random Id! note and reassign
1300	print ("\n\n*** Histogram "+str(hist)+" has repeated ranId. Fixing.\n")
1301	Histograms[hist]['ranId'] = ranId = ran.randint(0,sys.maxsize)
1302	hId = str(Histograms[hist]['hId'])
1303	HistIdLookup[hId] = (hist,ranId)
1304	HistRanIdLookup[ranId] = hId
1305	shortname = hist[:15]
1306	while shortname in ShortHistNames.values():
1307	shortname = hist[:11] + ' ('+ hId + ')'
1308	ShortHistNames[hId] = shortname
1309
1310	def LookupAtomId(pId,ranId):
1311	'''Get the atom number from a phase and atom random Id
1312
1313	:param int/str pId: the sequential number of the phase
1314	:param int ranId: the random Id assigned to an atom
1315
1316	:returns: the index number of the atom (str)
1317	'''
1318	if not AtomRanIdLookup:
1319	raise Exception('Error: LookupAtomId called before IndexAllIds was run')
1320	if pId is None or pId == '':
1321	raise KeyError('Error: phase is invalid (None or blank)')
1322	pId = str(pId)
1323	if pId not in AtomRanIdLookup:
1324	raise KeyError('Error: LookupAtomId does not have phase '+pId)
1325	if ranId not in AtomRanIdLookup[pId]:
1326	raise KeyError('Error: LookupAtomId, ranId '+str(ranId)+' not in AtomRanIdLookup['+pId+']')
1327	return AtomRanIdLookup[pId][ranId]
1328
1329	def LookupAtomLabel(pId,index):
1330	'''Get the atom label from a phase and atom index number
1331
1332	:param int/str pId: the sequential number of the phase
1333	:param int index: the index of the atom in the list of atoms
1334
1335	:returns: the label for the atom (str) and the random Id of the atom (int)
1336	'''
1337	if not AtomIdLookup:
1338	raise Exception('Error: LookupAtomLabel called before IndexAllIds was run')
1339	if pId is None or pId == '':
1340	raise KeyError('Error: phase is invalid (None or blank)')
1341	pId = str(pId)
1342	if pId not in AtomIdLookup:
1343	raise KeyError('Error: LookupAtomLabel does not have phase '+pId)
1344	if index not in AtomIdLookup[pId]:
1345	raise KeyError('Error: LookupAtomLabel, ranId '+str(index)+' not in AtomRanIdLookup['+pId+']')
1346	return AtomIdLookup[pId][index]
1347
1348	def LookupPhaseId(ranId):
1349	'''Get the phase number and name from a phase random Id
1350
1351	:param int ranId: the random Id assigned to a phase
1352	:returns: the sequential Id (pId) number for the phase (str)
1353	'''
1354	if not PhaseRanIdLookup:
1355	raise Exception('Error: LookupPhaseId called before IndexAllIds was run')
1356	if ranId not in PhaseRanIdLookup:
1357	raise KeyError('Error: LookupPhaseId does not have ranId '+str(ranId))
1358	return PhaseRanIdLookup[ranId]
1359
1360	def LookupPhaseName(pId):
1361	'''Get the phase number and name from a phase Id
1362
1363	:param int/str pId: the sequential assigned to a phase
1364	:returns: (phase,ranId) where phase is the name of the phase (str)
1365	and ranId is the random # id for the phase (int)
1366	'''
1367	if not PhaseIdLookup:
1368	raise Exception('Error: LookupPhaseName called before IndexAllIds was run')
1369	if pId is None or pId == '':
1370	raise KeyError('Error: phase is invalid (None or blank)')
1371	pId = str(pId)
1372	if pId not in PhaseIdLookup:
1373	raise KeyError('Error: LookupPhaseName does not have index '+pId)
1374	return PhaseIdLookup[pId]
1375
1376	def LookupHistId(ranId):
1377	'''Get the histogram number and name from a histogram random Id
1378
1379	:param int ranId: the random Id assigned to a histogram
1380	:returns: the sequential Id (hId) number for the histogram (str)
1381	'''
1382	if not HistRanIdLookup:
1383	raise Exception('Error: LookupHistId called before IndexAllIds was run')
1384	if ranId not in HistRanIdLookup:
1385	raise KeyError('Error: LookupHistId does not have ranId '+str(ranId))
1386	return HistRanIdLookup[ranId]
1387
1388	def LookupHistName(hId):
1389	'''Get the histogram number and name from a histogram Id
1390
1391	:param int/str hId: the sequential assigned to a histogram
1392	:returns: (hist,ranId) where hist is the name of the histogram (str)
1393	and ranId is the random # id for the histogram (int)
1394	'''
1395	if not HistIdLookup:
1396	raise Exception('Error: LookupHistName called before IndexAllIds was run')
1397	if hId is None or hId == '':
1398	raise KeyError('Error: histogram is invalid (None or blank)')
1399	hId = str(hId)
1400	if hId not in HistIdLookup:
1401	raise KeyError('Error: LookupHistName does not have index '+hId)
1402	return HistIdLookup[hId]
1403
1404	def fmtVarDescr(varname):
1405	'''Return a string with a more complete description for a GSAS-II variable
1406
1407	:param str varname: A full G2 variable name with 2 or 3 or 4
1408	colons (<p>:<h>:name[:<a>] or <p>::RBname:<r>:<t>])
1409
1410	:returns: a string with the description
1411	'''
1412	s,l = VarDescr(varname)
1413	return s+": "+l
1414
1415	def VarDescr(varname):
1416	'''Return two strings with a more complete description for a GSAS-II variable
1417
1418	:param str name: A full G2 variable name with 2 or 3 or 4
1419	colons (<p>:<h>:name[:<a>] or <p>::RBname:<r>:<t>])
1420
1421	:returns: (loc,meaning) where loc describes what item the variable is mapped
1422	(phase, histogram, etc.) and meaning describes what the variable does.
1423	'''
1424
1425	# special handling for parameter names without a colon
1426	# for now, assume self-defining
1427	if varname.find(':') == -1:
1428	return "Global",varname
1429
1430	l = getVarDescr(varname)
1431	if not l:
1432	return ("invalid variable name ("+str(varname)+")!"),""
1433	# return "invalid variable name!",""
1434
1435	if not l[-1]:
1436	l[-1] = "(variable needs a definition! Set it in CompileVarDesc)"
1437
1438	if len(l) == 3: #SASD variable name!
1439	s = 'component:'+l[1]
1440	return s,l[-1]
1441	s = ""
1442	if l[0] is not None and l[1] is not None: # HAP: keep short
1443	if l[2] == "Scale": # fix up ambigous name
1444	l[5] = "Phase fraction"
1445	if l[0] == '*':
1446	lbl = 'Seq. ref.'
1447	else:
1448	lbl = ShortPhaseNames.get(l[0],'? #'+str(l[0]))
1449	if l[1] == '*':
1450	hlbl = 'Seq. ref.'
1451	else:
1452	hlbl = ShortHistNames.get(l[1],'? #'+str(l[1]))
1453	if hlbl[:4] == 'HKLF':
1454	hlbl = 'Xtl='+hlbl[5:]
1455	elif hlbl[:4] == 'PWDR':
1456	hlbl = 'Pwd='+hlbl[5:]
1457	else:
1458	hlbl = 'Hist='+hlbl
1459	s = "Ph="+str(lbl)+" * "+str(hlbl)
1460	else:
1461	if l[2] == "Scale": # fix up ambigous name: must be scale factor, since not HAP
1462	l[5] = "Scale factor"
1463	if l[2] == 'Back': # background parameters are "special", alas
1464	s = 'Hist='+ShortHistNames.get(l[1],'? #'+str(l[1]))
1465	l[-1] += ' #'+str(l[3])
1466	elif l[4] is not None: # rigid body parameter or modulation parm
1467	lbl = ShortPhaseNames.get(l[0],'phase?')
1468	if 'RB' in l[2]: #rigid body parm
1469	s = "Res #"+str(l[3])+" body #"+str(l[4])+" in "+str(lbl)
1470	else: #modulation parm
1471	s = 'Atom %s wave %s in %s'%(LookupAtomLabel(l[0],l[3])[0],l[4],lbl)
1472	elif l[3] is not None: # atom parameter,
1473	lbl = ShortPhaseNames.get(l[0],'phase?')
1474	try:
1475	albl = LookupAtomLabel(l[0],l[3])[0]
1476	except KeyError:
1477	albl = 'Atom?'
1478	s = "Atom "+str(albl)+" in "+str(lbl)
1479	elif l[0] == '*':
1480	s = "All phases "
1481	elif l[0] is not None:
1482	lbl = ShortPhaseNames.get(l[0],'phase?')
1483	s = "Phase "+str(lbl)
1484	elif l[1] == '*':
1485	s = 'All hists'
1486	elif l[1] is not None:
1487	hlbl = ShortHistNames.get(l[1],'? #'+str(l[1]))
1488	if hlbl[:4] == 'HKLF':
1489	hlbl = 'Xtl='+hlbl[5:]
1490	elif hlbl[:4] == 'PWDR':
1491	hlbl = 'Pwd='+hlbl[5:]
1492	else:
1493	hlbl = 'Hist='+hlbl
1494	s = str(hlbl)
1495	if not s:
1496	s = 'Global'
1497	return s,l[-1]
1498
1499	def getVarDescr(varname):
1500	'''Return a short description for a GSAS-II variable
1501
1502	:param str name: A full G2 variable name with 2 or 3 or 4
1503	colons (<p>:<h>:name[:<a1>][:<a2>])
1504
1505	:returns: a six element list as [`p`,`h`,`name`,`a1`,`a2`,`description`],
1506	where `p`, `h`, `a1`, `a2` are str values or `None`, for the phase number,
1507	the histogram number and the atom number; `name` will always be
1508	a str; and `description` is str or `None`.
1509	If the variable name is incorrectly formed (for example, wrong
1510	number of colons), `None` is returned instead of a list.
1511	'''
1512	l = varname.split(':')
1513	if len(l) == 2: #SASD parameter name
1514	return varname,l[0],getDescr(l[1])
1515	if len(l) == 3:
1516	l += [None,None]
1517	elif len(l) == 4:
1518	l += [None]
1519	elif len(l) != 5:
1520	return None
1521	for i in (0,1,3,4):
1522	if l[i] == "":
1523	l[i] = None
1524	l += [getDescr(l[2])]
1525	return l
1526
1527	def CompileVarDesc():
1528	'''Set the values in the variable lookup tables
1529	(:attr:`reVarDesc` and :attr:`reVarStep`).
1530	This is called in :func:`getDescr` and :func:`getVarStep` so this
1531	initialization is always done before use.
1532
1533	Note that keys may contain regular expressions, where '[xyz]'
1534	matches 'x' 'y' or 'z' (equivalently '[x-z]' describes this as range
1535	of values). '.*' matches any string. For example::
1536
1537	'AUiso':'Atomic isotropic displacement parameter',
1538
1539	will match variable ``'p::AUiso:a'``.
1540	If parentheses are used in the key, the contents of those parentheses can be
1541	used in the value, such as::
1542
1543	'AU([123][123])':'Atomic anisotropic displacement parameter U\\1',
1544
1545	will match ``AU11``, ``AU23``,.. and `U11`, `U23` etc will be displayed
1546	in the value when used.
1547
1548	'''
1549	if reVarDesc: return # already done
1550	for key,value in {
1551	# derived or other sequential vars
1552	'([abc])$' : 'Lattice parameter, \\1, from Ai and Djk', # N.B. '$' prevents match if any characters follow
1553	u'\u03B1' : u'Lattice parameter, \u03B1, from Ai and Djk',
1554	u'\u03B2' : u'Lattice parameter, \u03B2, from Ai and Djk',
1555	u'\u03B3' : u'Lattice parameter, \u03B3, from Ai and Djk',
1556	# ambiguous, alas:
1557	'Scale' : 'Phase or Histogram scale factor',
1558	# Phase vars (p::<var>)
1559	'A([0-5])' : ('Reciprocal metric tensor component \\1',1e-5),
1560	'[vV]ol' : 'Unit cell volume', # probably an error that both upper and lower case are used
1561	# Atom vars (p::<var>:a)
1562	'dA([xyz])$' : ('change to atomic coordinate, \\1',1e-6),
1563	'A([xyz])$' : '\\1 fractional atomic coordinate',
1564	'AUiso':('Atomic isotropic displacement parameter',1e-4),
1565	'AU([123][123])':('Atomic anisotropic displacement parameter U\\1',1e-4),
1566	'Afrac': ('Atomic site fraction parameter',1e-5),
1567	'Amul': 'Atomic site multiplicity value',
1568	'AM([xyz])$' : 'Atomic magnetic moment parameter, \\1',
1569	# Hist & Phase (HAP) vars (p:h:<var>)
1570	'Back': 'Background term',
1571	'BkPkint;(.*)':'Background peak #\\1 intensity',
1572	'BkPkpos;(.*)':'Background peak #\\1 position',
1573	'BkPksig;(.*)':'Background peak #\\1 Gaussian width',
1574	'BkPkgam;(.*)':'Background peak #\\1 Cauchy width',
1575	'Bab([AU])': 'Babinet solvent scattering coef. \\1',
1576	'D([123][123])' : 'Anisotropic strain coef. \\1',
1577	'Extinction' : 'Extinction coef.',
1578	'MD' : 'March-Dollase coef.',
1579	'Mustrain;.*' : 'Microstrain coef.',
1580	'Size;.*' : 'Crystallite size value',
1581	'eA$' : 'Cubic mustrain value',
1582	'Ep$' : 'Primary extinction',
1583	'Es$' : 'Secondary type II extinction',
1584	'Eg$' : 'Secondary type I extinction',
1585	'Flack' : 'Flack parameter',
1586	'TwinFr' : 'Twin fraction',
1587	#Histogram vars (:h:<var>)
1588	'Absorption' : 'Absorption coef.',
1589	'Displace([XY])' : ('Debye-Scherrer sample displacement \\1',0.1),
1590	'Lam' : ('Wavelength',1e-6),
1591	'I\(L2\)\/I\(L1\)' : ('Ka2/Ka1 intensity ratio',0.001),
1592	'Polariz\.' : ('Polarization correction',1e-3),
1593	'SH/L' : ('FCJ peak asymmetry correction',1e-4),
1594	'([UVW])$' : ('Gaussian instrument broadening \\1',1e-5),
1595	'([XYZ])$' : ('Cauchy instrument broadening \\1',1e-5),
1596	'Zero' : 'Debye-Scherrer zero correction',
1597	'Shift' : 'Bragg-Brentano sample displ.',
1598	'SurfRoughA' : 'Bragg-Brenano surface roughness A',
1599	'SurfRoughB' : 'Bragg-Brenano surface roughness B',
1600	'Transparency' : 'Bragg-Brentano sample tranparency',
1601	'DebyeA' : 'Debye model amplitude',
1602	'DebyeR' : 'Debye model radius',
1603	'DebyeU' : 'Debye model Uiso',
1604	'RBV.*' : 'Vector rigid body parameter',
1605	'RBR.*' : 'Residue rigid body parameter',
1606	'RBRO([aijk])' : 'Residue rigid body orientation parameter',
1607	'RBRP([xyz])' : 'Residue rigid body position parameter',
1608	'RBRTr;.*' : 'Residue rigid body torsion parameter',
1609	'RBR([TLS])([123AB][123AB])' : 'Residue rigid body group disp. param.',
1610	'constr([0-9]*)' : 'Parameter from constraint',
1611	# supersymmetry parameters p::<var>:a:o 'Flen','Fcent'?
1612	'mV([0-2])$' : 'Modulation vector component \\1',
1613	'Fsin' : 'Sin site fraction modulation',
1614	'Fcos' : 'Cos site fraction modulation',
1615	'Fzero' : 'Crenel function offset', #may go away
1616	'Fwid' : 'Crenel function width',
1617	'Tmin' : 'ZigZag/Block min location',
1618	'Tmax' : 'ZigZag/Block max location',
1619	'([XYZ])max': 'ZigZag/Block max value for \\1',
1620	'([XYZ])sin' : 'Sin position wave for \\1',
1621	'([XYZ])cos' : 'Cos position wave for \\1',
1622	'U([123][123])sin$' : 'Sin thermal wave for U\\1',
1623	'U([123][123])cos$' : 'Cos thermal wave for U\\1',
1624	'M([XYZ])sin$' : 'Sin mag. moment wave for \\1',
1625	'M([XYZ])cos$' : 'Cos mag. moment wave for \\1',
1626	# PDF peak parms (l:<var>;l = peak no.)
1627	'PDFpos' : 'PDF peak position',
1628	'PDFmag' : 'PDF peak magnitude',
1629	'PDFsig' : 'PDF peak std. dev.',
1630	# SASD vars (l:<var>;l = component)
1631	'Aspect ratio' : 'Particle aspect ratio',
1632	'Length' : 'Cylinder length',
1633	'Diameter' : 'Cylinder/disk diameter',
1634	'Thickness' : 'Disk thickness',
1635	'Shell thickness' : 'Multiplier to get inner(<1) or outer(>1) sphere radius',
1636	'Dist' : 'Interparticle distance',
1637	'VolFr' : 'Dense scatterer volume fraction',
1638	'epis' : 'Sticky sphere epsilon',
1639	'Sticky' : 'Stickyness',
1640	'Depth' : 'Well depth',
1641	'Width' : 'Well width',
1642	'Volume' : 'Particle volume',
1643	'Radius' : 'Sphere/cylinder/disk radius',
1644	'Mean' : 'Particle mean radius',
1645	'StdDev' : 'Standard deviation in Mean',
1646	'G$': 'Guinier prefactor',
1647	'Rg$': 'Guinier radius of gyration',
1648	'B$': 'Porod prefactor',
1649	'P$': 'Porod power',
1650	'Cutoff': 'Porod cutoff',
1651	'PkInt': 'Bragg peak intensity',
1652	'PkPos': 'Bragg peak position',
1653	'PkSig': 'Bragg peak sigma',
1654	'PkGam': 'Bragg peak gamma',
1655	'e([12][12])' : 'strain tensor e\1', # strain vars e11, e22, e12
1656	'Dcalc': 'Calc. d-spacing',
1657	'Back$': 'background parameter',
1658	'pos$': 'peak position',
1659	'int$': 'peak intensity',
1660	'WgtFrac':'phase weight fraction',
1661	'alpha':'TOF profile term',
1662	'beta-[01q]':'TOF profile term',
1663	'sig-[012q]':'TOF profile term',
1664	'dif[ABC]':'TOF to d-space calibration',
1665	'C\([0-9],[0-9]\)' : 'spherical harmonics preferred orientation coef.',
1666	}.items():
1667	if len(value) == 2:
1668	#VarDesc[key] = value[0]
1669	reVarDesc[re.compile(key)] = value[0]
1670	reVarStep[re.compile(key)] = value[1]
1671	else:
1672	#VarDesc[key] = value
1673	reVarDesc[re.compile(key)] = value
1674
1675	def removeNonRefined(parmList):
1676	'''Remove items from variable list that are not refined and should not
1677	appear as options for constraints
1678
1679	:param list parmList: a list of strings of form "p:h:VAR:a" where
1680	VAR is the variable name
1681
1682	:returns: a list after removing variables where VAR matches a
1683	entry in local variable NonRefinedList
1684	'''
1685	NonRefinedList = ['Omega','Type','Chi','Phi', 'Azimuth','Gonio. radius',
1686	'Lam1','Lam2','Back','Temperature','Pressure',
1687	'FreePrm1','FreePrm2','FreePrm3',
1688	'Source','nPeaks','LeBail','newLeBail','Bank',
1689	'nDebye', #'',
1690	]
1691	return [prm for prm in parmList if prm.split(':')[2] not in NonRefinedList]
1692
1693	def getDescr(name):
1694	'''Return a short description for a GSAS-II variable
1695
1696	:param str name: The descriptive part of the variable name without colons (:)
1697
1698	:returns: a short description or None if not found
1699	'''
1700
1701	CompileVarDesc() # compile the regular expressions, if needed
1702	for key in reVarDesc:
1703	m = key.match(name)
1704	if m:
1705	reVarDesc[key]
1706	return m.expand(reVarDesc[key])
1707	return None
1708
1709	def getVarStep(name,parmDict=None):
1710	'''Return a step size for computing the derivative of a GSAS-II variable
1711
1712	:param str name: A complete variable name (with colons, :)
1713	:param dict parmDict: A dict with parameter values or None (default)
1714
1715	:returns: a float that should be an appropriate step size, either from
1716	the value supplied in :func:`CompileVarDesc` or based on the value for
1717	name in parmDict, if supplied. If not found or the value is zero,
1718	a default value of 1e-5 is used. If parmDict is None (default) and
1719	no value is provided in :func:`CompileVarDesc`, then None is returned.
1720	'''
1721	CompileVarDesc() # compile the regular expressions, if needed
1722	for key in reVarStep:
1723	m = key.match(name)
1724	if m:
1725	return reVarStep[key]
1726	if parmDict is None: return None
1727	val = parmDict.get(key,0.0)
1728	if abs(val) > 0.05:
1729	return abs(val)/1000.
1730	else:
1731	return 1e-5
1732
1733	def GenWildCard(varlist):
1734	'''Generate wildcard versions of G2 variables. These introduce '*'
1735	for a phase, histogram or atom number (but only for one of these
1736	fields) but only when there is more than one matching variable in the
1737	input variable list. So if the input is this::
1738
1739	varlist = ['0::AUiso:0', '0::AUiso:1', '1::AUiso:0']
1740
1741	then the output will be this::
1742
1743	wildList = ['::AUiso:0', '0::AUiso:']
1744
1745	:param list varlist: an input list of GSAS-II variable names
1746	(such as 0::AUiso:0)
1747
1748	:returns: wildList, the generated list of wild card variable names.
1749	'''
1750	wild = []
1751	for i in (0,1,3):
1752	currentL = varlist[:]
1753	while currentL:
1754	item1 = currentL.pop(0)
1755	i1splt = item1.split(':')
1756	if i >= len(i1splt): continue
1757	if i1splt[i]:
1758	nextL = []
1759	i1splt[i] = '[0-9]+'
1760	rexp = re.compile(':'.join(i1splt))
1761	matchlist = [item1]
1762	for nxtitem in currentL:
1763	if rexp.match(nxtitem):
1764	matchlist += [nxtitem]
1765	else:
1766	nextL.append(nxtitem)
1767	if len(matchlist) > 1:
1768	i1splt[i] = '*'
1769	wild.append(':'.join(i1splt))
1770	currentL = nextL
1771	return wild
1772
1773	def LookupWildCard(varname,varlist):
1774	'''returns a list of variable names from list varname
1775	that match wildcard name in varname
1776
1777	:param str varname: a G2 variable name containing a wildcard
1778	(such as \*::var)
1779	:param list varlist: the list of all variable names used in
1780	the current project
1781	:returns: a list of matching GSAS-II variables (may be empty)
1782	'''
1783	rexp = re.compile(varname.replace('*','[0-9]+'))
1784	return sorted([var for var in varlist if rexp.match(var)])
1785
1786
1787	def _lookup(dic,key):
1788	'''Lookup a key in a dictionary, where None returns an empty string
1789	but an unmatched key returns a question mark. Used in :class:`G2VarObj`
1790	'''
1791	if key is None:
1792	return ""
1793	elif key == "*":
1794	return "*"
1795	else:
1796	return dic.get(key,'?')
1797
1798	def SortVariables(varlist):
1799	'''Sorts variable names in a sensible manner
1800	'''
1801	def cvnnums(var):
1802	v = []
1803	for i in var.split(':'):
1804	if i == '':
1805	v.append(-1)
1806	continue
1807	try:
1808	v.append(int(i))
1809	except:
1810	v.append(i)
1811	return v
1812	return sorted(varlist,key=cvnnums)
1813
1814	class G2VarObj(object):
1815	'''Defines a GSAS-II variable either using the phase/atom/histogram
1816	unique Id numbers or using a character string that specifies
1817	variables by phase/atom/histogram number (which can change).
1818	Note that :func:`LoadID` should be used to (re)load the current Ids
1819	before creating or later using the G2VarObj object.
1820
1821	This can store rigid body variables, but does not translate the residue # and
1822	body # to/from random Ids
1823
1824	A :class:`G2VarObj` object can be created with a single parameter:
1825
1826	:param str/tuple varname: a single value can be used to create a :class:`G2VarObj`
1827	object. If a string, it must be of form "p:h:var" or "p:h:var:a", where
1828
1829	* p is the phase number (which may be left blank or may be '*' to indicate all phases);
1830	* h is the histogram number (which may be left blank or may be '*' to indicate all histograms);
1831	* a is the atom number (which may be left blank in which case the third colon is omitted).
1832	The atom number can be specified as '' if a phase number is specified (not as '').
1833	For rigid body variables, specify a will be a string of form "residue:body#"
1834
1835	Alternately a single tuple of form (Phase,Histogram,VarName,AtomID) can be used, where
1836	Phase, Histogram, and AtomID are None or are ranId values (or one can be '*')
1837	and VarName is a string. Note that if Phase is '*' then the AtomID is an atom number.
1838	For a rigid body variables, AtomID is a string of form "residue:body#".
1839
1840	If four positional arguments are supplied, they are:
1841
1842	:param str/int phasenum: The number for the phase (or None or '*')
1843	:param str/int histnum: The number for the histogram (or None or '*')
1844	:param str varname: a single value can be used to create a :class:`G2VarObj`
1845	:param str/int atomnum: The number for the atom (or None or '*')
1846
1847	'''
1848	IDdict = {}
1849	IDdict['phases'] = {}
1850	IDdict['hists'] = {}
1851	IDdict['atoms'] = {}
1852	def __init__(self,*args):
1853	self.phase = None
1854	self.histogram = None
1855	self.name = ''
1856	self.atom = None
1857	if len(args) == 1 and (type(args[0]) is list or type(args[0]) is tuple) and len(args[0]) == 4:
1858	# single arg with 4 values
1859	self.phase,self.histogram,self.name,self.atom = args[0]
1860	elif len(args) == 1 and ':' in args[0]:
1861	#parse a string
1862	lst = args[0].split(':')
1863	if lst[0] == '*':
1864	self.phase = '*'
1865	if len(lst) > 3:
1866	self.atom = lst[3]
1867	self.histogram = HistIdLookup.get(lst[1],[None,None])[1]
1868	elif lst[1] == '*':
1869	self.histogram = '*'
1870	self.phase = PhaseIdLookup.get(lst[0],[None,None])[1]
1871	else:
1872	self.histogram = HistIdLookup.get(lst[1],[None,None])[1]
1873	self.phase = PhaseIdLookup.get(lst[0],[None,None])[1]
1874	if len(lst) == 4:
1875	if lst[3] == '*':
1876	self.atom = '*'
1877	else:
1878	self.atom = AtomIdLookup[lst[0]].get(lst[3],[None,None])[1]
1879	elif len(lst) == 5:
1880	self.atom = lst[3]+":"+lst[4]
1881	elif len(lst) == 3:
1882	pass
1883	else:
1884	raise Exception("Too many colons in var name "+str(args[0]))
1885	self.name = lst[2]
1886	elif len(args) == 4:
1887	if args[0] == '*':
1888	self.phase = '*'
1889	self.atom = args[3]
1890	else:
1891	self.phase = PhaseIdLookup.get(str(args[0]),[None,None])[1]
1892	if args[3] == '*':
1893	self.atom = '*'
1894	elif args[0] is not None:
1895	self.atom = AtomIdLookup[args[0]].get(str(args[3]),[None,None])[1]
1896	if args[1] == '*':
1897	self.histogram = '*'
1898	else:
1899	self.histogram = HistIdLookup.get(str(args[1]),[None,None])[1]
1900	self.name = args[2]
1901	else:
1902	raise Exception("Incorrectly called GSAS-II parameter name")
1903
1904	#print "DEBUG: created ",self.phase,self.histogram,self.name,self.atom
1905
1906	def __str__(self):
1907	return self.varname()
1908
1909	def varname(self):
1910	'''Formats the GSAS-II variable name as a "traditional" GSAS-II variable
1911	string (p:h:<var>:a) or (p:h:<var>)
1912
1913	:returns: the variable name as a str
1914	'''
1915	a = ""
1916	if self.phase == "*":
1917	ph = "*"
1918	if self.atom:
1919	a = ":" + str(self.atom)
1920	else:
1921	ph = _lookup(PhaseRanIdLookup,self.phase)
1922	if self.atom == '*':
1923	a = ':*'
1924	elif self.atom:
1925	if ":" in str(self.atom):
1926	a = ":" + str(self.atom)
1927	elif ph in AtomRanIdLookup:
1928	a = ":" + AtomRanIdLookup[ph].get(self.atom,'?')
1929	else:
1930	a = ":?"
1931	if self.histogram == "*":
1932	hist = "*"
1933	else:
1934	hist = _lookup(HistRanIdLookup,self.histogram)
1935	s = (ph + ":" + hist + ":" + str(self.name)) + a
1936	return s
1937
1938	def __repr__(self):
1939	'''Return the detailed contents of the object
1940	'''
1941	s = "<"
1942	if self.phase == '*':
1943	s += "Phases: all; "
1944	if self.atom is not None:
1945	if ":" in str(self.atom):
1946	s += "Rigid body" + str(self.atom) + "; "
1947	else:
1948	s += "Atom #" + str(self.atom) + "; "
1949	elif self.phase is not None:
1950	ph = _lookup(PhaseRanIdLookup,self.phase)
1951	s += "Phase: rId=" + str(self.phase) + " (#"+ ph + "); "
1952	if self.atom == '*':
1953	s += "Atoms: all; "
1954	elif ":" in str(self.atom):
1955	s += "Rigid body" + str(self.atom) + "; "
1956	elif self.atom is not None:
1957	s += "Atom rId=" + str(self.atom)
1958	if ph in AtomRanIdLookup:
1959	s += " (#" + AtomRanIdLookup[ph].get(self.atom,'?') + "); "
1960	else:
1961	s += " (#? -- not found!); "
1962	if self.histogram == '*':
1963	s += "Histograms: all; "
1964	elif self.histogram is not None:
1965	hist = _lookup(HistRanIdLookup,self.histogram)
1966	s += "Histogram: rId=" + str(self.histogram) + " (#"+ hist + "); "
1967	s += 'Variable name="' + str(self.name) + '">'
1968	return s+" ("+self.varname()+")"
1969
1970	def __eq__(self, other):
1971	if type(other) is type(self):
1972	return (self.phase == other.phase and
1973	self.histogram == other.histogram and
1974	self.name == other.name and
1975	self.atom == other.atom)
1976	return False
1977
1978	def _show(self):
1979	'For testing, shows the current lookup table'
1980	print ('phases'+ self.IDdict['phases'])
1981	print ('hists'+ self.IDdict['hists'])
1982	print ('atomDict'+ self.IDdict['atoms'])
1983
1984	#==========================================================================
1985	def SetDefaultSample():
1986	'Fills in default items for the Sample dictionary for Debye-Scherrer & SASD'
1987	return {
1988	'InstrName':'',
1989	'ranId':ran.randint(0,sys.maxsize),
1990	'Scale':[1.0,True],'Type':'Debye-Scherrer','Absorption':[0.0,False],
1991	'DisplaceX':[0.0,False],'DisplaceY':[0.0,False],
1992	'Temperature':300.,'Pressure':0.1,'Time':0.0,
1993	'FreePrm1':0.,'FreePrm2':0.,'FreePrm3':0.,
1994	'Gonio. radius':200.0,
1995	'Omega':0.0,'Chi':0.0,'Phi':0.0,'Azimuth':0.0,
1996	#SASD items
1997	'Materials':[{'Name':'vacuum','VolFrac':1.0,},{'Name':'vacuum','VolFrac':0.0,}],
1998	'Thick':1.0,'Contrast':[0.0,0.0], #contrast & anomalous contrast
1999	'Trans':1.0, #measured transmission
2000	'SlitLen':0.0, #Slit length - in Q(A-1)
2001	}
2002	######################################################################
2003	class ImportBaseclass(object):
2004	'''Defines a base class for the reading of input files (diffraction
2005	data, coordinates,...). See :ref:`Writing a Import Routine<import_routines>`
2006	for an explanation on how to use a subclass of this class.
2007	'''
2008	class ImportException(Exception):
2009	'''Defines an Exception that is used when an import routine hits an expected error,
2010	usually in .Reader.
2011
2012	Good practice is that the Reader should define a value in self.errors that
2013	tells the user some information about what is wrong with their file.
2014	'''
2015	pass
2016
2017	UseReader = True # in __init__ set value of self.UseReader to False to skip use of current importer
2018	def __init__(self,formatName,longFormatName=None,
2019	extensionlist=[],strictExtension=False,):
2020	self.formatName = formatName # short string naming file type
2021	if longFormatName: # longer string naming file type
2022	self.longFormatName = longFormatName
2023	else:
2024	self.longFormatName = formatName
2025	# define extensions that are allowed for the file type
2026	# for windows, remove any extensions that are duplicate, as case is ignored
2027	if sys.platform == 'windows' and extensionlist:
2028	extensionlist = list(set([s.lower() for s in extensionlist]))
2029	self.extensionlist = extensionlist
2030	# If strictExtension is True, the file will not be read, unless
2031	# the extension matches one in the extensionlist
2032	self.strictExtension = strictExtension
2033	self.errors = ''
2034	self.warnings = ''
2035	self.SciPy = False #image reader needed scipy
2036	# used for readers that will use multiple passes to read
2037	# more than one data block
2038	self.repeat = False
2039	self.selections = []
2040	self.repeatcount = 0
2041	self.readfilename = '?'
2042	self.scriptable = False
2043	#print 'created',self.__class__
2044
2045	def ReInitialize(self):
2046	'Reinitialize the Reader to initial settings'
2047	self.errors = ''
2048	self.warnings = ''
2049	self.SciPy = False #image reader needed scipy
2050	self.repeat = False
2051	self.repeatcount = 0
2052	self.readfilename = '?'
2053
2054
2055	# def Reader(self, filename, filepointer, ParentFrame=None, **unused):
2056	# '''This method must be supplied in the child class to read the file.
2057	# if the read fails either return False or raise an Exception
2058	# preferably of type ImportException.
2059	# '''
2060	# #start reading
2061	# raise ImportException("Error occurred while...")
2062	# self.errors += "Hint for user on why the error occur
2063	# return False # if an error occurs
2064	# return True # if read OK
2065
2066	def ExtensionValidator(self, filename):
2067	'''This methods checks if the file has the correct extension
2068
2069	:returns:
2070
2071	* False if this filename will not be supported by this reader (only
2072	when strictExtension is True)
2073	* True if the extension matches the list supplied by the reader
2074	* None if the reader allows un-registered extensions
2075
2076	'''
2077	if filename:
2078	ext = ospath.splitext(filename)[1]
2079	if not ext and self.strictExtension: return False
2080	for ext in self.extensionlist:
2081	if sys.platform == 'windows':
2082	if filename.lower().endswith(ext): return True
2083	else:
2084	if filename.endswith(ext): return True
2085	if self.strictExtension:
2086	return False
2087	else:
2088	return None
2089
2090	def ContentsValidator(self, filename):
2091	'''This routine will attempt to determine if the file can be read
2092	with the current format.
2093	This will typically be overridden with a method that
2094	takes a quick scan of [some of]
2095	the file contents to do a "sanity" check if the file
2096	appears to match the selected format.
2097	the file must be opened here with the correct format (binary/text)
2098	'''
2099	#filepointer.seek(0) # rewind the file pointer
2100	return True
2101
2102	def CIFValidator(self, filepointer):
2103	'''A :meth:`ContentsValidator` for use to validate CIF files.
2104	'''
2105	filepointer.seek(0)
2106	for i,l in enumerate(filepointer):
2107	if i >= 1000: return True
2108	'''Encountered only blank lines or comments in first 1000
2109	lines. This is unlikely, but assume it is CIF anyway, since we are
2110	even less likely to find a file with nothing but hashes and
2111	blank lines'''
2112	line = l.strip()
2113	if len(line) == 0: # ignore blank lines
2114	continue
2115	elif line.startswith('#'): # ignore comments
2116	continue
2117	elif line.startswith('data_'): # on the right track, accept this file
2118	return True
2119	else: # found something invalid
2120	self.errors = 'line '+str(i+1)+' contains unexpected data:\n'
2121	if all([ord(c) < 128 and ord(c) != 0 for c in str(l)]): # show only if ASCII
2122	self.errors += ' '+str(l)
2123	else:
2124	self.errors += ' (binary)'
2125	self.errors += '\n Note: a CIF should only have blank lines or comments before'
2126	self.errors += '\n a data_ statement begins a block.'
2127	return False
2128
2129	######################################################################
2130	class ImportPhase(ImportBaseclass):
2131	'''Defines a base class for the reading of files with coordinates
2132
2133	Objects constructed that subclass this (in import/G2phase_*.py etc.) will be used
2134	in :meth:`GSASIIdataGUI.GSASII.OnImportPhase` and in
2135	:func:`GSASIIscriptable.import_generic`.
2136	See :ref:`Writing a Import Routine<import_routines>`
2137	for an explanation on how to use this class.
2138
2139	'''
2140	def __init__(self,formatName,longFormatName=None,extensionlist=[],
2141	strictExtension=False,):
2142	# call parent __init__
2143	ImportBaseclass.__init__(self,formatName,longFormatName,
2144	extensionlist,strictExtension)
2145	self.Phase = None # a phase must be created with G2IO.SetNewPhase in the Reader
2146	self.Constraints = None
2147
2148	######################################################################
2149	class ImportStructFactor(ImportBaseclass):
2150	'''Defines a base class for the reading of files with tables
2151	of structure factors.
2152
2153	Structure factors are read with a call to :meth:`GSASIIdataGUI.GSASII.OnImportSfact`
2154	which in turn calls :meth:`GSASIIdataGUI.GSASII.OnImportGeneric`, which calls
2155	methods :meth:`ExtensionValidator`, :meth:`ContentsValidator` and
2156	:meth:`Reader`.
2157
2158	See :ref:`Writing a Import Routine<import_routines>`
2159	for an explanation on how to use import classes in general. The specifics
2160	for reading a structure factor histogram require that
2161	the ``Reader()`` routine in the import
2162	class need to do only a few things: It
2163	should load :attr:`RefDict` item ``'RefList'`` with the reflection list,
2164	and set :attr:`Parameters` with the instrument parameters
2165	(initialized with :meth:`InitParameters` and set with :meth:`UpdateParameters`).
2166	'''
2167	def __init__(self,formatName,longFormatName=None,extensionlist=[],
2168	strictExtension=False,):
2169	ImportBaseclass.__init__(self,formatName,longFormatName,
2170	extensionlist,strictExtension)
2171
2172	# define contents of Structure Factor entry
2173	self.Parameters = []
2174	'self.Parameters is a list with two dicts for data parameter settings'
2175	self.InitParameters()
2176	self.RefDict = {'RefList':[],'FF':{},'Super':0}
2177	self.Banks = [] #for multi bank data (usually TOF)
2178	'''self.RefDict is a dict containing the reflection information, as read from the file.
2179	Item 'RefList' contains the reflection information. See the
2180	:ref:`Single Crystal Reflection Data Structure<XtalRefl_table>`
2181	for the contents of each row. Dict element 'FF'
2182	contains the form factor values for each element type; if this entry
2183	is left as initialized (an empty list) it will be initialized as needed later.
2184	'''
2185	def ReInitialize(self):
2186	'Reinitialize the Reader to initial settings'
2187	ImportBaseclass.ReInitialize(self)
2188	self.InitParameters()
2189	self.Banks = [] #for multi bank data (usually TOF)
2190	self.RefDict = {'RefList':[],'FF':{},'Super':0}
2191
2192	def InitParameters(self):
2193	'initialize the instrument parameters structure'
2194	Lambda = 0.70926
2195	HistType = 'SXC'
2196	self.Parameters = [{'Type':[HistType,HistType], # create the structure
2197	'Lam':[Lambda,Lambda]
2198	}, {}]
2199	'Parameters is a list with two dicts for data parameter settings'
2200
2201	def UpdateParameters(self,Type=None,Wave=None):
2202	'Revise the instrument parameters'
2203	if Type is not None:
2204	self.Parameters[0]['Type'] = [Type,Type]
2205	if Wave is not None:
2206	self.Parameters[0]['Lam'] = [Wave,Wave]
2207
2208	######################################################################
2209	class ImportPowderData(ImportBaseclass):
2210	'''Defines a base class for the reading of files with powder data.
2211
2212	Objects constructed that subclass this (in import/G2pwd_*.py etc.) will be used
2213	in :meth:`GSASIIdataGUI.GSASII.OnImportPowder` and in
2214	:func:`GSASIIscriptable.import_generic`.
2215	See :ref:`Writing a Import Routine<import_routines>`
2216	for an explanation on how to use this class.
2217	'''
2218	def __init__(self,formatName,longFormatName=None,
2219	extensionlist=[],strictExtension=False,):
2220	ImportBaseclass.__init__(self,formatName,longFormatName,
2221	extensionlist,strictExtension)
2222	self.clockWd = None # used in TOF
2223	self.ReInitialize()
2224
2225	def ReInitialize(self):
2226	'Reinitialize the Reader to initial settings'
2227	ImportBaseclass.ReInitialize(self)
2228	self.powderentry = ['',None,None] # (filename,Pos,Bank)
2229	self.powderdata = [] # Powder dataset
2230	'''A powder data set is a list with items [x,y,w,yc,yb,yd]:
2231	np.array(x), # x-axis values
2232	np.array(y), # powder pattern intensities
2233	np.array(w), # 1/sig(intensity)^2 values (weights)
2234	np.array(yc), # calc. intensities (zero)
2235	np.array(yb), # calc. background (zero)
2236	np.array(yd), # obs-calc profiles
2237	'''
2238	self.comments = []
2239	self.idstring = ''
2240	self.Sample = SetDefaultSample() # default sample parameters
2241	self.Controls = {} # items to be placed in top-level Controls
2242	self.GSAS = None # used in TOF
2243	self.repeat_instparm = True # Should a parm file be
2244	# used for multiple histograms?
2245	self.instparm = None # name hint from file of instparm to use
2246	self.instfile = '' # full path name to instrument parameter file
2247	self.instbank = '' # inst parm bank number
2248	self.instmsg = '' # a label that gets printed to show
2249	# where instrument parameters are from
2250	self.numbanks = 1
2251	self.instdict = {} # place items here that will be transferred to the instrument parameters
2252	self.pwdparms = {} # place parameters that are transferred directly to the tree
2253	# here (typically from an existing GPX file)
2254	######################################################################
2255	class ImportSmallAngleData(ImportBaseclass):
2256	'''Defines a base class for the reading of files with small angle data.
2257	See :ref:`Writing a Import Routine<import_routines>`
2258	for an explanation on how to use this class.
2259	'''
2260	def __init__(self,formatName,longFormatName=None,extensionlist=[],
2261	strictExtension=False,):
2262
2263	ImportBaseclass.__init__(self,formatName,longFormatName,extensionlist,
2264	strictExtension)
2265	self.ReInitialize()
2266
2267	def ReInitialize(self):
2268	'Reinitialize the Reader to initial settings'
2269	ImportBaseclass.ReInitialize(self)
2270	self.smallangleentry = ['',None,None] # (filename,Pos,Bank)
2271	self.smallangledata = [] # SASD dataset
2272	'''A small angle data set is a list with items [x,y,w,yc,yd]:
2273	np.array(x), # x-axis values
2274	np.array(y), # powder pattern intensities
2275	np.array(w), # 1/sig(intensity)^2 values (weights)
2276	np.array(yc), # calc. intensities (zero)
2277	np.array(yd), # obs-calc profiles
2278	np.array(yb), # preset bkg
2279	'''
2280	self.comments = []
2281	self.idstring = ''
2282	self.Sample = SetDefaultSample()
2283	self.GSAS = None # used in TOF
2284	self.clockWd = None # used in TOF
2285	self.numbanks = 1
2286	self.instdict = {} # place items here that will be transferred to the instrument parameters
2287
2288	######################################################################
2289	class ImportReflectometryData(ImportBaseclass):
2290	'''Defines a base class for the reading of files with reflectometry data.
2291	See :ref:`Writing a Import Routine<import_routines>`
2292	for an explanation on how to use this class.
2293	'''
2294	def __init__(self,formatName,longFormatName=None,extensionlist=[],
2295	strictExtension=False,):
2296
2297	ImportBaseclass.__init__(self,formatName,longFormatName,extensionlist,
2298	strictExtension)
2299	self.ReInitialize()
2300
2301	def ReInitialize(self):
2302	'Reinitialize the Reader to initial settings'
2303	ImportBaseclass.ReInitialize(self)
2304	self.reflectometryentry = ['',None,None] # (filename,Pos,Bank)
2305	self.reflectometrydata = [] # SASD dataset
2306	'''A small angle data set is a list with items [x,y,w,yc,yd]:
2307	np.array(x), # x-axis values
2308	np.array(y), # powder pattern intensities
2309	np.array(w), # 1/sig(intensity)^2 values (weights)
2310	np.array(yc), # calc. intensities (zero)
2311	np.array(yd), # obs-calc profiles
2312	np.array(yb), # preset bkg
2313	'''
2314	self.comments = []
2315	self.idstring = ''
2316	self.Sample = SetDefaultSample()
2317	self.GSAS = None # used in TOF
2318	self.clockWd = None # used in TOF
2319	self.numbanks = 1
2320	self.instdict = {} # place items here that will be transferred to the instrument parameters
2321
2322	######################################################################
2323	class ImportPDFData(ImportBaseclass):
2324	'''Defines a base class for the reading of files with PDF G(R) data.
2325	See :ref:`Writing a Import Routine<import_routines>`
2326	for an explanation on how to use this class.
2327	'''
2328	def __init__(self,formatName,longFormatName=None,extensionlist=[],
2329	strictExtension=False,):
2330
2331	ImportBaseclass.__init__(self,formatName,longFormatName,extensionlist,
2332	strictExtension)
2333	self.ReInitialize()
2334
2335	def ReInitialize(self):
2336	'Reinitialize the Reader to initial settings'
2337	ImportBaseclass.ReInitialize(self)
2338	self.pdfentry = ['',None,None] # (filename,Pos,Bank)
2339	self.pdfdata = [] # PDF G(R) dataset
2340	'''A pdf g(r) data set is a list with items [x,y]:
2341	np.array(x), # r-axis values
2342	np.array(y), # pdf g(r)
2343	'''
2344	self.comments = []
2345	self.idstring = ''
2346	self.numbanks = 1
2347
2348	######################################################################
2349	class ImportImage(ImportBaseclass):
2350	'''Defines a base class for the reading of images
2351
2352	Images are read in only these places:
2353
2354	* Initial reading is typically done from a menu item
2355	with a call to :meth:`GSASIIdataGUI.GSASII.OnImportImage`
2356	which in turn calls :meth:`GSASIIdataGUI.GSASII.OnImportGeneric`. That calls
2357	methods :meth:`ExtensionValidator`, :meth:`ContentsValidator` and
2358	:meth:`Reader`. This returns a list of reader objects for each read image.
2359	Also used in :func:`GSASIIscriptable.import_generic`.
2360
2361	* Images are read alternatively in :func:`GSASIIIO.ReadImages`, which puts image info
2362	directly into the data tree.
2363
2364	* Images are reloaded with :func:`GSASIIIO.GetImageData`.
2365
2366	When reading an image, the ``Reader()`` routine in the ImportImage class
2367	should set:
2368
2369	* :attr:`Comments`: a list of strings (str),
2370	* :attr:`Npix`: the number of pixels in the image (int),
2371	* :attr:`Image`: the actual image as a numpy array (np.array)
2372	* :attr:`Data`: a dict defining image parameters (dict). Within this dict the following
2373	data items are needed:
2374
2375	* 'pixelSize': size of each pixel in microns (such as ``[200.,200.]``.
2376	* 'wavelength': wavelength in :math:`\\AA`.
2377	* 'distance': distance of detector from sample in cm.
2378	* 'center': uncalibrated center of beam on detector (such as ``[204.8,204.8]``.
2379	* 'size': size of image (such as ``[2048,2048]``).
2380	* 'ImageTag': image number or other keyword used to retrieve image from
2381	a multi-image data file (defaults to ``1`` if not specified).
2382	* 'sumfile': holds sum image file name if a sum was produced from a multi image file
2383
2384	optional data items:
2385
2386	* :attr:`repeat`: set to True if there are additional images to
2387	read in the file, False otherwise
2388	* :attr:`repeatcount`: set to the number of the image.
2389
2390	Note that the above is initialized with :meth:`InitParameters`.
2391	(Also see :ref:`Writing a Import Routine<import_routines>`
2392	for an explanation on how to use import classes in general.)
2393	'''
2394	def __init__(self,formatName,longFormatName=None,extensionlist=[],
2395	strictExtension=False,):
2396	ImportBaseclass.__init__(self,formatName,longFormatName,
2397	extensionlist,strictExtension)
2398	self.InitParameters()
2399
2400	def ReInitialize(self):
2401	'Reinitialize the Reader to initial settings -- not used at present'
2402	ImportBaseclass.ReInitialize(self)
2403	self.InitParameters()
2404
2405	def InitParameters(self):
2406	'initialize the instrument parameters structure'
2407	self.Comments = ['No comments']
2408	self.Data = {}
2409	self.Npix = 0
2410	self.Image = None
2411	self.repeat = False
2412	self.repeatcount = 1
2413	self.sumfile = ''
2414
2415	def LoadImage(self,ParentFrame,imagefile,imagetag=None):
2416	'''Optionally, call this after reading in an image to load it into the tree.
2417	This saves time by preventing a reread of the same information.
2418	'''
2419	if ParentFrame:
2420	ParentFrame.ImageZ = self.Image # store the image for plotting
2421	ParentFrame.oldImagefile = imagefile # save the name of the last image file read
2422	ParentFrame.oldImageTag = imagetag # save the tag of the last image file read
2423
2424	#################################################################################################
2425	# shortcut routines
2426	exp = np.exp
2427	sind = sin = s = lambda x: np.sin(x*np.pi/180.)
2428	cosd = cos = c = lambda x: np.cos(x*np.pi/180.)
2429	tand = tan = t = lambda x: np.tan(x*np.pi/180.)
2430	sqrt = sq = lambda x: np.sqrt(x)
2431	pi = lambda: np.pi
2432	class ExpressionObj(object):
2433	'''Defines an object with a user-defined expression, to be used for
2434	secondary fits or restraints. Object is created null, but is changed
2435	using :meth:`LoadExpression`. This contains only the minimum
2436	information that needs to be stored to save and load the expression
2437	and how it is mapped to GSAS-II variables.
2438	'''
2439	def __init__(self):
2440	self.expression = ''
2441	'The expression as a text string'
2442	self.assgnVars = {}
2443	'''A dict where keys are label names in the expression mapping to a GSAS-II
2444	variable. The value a G2 variable name.
2445	Note that the G2 variable name may contain a wild-card and correspond to
2446	multiple values.
2447	'''
2448	self.freeVars = {}
2449	'''A dict where keys are label names in the expression mapping to a free
2450	parameter. The value is a list with:
2451
2452	* a name assigned to the parameter
2453	* a value for to the parameter and
2454	* a flag to determine if the variable is refined.
2455	'''
2456	self.depVar = None
2457
2458	self.lastError = ('','')
2459	'''Shows last encountered error in processing expression
2460	(list of 1-3 str values)'''
2461
2462	self.distance_dict = None # to be used for defining atom phase/symmetry info
2463	self.distance_atoms = None # to be used for defining atom distances
2464
2465	def LoadExpression(self,expr,exprVarLst,varSelect,varName,varValue,varRefflag):
2466	'''Load the expression and associated settings into the object. Raises
2467	an exception if the expression is not parsed, if not all functions
2468	are defined or if not all needed parameter labels in the expression
2469	are defined.
2470
2471	This will not test if the variable referenced in these definitions
2472	are actually in the parameter dictionary. This is checked when the
2473	computation for the expression is done in :meth:`SetupCalc`.
2474
2475	:param str expr: the expression
2476	:param list exprVarLst: parameter labels found in the expression
2477	:param dict varSelect: this will be 0 for Free parameters
2478	and non-zero for expression labels linked to G2 variables.
2479	:param dict varName: Defines a name (str) associated with each free parameter
2480	:param dict varValue: Defines a value (float) associated with each free parameter
2481	:param dict varRefflag: Defines a refinement flag (bool)
2482	associated with each free parameter
2483	'''
2484	self.expression = expr
2485	self.compiledExpr = None
2486	self.freeVars = {}
2487	self.assgnVars = {}
2488	for v in exprVarLst:
2489	if varSelect[v] == 0:
2490	self.freeVars[v] = [
2491	varName.get(v),
2492	varValue.get(v),
2493	varRefflag.get(v),
2494	]
2495	else:
2496	self.assgnVars[v] = varName[v]
2497	self.CheckVars()
2498
2499	def EditExpression(self,exprVarLst,varSelect,varName,varValue,varRefflag):
2500	'''Load the expression and associated settings from the object into
2501	arrays used for editing.
2502
2503	:param list exprVarLst: parameter labels found in the expression
2504	:param dict varSelect: this will be 0 for Free parameters
2505	and non-zero for expression labels linked to G2 variables.
2506	:param dict varName: Defines a name (str) associated with each free parameter
2507	:param dict varValue: Defines a value (float) associated with each free parameter
2508	:param dict varRefflag: Defines a refinement flag (bool)
2509	associated with each free parameter
2510
2511	:returns: the expression as a str
2512	'''
2513	for v in self.freeVars:
2514	varSelect[v] = 0
2515	varName[v] = self.freeVars[v][0]
2516	varValue[v] = self.freeVars[v][1]
2517	varRefflag[v] = self.freeVars[v][2]
2518	for v in self.assgnVars:
2519	varSelect[v] = 1
2520	varName[v] = self.assgnVars[v]
2521	return self.expression
2522
2523	def GetVaried(self):
2524	'Returns the names of the free parameters that will be refined'
2525	return ["::"+self.freeVars[v][0] for v in self.freeVars if self.freeVars[v][2]]
2526
2527	def GetVariedVarVal(self):
2528	'Returns the names and values of the free parameters that will be refined'
2529	return [("::"+self.freeVars[v][0],self.freeVars[v][1]) for v in self.freeVars if self.freeVars[v][2]]
2530
2531	def UpdateVariedVars(self,varyList,values):
2532	'Updates values for the free parameters (after a refinement); only updates refined vars'
2533	for v in self.freeVars:
2534	if not self.freeVars[v][2]: continue
2535	if "::"+self.freeVars[v][0] not in varyList: continue
2536	indx = list(varyList).index("::"+self.freeVars[v][0])
2537	self.freeVars[v][1] = values[indx]
2538
2539	def GetIndependentVars(self):
2540	'Returns the names of the required independent parameters used in expression'
2541	return [self.assgnVars[v] for v in self.assgnVars]
2542
2543	def CheckVars(self):
2544	'''Check that the expression can be parsed, all functions are
2545	defined and that input loaded into the object is internally
2546	consistent. If not an Exception is raised.
2547
2548	:returns: a dict with references to packages needed to
2549	find functions referenced in the expression.
2550	'''
2551	ret = self.ParseExpression(self.expression)
2552	if not ret:
2553	raise Exception("Expression parse error")
2554	exprLblList,fxnpkgdict = ret
2555	# check each var used in expression is defined
2556	defined = list(self.assgnVars.keys()) + list(self.freeVars.keys())
2557	notfound = []
2558	for var in exprLblList:
2559	if var not in defined:
2560	notfound.append(var)
2561	if notfound:
2562	msg = 'Not all variables defined'
2563	msg1 = 'The following variables were not defined: '
2564	msg2 = ''
2565	for var in notfound:
2566	if msg: msg += ', '
2567	msg += var
2568	self.lastError = (msg1,' '+msg2)
2569	raise Exception(msg)
2570	return fxnpkgdict
2571
2572	def ParseExpression(self,expr):
2573	'''Parse an expression and return a dict of called functions and
2574	the variables used in the expression. Returns None in case an error
2575	is encountered. If packages are referenced in functions, they are loaded
2576	and the functions are looked up into the modules global
2577	workspace.
2578
2579	Note that no changes are made to the object other than
2580	saving an error message, so that this can be used for testing prior
2581	to the save.
2582
2583	:returns: a list of used variables
2584	'''
2585	self.lastError = ('','')
2586	import ast
2587	def FindFunction(f):
2588	'''Find the object corresponding to function f
2589	:param str f: a function name such as 'numpy.exp'
2590	:returns: (pkgdict,pkgobj) where pkgdict contains a dict
2591	that defines the package location(s) and where pkgobj
2592	defines the object associated with the function.
2593	If the function is not found, pkgobj is None.
2594	'''
2595	df = f.split('.')
2596	pkgdict = {}
2597	# no listed package, try in current namespace
2598	if len(df) == 1:
2599	try:
2600	fxnobj = eval(f)
2601	return pkgdict,fxnobj
2602	except (AttributeError, NameError):
2603	return None,None
2604	else:
2605	try:
2606	fxnobj = eval(f)
2607	pkgdict[df[0]] = eval(df[0])
2608	return pkgdict,fxnobj
2609	except (AttributeError, NameError):
2610	pass
2611	# includes a package, lets try to load the packages
2612	pkgname = ''
2613	path = sys.path+['./',]
2614	for pkg in f.split('.')[:-1]: # if needed, descend down the tree
2615	if pkgname:
2616	pkgname += '.' + pkg
2617	else:
2618	pkgname = pkg
2619	fp = None
2620	try:
2621	fp, fppath,desc = imp.find_module(pkg,path)
2622	pkgobj = imp.load_module(pkg,fp,fppath,desc)
2623	pkgdict[pkgname] = pkgobj
2624	path = [fppath]
2625	except Exception as msg:
2626	print('load of '+pkgname+' failed with error='+str(msg))
2627	return {},None
2628	finally:
2629	if fp: fp.close()
2630	try:
2631	#print 'before',pkgdict.keys()
2632	fxnobj = eval(f,globals(),pkgdict)
2633	#print 'after 1',pkgdict.keys()
2634	#fxnobj = eval(f,pkgdict)
2635	#print 'after 2',pkgdict.keys()
2636	return pkgdict,fxnobj
2637	except:
2638	continue
2639	return None # not found
2640	def ASTtransverse(node,fxn=False):
2641	'''Transverse a AST-parsed expresson, compiling a list of variables
2642	referenced in the expression. This routine is used recursively.
2643
2644	:returns: varlist,fxnlist where
2645	varlist is a list of referenced variable names and
2646	fxnlist is a list of used functions
2647	'''
2648	varlist = []
2649	fxnlist = []
2650	if isinstance(node, list):
2651	for b in node:
2652	v,f = ASTtransverse(b,fxn)
2653	varlist += v
2654	fxnlist += f
2655	elif isinstance(node, ast.AST):
2656	for a, b in ast.iter_fields(node):
2657	if isinstance(b, ast.AST):
2658	if a == 'func':
2659	fxnlist += ['.'.join(ASTtransverse(b,True)[0])]
2660	continue
2661	v,f = ASTtransverse(b,fxn)
2662	varlist += v
2663	fxnlist += f
2664	elif isinstance(b, list):
2665	v,f = ASTtransverse(b,fxn)
2666	varlist += v
2667	fxnlist += f
2668	elif node.__class__.__name__ == "Name":
2669	varlist += [b]
2670	elif fxn and node.__class__.__name__ == "Attribute":
2671	varlist += [b]
2672	return varlist,fxnlist
2673	try:
2674	exprast = ast.parse(expr)
2675	except SyntaxError:
2676	s = ''
2677	import traceback
2678	for i in traceback.format_exc().splitlines()[-3:-1]:
2679	if s: s += "\n"
2680	s += str(i)
2681	self.lastError = ("Error parsing expression:",s)
2682	return
2683	# find the variables & functions
2684	v,f = ASTtransverse(exprast)
2685	varlist = sorted(list(set(v)))
2686	fxnlist = list(set(f))
2687	pkgdict = {}
2688	# check the functions are defined
2689	for fxn in fxnlist:
2690	fxndict,fxnobj = FindFunction(fxn)
2691	if not fxnobj:
2692	self.lastError = ("Error: Invalid function",fxn,
2693	"is not defined")
2694	return
2695	if not hasattr(fxnobj,'__call__'):
2696	self.lastError = ("Error: Not a function.",fxn,
2697	"cannot be called as a function")
2698	return
2699	pkgdict.update(fxndict)
2700	return varlist,pkgdict
2701
2702	def GetDepVar(self):
2703	'return the dependent variable, or None'
2704	return self.depVar
2705
2706	def SetDepVar(self,var):
2707	'Set the dependent variable, if used'
2708	self.depVar = var
2709	#==========================================================================
2710	class ExpressionCalcObj(object):
2711	'''An object used to evaluate an expression from a :class:`ExpressionObj`
2712	object.
2713
2714	:param ExpressionObj exprObj: a :class:`~ExpressionObj` expression object with
2715	an expression string and mappings for the parameter labels in that object.
2716	'''
2717	def __init__(self,exprObj):
2718	self.eObj = exprObj
2719	'The expression and mappings; a :class:`ExpressionObj` object'
2720	self.compiledExpr = None
2721	'The expression as compiled byte-code'
2722	self.exprDict = {}
2723	'''dict that defines values for labels used in expression and packages
2724	referenced by functions
2725	'''
2726	self.lblLookup = {}
2727	'''Lookup table that specifies the expression label name that is
2728	tied to a particular GSAS-II parameters in the parmDict.
2729	'''
2730	self.fxnpkgdict = {}
2731	'''a dict with references to packages needed to
2732	find functions referenced in the expression.
2733	'''
2734	self.varLookup = {}
2735	'''Lookup table that specifies the GSAS-II variable(s)
2736	indexed by the expression label name. (Used for only for diagnostics
2737	not evaluation of expression.)
2738	'''
2739	self.su = None
2740	'''Standard error evaluation where supplied by the evaluator
2741	'''
2742	# Patch: for old-style expressions with a (now removed step size)
2743	if '2' in platform.python_version_tuple()[0]:
2744	basestr = basestring
2745	else:
2746	basestr = str
2747	for v in self.eObj.assgnVars:
2748	if not isinstance(self.eObj.assgnVars[v], basestr):
2749	self.eObj.assgnVars[v] = self.eObj.assgnVars[v][0]
2750	self.parmDict = {}
2751	'''A copy of the parameter dictionary, for distance and angle computation
2752	'''
2753
2754	def SetupCalc(self,parmDict):
2755	'''Do all preparations to use the expression for computation.
2756	Adds the free parameter values to the parameter dict (parmDict).
2757	'''
2758	if self.eObj.expression.startswith('Dist') or self.eObj.expression.startswith('Angle'):
2759	return
2760	self.fxnpkgdict = self.eObj.CheckVars()
2761	# all is OK, compile the expression
2762	self.compiledExpr = compile(self.eObj.expression,'','eval')
2763
2764	# look at first value in parmDict to determine its type
2765	parmsInList = True
2766	if '2' in platform.python_version_tuple()[0]:
2767	basestr = basestring
2768	else:
2769	basestr = str
2770	for key in parmDict:
2771	val = parmDict[key]
2772	if isinstance(val, basestr):
2773	parmsInList = False
2774	break
2775	try: # check if values are in lists
2776	val = parmDict[key][0]
2777	except (TypeError,IndexError):
2778	parmsInList = False
2779	break
2780
2781	# set up the dicts needed to speed computations
2782	self.exprDict = {}
2783	self.lblLookup = {}
2784	self.varLookup = {}
2785	for v in self.eObj.freeVars:
2786	varname = self.eObj.freeVars[v][0]
2787	varname = "::" + varname.lstrip(':').replace(' ','_').replace(':',';')
2788	self.lblLookup[varname] = v
2789	self.varLookup[v] = varname
2790	if parmsInList:
2791	parmDict[varname] = [self.eObj.freeVars[v][1],self.eObj.freeVars[v][2]]
2792	else:
2793	parmDict[varname] = self.eObj.freeVars[v][1]
2794	self.exprDict[v] = self.eObj.freeVars[v][1]
2795	for v in self.eObj.assgnVars:
2796	varname = self.eObj.assgnVars[v]
2797	if varname in parmDict:
2798	self.lblLookup[varname] = v
2799	self.varLookup[v] = varname
2800	if parmsInList:
2801	self.exprDict[v] = parmDict[varname][0]
2802	else:
2803	self.exprDict[v] = parmDict[varname]
2804	elif '*' in varname:
2805	varlist = LookupWildCard(varname,list(parmDict.keys()))
2806	if len(varlist) == 0:
2807	raise Exception("No variables match "+str(v))
2808	for var in varlist:
2809	self.lblLookup[var] = v
2810	if parmsInList:
2811	self.exprDict[v] = np.array([parmDict[var][0] for var in varlist])
2812	else:
2813	self.exprDict[v] = np.array([parmDict[var] for var in varlist])
2814	self.varLookup[v] = [var for var in varlist]
2815	else:
2816	self.exprDict[v] = None
2817	# raise Exception,"No value for variable "+str(v)
2818	self.exprDict.update(self.fxnpkgdict)
2819
2820	def UpdateVars(self,varList,valList):
2821	'''Update the dict for the expression with a set of values
2822	:param list varList: a list of variable names
2823	:param list valList: a list of corresponding values
2824	'''
2825	for var,val in zip(varList,valList):
2826	self.exprDict[self.lblLookup.get(var,'undefined: '+var)] = val
2827
2828	def UpdateDict(self,parmDict):
2829	'''Update the dict for the expression with values in a dict
2830	:param dict parmDict: a dict of values, items not in use are ignored
2831	'''
2832	if self.eObj.expression.startswith('Dist') or self.eObj.expression.startswith('Angle'):
2833	self.parmDict = parmDict
2834	return
2835	for var in parmDict:
2836	if var in self.lblLookup:
2837	self.exprDict[self.lblLookup[var]] = parmDict[var]
2838
2839	def EvalExpression(self):
2840	'''Evaluate an expression. Note that the expression
2841	and mapping are taken from the :class:`ExpressionObj` expression object
2842	and the parameter values were specified in :meth:`SetupCalc`.
2843	:returns: a single value for the expression. If parameter
2844	values are arrays (for example, from wild-carded variable names),
2845	the sum of the resulting expression is returned.
2846
2847	For example, if the expression is ``'A*B'``,
2848	where A is 2.0 and B maps to ``'1::Afrac:*'``, which evaluates to::
2849
2850	[0.5, 1, 0.5]
2851
2852	then the result will be ``4.0``.
2853	'''
2854	self.su = None
2855	if self.eObj.expression.startswith('Dist'):
2856	# GSASIIpath.IPyBreak()
2857	dist = G2mth.CalcDist(self.eObj.distance_dict, self.eObj.distance_atoms, self.parmDict)
2858	return dist
2859	elif self.eObj.expression.startswith('Angle'):
2860	angle = G2mth.CalcAngle(self.eObj.angle_dict, self.eObj.angle_atoms, self.parmDict)
2861	return angle
2862	if self.compiledExpr is None:
2863	raise Exception("EvalExpression called before SetupCalc")
2864	try:
2865	val = eval(self.compiledExpr,globals(),self.exprDict)
2866	except TypeError:
2867	val = None
2868	if not np.isscalar(val):
2869	val = np.sum(val)
2870	return val
2871
2872	class G2Exception(Exception):
2873	'A generic GSAS-II exception class'
2874	def __init__(self,msg):
2875	self.msg = msg
2876	def __str__(self):
2877	return repr(self.msg)
2878
2879	class G2RefineCancel(Exception):
2880	'Raised when Cancel is pressed in a refinement dialog'
2881	def __init__(self,msg):
2882	self.msg = msg
2883	def __str__(self):
2884	return repr(self.msg)
2885
2886	def HowDidIgetHere(wherecalledonly=False):
2887	'''Show a traceback with calls that brought us to the current location.
2888	Used for debugging.
2889	'''
2890	import traceback
2891	if wherecalledonly:
2892	i = traceback.format_list(traceback.extract_stack()[:-1])[-2]
2893	print(i.strip().rstrip())
2894	else:
2895	print (70'')
2896	for i in traceback.format_list(traceback.extract_stack()[:-1]): print(i.strip().rstrip())
2897	print (70'')
2898
2899	# Note that this is GUI code and should be moved at somepoint
2900	def CreatePDFitems(G2frame,PWDRtree,ElList,Qlimits,numAtm=1,FltBkg=0,PDFnames=[]):
2901	'''Create and initialize a new set of PDF tree entries
2902
2903	:param Frame G2frame: main GSAS-II tree frame object
2904	:param str PWDRtree: name of PWDR to be used to create PDF item
2905	:param dict ElList: data structure with composition
2906	:param list Qlimits: Q limits to be used for computing the PDF
2907	:param float numAtm: no. atom in chemical formula
2908	:param float FltBkg: flat background value
2909	:param list PDFnames: previously used PDF names
2910
2911	:returns: the Id of the newly created PDF entry
2912	'''
2913	PDFname = 'PDF '+PWDRtree[4:] # this places two spaces after PDF, which is needed is some places
2914	if PDFname in PDFnames:
2915	print('Skipping, entry already exists: '+PDFname)
2916	return None
2917	#PDFname = MakeUniqueLabel(PDFname,PDFnames)
2918	Id = G2frame.GPXtree.AppendItem(parent=G2frame.root,text=PDFname)
2919	Data = {
2920	'Sample':{'Name':PWDRtree,'Mult':1.0},
2921	'Sample Bkg.':{'Name':'','Mult':-1.0,'Refine':False},
2922	'Container':{'Name':'','Mult':-1.0,'Refine':False},
2923	'Container Bkg.':{'Name':'','Mult':-1.0},'ElList':ElList,
2924	'Geometry':'Cylinder','Diam':1.0,'Pack':0.50,'Form Vol':10.0*numAtm,'Flat Bkg':FltBkg,
2925	'DetType':'Area detector','ObliqCoeff':0.2,'Ruland':0.025,'QScaleLim':Qlimits,
2926	'Lorch':False,'BackRatio':0.0,'Rmax':100.,'noRing':False,'IofQmin':1.0,'Rmin':1.0,
2927	'I(Q)':[],'S(Q)':[],'F(Q)':[],'G(R)':[]}
2928	G2frame.GPXtree.SetItemPyData(G2frame.GPXtree.AppendItem(Id,text='PDF Controls'),Data)
2929	G2frame.GPXtree.SetItemPyData(G2frame.GPXtree.AppendItem(Id,text='PDF Peaks'),
2930	{'Limits':[1.,5.],'Background':[2,[0.,-0.2*np.pi],False],'Peaks':[]})
2931	return Id
2932	#%%
2933	class ShowTiming(object):
2934	'''An object to use for timing repeated sections of code.
2935
2936	Create the object with::
2937	tim0 = ShowTiming()
2938
2939	Tag sections of code to be timed with::
2940	tim0.start('start')
2941	tim0.start('in section 1')
2942	tim0.start('in section 2')
2943
2944	etc. (Note that each section should have a unique label.)
2945
2946	After the last section, end timing with::
2947	tim0.end()
2948
2949	Show timing results with::
2950	tim0.show()
2951
2952	'''
2953	def __init__(self):
2954	self.timeSum = []
2955	self.timeStart = []
2956	self.label = []
2957	self.prev = None
2958	def start(self,label):
2959	import time
2960	if label in self.label:
2961	i = self.label.index(label)
2962	self.timeStart[i] = time.time()
2963	else:
2964	i = len(self.label)
2965	self.timeSum.append(0.0)
2966	self.timeStart.append(time.time())
2967	self.label.append(label)
2968	if self.prev is not None:
2969	self.timeSum[self.prev] += self.timeStart[i] - self.timeStart[self.prev]
2970	self.prev = i
2971	def end(self):
2972	import time
2973	if self.prev is not None:
2974	self.timeSum[self.prev] += time.time() - self.timeStart[self.prev]
2975	self.prev = None
2976	def show(self):
2977	sumT = sum(self.timeSum)
2978	print('Timing results (total={:.2f} sec)'.format(sumT))
2979	for i,(lbl,val) in enumerate(zip(self.label,self.timeSum)):
2980	print('{} {:20} {:8.2f} ms {:5.2f}%'.format(i,lbl,1000.val,100val/sumT))
2981	#%%
2982
2983	if __name__ == "__main__":
2984	# test variable descriptions
2985	for var in '0::Afrac:*',':1:Scale','1::dAx:0','::undefined':
2986	v = var.split(':')[2]
2987	print(var+':\t', getDescr(v),getVarStep(v))
2988	import sys; sys.exit()
2989	# test equation evaluation
2990	def showEQ(calcobj):
2991	print (50*'=')
2992	print (calcobj.eObj.expression+'='+calcobj.EvalExpression())
2993	for v in sorted(calcobj.varLookup):
2994	print (" "+v+'='+calcobj.exprDict[v]+'='+calcobj.varLookup[v])
2995	# print ' Derivatives'
2996	# for v in calcobj.derivStep.keys():
2997	# print ' d(Expr)/d('+v+') =',calcobj.EvalDeriv(v)
2998
2999	obj = ExpressionObj()
3000
3001	obj.expression = "A*np.exp(B)"
3002	obj.assgnVars = {'B': '0::Afrac:1'}
3003	obj.freeVars = {'A': [u'A', 0.5, True]}
3004	#obj.CheckVars()
3005	calcobj = ExpressionCalcObj(obj)
3006
3007	obj1 = ExpressionObj()
3008	obj1.expression = "A*np.exp(B)"
3009	obj1.assgnVars = {'B': '0::Afrac:*'}
3010	obj1.freeVars = {'A': [u'Free Prm A', 0.5, True]}
3011	#obj.CheckVars()
3012	calcobj1 = ExpressionCalcObj(obj1)
3013
3014	obj2 = ExpressionObj()
3015	obj2.distance_stuff = np.array([[0,1],[1,-1]])
3016	obj2.expression = "Dist(1,2)"
3017	GSASIIpath.InvokeDebugOpts()
3018	parmDict2 = {'0::Afrac:0':[0.0,True], '0::Afrac:1': [1.0,False]}
3019	calcobj2 = ExpressionCalcObj(obj2)
3020	calcobj2.SetupCalc(parmDict2)
3021	showEQ(calcobj2)
3022
3023	parmDict1 = {'0::Afrac:0':1.0, '0::Afrac:1': 1.0}
3024	print ('\nDict = '+parmDict1)
3025	calcobj.SetupCalc(parmDict1)
3026	showEQ(calcobj)
3027	calcobj1.SetupCalc(parmDict1)
3028	showEQ(calcobj1)
3029
3030	parmDict2 = {'0::Afrac:0':[0.0,True], '0::Afrac:1': [1.0,False]}
3031	print ('Dict = '+parmDict2)
3032	calcobj.SetupCalc(parmDict2)
3033	showEQ(calcobj)
3034	calcobj1.SetupCalc(parmDict2)
3035	showEQ(calcobj1)
3036	calcobj2.SetupCalc(parmDict2)
3037	showEQ(calcobj2)

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

Download in other formats: