1 | # TODO: change this to assemble the look-up tables of atoms, phases and hists from the tree |
---|
2 | # and then save/unsave those values in __init__ & __str__, etc. |
---|
3 | |
---|
4 | ''' |
---|
5 | *GSASIIobj: Data objects* |
---|
6 | ========================= |
---|
7 | |
---|
8 | This module defines and/or documents the data structures used in GSAS-II. |
---|
9 | |
---|
10 | |
---|
11 | Constraints Tree Item |
---|
12 | ---------------------- |
---|
13 | |
---|
14 | .. _Constraints_table: |
---|
15 | |
---|
16 | .. index:: |
---|
17 | single: Constraints object description |
---|
18 | single: Data object descriptions; Constraints |
---|
19 | |
---|
20 | Constraints are stored in a dict, separated into groups. |
---|
21 | Note that parameter are named in the following pattern, |
---|
22 | p:h:<var>:n, where p is the phase number, h is the histogram number |
---|
23 | <var> is a variable name and n is the parameter number. |
---|
24 | If a parameter does not depend on a histogram or phase or is unnumbered, that |
---|
25 | number is omitted. |
---|
26 | Note that the contents of each dict item is a List where each element in the |
---|
27 | list is a :ref:`constraint definition objects <Constraint_definitions_table>`. |
---|
28 | |
---|
29 | The keys in the Constraints dict are: |
---|
30 | |
---|
31 | .. tabularcolumns:: |l|p{4.5in}| |
---|
32 | |
---|
33 | ========== ==================================================== |
---|
34 | key explanation |
---|
35 | ========== ==================================================== |
---|
36 | Hist This specifies a list of constraints on |
---|
37 | histogram-related parameters, |
---|
38 | which will be of form :h:<var>:n. |
---|
39 | HAP This specifies a list of constraints on parameters |
---|
40 | that are defined for every histogram in each phase |
---|
41 | and are of form p:h:<var>:n. |
---|
42 | Phase This specifies a list of constraints on phase |
---|
43 | parameters, |
---|
44 | which will be of form p::<var>:n. |
---|
45 | Global This specifies a list of constraints on parameters |
---|
46 | that are not tied to a histogram or phase and |
---|
47 | are of form ::<var>:n |
---|
48 | ========== ==================================================== |
---|
49 | |
---|
50 | .. _Constraint_definitions_table: |
---|
51 | |
---|
52 | .. index:: |
---|
53 | single: Constraint definition object description |
---|
54 | single: Data object descriptions; Constraint Definition |
---|
55 | |
---|
56 | Each constraint is defined as a list using a series of terms of form |
---|
57 | |
---|
58 | :: |
---|
59 | |
---|
60 | [[<mult1>, <var1>], [<mult2>, <var2>],..., <fixed val>, <vary flag>, <cons type>] |
---|
61 | |
---|
62 | Where the variable pair list item containing two values [<mult>, <var>], |
---|
63 | |
---|
64 | * <mult> is a multiplier for the constraint (float) |
---|
65 | * <var> is the name of the variable (str) (or to be implemented a :class:`VarName` object.) |
---|
66 | |
---|
67 | Note that the last three items in the list play a special role: |
---|
68 | |
---|
69 | * <fixed val> is the fixed value for a constraint equation or is None |
---|
70 | * <vary flag> is True, False or None and is intended to use to indicate if new variables |
---|
71 | should be refined. |
---|
72 | * <cons type> is one of four letters, 'e', 'c', 'h', 'f' that determines the type of constraint. |
---|
73 | |
---|
74 | * 'e' defines a set of equivalent variables. Only the first variable is refined (if the |
---|
75 | appropriate refine flag is set) and and all other equivalent variables in the list |
---|
76 | are generated from that variable. The vary flag for those variables is ignored. |
---|
77 | * 'c' defines a constraint equation of form, :math:`m_1 \\times var_1 + m_2 \\times var_2 + ... = c` |
---|
78 | * 'h' defines a variable to hold (not vary). Any variable on this list is not varied, even if its refinement |
---|
79 | flag is set. This is of particular value when needing to hold one or more variables in a set such as |
---|
80 | the reciprocal metric tensor or anisotropic displacement parameter. |
---|
81 | * 'f' defines a relationship to define a new variable according to relationship |
---|
82 | :math:`newvar = m_1 \\times var_1 + m_2 \\times var_2 + ...` |
---|
83 | |
---|
84 | Covariance Tree Item |
---|
85 | -------------------- |
---|
86 | |
---|
87 | .. _Covariance_table: |
---|
88 | |
---|
89 | .. index:: |
---|
90 | single: Covariance description |
---|
91 | single: Data object descriptions; Covariance |
---|
92 | |
---|
93 | The Covariance tree item has results from the last least-squares run. They |
---|
94 | are stored in a dict with these keys: |
---|
95 | |
---|
96 | .. tabularcolumns:: |l|l|p{4in}| |
---|
97 | |
---|
98 | ============= =============== ==================================================== |
---|
99 | key sub-key explanation |
---|
100 | ============= =============== ==================================================== |
---|
101 | newCellDict \ dict with lattice parameters computed by |
---|
102 | :func:`GSASIIstrMath.GetNewCellParms` (dict) |
---|
103 | title \ Name of gpx file(?) (str) |
---|
104 | variables \ Values for all N refined variables |
---|
105 | (list of float values, length N, |
---|
106 | ordered to match varyList) |
---|
107 | sig \ Uncertainty values for all N refined variables |
---|
108 | (list of float values, length N, |
---|
109 | ordered to match varyList) |
---|
110 | varyList \ List of directly refined variables |
---|
111 | (list of str values, length N) |
---|
112 | newAtomDict \ dict with atom position values computed in |
---|
113 | :func:`GSASIIstrMath.ApplyXYZshifts` (dict) |
---|
114 | Rvals \ R-factors, GOF, Marquardt value for last |
---|
115 | refinement cycle (dict) |
---|
116 | \ Nobs Number of observed data points (int) |
---|
117 | \ Rwp overall weighted profile R-factor (%, float) |
---|
118 | \ chisq sum[w*(Iobs-Icalc)**2] for all data |
---|
119 | note this is not the reduced chi squared (float) |
---|
120 | \ lamMax Marquardt value applied to Hessian diagonal |
---|
121 | (float) |
---|
122 | \ GOF The goodness-of-fit, aka square root of |
---|
123 | the reduced chi squared. (float) |
---|
124 | covMatrix \ The (NxN) covVariance matrix (np.array) |
---|
125 | ============= =============== ==================================================== |
---|
126 | |
---|
127 | Phase Tree Item |
---|
128 | ---------------- |
---|
129 | |
---|
130 | .. _Phase_table: |
---|
131 | |
---|
132 | .. index:: |
---|
133 | single: Phase object description |
---|
134 | single: Data object descriptions; Phase |
---|
135 | |
---|
136 | Phase information is stored in the GSAS-II data tree as children of the |
---|
137 | Phases item in a dict with keys: |
---|
138 | |
---|
139 | .. tabularcolumns:: |l|l|p{4in}| |
---|
140 | |
---|
141 | ========== =============== ==================================================== |
---|
142 | key sub-key explanation |
---|
143 | ========== =============== ==================================================== |
---|
144 | General \ Overall information for the phase (dict) |
---|
145 | \ AtomPtrs ? (list) |
---|
146 | \ F000X x-ray F(000) intensity (float) |
---|
147 | \ F000N neutron F(000) intensity (float) |
---|
148 | \ Mydir directory of current .gpx file (str) |
---|
149 | \ MCSA controls ? |
---|
150 | \ Cell List with 7 items: cell refinement flag (bool) |
---|
151 | a, b, c, (Angstrom, float) |
---|
152 | alpha, beta & gamma (degrees, float) |
---|
153 | \ Type for now 'nuclear' (str) |
---|
154 | \ Map dict of map parameters |
---|
155 | \ SH Texture dict of spherical harmonic preferred orientation |
---|
156 | parameters |
---|
157 | \ Isotope dict of isotopes for each atom type |
---|
158 | \ Isotopes dict of scattering lengths for each isotope |
---|
159 | combination for each element in phase |
---|
160 | \ Name phase name (str) |
---|
161 | \ SGData Space group details, |
---|
162 | as defined in :mod:`GSASIIspc` as :ref:`SGData definition <SGData_table>` |
---|
163 | \ Pawley neg wt Restraint value for negative Pawley intensities |
---|
164 | (float) |
---|
165 | \ Flip Charge flip controls dict? |
---|
166 | \ Data plot type ? |
---|
167 | \ Mass Mass of unit cell contents in g/mol |
---|
168 | \ POhkl March-Dollase preferred orientation direction |
---|
169 | \ Z ? |
---|
170 | \ vdWRadii ? |
---|
171 | \ Color Colors for atoms (list of (r,b,g) triplets) |
---|
172 | \ AtomTypes List of atom types |
---|
173 | \ AtomMass List of masses for atoms |
---|
174 | \ doPawley Flag for Pawley intensity extraction (bool) |
---|
175 | \ NoAtoms Number of atoms per unit cell of each type (dict) |
---|
176 | \ Pawley dmin maximum Q (as d-space) to use for Pawley |
---|
177 | extraction (float) |
---|
178 | \ BondRadii Radius for each atom used to compute |
---|
179 | interatomic distances (list of floats) |
---|
180 | \ AngleRadii Radius for each atom used to compute |
---|
181 | interatomic angles (list of floats) |
---|
182 | ranId \ unique random number Id for phase (int) |
---|
183 | pId \ ? (int) |
---|
184 | Atoms \ Atoms in phase as a list of lists. The outer list |
---|
185 | is for each atom, the inner list contains 18 |
---|
186 | items: |
---|
187 | 0) atom label, 1) the atom type, |
---|
188 | 2) the refinement flags, 3-6) x, y, z, frac |
---|
189 | 7) site symmetry, 8) site multiplicity, |
---|
190 | 9) 'I' or 'A' for iso/anisotropic, |
---|
191 | 10) Uiso, 10-16) Uij, 16) unique Id #. |
---|
192 | (list of lists) |
---|
193 | Drawing \ Display parameters (dict) |
---|
194 | \ ballScale Size of spheres in ball-and-stick display (float) |
---|
195 | \ bondList dict with bonds |
---|
196 | \ contourLevel ? (float) |
---|
197 | \ showABC Flag to show view point triplet (bool). True=show. |
---|
198 | \ viewDir cartesian viewing direction (np.array with three |
---|
199 | elements) |
---|
200 | \ Zclip clipping distance in A (float) |
---|
201 | \ backColor background for plot as and R,G,B triplet |
---|
202 | (default = [0, 0, 0], black). |
---|
203 | (list with three atoms) |
---|
204 | \ selectedAtoms List of selected atoms (list of int values) |
---|
205 | \ showRigidBodies Flag to highlight rigid body placement |
---|
206 | \ sizeH Size ratio for H atoms (float) |
---|
207 | \ bondRadius Size of binds in A (float) |
---|
208 | \ atomPtrs ? (list) |
---|
209 | \ viewPoint list of lists. First item in list is [x,y,z] |
---|
210 | in fractional coordinates for the center of |
---|
211 | the plot. Second item ?. |
---|
212 | \ showHydrogen Flag to control plotting of H atoms. |
---|
213 | \ unitCellBox Flag to control display of the unit cell. |
---|
214 | \ ellipseProb Probability limit for display of thermal |
---|
215 | ellipsoids in % (float). |
---|
216 | \ vdwScale Multiplier of van der Waals radius for |
---|
217 | display of vdW spheres. |
---|
218 | \ Atoms A list of lists with an entry for each atom |
---|
219 | that is plotted. |
---|
220 | \ Zstep Step to de/increase Z-clip (float) |
---|
221 | \ Quaternion Viewing quaternion (4 element np.array) |
---|
222 | \ radiusFactor Distance ratio for searching for bonds. ? Bonds |
---|
223 | are located that are within r(Ra+Rb) and (Ra+Rb)/r |
---|
224 | where Ra and Rb are the atomic radii. |
---|
225 | \ oldxy ? (list with two floats) |
---|
226 | \ cameraPos Viewing position in A for plot (float) |
---|
227 | \ depthFog ? (bool) |
---|
228 | RBModels \ Rigid body assignments (note Rigid body definitions |
---|
229 | are stored in their own main top-level tree entry.) |
---|
230 | Pawley ref \ Pawley reflections |
---|
231 | Histograms \ A dict of dicts. The key for the outer dict is |
---|
232 | the histograms tied to this phase. The inner |
---|
233 | dict contains the combined phase/histogram |
---|
234 | parameters for items such as scale factors, |
---|
235 | size and strain parameters. (dict) |
---|
236 | MCSA \ Monte-Carlo simulated annealing parameters |
---|
237 | ========== =============== ==================================================== |
---|
238 | |
---|
239 | Space Group Objects |
---|
240 | ------------------- |
---|
241 | |
---|
242 | .. _SGData_table: |
---|
243 | |
---|
244 | .. index:: |
---|
245 | single: SGData description |
---|
246 | single: Data object descriptions; SGData |
---|
247 | |
---|
248 | Space groups are interpreted by :func:`GSASIIspc.SpcGroup` |
---|
249 | and the information is placed in a SGdata object, |
---|
250 | which is a dict with these keys: |
---|
251 | |
---|
252 | .. tabularcolumns:: |l|p{4.5in}| |
---|
253 | |
---|
254 | ========== ==================================================== |
---|
255 | key explanation |
---|
256 | ========== ==================================================== |
---|
257 | SpGrp space group symbol (str) |
---|
258 | Laue one of the following 14 Laue classes: |
---|
259 | -1, 2/m, mmm, 4/m, 4/mmm, 3R, |
---|
260 | 3mR, 3, 3m1, 31m, 6/m, 6/mmm, m3, m3m (str) |
---|
261 | SGInv True if centrosymmetric, False if not (bool) |
---|
262 | SGLatt Lattice centering type. Will be one of |
---|
263 | P, A, B, C, I, F, R (str) |
---|
264 | SGUniq unique axis if monoclinic. Will be |
---|
265 | a, b, or c for monoclinic space groups. |
---|
266 | Will be blank for non-monoclinic. (str) |
---|
267 | SGCen Symmetry cell centering vectors. A (n,3) np.array |
---|
268 | of centers. Will always have at least one row: |
---|
269 | ``np.array([[0, 0, 0]])`` |
---|
270 | SGOps symmetry operations as a list of form |
---|
271 | ``[[M1,T1], [M2,T2],...]`` |
---|
272 | where :math:`M_n` is a 3x3 np.array |
---|
273 | and :math:`T_n` is a length 3 np.array. |
---|
274 | Atom coordinates are transformed where the |
---|
275 | Asymmetric unit coordinates [X is (x,y,z)] |
---|
276 | are transformed using |
---|
277 | :math:`X\prime = M_n*X+T_n` |
---|
278 | SGSys symmetry unit cell: type one of |
---|
279 | 'triclinic', 'monoclinic', 'orthorhombic', |
---|
280 | 'tetragonal', 'rhombohedral', 'trigonal', |
---|
281 | 'hexagonal', 'cubic' (str) |
---|
282 | SGPolax Axes for space group polarity. Will be one of |
---|
283 | '', 'x', 'y', 'x y', 'z', 'x z', 'y z', |
---|
284 | 'xyz'. In the case where axes are arbitrary |
---|
285 | '111' is used (P 1, and ?). |
---|
286 | ========== ==================================================== |
---|
287 | |
---|
288 | ''' |
---|
289 | |
---|
290 | def LoadHistogramIDs(histList,idList): |
---|
291 | '''Save the Id values for a series of histograms''' |
---|
292 | VarName.IDdict['hists'] = {} |
---|
293 | for h,i in zip(histList,idList): |
---|
294 | VarName.IDdict['hists'][i] = h |
---|
295 | |
---|
296 | def LoadPhaseIDs(self): |
---|
297 | pass |
---|
298 | |
---|
299 | class VarName(object): |
---|
300 | '''Defines a GSAS-II variable either using the phase/atom/histogram |
---|
301 | unique Id numbers or using a character string that specifies |
---|
302 | variables by phase/atom/histogram number (which can change). |
---|
303 | Note that :func:`LoadID` should be used to (re)load the current Ids |
---|
304 | before creating or later using the VarName object. |
---|
305 | |
---|
306 | A :class:`VarName` object can be created with a single parameter: |
---|
307 | |
---|
308 | :param str varname: a single value can be used to create a :class:`VarName` |
---|
309 | object. The string must be of form "p:h:var" or "p:h:var:a", where |
---|
310 | |
---|
311 | * p is the phase number (which may be left blank); |
---|
312 | * h is the histogram number (which may be left blank); |
---|
313 | * a is the atom number (which may be left blank in which case the third colon is omitted). |
---|
314 | |
---|
315 | Alternately, a :class:`VarName` object can be created with exactly four positional parameters: |
---|
316 | |
---|
317 | :param int phasenum: The number for the phase |
---|
318 | :param int histnum: The number for the histogram |
---|
319 | :param str varname: a single value can be used to create a :class:`VarName` |
---|
320 | :param int atomnum: The number for the atom |
---|
321 | |
---|
322 | ''' |
---|
323 | IDdict = {} |
---|
324 | IDdict['phases'] = {} |
---|
325 | IDdict['hists'] = {} |
---|
326 | IDdict['atoms'] = {} |
---|
327 | # This dictionary lists descriptions for GSAS-II variables. |
---|
328 | # Note that keys may contain regular expressions, where '[xyz]' |
---|
329 | # matches 'x' 'y' or 'z' (equivalently '[x-z]' describes this as range of values). |
---|
330 | # '.*' matches any string |
---|
331 | VarDesc = { |
---|
332 | # Phase vars (p::<var>) |
---|
333 | 'A[0-5]' : 'Reciprocal metric tensor component', |
---|
334 | 'Vol' : 'Unit cell volume????', |
---|
335 | # Atom vars (p::<var>:a) |
---|
336 | 'dA[xyz]' : 'change to atomic position', |
---|
337 | 'AUiso':'Atomic isotropic displacement parameter', |
---|
338 | 'AU[123][123]':'Atomic anisotropic displacement parameter', |
---|
339 | 'AFrac': 'Atomic occupancy parameter', |
---|
340 | # Hist & Phase (HAP) vars (p:h:<var>) |
---|
341 | 'Bab[AU]': 'Babinet solvent scattering coef.', |
---|
342 | 'D[123][123]' : 'Anisotropic strain coef.', |
---|
343 | 'Extinction' : 'Extinction coef.', |
---|
344 | 'MD' : 'March-Dollase coef.', |
---|
345 | 'Mustrain;.*' : 'Microstrain coef.', |
---|
346 | 'Scale' : 'Phase scale factor', |
---|
347 | 'Size;.*' : 'Crystallite size value', |
---|
348 | 'eA' : '?', |
---|
349 | #Histogram vars (:h:<var>) |
---|
350 | 'Absorption' : 'Absorption coef.', |
---|
351 | 'Displace[XY]' : 'Debye-Scherrer sample displacement', |
---|
352 | 'Lam' : 'Wavelength', |
---|
353 | 'Polariz' : 'Polarization correction', |
---|
354 | 'SH/L' : 'FCJ peak asymmetry correction', |
---|
355 | 'Scale' : 'Histogram scale factor', |
---|
356 | '[UVW]' : 'Gaussian instrument broadening', |
---|
357 | '[XY]' : 'Cauchy instrument broadening', |
---|
358 | 'Zero' : 'Debye-Scherrer zero correction', |
---|
359 | 'nDebye' : 'Debye model background corr. terms', |
---|
360 | 'nPeaks' : 'Fixed peak background corr. terms', |
---|
361 | # Global vars (::<var>) |
---|
362 | } |
---|
363 | def __init__(self,*args): |
---|
364 | self.phase = None |
---|
365 | self.histogram = None |
---|
366 | self.name = '' |
---|
367 | self.atom = None |
---|
368 | if len(args) == 1: |
---|
369 | lst = args[0].split(':') |
---|
370 | raise Exception, "Need to look up IDs" |
---|
371 | self.phase = lst[0] |
---|
372 | self.histogram = lst[1] |
---|
373 | self.name = lst[2] |
---|
374 | if len(lst) > 3: |
---|
375 | self.atom = lst[3] |
---|
376 | elif len(args) == 4: |
---|
377 | self.phase = args[0] |
---|
378 | self.histogram = args[1] |
---|
379 | self.name = args[2] |
---|
380 | self.atom = args[3] |
---|
381 | else: |
---|
382 | raise Exception,"Incorrectly called GSAS-II parameter name" |
---|
383 | |
---|
384 | def __str__(self): |
---|
385 | return self.name() |
---|
386 | |
---|
387 | def name(self): |
---|
388 | '''Formats the GSAS-II variable name as a "traditional" string (p:h:<var>:a) |
---|
389 | |
---|
390 | :returns: the variable name as a str |
---|
391 | ''' |
---|
392 | def _fmt(val): |
---|
393 | if val is None: |
---|
394 | return "" |
---|
395 | return str(val) |
---|
396 | return _fmt(self.phase) + ":" + _fmt(self.histogram) + _fmt(self.name) + _fmt(self.atom) |
---|
397 | |
---|
398 | def __repr__(self): |
---|
399 | '''Return the detailed contents of the object |
---|
400 | ''' |
---|
401 | s = "" |
---|
402 | if self.phase: |
---|
403 | s += "Phase: " + str(self.phase) + "; " |
---|
404 | |
---|
405 | if self.histogram: |
---|
406 | s += "Histogram: " + str(self.histogram) + "; " |
---|
407 | |
---|
408 | if self.name: |
---|
409 | s += "Variable name: " + str(self.name) + "; " |
---|
410 | |
---|
411 | if self.atom: |
---|
412 | s += "Atom number: " + str(self.atom) + "; " |
---|
413 | |
---|
414 | return s+"("+self.name()+")" |
---|
415 | |
---|
416 | def getDescr(self): |
---|
417 | '''Return a short description for a GSAS-II variable |
---|
418 | |
---|
419 | :returns: a short description or 'no definition' if not found |
---|
420 | ''' |
---|
421 | # iterating over uncompiled regular expressions is not terribly fast, |
---|
422 | # but this routine should not need to be all that speedy |
---|
423 | for key in self.VarDesc: |
---|
424 | if re.match(key, self.name): |
---|
425 | return self.VarDesc[key] |
---|
426 | return 'no definition' |
---|
427 | |
---|
428 | def getDescr(self): |
---|
429 | '''Return a short description for a GSAS-II variable |
---|
430 | |
---|
431 | :returns: a short description or 'no definition' if not found |
---|
432 | ''' |
---|
433 | # iterating over uncompiled regular expressions is not terribly fast, |
---|
434 | # but this routine should not need to be all that speedy |
---|
435 | for key in self.VarDesc: |
---|
436 | if re.match(key, self.name): |
---|
437 | return self.VarDesc[key] |
---|
438 | return 'no definition' |
---|
439 | |
---|
440 | def fullDescr(self): |
---|
441 | '''Return a longer description for a GSAS-II variable |
---|
442 | |
---|
443 | :returns: a short description or 'no definition' if not found |
---|
444 | ''' |
---|
445 | # iterating over uncompiled regular expressions is not terribly fast, |
---|
446 | # but this routine should not need to be all that speedy |
---|
447 | str = self.name() |
---|
448 | |
---|
449 | for key in self.VarDesc: |
---|
450 | if re.match(key, self.name): |
---|
451 | return self.VarDesc[key] |
---|
452 | return 'no definition' |
---|
453 | |
---|
454 | |
---|
455 | def _show(self): |
---|
456 | 'For testing, shows the current lookup table' |
---|
457 | print 'phases', self.IDdict['phases'] |
---|
458 | print 'hists', self.IDdict['hists'] |
---|
459 | print 'atomDict', self.IDdict['atoms'] |
---|
460 | |
---|