source: trunk/docs/source/GSASIIobj.rst

Last change on this file was 5578, checked in by toby, 4 weeks ago

add other .py files to Sphinx docs

File size: 82.5 KB
1*GSASIIobj: Data objects & Docs*
7This module defines and/or documents the data structures used in GSAS-II, as well
8as provides misc. support routines.
10.. contents:: Section Contents
12.. index::
13   single: Parameter names
14   single: GSAS-II variable naming
16.. _VarNames_table:
18Variable names in GSAS-II
21Parameter are named using the following pattern,
22``p:h:<var>:n``, where ``<var>`` is a variable name, as shown in the following table. Also,
23``p`` is the phase number, ``h`` is the histogram number,
24and ``n`` is the atom parameter number
25If a parameter does not depend on a histogram, phase or atom, ``h``, ``p`` and/or ``n`` will be omitted,
26so ``p::<var>:n``, ``:h:<var>`` and ``p:h:<var>`` are all valid names.
28.. include:: vars.rst
30.. _Constraints_table:
32.. index::
33   single: Constraints object description
34   single: Data object descriptions; Constraints
36Constraints Tree Item
39Constraints are stored in a dict, separated into groups.
40Note that parameter are named in the following pattern,
41p:h:<var>:n, where p is the phase number, h is the histogram number
42<var> is a variable name and n is the parameter number.
43If a parameter does not depend on a histogram or phase or is unnumbered, that
44number is omitted.
45Note that the contents of each dict item is a List where each element in the
46list is a :ref:`constraint definition objects <Constraint_definitions_table>`.
47The constraints in this form are converted in
48:func:`GSASIImapvars.ProcessConstraints` to the form used in :mod:`GSASIImapvars`
50The keys in the Constraints dict are:
52.. tabularcolumns:: |l|p{4.5in}|
54==========  ====================================================
55  key         explanation
56==========  ====================================================
57Hist        This specifies a list of constraints on
58            histogram-related parameters,
59            which will be of form :h:<var>:n.
60HAP         This specifies a list of constraints on parameters
61            that are defined for every histogram in each phase
62            and are of form p:h:<var>:n.
63Phase       This specifies a list of constraints on phase
64            parameters,
65            which will be of form p::<var>:n.
66Global      This specifies a list of constraints on parameters
67            that are not tied to a histogram or phase and
68            are of form ::<var>:n
69==========  ====================================================
71.. _Constraint_definitions_table:
73.. index::
74   single: Constraint definition object description
75   single: Data object descriptions; Constraint Definition
77Each constraint is defined as an item in a list. Each constraint is of form::
79[[<mult1>, <var1>], [<mult2>, <var2>],..., <fixedval>, <varyflag>, <constype>]
81Where the variable pair list item containing two values [<mult>, <var>], where:
83  * <mult> is a multiplier for the constraint (float)
84  * <var> a :class:`G2VarObj` object. (Note that in very old .gpx files this might be a str with a variable name of form 'p:h:name[:at]')
86Note that the last three items in the list play a special role:
88 * <fixedval> is the fixed value for a `constant equation` (``constype=c``)
89   constraint or is None. For a `New variable` (``constype=f``) constraint,
90   a variable name can be specified as a str (used for externally
91   generated constraints)
92 * <varyflag> is True or False for `New variable` (``constype=f``) constraints
93   or is None. This indicates if this variable should be refined.
94 * <constype> is one of four letters, 'e', 'c', 'h', 'f' that determines the type of constraint:
96    * 'e' defines a set of equivalent variables. Only the first variable is refined (if the
97      appropriate refine flag is set) and and all other equivalent variables in the list
98      are generated from that variable, using the appropriate multipliers.
99    * 'c' defines a constraint equation of form,
100      :math:`m_1 \times var_1 + m_2 \times var_2 + ... = c`
101    * 'h' defines a variable to hold (not vary). Any variable on this list is not varied,
102      even if its refinement flag is set. Only one [mult,var] pair is allowed in a hold
103      constraint and the mult value is ignored.
104      This is of particular value when needing to hold one or more variables where a
105      single flag controls a set of variables such as, coordinates,
106      the reciprocal metric tensor or anisotropic displacement parameter.
107    * 'f' defines a new variable (function) according to relationship
108      :math:`newvar = m_1 \times var_1 + m_2 \times var_2 + ...`
110.. _Covariance_table:
112.. index::
113   single: Covariance description
114   single: Data object descriptions; Covariance
116Covariance Tree Item
119The Covariance tree item has results from the last least-squares run. They
120are stored in a dict with these keys:
122.. tabularcolumns:: |l|l|p{4in}|
124=============  ===============  ====================================================
125  key            sub-key        explanation
126=============  ===============  ====================================================
127newCellDict    \                (dict) ith lattice parameters computed by
128                                :func:`GSASIIstrMath.GetNewCellParms`
129title          \                (str) Name of gpx file(?)
130variables      \                (list) Values for all N refined variables
131                                (list of float values, length N,
132                                ordered to match varyList)
133sig            \                (list) Uncertainty values for all N refined variables
134                                (list of float values, length N,
135                                ordered to match varyList)
136varyList       \                (list of str values, length N) List of directly refined variables
138newAtomDict    \                (dict) atom position values computed in
139                                :func:`GSASIIstrMath.ApplyXYZshifts` 
140Rvals          \                (dict) R-factors, GOF, Marquardt value for last
141                                refinement cycle
142\              Nobs             (int) Number of observed data points
143\              Rwp              (float) overall weighted profile R-factor (%)
144\              chisq            (float) :math:`\sum w*(I_{obs}-I_{calc})^2`                               
145                                for all data.
146                                Note: this is not the reduced :math:`\chi^2`.
147\              lamMax           (float) Marquardt value applied to Hessian diagonal
148\              GOF              (float) The goodness-of-fit, aka square root of
149                                the reduced chi squared.
150covMatrix      \                (np.array) The (NxN) covVariance matrix
151=============  ===============  ====================================================
153.. _Phase_table:
155.. index::
156   single: Phase object description
157   single: Data object descriptions; Phase
159Phase Tree Items
162Phase information is stored in the GSAS-II data tree as children of the
163Phases item in a dict with keys:
165.. tabularcolumns:: |l|l|p{4in}|
167==========  ===============     =====================================================================================================
168  key         sub-key           explanation
169==========  ===============     =====================================================================================================
170General         \               (dict) Overall information for the phase
171  \         3Dproj              (list of str) projections for 3D pole distribution plots
172  \         AngleRadii          (list of floats) Default radius for each atom used to compute
173                                interatomic angles
174  \         AtomMass            (list of floats) Masses for atoms
175  \         AtomPtrs            (list of int) four locations (cx,ct,cs & cu) to use to pull info
176                                from the atom records
177  \         AtomTypes           (llist of str) Atom types
178  \         BondRadii           (list of floats) Default radius for each atom used to compute
179                                interatomic distances
180  \         Cell                Unit cell parameters & ref. flag
181                                (list with 8 items. All but first item are float.)
183                                 0: cell refinement flag (True/False),
185                                 1-3: a, b, c, (:math:`\AA`)
187                                 4-6: alpha, beta & gamma, (degrees)
189                                 7: volume (:math:`\AA^3`)
191  \         Color               (list of (r,b,g) triplets) Colors for atoms
192  \         Compare             (dict) Polygon comparison parameters
193  \         Data plot type      (str) data plot type ('Mustrain', 'Size' or
194                                'Preferred orientation') for powder data
195  \         DisAglCtls          (dDict) with distance/angle search controls,
196                                which has keys 'Name', 'AtomTypes',
197                                'BondRadii', 'AngleRadii' which are as above
198                                except are possibly edited. Also contains
199                                'Factors', which is a 2 element list with
200                                a multiplier for bond and angle search range
201                                [typically (0.85,0.85)].
202  \         F000X               (float) x-ray F(000) intensity
203  \         F000N               (float) neutron F(000) intensity
204  \         Flip                (dict) Charge flip controls
205  \         HydIds              (dict) geometrically generated hydrogen atoms
206  \         Isotope             (dict) Isotopes for each atom type
207  \         Isotopes            (dict) Scattering lengths for each isotope
208                                combination for each element in phase
209  \         MCSA controls       (dict) Monte Carlo-Simulated Annealing controls
210  \         Map                 (dict) Map parameters
211  \         Mass                (float) Mass of unit cell contents in g/mol
212  \         Modulated           (bool) True if phase modulated
213  \         Mydir               (str) Directory of current .gpx file
214  \         Name                (str) Phase name
215  \         NoAtoms             (dict) Number of atoms per unit cell of each type
216  \         POhkl               (list) March-Dollase preferred orientation direction
217  \         Pawley dmin         (float) maximum Q (as d-space) to use for Pawley extraction
218  \         Pawley dmax         (float) minimum Q (as d-space) to use for Pawley extraction
219  \         Pawley neg wt       (float) Restraint value for negative Pawley intensities
220  \         SGData              (object) Space group details as a
221                                :ref:`space group (SGData) <SGData_table>` 
222                                object, as defined in :func:`GSASIIspc.SpcGroup`.
223  \         SH Texture          (dict) Spherical harmonic preferred orientation parameters
224  \         Super               (int) dimension of super group (0,1 only)
225  \         Type                (str) phase type (e.g. 'nuclear')
226  \         Z                   (dict) Atomic numbers for each atom type
227  \         doDysnomia          (bool) flag for max ent map modification via Dysnomia
228  \         doPawley            (bool) Flag for Pawley intensity extraction
229  \         vdWRadii            (dict) Van der Waals radii for each atom type
230ranId           \               (int) unique random number Id for phase
231pId             \               (int) Phase Id number for current project.
232Atoms           \               (list of lists) Atoms in phase as a list of lists. The outer list
233                                is for each atom, the inner list contains varying
234                                items depending on the type of phase, see
235                                the :ref:`Atom Records <Atoms_table>` description.
236Drawing         \               (dict) Display parameters
237\           Atoms               (list of lists) with an entry for each atom that is drawn
238\           Plane               (list) Controls for contour density plane display
239\           Quaternion          (4 element np.array) Viewing quaternion
240\           Zclip               (float) clipping distance in :math:`\AA`
241\           Zstep               (float) Step to de/increase Z-clip
242\           atomPtrs            (list) positions of x, type, site sym, ADP flag in Draw Atoms
243\           backColor           (list) background for plot as and R,G,B triplet
244                                (default = [0, 0, 0], black).
245\           ballScale           (float) Radius of spheres in ball-and-stick display
246\           bondList            (dict) Bonds
247\           bondRadius          (float) Radius of binds in :math:`\AA` 
248\           cameraPos           (float) Viewing position in :math:`\AA` for plot
249\           contourLevel        (float) map contour level in :math:`e/\AA^3` 
250\           contourMax          (float) map contour maximum
251\           depthFog            (bool) True if use depthFog on plot - set currently as False
252\           ellipseProb         (float) Probability limit for display of thermal
253                                ellipsoids in % .
254\           magMult             (float) multiplier for magnetic moment arrows
255\           mapSize             (float) x & y dimensions of contourmap (fixed internally)
256\           modelView           (4,4 array) from openGL drawing transofmation matrix
257\           oldxy               (list with two floats) previous view point
258\           radiusFactor        (float) Distance ratio for searching for bonds. Bonds
259                                are located that are within r(Ra+Rb) and (Ra+Rb)/r
260                                where Ra and Rb are the atomic radii.
261\           selectedAtoms       (list of int values) List of selected atoms
262\           showABC             (bool) Flag to show view point triplet. True=show.
263\           showHydrogen        (bool) Flag to control plotting of H atoms.
264\           showRigidBodies     (bool) Flag to highlight rigid body placement
265\           showSlice           (bool) flag to show contour map
266\           sizeH               (float) Size ratio for H atoms
267\           unitCellBox         (bool) Flag to control display of the unit cell.
268\           vdwScale            (float) Multiplier of van der Waals radius for display of vdW spheres.
269\           viewDir             (np.array with three floats) cartesian viewing direction
270\           viewPoint           (list of lists) First item in list is [x,y,z]
271                                in fractional coordinates for the center of
272                                the plot. Second item list of previous & current
273                                atom number viewed (may be [0,0])
274ISODISTORT      \               (dict) contains controls for running ISODISTORT and results from it
275\           ISOmethod           (int) ISODISTORT method (currently 1 or 4; 2 & 3 not implemented in GSAS-II)
276\           ParentCIF           (str) parent cif file name for ISODISTORT method 4
277\           ChildCIF            (str) child cif file name for ISODISTORT method 4
278\           SGselect            (dict) selection list for lattice types in radio result from ISODISTORT method 1
279\           selection           (int) chosen selection from radio
280\           radio               (list) results from ISODISTORT method 1
281\           ChildMatrix         (3x3 array) transformation matrix for method 3 (not currently used)
282\           ChildSprGp          (str) child space group for method 3 (not currently used)
283\           ChildCell           (str) cell ordering for nonstandard orthorhombic ChildSprGrp in method 3 (not currently used)
284\           G2ModeList          (list) ISODISTORT mode names
285\           modeDispl           (list) distortion mode values; refinable parameters
286\           ISOmodeDispl        (list) distortion mode values as determined in method 4 by ISODISTORT
287\           NormList            (list) ISODISTORT normalization values; to convert mode value to fractional coordinate dsplacement
288\           G2parentCoords      (list) full set of parent structure coordinates transformed to child structure; starting basis for mode displacements
289\           G2VarList           (list)
290\           IsoVarList          (list)
291\           G2coordOffset       (list) only adjustible set of parent structure coordinates
292\           G2OccVarList        (list)
293\           Var2ModeMatrix      (array) atom variable to distortion mode transformation
294\           Mode2VarMatrix      (array) distortion mode to atom variable transformation
295\           rundata             (dict) saved input information for use by ISODISTORT method 1
297RBModels        \               Rigid body assignments (note Rigid body definitions
298                                are stored in their own main top-level tree entry.)
299RMC             \               (dict) RMCProfile, PDFfit & fullrmc controls
300Pawley ref      \               (list) Pawley reflections
301Histograms      \               (dict of dicts) The key for the outer dict is
302                                the histograms tied to this phase. The inner
303                                dict contains the combined phase/histogram
304                                parameters for items such as scale factors,
305                                size and strain parameters. The following are the
306                                keys to the inner dict. (dict)
307\           Babinet             (dict) For protein crystallography. Dictionary with two
308                                entries, 'BabA', 'BabU'
309\           Extinction          (list of float, bool) Extinction parameter
310\           Flack               (list of [float, bool]) Flack parameter & refine flag
311\           HStrain             (list of two lists) Hydrostatic strain. The first is
312                                a list of the HStrain parameters (1, 2, 3, 4, or 6
313                                depending on unit cell), the second is a list of boolean
314                                refinement parameters (same length)
315\           Histogram           (str) The name of the associated histogram
316\           Layer Disp          (list of [float, bool]) Layer displacement in beam direction & refine flag
317\           LeBail              (bool) Flag for LeBail extraction
318\           Mustrain            (list) Microstrain parameters, in order:
320                                0. Type, one of  u'isotropic', u'uniaxial', u'generalized'
321                                1. Isotropic/uniaxial parameters - list of 3 floats
322                                2. Refinement flags - list of 3 bools
323                                3. Microstrain axis - list of 3 ints, [h, k, l]
324                                4. Generalized mustrain parameters - list of 2-6 floats, depending on space group
325                                5. Generalized refinement flags - list of bools, corresponding to the parameters of (4)
326\           Pref.Ori.           (list) Preferred Orientation. List of eight parameters.
327                                Items marked SH are only used for Spherical Harmonics.
329                                0. (str) Type, 'MD' for March-Dollase or 'SH' for Spherical Harmonics
330                                1. (float) Value
331                                2. (bool) Refinement flag
332                                3. (list) Preferred direction, list of ints, [h, k, l]
333                                4. (int) SH - number of terms
334                                5. (dict) SH - 
335                                6. (list) SH
336                                7. (float) SH
337\           Scale               (list of [float, bool]) Phase fraction & refine flag
338\           Size                List of crystallite size parameters, in order:
340                                0. (str) Type, one of  u'isotropic', u'uniaxial', u'ellipsoidal'
341                                1. (list) Isotropic/uniaxial parameters - list of 3 floats
342                                2. (list) Refinement flags - list of 3 bools
343                                3. (list) Size axis - list of 3 ints, [h, k, l]
344                                4. (list) Ellipsoidal size parameters - list of 6 floats
345                                5. (list) Ellipsoidal refinement flags - list of bools, corresponding to the parameters of (4)
346\           Use                 (bool) True if this histogram is to be used in refinement
347MCSA            \               (dict) Monte-Carlo simulated annealing parameters
348==========  ===============     =====================================================================================================
350.. _RBData_table:
352.. index::
353   single: Rigid Body Data description
354   single: Data object descriptions; Rigid Body Data
356Rigid Body Objects
359Rigid body descriptions are available for two types of rigid bodies: 'Vector'
360and 'Residue'. Vector rigid bodies are developed by a sequence of translations each
361with a refinable magnitude and Residue rigid bodies are described as Cartesian coordinates
362with defined refinable torsion angles.
364.. tabularcolumns:: |l|l|p{4in}|
366==========  ===============     ====================================================
367  key         sub-key           explanation
368==========  ===============     ====================================================
369Vector      RBId                (dict of dict) vector rigid bodies
370\           AtInfo              (dict) Drad, Color: atom drawing radius & color for each atom type
371\           RBname              (str) Name assigned by user to rigid body
372\           VectMag             (list) vector magnitudes in :math:`\AA` 
373\           rbXYZ               (list of 3 float Cartesian coordinates for Vector rigid body )
374\           rbRef               (list of 3 int & 1 bool) 3 assigned reference atom nos. in rigid body for origin
375                                definition, use center of atoms flag
376\           VectRef             (list of bool refinement flags for VectMag values )
377\           rbTypes             (list of str) Atom types for each atom in rigid body
378\           rbVect              (list of lists) Cartesian vectors for each translation used to build rigid body
379\           useCount            (int) Number of times rigid body is used in any structure
380Residue     RBId                (dict of dict) residue rigid bodies
381\           AtInfo              (dict) Drad, Color: atom drawing radius & color for each atom type
382\           RBname              (str) Name assigned by user to rigid body
383\           rbXYZ               (list of 3 float) Cartesian coordinates for Residue rigid body
384\           rbTypes             (list of str) Atom types for each atom in rigid body
385\           atNames             (list of str) Names of each atom in rigid body (e.g. C1,N2...)
386\           rbRef               (list of 3 int & 1 bool) 3 assigned reference atom nos. in rigid body for origin
387                                definition, use center of atoms flag
388\           rbSeq               (list) Orig,Piv,angle,Riding : definition of internal rigid body
389                                torsion; origin atom (int), pivot atom (int), torsion angle (float),
390                                riding atoms (list of int)
391\           SelSeq              (int,int) used by SeqSizer to identify objects
392\           useCount            (int)Number of times rigid body is used in any structure
393RBIds           \               (dict) unique Ids generated upon creation of each rigid body
394\           Vector              (list) Ids for each Vector rigid body
395\           Residue             (list) Ids for each Residue rigid body
396==========  ===============     ====================================================
398.. _SGData_table:
400.. index::
401   single: Space Group Data description
402   single: Data object descriptions; Space Group Data
404Space Group Objects
407Space groups are interpreted by :func:`GSASIIspc.SpcGroup`
408and the information is placed in a SGdata object
409which is a dict with these keys. Magnetic ones are marked "mag"
411.. tabularcolumns:: |l|p{4.5in}|
413==========  ========================================================================================
414  key         explanation
415==========  ========================================================================================
416BNSlattsym  mag - (str) BNS magnetic space group symbol and centering vector
417GenFlg      mag - (list) symmetry generators indices
418GenSym      mag - (list) names for each generator
419MagMom      mag - (list) "time reversals" for each magnetic operator
420MagPtGp     mag - (str) Magnetic point group symbol
421MagSpGrp    mag - (str) Magnetic space group symbol
422OprNames    mag - (list) names for each space group operation
423SGCen       (np.array) Symmetry cell centering vectors. A (n,3) np.array
424            of centers. Will always have at least one row: ``np.array([[0, 0, 0]])``
425SGFixed     (bool) Only True if phase mported from a magnetic cif file
426            then the space group can not be changed by the user because
427            operator set from cif may be nonstandard
428SGGen       (list) generators
429SGGray      (bool) True if space group is a gray group (incommensurate magnetic structures)
430SGInv       (bool) True if centrosymmetric, False if not
431SGLatt      (str)Lattice centering type. Will be one of
432            P, A, B, C, I, F, R
433SGLaue      (str) one of the following 14 Laue classes:
434            -1, 2/m, mmm, 4/m, 4/mmm, 3R,
435            3mR, 3, 3m1, 31m, 6/m, 6/mmm, m3, m3m
436SGOps       (list) symmetry operations as a list of form
437            ``[[M1,T1], [M2,T2],...]``
438            where :math:`M_n` is a 3x3 np.array
439            and :math:`T_n` is a length 3 np.array.
440            Atom coordinates are transformed where the
441            Asymmetric unit coordinates [X is (x,y,z)]
442            are transformed using
443            :math:`X^\prime = M_n*X+T_n`
444SGPolax     (str) Axes for space group polarity. Will be one of
445            '', 'x', 'y', 'x y', 'z', 'x z', 'y z',
446            'xyz'. In the case where axes are arbitrary
447            '111' is used (P 1, and ?).
448SGPtGrp     (str) Point group of the space group
449SGUniq      unique axis if monoclinic. Will be
450            a, b, or c for monoclinic space groups.
451            Will be blank for non-monoclinic.
452SGSpin      mag - (list) of spin flip operatiors (+1 or -1) for the space group operations
453SGSys       (str) symmetry unit cell: type one of
454            'triclinic', 'monoclinic', 'orthorhombic',
455            'tetragonal', 'rhombohedral', 'trigonal',
456            'hexagonal', 'cubic'
457SSGK1       (list) Superspace multipliers
458SpGrp       (str) space group symbol
459SpnFlp      mag - (list) Magnetic spin flips for every magnetic space group operator
460==========  ========================================================================================
462.. _SSGData_table:
464.. index::
465   single: Superspace Group Data description
466   single: Data object descriptions; Superspace Group Data
468Superspace groups [3+1] are interpreted by :func:`GSASIIspc.SSpcGroup`
469and the information is placed in a SSGdata object
470which is a dict with these keys:
472.. tabularcolumns:: |l|p{4.5in}|
474==========  ====================================================
475  key         explanation
476==========  ====================================================
477SSGCen      (list) 4D cell centering vectors [0,0,0,0] at least
478SSGK1       (list) Superspace multipliers
479SSGOps      (list) 4D symmetry operations as [M,T] so that M*x+T = x'
480SSpGrp      (str) superspace group symbol extension to space group
481            symbol, accidental spaces removed
482modQ        (list) modulation/propagation vector
483modSymb     (list of str) Modulation symbols
484==========  ====================================================
487Phase Information
490.. index::
491   single: Phase information record description
493Phase information is placed in one of the following keys:
495.. tabularcolumns:: |l|p{4.5in}|
497==========  ==============================================================
498  key         explanation
499==========  ==============================================================
500General       Overall information about a phase
501Histograms    Information about each histogram linked to the
502              current phase as well as parameters that
503              are defined for each histogram and phase
504              (such as sample peak widths and preferred
505              orientation parameters.
506Atoms         Contains a list of atoms, as described in the
507              :ref:`Atom Records <Atoms_table>` description.
508Drawing       Parameters that determine how the phase is
509              displayed, including a list of atoms to be
510              included, as described in the
511              :ref:`Drawing Atom Records <Drawing_atoms_table>`
512              description
513MCSA          Monte-Carlo simulated annealing parameters
514pId           The index of each phase in the project, numbered
515              starting at 0
516ranId         An int value with a unique value for each phase
517RBModels      A list of dicts with parameters for each
518              rigid body inserted into the current phase,
519              as defined in the
520              :ref:`Rigid Body Insertions <Rigid_Body_Insertions>`.
521              Note that the rigid bodies are defined as
522              :ref:`Rigid Body Objects <RBData_table>` 
523RMC           PDF modeling parameters
524Pawley ref    Pawley refinement parameters
526==========  ==============================================================
528.. _Atoms_table:
530.. index::
531   single: Atoms record description
532   single: Data object descriptions; Atoms record
535Atom Records
538If ``phasedict`` points to the phase information in the data tree, then
539atoms are contained in a list of atom records (list) in
540``phasedict['Atoms']``. Also needed to read atom information
541are four pointers, ``cx,ct,cs,cia = phasedict['General']['AtomPtrs']``,
542which define locations in the atom record, as shown below. Items shown are
543always present; additional ones for macromolecular phases are marked 'mm',
544and those for magnetic structures are marked 'mg'
546.. tabularcolumns:: |l|p{4.5in}|
548==============      ====================================================
549location            explanation
550==============      ====================================================
551ct-4                mm - (str) residue number
552ct-3                mm - (str) residue name (e.g. ALA)
553ct-2                mm - (str) chain label
554ct-1                (str) atom label
555ct                  (str) atom type
556ct+1                (str) refinement flags; combination of 'F', 'X', 'U', 'M'
557cx,cx+1,cx+2        (3 floats) the x,y and z coordinates
558cx+3                (float) site occupancy
559cx+4,cx+5,cx+6      mg - (list) atom magnetic moment along a,b,c in Bohr magnetons
560cs                  (str) site symmetry
561cs+1                (int) site multiplicity
562cia                 (str) ADP flag: Isotropic ('I') or Anisotropic ('A')
563cia+1               (float) Uiso
564cia+2...cia+7       (6 floats) U11, U22, U33, U12, U13, U23
565atom[cia+8]         (int) unique atom identifier
567==============      ====================================================
569.. _Drawing_atoms_table:
571.. index::
572   single: Drawing atoms record description
573   single: Data object descriptions; Drawing atoms record
576Drawing Atom Records
579If ``phasedict`` points to the phase information in the data tree, then
580drawing atoms are contained in a list of drawing atom records (list) in
581``phasedict['Drawing']['Atoms']``. Also needed to read atom information
582are four pointers, ``cx,ct,cs,ci = phasedict['Drawing']['AtomPtrs']``,
583which define locations in the atom record, as shown below. Items shown are
584always present; additional ones for macromolecular phases are marked 'mm',
585and those for magnetic structures are marked 'mg'
587.. tabularcolumns:: |l|p{4.5in}|
589==============   ===================================================================================
590location            explanation
591==============   ===================================================================================
592ct-4                mm - (str) residue number
593ct-3                mm - (str) residue name (e.g. ALA)
594ct-2                mm - (str) chain label
595ct-1                (str) atom label
596ct                  (str) atom type
597cx,cx+1,cx+2        (3 floats) the x,y and z coordinates
598cx+3,cx+4,cx+5      mg - (3 floats) atom magnetic moment along a,b,c in Bohr magnetons
599cs-1                (str) Sym Op symbol; sym. op number + unit cell id (e.g. '1,0,-1')
600cs                  (str) atom drawing style; e.g. 'balls & sticks'
601cs+1                (str) atom label style (e.g. 'name')
602cs+2                (int) atom color (RBG triplet)
603cs+3                (str) ADP flag: Isotropic ('I') or Anisotropic ('A')
604cs+4                (float) Uiso
605cs+5...cs+11        (6 floats) U11, U22, U33, U12, U13, U23
606ci                  (int) unique atom identifier; matches source atom Id in Atom Records
607==============   ===================================================================================
609.. _Rigid_Body_Insertions:
612Rigid Body Insertions
615If ``phasedict`` points to the phase information in the data tree, then
616rigid body information is contained in list(s) in
617``phasedict['RBModels']['Residue']`` and/or ``phasedict['RBModels']['Vector']``
618for each rigid body inserted into the current phase.
620.. tabularcolumns:: |l|p{4.5in}|
622==============   ===================================================================================
623key              explanation
624==============   ===================================================================================
625fixOrig           Should the origin be fixed (when editing, not the refinement flag)
626Ids               Ids for assignment of atoms in the rigid body
627numChain          Chain number for macromolecular fits
628Orient            Orientation of the RB as a quaternion and a refinement flag (' ', 'A' or 'AV')
629OrientVec         Orientation of the RB expressed as a vector and azimuthal rotation angle
630Orig              Origin of the RB in fractional coordinates and refinement flag (bool)
631RBId              References the unique ID of a rigid body in the
632                  :ref:`Rigid Body Objects <RBData_table>`
633RBname            The name for the rigid body (str)
634AtomFrac          The atom fractions for the rigid body
635ThermalMotion     The thermal motion description for the rigid body, which includes a choice for
636                  the model and can include TLS parameters or an overall Uiso value.
637Torsions          Defines the torsion angle and refinement flag for each torsion defined in
638                  the :ref:`Rigid Body Object <RBData_table>`
639==============   ===================================================================================
641.. _Powder_table:
643.. index::
644   single: Powder data object description
645   single: Data object descriptions; Powder Data
647Powder Diffraction Tree Items
650Every powder diffraction histogram is stored in the GSAS-II data tree
651with a top-level entry named beginning with the string "PWDR ". The
652diffraction data for that information are directly associated with
653that tree item and there are a series of children to that item. The
654routines :func:`GSASIIdataGUI.GSASII.GetUsedHistogramsAndPhasesfromTree`
655and :func:`GSASIIstrIO.GetUsedHistogramsAndPhases` will
656load this information into a dictionary where the child tree name is
657used as a key, and the information in the main entry is assigned
658a key of ``Data``, as outlined below.
660.. tabularcolumns:: |p{1in}|p{1in}|p{4in}|
662======================     ===============  ===========================================================
663  key                       sub-key          explanation
664======================     ===============  ===========================================================
665Comments                    \               (list of str) Text strings extracted from the original powder
666                                            data header. These cannot be changed by the user;
667                                            it may be empty.
668Limits                      \               (list) two two element lists, as [[Ld,Hd],[L,H]]
669                                            where L and Ld are the current and default lowest
670                                            two-theta value to be used and
671                                            where H and Hd are the current and default highest
672                                            two-theta value to be used.
673Reflection Lists            \               (dict of dicts) with an entry for each phase in the
674                                            histogram. The contents of each dict item
675                                            is a dict containing reflections, as described in
676                                            the :ref:`Powder Reflections <PowderRefl_table>`
677                                            description.
678Instrument Parameters       \               (dict) The instrument parameters uses different dicts
679                                            for the constant wavelength (CW) and time-of-flight (TOF)
680                                            cases. See below for the descriptions of each.
681wtFactor                    \               (float) A weighting factor to increase or decrease
682                                            the leverage of data in the histogram .
683                                            A value of 1.0 weights the data with their
684                                            standard uncertainties and a larger value
685                                            increases the weighting of the data (equivalent
686                                            to decreasing the uncertainties).
687Sample Parameters           \               (dict) Parameters that describe how
688                                            the data were collected, as listed
689                                            below. Refinable parameters are a list containing
690                                            a float and a bool, where the second value
691                                            specifies if the value is refined, otherwise
692                                            the value is a float unless otherwise noted.
693\                           Scale           The histogram scale factor (refinable)
694\                           Absorption      The sample absorption coefficient as
695                                            :math:`\mu r` where r is the radius
696                                            (refinable). Only valid for Debye-Scherrer geometry.
697\                           SurfaceRoughA   Surface roughness parameter A as defined by
698                                            Surotti, *J. Appl. Cryst*, **5**, 325-331, 1972.
699                                            (refinable - only valid for Bragg-Brentano geometry)
700\                           SurfaceRoughB   Surface roughness parameter B (refinable -
701                                            only valid for Bragg-Brentano geometry)
702\                           DisplaceX,      Sample displacement from goniometer center
703                            DisplaceY       where Y is along the beam direction and
704                                            X is perpendicular. Units are :math:`\mu m`
705                                            (refinable).
706\                           Phi, Chi,       Goniometer sample setting angles, in degrees.
707                            Omega
708\                           Gonio. radius   Radius of the diffractometer in mm
709\                           InstrName       (str) A name for the instrument, used in preparing
710                                            a CIF .
711\                           Force,          Variables that describe how the measurement
712                            Temperature,    was performed. Not used directly in
713                            Humidity,       any computations.
714                            Pressure,
715                            Voltage
716\                           ranId           (int) The random-number Id for the histogram
717                                            (same value as where top-level key is ranId)
718\                           Type            (str) Type of diffraction data, may be 'Debye-Scherrer'
719                                            or 'Bragg-Brentano' .
720hId                         \               (int) The number assigned to the histogram when
721                                            the project is loaded or edited (can change)
722ranId                       \               (int) A random number id for the histogram
723                                            that does not change
724Background                  \               (list) The background is stored as a list with where
725                                            the first item in the list is list and the second
726                                            item is a dict. The list contains the background
727                                            function and its coefficients; the dict contains
728                                            Debye diffuse terms and background peaks.
729                                            (TODO: this needs to be expanded.)
730Data                        \               (list) The data consist of a list of 6 np.arrays
731                                            containing in order:
733                                            0. the x-postions (two-theta in degrees),
734                                            1. the intensity values (Yobs),
735                                            2. the weights for each Yobs value
736                                            3. the computed intensity values (Ycalc)
737                                            4. the background values
738                                            5. Yobs-Ycalc
739======================     ===============  ===========================================================
741.. _CWPowder_table:
743.. index::
744   single: Powder data CW Instrument Parameters
747CW Instrument Parameters
750Instrument Parameters are placed in a list of two dicts,
751where the keys in the first dict are listed below. Note that the dict contents are different for
752constant wavelength (CW) vs. time-of-flight (TOF) histograms.
753The value for each item is a list containing three values: the initial value, the current value
754and a refinement flag which can have a value of True, False or 0 where 0 indicates a value that
755cannot be refined. The first and second values are floats unless otherwise noted.
756Items not refined are noted as [*]
758.. tabularcolumns:: |l|p{1in}|p{4in}|
760========================    ===============  ===========================================================
761  key                       sub-key           explanation
762========================    ===============  ===========================================================
763Instrument Parameters[0]    Type [*]            (str) Histogram type:
764                                                * 'PXC' for constant wavelength x-ray
765                                                * 'PNC' for constant wavelength neutron
766\                           Bank [*]            (int) Data set number in a multidata file (usually 1)
767\                           Lam                 (float) Specifies a wavelength in :math:`\AA`
768\                           Lam1 [*]            (float) Specifies the primary wavelength in
769                                                :math:`\AA`, used in place of Lam
770                                                when an :math:`\alpha_1, \alpha_2`
771                                                source is used.
772\                           Lam2 [*]            (float) Specifies the secondary wavelength in
773                                                :math:`\AA`, used with Lam1
774\                           I(L2)/I(L1)         (float) Ratio of Lam2 to Lam1, used with Lam1
775\                           Zero                (float) Two-theta zero correction in *degrees*
776\                           Azimuth [*]         (float) Azimuthal setting angle for data recorded with differing setting angles
777\                           U, V, W             (float) Cagliotti profile coefficients
778                                                for Gaussian instrumental broadening, where the
779                                                FWHM goes as
780                                                :math:`U \tan^2\theta + V \tan\theta + W`
781\                           X, Y, Z             (float) Cauchy (Lorentzian) instrumental broadening coefficients
782\                           SH/L                (float) Variant of the Finger-Cox-Jephcoat asymmetric
783                                                peak broadening ratio. Note that this is the
784                                                sum of S/L and H/L where S is
785                                                sample height, H is the slit height and
786                                                L is the goniometer diameter.
787\                           Polariz.            (float) Polarization coefficient.
788Instrument Parameters[1]                        (empty dict)
789========================    ===============  ===========================================================
791.. _TOFPowder_table:
793.. index::
794   single: Powder data TOF Instrument Parameters
797TOF Instrument Parameters
800Instrument Parameters are also placed in a list of two dicts,
801where the keys in each dict listed below, but here for
802time-of-flight (TOF) histograms.
803The value for each item is a list containing three values: the initial value, the current value
804and a refinement flag which can have a value of True, False or 0 where 0 indicates a value that
805cannot be refined. The first and second values are floats unless otherwise noted.
806Items not refined are noted as [*]
808.. tabularcolumns:: |l|p{1.5in}|p{4in}|
810========================    ===============  ===========================================================
811  key                        sub-key          explanation
812========================    ===============  ===========================================================
813Instrument Parameters[0]    Type [*]            (str) Histogram type:
814                                                * 'PNT' for time of flight neutron
815\                           Bank                (int) Data set number in a multidata file
816\                           2-theta [*]         (float) Nominal scattering angle for the detector
817\                           fltPath [*]         (float) Total flight path source-sample-detector
818\                           Azimuth [*]         (float) Azimuth angle for detector right hand rotation
819                                                from horizontal away from source
820\                           difC,difA,          (float) Diffractometer constants for conversion of d-spacing to TOF
821                            difB                in microseconds
822\                           Zero                (float) Zero point offset (microseconds)
823\                           alpha               (float) Exponential rise profile coefficients
824\                           beta-0              (float) Exponential decay profile coefficients
825                            beta-1
826                            beta-q
827\                           sig-0               (float) Gaussian profile coefficients
828                            sig-1
829                            sig-2
830                            sig-q   
831\                           X,Y,Z               (float) Lorentzian profile coefficients
832Instrument Parameters[1]    Pdabc               (list of 4 float lists) Originally created for use in gsas as optional tables
833                                                of d, alp, bet, d-true; for a reflection alpha & beta are obtained via interpolation
834                                                from the d-spacing and these tables. The d-true column is apparently unused.
835========================    ===============  ===========================================================
838.. _PowderRefl_table:
840.. index::
841   single: Powder reflection object description
842   single: Data object descriptions; Powder Reflections
844Powder Reflection Data Structure
847For every phase in a histogram, the ``Reflection Lists`` value is a dict
848one element of which is `'RefList'`, which is a np.array containing
849reflections. The columns in that array are documented below.
851==========  ====================================================
852  index         explanation
853==========  ====================================================
854 0,1,2          h,k,l (float)
855 3              (int) multiplicity
856 4              (float) d-space, :math:`\AA`
857 5              (float) pos, two-theta
858 6              (float) sig, Gaussian width
859 7              (float) gam, Lorenzian width
860 8              (float) :math:`F_{obs}^2`
861 9              (float) :math:`F_{calc}^2`
862 10             (float) reflection phase, in degrees
863 11             (float) intensity correction for reflection, this times
864                :math:`F_{obs}^2` or :math:`F_{calc}^2` gives Iobs or Icalc
865 12             (float) Preferred orientation correction
866 13             (float) Transmission (absorption correction)
867 14             (float) Extinction correction
868==========  ====================================================
870.. _Xtal_table:
872.. index::
873   single: Single Crystal data object description
874   single: Data object descriptions; Single crystal data
876Single Crystal Tree Items
879Every single crystal diffraction histogram is stored in the GSAS-II data tree
880with a top-level entry named beginning with the string "HKLF ". The
881diffraction data for that information are directly associated with
882that tree item and there are a series of children to that item. The
883routines :func:`GSASIIdataGUI.GSASII.GetUsedHistogramsAndPhasesfromTree`
884and :func:`GSASIIstrIO.GetUsedHistogramsAndPhases` will
885load this information into a dictionary where the child tree name is
886used as a key, and the information in the main entry is assigned
887a key of ``Data``, as outlined below.
889.. tabularcolumns:: |l|l|p{4in}|
891======================  ===============     ====================================================
892  key                      sub-key          explanation
893======================  ===============     ====================================================
894Data                        \               (dict) that contains the
895                                            reflection table,
896                                            as described in the
897                                            :ref:`Single Crystal Reflections
898                                            <XtalRefl_table>`
899                                            description.
901Instrument Parameters       \               (list) containing two dicts where the possible
902                                            keys in each dict are listed below. The value
903                                            for most items is a list containing two values:
904                                            the initial value, the current value.
905                                            The first and second
906                                            values are floats unless otherwise noted.
907\                           Lam             (two floats) Specifies a wavelength in :math:`\AA` 
908\                           Type            (two str values) Histogram type :
909                                            * 'SXC' for constant wavelength x-ray
910                                            * 'SNC' for constant wavelength neutron
911                                            * 'SNT' for time of flight neutron
912                                            * 'SEC' for constant wavelength electrons (e.g. micro-ED)
913\                           InstrName       (str) A name for the instrument, used in preparing a CIF
914wtFactor                    \               (float) A weighting factor to increase or decrease
915                                            the leverage of data in the histogram.
916                                            A value of 1.0 weights the data with their
917                                            standard uncertainties and a larger value
918                                            increases the weighting of the data (equivalent
919                                            to decreasing the uncertainties).
921hId                         \               (int) The number assigned to the histogram when
922                                            the project is loaded or edited (can change)
923ranId                       \               (int) A random number id for the histogram
924                                            that does not change
925======================  ===============     ====================================================
927.. _XtalRefl_table:
929.. index::
930   single: Single Crystal reflection object description
931   single: Data object descriptions; Single Crystal Reflections
933Single Crystal Reflection Data Structure
936For every single crystal a histogram, the ``'Data'`` item contains
937the structure factors as an np.array in item `'RefList'`.
938The columns in that array are documented below.
940.. tabularcolumns:: |l|p{4in}|
942==========  ====================================================
943  index         explanation
944==========  ====================================================
945 0,1,2          (float) h,k,l
946 3              (int) multiplicity
947 4              (float) d-space, :math:`\AA`
948 5              (float) :math:`F_{obs}^2`
949 6              (float) :math:`\sigma(F_{obs}^2)`
950 7              (float) :math:`F_{calc}^2`
951 8              (float) :math:`F_{obs}^2T`
952 9              (float) :math:`F_{calc}^2T`
953 10             (float) reflection phase, in degrees
954 11             (float) intensity correction for reflection, this times
955                :math:`F_{obs}^2` or :math:`F_{calc}^2`
956                gives Iobs or Icalc
957==========  ====================================================
959.. _Image_table:
961.. index::
962   image: Image data object description
963   image: Image object descriptions
965Image Data Structure
968Every 2-dimensional image is stored in the GSAS-II data tree
969with a top-level entry named beginning with the string "IMG ". The
970image data are directly associated with that tree item and there
971are a series of children to that item. The routines :func:`GSASIIdataGUI.GSASII.GetUsedHistogramsAndPhasesfromTree`
972and :func:`GSASIIstrIO.GetUsedHistogramsAndPhases` will
973load this information into a dictionary where the child tree name is
974used as a key, and the information in the main entry is assigned
975a key of ``Data``, as outlined below.
977.. tabularcolumns:: |l|l|p{4in}|
979======================  ======================  ====================================================
980  key                      sub-key              explanation
981======================  ======================  ====================================================
982Comments                    \                   (list of str) Text strings extracted from the original image data
983                                                header or a metafile. These cannot be changed by
984                                                the user; it may be empty.
985Image Controls              azmthOff            (float) The offset to be applied to an azimuthal
986                                                value. Accomodates
987                                                detector orientations other than with the detector
988                                                X-axis
989                                                horizontal.
990\                           background image    (list:str,float) The name of a tree item ("IMG ...") that is to be subtracted
991                                                during image integration multiplied by value. It must have the same size/shape as
992                                                the integrated image. NB: value < 0 for subtraction.
993\                           calibrant           (str) The material used for determining the position/orientation
994                                                of the image. The data is obtained from :func:`ImageCalibrants`
995                                                and (supplied by user).
996\                           calibdmin           (float) The minimum d-spacing used during the last calibration run.
997\                           calibskip           (int) The number of expected diffraction lines skipped during the last
998                                                calibration run.
999\                           center              (list:floats) The [X,Y] point in detector coordinates (mm) where the direct beam
1000                                                strikes the detector plane as determined by calibration. This point
1001                                                does not have to be within the limits of the detector boundaries.
1002\                           centerAzm           (bool) If True then the azimuth reported for the integrated slice
1003                                                of the image is at the center line otherwise it is at the leading edge.
1004\                           color               (str) The name of the colormap used to display the image. Default = 'Paired'.
1005\                           cutoff              (float) The minimum value of I/Ib for a point selected in a diffraction ring for
1006                                                calibration calculations. See pixLimit for details as how point is found.
1007\                           DetDepth            (float) Coefficient for penetration correction to distance; accounts for diffraction
1008                                                ring offset at higher angles. Optionally determined by calibration.
1009\                           DetDepthRef         (bool) If True then refine DetDepth during calibration/recalibration calculation.
1010\                           distance            (float) The distance (mm) from sample to detector plane.
1011\                           ellipses            (list:lists) Each object in ellipses is a list [center,phi,radii,color] where
1012                                                center (list) is location (mm) of the ellipse center on the detector plane, phi is the
1013                                                rotation of the ellipse minor axis from the x-axis, and radii are the minor & major
1014                                                radii of the ellipse. If radii[0] is negative then parameters describe a hyperbola. Color
1015                                                is the selected drawing color (one of 'b', 'g' ,'r') for the ellipse/hyperbola.
1016\                           edgemin             (float) Not used;  parameter in EdgeFinder code.
1017\                           fullIntegrate       (bool) If True then integrate over full 360 deg azimuthal range.
1018\                           GonioAngles         (list:floats) The 'Omega','Chi','Phi' goniometer angles used for this image.
1019                                                Required for texture calculations.
1020\                           invert_x            (bool) If True display the image with the x-axis inverted.
1021\                           invert_y            (bool) If True display the image with the y-axis inverted.
1022\                           IOtth               (list:floats) The minimum and maximum 2-theta values to be used for integration.
1023\                           LRazimuth           (list:floats) The minimum and maximum azimuth values to be used for integration.
1024\                           Oblique             (list:float,bool) If True apply a detector absorption correction using the value to the
1025                                                intensities obtained during integration.
1026\                           outAzimuths         (int) The number of azimuth pie slices.
1027\                           outChannels         (int) The number of 2-theta steps.
1028\                           pixelSize           (list:ints) The X,Y dimensions (microns) of each pixel.
1029\                           pixLimit            (int) A box in the image with 2*pixLimit+1 edges is searched to find the maximum.
1030                                                This value (I) along with the minimum (Ib) in the box is reported by :func:`GSASIIimage.ImageLocalMax`
1031                                                and subject to cutoff in :func:`GSASIIimage.makeRing`.
1032                                                Locations are used to construct rings of points for calibration calcualtions.
1033\                           PolaVal             (list:float,bool) If type='SASD' and if True, apply polarization correction to intensities from
1034                                                integration using value.
1035\                           rings               (list:lists) Each entry is [X,Y,dsp] where X & Y are lists of x,y coordinates around a
1036                                                diffraction ring with the same d-spacing (dsp)
1037\                           ring                (list) The x,y coordinates of the >5 points on an inner ring
1038                                                selected by the user,
1039\                           Range               (list) The minimum & maximum values of the image
1040\                           rotation            (float) The angle between the x-axis and the vector about which the
1041                                                detector is tilted. Constrained to -180 to 180 deg.
1042\                           SampleShape         (str) Currently only 'Cylinder'. Sample shape for Debye-Scherrer experiments; used for absorption
1043                                                calculations.
1044\                           SampleAbs           (list: float,bool) Value of absorption coefficient for Debye-Scherrer experimnents, flag if True
1045                                                to cause correction to be applied.
1046\                           setDefault          (bool) If True the use the image controls values for all new images to be read. (might be removed)
1047\                           setRings            (bool) If True then display all the selected x,y ring positions (vida supra rings) used in the calibration.
1048\                           showLines           (bool) If True then isplay the integration limits to be used.
1049\                           size                (list:int) The number of pixels on the image x & y axes
1050\                           type                (str) One of 'PWDR', 'SASD' or 'REFL' for powder, small angle or reflectometry data, respectively.
1051\                           tilt                (float) The angle the detector normal makes with the incident beam; range -90 to 90.
1052\                           wavelength          (float) The radiation wavelength (:math:`\AA`) as entered by the user
1053                                                (or someday obtained from the image header).
1054Masks                       Arcs                (list: lists) Each entry [2-theta,[azimuth[0],azimuth[1]],thickness] describes an arc mask
1055                                                to be excluded from integration
1056\                           Frames              (list:lists) Each entry describes the x,y points (3 or more - mm) that describe a frame outside
1057                                                of which is excluded from recalibration and integration. Only one frame is allowed.
1058\                           Points              (list:lists) Each entry [x,y,radius] (mm) describes an excluded spot on the image to be excluded
1059                                                from integration.
1060\                           Polygons            (list:lists) Each entry is a list of 3+ [x,y] points (mm) that describe a polygon on the image
1061                                                to be excluded from integration.
1062\                           Rings               (list: lists) Each entry [2-theta,thickness] describes a ring mask
1063                                                to be excluded from integration.
1064\                           Thresholds          (list:[tuple,list]) [(Imin,Imax),[Imin,Imax]] This gives lower and upper limits for points on the image to be included
1065                                                in integrsation. The tuple is the image intensity limits and the list are those set by the user.
1066\                           SpotMask            (dict: int & array)
1067                                                'esdMul'(int) number of standard deviations above mean ring intensity to mask
1068                                                'spotMask' (bool array) the spot mask for every pixel in image         
1070Stress/Strain               Sample phi          (float) Sample rotation about vertical axis.
1071\                           Sample z            (float) Sample translation from the calibration sample position (for Sample phi = 0)
1072                                                These will be restricted by space group symmetry; result of strain fit refinement.
1073\                           Type                (str) 'True' or 'Conventional': The strain model used for the calculation.
1074\                           d-zero              (list:dict) Each item is for a diffraction ring on the image; all items are from the same phase
1075                                                and are used to determine the strain tensor.
1076                                                The dictionary items are:
1077                                                'Dset': (float) True d-spacing for the diffraction ring; entered by the user.
1078                                                'Dcalc': (float) Average calculated d-spacing determined from strain coeff.
1079                                                'Emat': (list: float) The strain tensor elements e11, e12 & e22 (e21=e12, rest are 0)
1080                                                'Esig': (list: float) Esds for Emat from fitting.
1081                                                'pixLimit': (int) Search range to find highest point on ring for each data point
1082                                                'cutoff': (float) I/Ib cutoff for searching.
1083                                                'ImxyObs': (list: lists) [[X],[Y]] observed points to be used for strain calculations.
1084                                                'ImtaObs': (list: lists) [[d],[azm]] transformed via detector calibration from ImxyObs.
1085                                                'ImtaCalc': (list: lists [[d],[azm]] calculated d-spacing & azimuth from fit.
1087======================  ======================  ====================================================
1089.. _parmDict_table:
1091.. index::
1092   single: Parameter dictionary
1094Parameter Dictionary
1097The parameter dictionary contains all of the variable parameters for the refinement.
1098The dictionary keys are the name of the parameter (<phase>:<hist>:<name>:<atom>).
1099It is prepared in two ways. When loaded from the tree
1100(in :meth:`GSASIIdataGUI.GSASII.MakeLSParmDict` and
1102the values are lists with two elements: ``[value, refine flag]``
1104When loaded from the GPX file (in
1105:func:`GSASIIstrMain.Refine` and :func:`GSASIIstrMain.SeqRefine`), the value in the
1106dict is the actual parameter value (usually a float, but sometimes a
1107letter or string flag value (such as I or A for iso/anisotropic).
1109Texture implementation
1112There are two different places where texture can be treated in GSAS-II.
1113One is for mitigating the effects of texture in a structural refinement.
1114The other is for texture characterization.
1116For reducing the effect of texture in a structural refinement
1117there are entries labeled preferred orientation in each phase's
1118data tab. Two different approaches can be used for this, the March-Dollase
1119model and spherical harmonics.
1121For the March-Dollase model, one axis in reciprocal space is designated as
1122unique (defaulting to the 001 axis) and reflections are corrected
1123according to the angle they make with this axis depending on
1124the March-Dollase ratio. (If unity, no correction is made).
1125The ratio can be greater than one or less than one depending on if
1126crystallites oriented along the designated axis are
1127overrepresented or underrepresented. For most crystal systems there is an
1128obvious choice for the direction of the unique axis and then only a single
1129term needs to be refined. If the number is close to 1, then the correction
1130is not needed.
1132The second method for reducing the effect of texture in a structural
1133refinement is to create a crystallite orientation probability surface as an
1134expansion in terms spherical harmonic functions. Only functions consistent with
1135cylindrical diffraction suymmetry and having texture symmetry
1136consistent with the Laue class of phase are used and are allowed,
1137so the higher the symmetry the fewer terms that are available for a given spherical harmonics order.
1138To use this correction, select the lowest order that provides
1139refinable terms and perform a refinement. If the texture index remains close to
1140one, then the correction is not needed. If a significant improvement is
1141noted in the profile Rwp, one may wish to see if a higher order expansion
1142gives an even larger improvement.
1144To characterize texture in a material, generally one needs data collected with the
1145sample at multiple orientations or, for TOF, with detectors at multiple
1146locations around the sample. In this case the detector orientation is given in
1147each histogram's Sample Parameters and the sample's orientation is described
1148with the Euler angles specifed on the phase's Texture tab, which is also
1149where the texture type (cylindrical, rolling,...) and the spherical
1150harmonic order is selected. This should not be used with a single dataset and
1151should not be used if the preferred orientations corrections are used.
1153The coordinate system used for texture characterization is defined where
1154the sample coordinates (Psi, gamma) are defined with an instrument coordinate
1155system (I, J, K) such that K is normal to the diffraction plane and J is coincident with the
1156direction of the incident radiation beam toward the source. We further define
1157a standard set of right-handed goniometer eulerian angles (Omega, Chi, Phi) so that Omega and Phi are
1158rotations about K and Chi is a rotation about J when Omega = 0. Finally, as the sample
1159may be mounted so that the sample coordinate system (Is, Js, Ks) does not coincide with
1160the instrument coordinate system (I, J, K), we define three eulerian sample rotation angles
1161(Omega-s, Chi-s, Phi-s) that describe the rotation from (Is, Js, Ks) to (I, J, K). The sample rotation
1162angles are defined so that with the goniometer angles at zero Omega-s and Phi-s are rotations
1163about K and Chi-s is a rotation about J.
1165Three typical examples:
1167    1) Bragg-Brentano laboratory diffractometer: Chi=0
1168    2) Debye-Scherrer counter detector; sample capillary axis perpendicular to diffraction plane: Chi=90
1169    3) Debye-Scherrer 2D area detector positioned directly behind sample; sample capillary axis horizontal; Chi=0
1171NB: The area detector azimuthal angle will equal 0 in horizontal plane to right as viewed from x-ray source and will equal
117290 at vertical "up" direction.
1174ISODISTORT implementation
1177CIFs prepared with the ISODISTORT web site
1179[B. J. Campbell, H. T. Stokes, D. E. Tanner, and D. M. Hatch, "ISODISPLACE: An Internet Tool for Exploring Structural Distortions."
1180J. Appl. Cryst. 39, 607-614 (2006).] can be read into GSAS-II using import CIF. This will cause constraints to be established for
1181structural distortion modes read from the CIF. At present, of the five types of modes  only displacive(``_iso_displacivemode``...)
1182and occupancy (``_iso_occupancymode``...) are processed. Not yet processed: ``_iso_magneticmode``...,
1183``_iso_rotationalmode``... & ``_iso_strainmode``...
1185The CIF importer :mod:`G2phase_CIF` implements class :class:`G2phase_CIF.CIFPhaseReader` which offers two methods associated
1186with ISODISTORT (ID) input. Method :meth:`G2phase_CIF.CIFPhaseReader.ISODISTORT_test` checks to see if a CIF block contains
1187the loops with ``_iso_displacivemode_label`` or  ``_iso_occupancymode_label`` items. If so, method
1188:meth:`G2phase_CIF.CIFPhaseReader.ISODISTORT_proc` is called to read and interpret them. The results are placed into the
1189reader object's ``.Phase`` class variable as a dict item with key ``'ISODISTORT'``.
1191Note that each mode ID has a long label with a name such as  Pm-3m[1/2,1/2,1/2]R5+(a,a,0)[La:b:dsp]T1u(a). Function
1192:func:`G2phase_CIF.ISODISTORT_shortLbl` is used to create a short name for this, such as R5_T1u(a) which is made unique
1193by addition of _n if the short name is duplicated. As each mode is processed, a constraint corresponding to that mode is
1194created and is added to list in the reader object's ``.Constraints`` class variable. Items placed into that list can either
1195be a list, which corresponds to a function (new var) type :ref:`constraint definition <Constraints_table>` entry, or an item
1196can be a dict, which provides help information for each constraint.
1199Displacive modes
1202The coordinate variables, as named by ISODISTORT, are placed in ``.Phase['ISODISTORT']['IsoVarList']`` and the
1203corresponding :class:`GSASIIobj.G2VarObj` objects for each are placed in ``.Phase['ISODISTORT']['G2VarList']``.
1204The mode variables, as named by ISODISTORT, are placed in ``.Phase['ISODISTORT']['IsoModeList']`` and the
1205corresponding :class:`GSASIIobj.G2VarObj` objects for each are placed in ``.Phase['ISODISTORT']['G2ModeList']``.
1206[Use ``str(G2VarObj)`` to get the variable name from the G2VarObj object, but note that the phase number, *n*, for the prefix
1207"*n*::" cannot be determined as the phase number is not yet assigned.]
1209Displacive modes are a bit complex in that they relate to delta displacements, relative to an offset value for each coordinate,
1210and because the modes are normalized. While GSAS-II also uses displacements,  these are added to the coordinates after
1211each refinement cycle and then the delta values are set to zero.
1212ISODISTORT uses fixed offsets (subtracted from the actual position
1213to obtain the delta values) that are taken from the parent structure coordinate and the initial offset value
1214(in ``_iso_deltacoordinate_value``) and these are placed in
1215``.Phase['ISODISTORT']['G2coordOffset']`` in the same order as ``.Phase['ISODISTORT']['G2ModeList']``,
1216``.Phase['ISODISTORT']['IsoVarList']`` and ''.Phase[ISODISTORT']['G2parentCoords']''.'
1218The normalization factors (which the delta values are divided by)
1219are taken from ``_iso_displacivemodenorm_value`` and are placed in ``.Phase['ISODISTORT']['NormList']`` in the same
1220order as as ``...['IsoModeList']`` and ``...['G2ModeList']``.
1222The CIF contains a sparse matrix, from the ``loop_`` containing ``_iso_displacivemodematrix_value`` which provides the equations
1223for determining the mode values from the coordinates, that matrix is placed in ``.Phase['ISODISTORT']['Mode2VarMatrix']``.
1224The matrix is inverted to produce ``.Phase['ISODISTORT']['Var2ModeMatrix']``, which determines how to compute the
1225mode values from the delta coordinate values. These values are used for the in :func:`GSASIIconstrGUI.ShowIsoDistortCalc`,
1226which shows coordinate and mode values, the latter with s.u. values.
1229Occupancy modes
1233The delta occupancy variables, as named by ISODISTORT, are placed in
1234``.Phase['ISODISTORT']['OccVarList']`` and the corresponding :class:`GSASIIobj.G2VarObj` objects for each are placed
1235in ``.Phase['ISODISTORT']['G2OccVarList']``. The mode variables, as named by ISODISTORT, are placed in
1236``.Phase['ISODISTORT']['OccModeList']`` and the corresponding :class:`GSASIIobj.G2VarObj` objects for each are placed
1237in ``.Phase['ISODISTORT']['G2OccModeList']``.
1239Occupancy modes, like Displacive modes, are also refined as delta values.  However, GSAS-II directly refines the fractional
1240occupancies. Offset values for each atom, are taken from ``_iso_occupancy_formula`` and are placed in
1241``.Phase['ISODISTORT']['ParentOcc]``. (Offset values are subtracted from the actual position to obtain the delta values.)
1242Modes are normalized (where the mode values are divided by the normalization factor) are taken from ``_iso_occupancymodenorm_value`` 
1243and are placed in ``.Phase['ISODISTORT']['OccNormList']`` in the same order as as ``...['OccModeList']`` and
1246The CIF contains a sparse matrix, from the ``loop_`` containing ``_iso_occupancymodematrix_value``, which provides the
1247equations for determining the mode values from the coordinates. That matrix is placed in ``.Phase['ISODISTORT']['Occ2VarMatrix']``.
1248The matrix is inverted to produce ``.Phase['ISODISTORT']['Var2OccMatrix']``, which determines how to compute the
1249mode values from the delta coordinate values.
1253Mode Computations
1256Constraints are processed after the CIF has been read in :meth:`GSASIIdataGUI.GSASII.OnImportPhase` or 
1257:meth:`GSASIIscriptable.G2Project.add_phase` by moving them from the reader object's ``.Constraints`` 
1258class variable to the Constraints tree entry's ['Phase'] list (for list items defining constraints) or
1259the Constraints tree entry's ['_Explain'] dict (for dict items defining constraint help information)
1261The information in ``.Phase['ISODISTORT']`` is used in :func:`GSASIIconstrGUI.ShowIsoDistortCalc` which shows coordinate and mode
1262values, the latter with s.u. values. This can be called from the Constraints and Phase/Atoms tree items.
1264Before each refinement, constraints are processed as :ref:`described elsewhere <Constraints_processing>`. After a refinement
1265is complete, :func:`GSASIIstrIO.PrintIndependentVars` shows the shifts and s.u.'s on the refined modes,
1266using GSAS-II values, but :func:`GSASIIstrIO.PrintISOmodes` prints the ISODISTORT modes as computed in the web site.
1269.. _ParameterLimits:
1271.. index::
1272   single: Parameter limits
1274Parameter Limits
1277One of the most often requested "enhancements" for GSAS-II would be the inclusion
1278of constraints to force parameters such as occupancies or Uiso values to stay within
1279expected ranges. While it is possible for users to supply their own restraints that would
1280perform this by supplying an appropriate expression with the "General" restraints, the
1281GSAS-II authors do not feel that use of restraints or constraints are a good solution for
1282this common problem where parameters refine to non-physical values. This is because when
1283this occurs, most likely one of the following cases is occurring:
1285#. there is a significant problem
1286   with the model, for example for an x-ray fit if an O atom is placed where a S is actually
1287   present, the Uiso will refine artificially small or the occupancy much larger than unity
1288   to try to compensate for the missing electrons; or
1290#. the data are simply insensitive
1291   to the parameter or combination of parameters, for example unless very high-Q data
1292   are included, the effects of a occupancy and Uiso value can have compensating effects,
1293   so an assumption must be made; likewise, with neutron data natural-abundance V atoms
1294   are nearly invisible due to weak coherent scattering. No parameters can be fit for a
1295   V atom with neutrons.
1297#. the parameter is non-physical (such as a negative Uiso value) but within
1298   two sigma (sigma = standard uncertainty, aka e.s.d.) of a reasonable value,
1299   in which case the
1300   value is not problematic as it is experimentally indistinguishable from an
1301   expected value. 
1303#. there is a systematic problem with the data (experimental error)
1305In all these cases, this situation needs to be reviewed by a crystallographer to decide
1306how to best determine a structural model for these data. An implementation with a constraint
1307or restraint is likely to simply hide the problem from the user, making it more probable
1308that a poor model choice is obtained.
1310What GSAS-II does implement is to allow users to specify ranges for parameters
1311that works by disabling
1312refinement of parameters that refine beyond either a lower limit or an upper limit, where
1313either or both may be optionally specified. Parameters limits are specified in the Controls
1314tree entry in dicts named as ``Controls['parmMaxDict']`` and ``Controls['parmMinDict']``, where
1315the keys are :class:`G2VarObj` objects corresponding to standard GSAS-II variable
1316(see :func:`getVarDescr` and :func:`CompileVarDesc`) names, where a
1317wildcard ('*') may optionally be used for histogram number or atom number
1318(phase number is intentionally not  allowed as a wildcard as it makes little sense
1319to group the same parameter together different phases). Note
1320that :func:`prmLookup` is used to see if a name matches a wildcard. The upper or lower limit
1321is placed into these dicts as a float value. These values can be edited using the window
1322created by the Calculate/"View LS parms" menu command or in scripting with the
1323:meth:`GSASIIscriptable.G2Project.set_Controls` function.
1324In the GUI, a checkbox labeled "match all histograms/atoms" is used to insert a wildcard
1325into the appropriate part of the variable name.
1327When a refinement is conducted, routine :func:`GSASIIstrMain.dropOOBvars` is used to
1328find parameters that have refined to values outside their limits. If this occurs, the parameter
1329is set to the limiting value and the variable name is added to a list of frozen variables
1330(as a :class:`G2VarObj` objects) kept in a list in the
1331``Controls['parmFrozen']`` dict. In a sequential refinement, this is kept separate for
1332each histogram as a list in
1333``Controls['parmFrozen'][histogram]`` (where the key is the histogram name) or as a list in
1334``Controls['parmFrozen']['FrozenList']`` for a non-sequential fit.
1335This allows different variables
1336to be frozen in each section of a sequential fit.
1337Frozen parameters are not included in refinements through removal from the
1338list of parameters to be refined (``varyList``) in :func:`GSASIIstrMain.Refine` or
1340The data window for the Controls tree item shows the number of Frozen variables and
1341the individual variables can be viewed with the Calculate/"View LS parms" menu window or
1342obtained with :meth:`GSASIIscriptable.G2Project.get_Frozen`.
1343Once a variable is frozen, it will not be refined in any
1344future refinements unless the the variable is removed (manually) from the list. This can also
1345be done with the Calculate/"View LS parms" menu window or
1349.. seealso::
1350  :class:`G2VarObj`
1351  :func:`getVarDescr` 
1352  :func:`CompileVarDesc`
1353  :func:`prmLookup`
1354  :class:`GSASIIctrlGUI.ShowLSParms`
1355  :class:`GSASIIctrlGUI.VirtualVarBox`
1356  :func:`GSASIIstrIO.SetUsedHistogramsAndPhases`
1357  :func:`GSASIIstrIO.SaveUpdatedHistogramsAndPhases`
1358  :func:`GSASIIstrIO.SetSeqResult`
1359  :func:`GSASIIstrMain.dropOOBvars`
1360  :meth:`GSASIIscriptable.G2Project.set_Controls`
1361  :meth:`GSASIIscriptable.G2Project.get_Frozen`
1362  :meth:`GSASIIscriptable.G2Project.set_Frozen`
1364*GSASIIobj Classes and routines*
1368.. automodule:: GSASIIobj
1369    :members: 
1370    :private-members:
1371    :special-members:
Note: See TracBrowser for help on using the repository browser.