Context Navigation

← Previous Revision
Next Revision →
Normal
Revision Log

GSASIIobj.rst

Last change on this file was 5578, checked in by toby, 2 weeks ago
add other .py files to Sphinx docs
File size: 82.5 KB

Rev	Line
[5572]	1	GSASIIobj: Data objects & Docs
	2	=================================================
	3
	4	Summary/Contents
	5	----------------------------
	6
	7	This module defines and/or documents the data structures used in GSAS-II, as well
	8	as provides misc. support routines.
	9
	10	.. contents:: Section Contents
	11
	12	.. index::
	13	single: Parameter names
	14	single: GSAS-II variable naming
	15
[5578]	16	.. _VarNames_table:
	17
[5572]	18	Variable names in GSAS-II
	19	----------------------------
	20
	21	Parameter 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,
	24	and ``n`` is the atom parameter number
	25	If a parameter does not depend on a histogram, phase or atom, ``h``, ``p`` and/or ``n`` will be omitted,
	26	so ``p::<var>:n``, ``:h:<var>`` and ``p:h:<var>`` are all valid names.
	27
	28	.. include:: vars.rst
	29
	30	.. _Constraints_table:
	31
	32	.. index::
	33	single: Constraints object description
	34	single: Data object descriptions; Constraints
	35
	36	Constraints Tree Item
	37	----------------------
	38
	39	Constraints are stored in a dict, separated into groups.
	40	Note that parameter are named in the following pattern,
	41	p: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.
	43	If a parameter does not depend on a histogram or phase or is unnumbered, that
	44	number is omitted.
	45	Note that the contents of each dict item is a List where each element in the
	46	list is a :ref:`constraint definition objects <Constraint_definitions_table>`.
	47	The constraints in this form are converted in
	48	:func:`GSASIImapvars.ProcessConstraints` to the form used in :mod:`GSASIImapvars`
	49
	50	The keys in the Constraints dict are:
	51
	52	.. tabularcolumns:: \|l\|p{4.5in}\|
	53
	54	========== ====================================================
	55	key explanation
	56	========== ====================================================
	57	Hist This specifies a list of constraints on
	58	histogram-related parameters,
	59	which will be of form :h:<var>:n.
	60	HAP 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.
	63	Phase This specifies a list of constraints on phase
	64	parameters,
	65	which will be of form p::<var>:n.
	66	Global 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	========== ====================================================
	70
	71	.. _Constraint_definitions_table:
	72
	73	.. index::
	74	single: Constraint definition object description
	75	single: Data object descriptions; Constraint Definition
	76
	77	Each constraint is defined as an item in a list. Each constraint is of form::
	78
	79	[[<mult1>, <var1>], [<mult2>, <var2>],..., <fixedval>, <varyflag>, <constype>]
	80
	81	Where the variable pair list item containing two values [<mult>, <var>], where:
	82
	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]')
	85
	86	Note that the last three items in the list play a special role:
	87
	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:
	95
	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 + ...`
	109
	110	.. _Covariance_table:
	111
	112	.. index::
	113	single: Covariance description
	114	single: Data object descriptions; Covariance
	115
	116	Covariance Tree Item
	117	--------------------
	118
	119	The Covariance tree item has results from the last least-squares run. They
	120	are stored in a dict with these keys:
	121
	122	.. tabularcolumns:: \|l\|l\|p{4in}\|
	123
	124	============= =============== ====================================================
	125	key sub-key explanation
	126	============= =============== ====================================================
	127	newCellDict \ (dict) ith lattice parameters computed by
	128	:func:`GSASIIstrMath.GetNewCellParms`
	129	title \ (str) Name of gpx file(?)
	130	variables \ (list) Values for all N refined variables
	131	(list of float values, length N,
	132	ordered to match varyList)
	133	sig \ (list) Uncertainty values for all N refined variables
	134	(list of float values, length N,
	135	ordered to match varyList)
	136	varyList \ (list of str values, length N) List of directly refined variables
	137
	138	newAtomDict \ (dict) atom position values computed in
	139	:func:`GSASIIstrMath.ApplyXYZshifts`
	140	Rvals \ (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.
	150	covMatrix \ (np.array) The (NxN) covVariance matrix
	151	============= =============== ====================================================
	152
	153	.. _Phase_table:
	154
	155	.. index::
	156	single: Phase object description
	157	single: Data object descriptions; Phase
	158
	159	Phase Tree Items
	160	----------------
	161
	162	Phase information is stored in the GSAS-II data tree as children of the
	163	Phases item in a dict with keys:
	164
	165	.. tabularcolumns:: \|l\|l\|p{4in}\|
	166
	167	========== =============== =====================================================================================================
	168	key sub-key explanation
	169	========== =============== =====================================================================================================
	170	General \ (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.)
	182
	183	0: cell refinement flag (True/False),
	184
	185	1-3: a, b, c, (:math:`\AA`)
	186
	187	4-6: alpha, beta & gamma, (degrees)
	188
	189	7: volume (:math:`\AA^3`)
	190
	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
	230	ranId \ (int) unique random number Id for phase
	231	pId \ (int) Phase Id number for current project.
	232	Atoms \ (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.
	236	Drawing \ (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])
	274	ISODISTORT \ (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
	296
	297	RBModels \ Rigid body assignments (note Rigid body definitions
	298	are stored in their own main top-level tree entry.)
	299	RMC \ (dict) RMCProfile, PDFfit & fullrmc controls
	300	Pawley ref \ (list) Pawley reflections
	301	Histograms \ (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:
	319
	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.
	328
	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:
	339
	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
	347	MCSA \ (dict) Monte-Carlo simulated annealing parameters
	348	========== =============== =====================================================================================================
	349
	350	.. _RBData_table:
	351
	352	.. index::
	353	single: Rigid Body Data description
	354	single: Data object descriptions; Rigid Body Data
	355
	356	Rigid Body Objects
	357	------------------
	358
	359	Rigid body descriptions are available for two types of rigid bodies: 'Vector'
	360	and 'Residue'. Vector rigid bodies are developed by a sequence of translations each
	361	with a refinable magnitude and Residue rigid bodies are described as Cartesian coordinates
	362	with defined refinable torsion angles.
	363
	364	.. tabularcolumns:: \|l\|l\|p{4in}\|
	365
	366	========== =============== ====================================================
	367	key sub-key explanation
	368	========== =============== ====================================================
	369	Vector 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
	380	Residue 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
	393	RBIds \ (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	========== =============== ====================================================
	397
	398	.. _SGData_table:
	399
	400	.. index::
	401	single: Space Group Data description
	402	single: Data object descriptions; Space Group Data
	403
	404	Space Group Objects
	405	-------------------
	406
	407	Space groups are interpreted by :func:`GSASIIspc.SpcGroup`
	408	and the information is placed in a SGdata object
	409	which is a dict with these keys. Magnetic ones are marked "mag"
	410
	411	.. tabularcolumns:: \|l\|p{4.5in}\|
	412
	413	========== ========================================================================================
	414	key explanation
	415	========== ========================================================================================
	416	BNSlattsym mag - (str) BNS magnetic space group symbol and centering vector
	417	GenFlg mag - (list) symmetry generators indices
	418	GenSym mag - (list) names for each generator
	419	MagMom mag - (list) "time reversals" for each magnetic operator
	420	MagPtGp mag - (str) Magnetic point group symbol
	421	MagSpGrp mag - (str) Magnetic space group symbol
	422	OprNames mag - (list) names for each space group operation
	423	SGCen (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]])``
	425	SGFixed (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
	428	SGGen (list) generators
	429	SGGray (bool) True if space group is a gray group (incommensurate magnetic structures)
	430	SGInv (bool) True if centrosymmetric, False if not
	431	SGLatt (str)Lattice centering type. Will be one of
	432	P, A, B, C, I, F, R
	433	SGLaue (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
	436	SGOps (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`
	444	SGPolax (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 ?).
	448	SGPtGrp (str) Point group of the space group
	449	SGUniq unique axis if monoclinic. Will be
	450	a, b, or c for monoclinic space groups.
	451	Will be blank for non-monoclinic.
	452	SGSpin mag - (list) of spin flip operatiors (+1 or -1) for the space group operations
	453	SGSys (str) symmetry unit cell: type one of
	454	'triclinic', 'monoclinic', 'orthorhombic',
	455	'tetragonal', 'rhombohedral', 'trigonal',
	456	'hexagonal', 'cubic'
	457	SSGK1 (list) Superspace multipliers
	458	SpGrp (str) space group symbol
	459	SpnFlp mag - (list) Magnetic spin flips for every magnetic space group operator
	460	========== ========================================================================================
	461
	462	.. _SSGData_table:
	463
	464	.. index::
	465	single: Superspace Group Data description
	466	single: Data object descriptions; Superspace Group Data
	467
	468	Superspace groups [3+1] are interpreted by :func:`GSASIIspc.SSpcGroup`
	469	and the information is placed in a SSGdata object
	470	which is a dict with these keys:
	471
	472	.. tabularcolumns:: \|l\|p{4.5in}\|
	473
	474	========== ====================================================
	475	key explanation
	476	========== ====================================================
	477	SSGCen (list) 4D cell centering vectors [0,0,0,0] at least
	478	SSGK1 (list) Superspace multipliers
	479	SSGOps (list) 4D symmetry operations as [M,T] so that M*x+T = x'
	480	SSpGrp (str) superspace group symbol extension to space group
	481	symbol, accidental spaces removed
	482	modQ (list) modulation/propagation vector
	483	modSymb (list of str) Modulation symbols
	484	========== ====================================================
	485
	486
	487	Phase Information
	488	--------------------
	489
	490	.. index::
	491	single: Phase information record description
	492
	493	Phase information is placed in one of the following keys:
	494
	495	.. tabularcolumns:: \|l\|p{4.5in}\|
	496
	497	========== ==============================================================
	498	key explanation
	499	========== ==============================================================
	500	General Overall information about a phase
	501	Histograms 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.
	506	Atoms Contains a list of atoms, as described in the
	507	:ref:`Atom Records <Atoms_table>` description.
	508	Drawing 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
	513	MCSA Monte-Carlo simulated annealing parameters
	514	pId The index of each phase in the project, numbered
	515	starting at 0
	516	ranId An int value with a unique value for each phase
	517	RBModels 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>`
	523	RMC PDF modeling parameters
	524	Pawley ref Pawley refinement parameters
	525
	526	========== ==============================================================
	527
	528	.. _Atoms_table:
	529
	530	.. index::
	531	single: Atoms record description
	532	single: Data object descriptions; Atoms record
	533
	534	--------------------
	535	Atom Records
	536	--------------------
	537
	538	If ``phasedict`` points to the phase information in the data tree, then
	539	atoms are contained in a list of atom records (list) in
	540	``phasedict['Atoms']``. Also needed to read atom information
	541	are four pointers, ``cx,ct,cs,cia = phasedict['General']['AtomPtrs']``,
	542	which define locations in the atom record, as shown below. Items shown are
	543	always present; additional ones for macromolecular phases are marked 'mm',
	544	and those for magnetic structures are marked 'mg'
	545
	546	.. tabularcolumns:: \|l\|p{4.5in}\|
	547
	548	============== ====================================================
	549	location explanation
	550	============== ====================================================
	551	ct-4 mm - (str) residue number
	552	ct-3 mm - (str) residue name (e.g. ALA)
	553	ct-2 mm - (str) chain label
	554	ct-1 (str) atom label
	555	ct (str) atom type
	556	ct+1 (str) refinement flags; combination of 'F', 'X', 'U', 'M'
	557	cx,cx+1,cx+2 (3 floats) the x,y and z coordinates
	558	cx+3 (float) site occupancy
	559	cx+4,cx+5,cx+6 mg - (list) atom magnetic moment along a,b,c in Bohr magnetons
	560	cs (str) site symmetry
	561	cs+1 (int) site multiplicity
	562	cia (str) ADP flag: Isotropic ('I') or Anisotropic ('A')
	563	cia+1 (float) Uiso
	564	cia+2...cia+7 (6 floats) U11, U22, U33, U12, U13, U23
	565	atom[cia+8] (int) unique atom identifier
	566
	567	============== ====================================================
	568
	569	.. _Drawing_atoms_table:
	570
	571	.. index::
	572	single: Drawing atoms record description
	573	single: Data object descriptions; Drawing atoms record
	574
	575	----------------------------
	576	Drawing Atom Records
	577	----------------------------
	578
	579	If ``phasedict`` points to the phase information in the data tree, then
	580	drawing atoms are contained in a list of drawing atom records (list) in
	581	``phasedict['Drawing']['Atoms']``. Also needed to read atom information
	582	are four pointers, ``cx,ct,cs,ci = phasedict['Drawing']['AtomPtrs']``,
	583	which define locations in the atom record, as shown below. Items shown are
	584	always present; additional ones for macromolecular phases are marked 'mm',
	585	and those for magnetic structures are marked 'mg'
	586
	587	.. tabularcolumns:: \|l\|p{4.5in}\|
	588
	589	============== ===================================================================================
	590	location explanation
	591	============== ===================================================================================
	592	ct-4 mm - (str) residue number
	593	ct-3 mm - (str) residue name (e.g. ALA)
	594	ct-2 mm - (str) chain label
	595	ct-1 (str) atom label
	596	ct (str) atom type
	597	cx,cx+1,cx+2 (3 floats) the x,y and z coordinates
	598	cx+3,cx+4,cx+5 mg - (3 floats) atom magnetic moment along a,b,c in Bohr magnetons
	599	cs-1 (str) Sym Op symbol; sym. op number + unit cell id (e.g. '1,0,-1')
	600	cs (str) atom drawing style; e.g. 'balls & sticks'
	601	cs+1 (str) atom label style (e.g. 'name')
	602	cs+2 (int) atom color (RBG triplet)
	603	cs+3 (str) ADP flag: Isotropic ('I') or Anisotropic ('A')
	604	cs+4 (float) Uiso
	605	cs+5...cs+11 (6 floats) U11, U22, U33, U12, U13, U23
	606	ci (int) unique atom identifier; matches source atom Id in Atom Records
	607	============== ===================================================================================
	608
	609	.. _Rigid_Body_Insertions:
	610
	611	----------------------------
	612	Rigid Body Insertions
	613	----------------------------
	614
	615	If ``phasedict`` points to the phase information in the data tree, then
	616	rigid body information is contained in list(s) in
	617	``phasedict['RBModels']['Residue']`` and/or ``phasedict['RBModels']['Vector']``
	618	for each rigid body inserted into the current phase.
	619
	620	.. tabularcolumns:: \|l\|p{4.5in}\|
	621
	622	============== ===================================================================================
	623	key explanation
	624	============== ===================================================================================
	625	fixOrig Should the origin be fixed (when editing, not the refinement flag)
	626	Ids Ids for assignment of atoms in the rigid body
	627	numChain Chain number for macromolecular fits
	628	Orient Orientation of the RB as a quaternion and a refinement flag (' ', 'A' or 'AV')
	629	OrientVec Orientation of the RB expressed as a vector and azimuthal rotation angle
	630	Orig Origin of the RB in fractional coordinates and refinement flag (bool)
	631	RBId References the unique ID of a rigid body in the
	632	:ref:`Rigid Body Objects <RBData_table>`
	633	RBname The name for the rigid body (str)
	634	AtomFrac The atom fractions for the rigid body
	635	ThermalMotion 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.
	637	Torsions Defines the torsion angle and refinement flag for each torsion defined in
	638	the :ref:`Rigid Body Object <RBData_table>`
	639	============== ===================================================================================
	640
	641	.. _Powder_table:
	642
	643	.. index::
	644	single: Powder data object description
	645	single: Data object descriptions; Powder Data
	646
	647	Powder Diffraction Tree Items
	648	-----------------------------
	649
	650	Every powder diffraction histogram is stored in the GSAS-II data tree
	651	with a top-level entry named beginning with the string "PWDR ". The
	652	diffraction data for that information are directly associated with
	653	that tree item and there are a series of children to that item. The
	654	routines :func:`GSASIIdataGUI.GSASII.GetUsedHistogramsAndPhasesfromTree`
	655	and :func:`GSASIIstrIO.GetUsedHistogramsAndPhases` will
	656	load this information into a dictionary where the child tree name is
	657	used as a key, and the information in the main entry is assigned
	658	a key of ``Data``, as outlined below.
	659
	660	.. tabularcolumns:: \|p{1in}\|p{1in}\|p{4in}\|
	661
	662	====================== =============== ===========================================================
	663	key sub-key explanation
	664	====================== =============== ===========================================================
	665	Comments \ (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.
	668	Limits \ (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.
	673	Reflection 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.
	678	Instrument 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.
	681	wtFactor \ (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).
	687	Sample 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' .
	720	hId \ (int) The number assigned to the histogram when
	721	the project is loaded or edited (can change)
	722	ranId \ (int) A random number id for the histogram
	723	that does not change
	724	Background \ (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.)
	730	Data \ (list) The data consist of a list of 6 np.arrays
	731	containing in order:
	732
	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	====================== =============== ===========================================================
	740
	741	.. _CWPowder_table:
	742
	743	.. index::
	744	single: Powder data CW Instrument Parameters
	745
	746	-----------------------------
	747	CW Instrument Parameters
	748	-----------------------------
	749
	750	Instrument Parameters are placed in a list of two dicts,
	751	where the keys in the first dict are listed below. Note that the dict contents are different for
	752	constant wavelength (CW) vs. time-of-flight (TOF) histograms.
	753	The value for each item is a list containing three values: the initial value, the current value
	754	and a refinement flag which can have a value of True, False or 0 where 0 indicates a value that
	755	cannot be refined. The first and second values are floats unless otherwise noted.
	756	Items not refined are noted as [*]
	757
	758	.. tabularcolumns:: \|l\|p{1in}\|p{4in}\|
	759
	760	======================== =============== ===========================================================
	761	key sub-key explanation
	762	======================== =============== ===========================================================
	763	Instrument 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.
	788	Instrument Parameters[1] (empty dict)
	789	======================== =============== ===========================================================
	790
	791	.. _TOFPowder_table:
	792
	793	.. index::
	794	single: Powder data TOF Instrument Parameters
	795
	796	-----------------------------
	797	TOF Instrument Parameters
	798	-----------------------------
	799
	800	Instrument Parameters are also placed in a list of two dicts,
	801	where the keys in each dict listed below, but here for
	802	time-of-flight (TOF) histograms.
	803	The value for each item is a list containing three values: the initial value, the current value
	804	and a refinement flag which can have a value of True, False or 0 where 0 indicates a value that
	805	cannot be refined. The first and second values are floats unless otherwise noted.
	806	Items not refined are noted as [*]
	807
	808	.. tabularcolumns:: \|l\|p{1.5in}\|p{4in}\|
	809
	810	======================== =============== ===========================================================
	811	key sub-key explanation
	812	======================== =============== ===========================================================
	813	Instrument 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
	832	Instrument 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	======================== =============== ===========================================================
	836
	837
	838	.. _PowderRefl_table:
	839
	840	.. index::
	841	single: Powder reflection object description
	842	single: Data object descriptions; Powder Reflections
	843
	844	Powder Reflection Data Structure
	845	--------------------------------
	846
	847	For every phase in a histogram, the ``Reflection Lists`` value is a dict
	848	one element of which is `'RefList'`, which is a np.array containing
	849	reflections. The columns in that array are documented below.
	850
	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	========== ====================================================
	869
	870	.. _Xtal_table:
	871
	872	.. index::
	873	single: Single Crystal data object description
	874	single: Data object descriptions; Single crystal data
	875
	876	Single Crystal Tree Items
	877	-------------------------
	878
	879	Every single crystal diffraction histogram is stored in the GSAS-II data tree
	880	with a top-level entry named beginning with the string "HKLF ". The
	881	diffraction data for that information are directly associated with
	882	that tree item and there are a series of children to that item. The
	883	routines :func:`GSASIIdataGUI.GSASII.GetUsedHistogramsAndPhasesfromTree`
	884	and :func:`GSASIIstrIO.GetUsedHistogramsAndPhases` will
	885	load this information into a dictionary where the child tree name is
	886	used as a key, and the information in the main entry is assigned
	887	a key of ``Data``, as outlined below.
	888
	889	.. tabularcolumns:: \|l\|l\|p{4in}\|
	890
	891	====================== =============== ====================================================
	892	key sub-key explanation
	893	====================== =============== ====================================================
	894	Data \ (dict) that contains the
	895	reflection table,
	896	as described in the
	897	:ref:`Single Crystal Reflections
	898	<XtalRefl_table>`
	899	description.
	900
	901	Instrument 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
	914	wtFactor \ (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).
	920
	921	hId \ (int) The number assigned to the histogram when
	922	the project is loaded or edited (can change)
	923	ranId \ (int) A random number id for the histogram
	924	that does not change
	925	====================== =============== ====================================================
	926
	927	.. _XtalRefl_table:
	928
	929	.. index::
	930	single: Single Crystal reflection object description
	931	single: Data object descriptions; Single Crystal Reflections
	932
	933	Single Crystal Reflection Data Structure
	934	----------------------------------------
	935
	936	For every single crystal a histogram, the ``'Data'`` item contains
	937	the structure factors as an np.array in item `'RefList'`.
	938	The columns in that array are documented below.
	939
	940	.. tabularcolumns:: \|l\|p{4in}\|
	941
	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	========== ====================================================
	958
	959	.. _Image_table:
	960
	961	.. index::
	962	image: Image data object description
	963	image: Image object descriptions
	964
	965	Image Data Structure
	966	--------------------
	967
	968	Every 2-dimensional image is stored in the GSAS-II data tree
	969	with a top-level entry named beginning with the string "IMG ". The
	970	image data are directly associated with that tree item and there
	971	are a series of children to that item. The routines :func:`GSASIIdataGUI.GSASII.GetUsedHistogramsAndPhasesfromTree`
	972	and :func:`GSASIIstrIO.GetUsedHistogramsAndPhases` will
	973	load this information into a dictionary where the child tree name is
	974	used as a key, and the information in the main entry is assigned
	975	a key of ``Data``, as outlined below.
	976
	977	.. tabularcolumns:: \|l\|l\|p{4in}\|
	978
	979	====================== ====================== ====================================================
	980	key sub-key explanation
	981	====================== ====================== ====================================================
	982	Comments \ (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.
	985	Image 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 UserCalibrants.py (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).
	1054	Masks 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
	1069
	1070	Stress/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.
	1086
	1087	====================== ====================== ====================================================
	1088
	1089	.. _parmDict_table:
	1090
	1091	.. index::
	1092	single: Parameter dictionary
	1093
	1094	Parameter Dictionary
	1095	-------------------------
	1096
	1097	The parameter dictionary contains all of the variable parameters for the refinement.
	1098	The dictionary keys are the name of the parameter (<phase>:<hist>:<name>:<atom>).
	1099	It is prepared in two ways. When loaded from the tree
	1100	(in :meth:`GSASIIdataGUI.GSASII.MakeLSParmDict` and
	1101	:meth:`GSASIIIO.ExportBaseclass.loadParmDict`),
	1102	the values are lists with two elements: ``[value, refine flag]``
	1103
	1104	When loaded from the GPX file (in
	1105	:func:`GSASIIstrMain.Refine` and :func:`GSASIIstrMain.SeqRefine`), the value in the
	1106	dict is the actual parameter value (usually a float, but sometimes a
	1107	letter or string flag value (such as I or A for iso/anisotropic).
	1108
	1109	Texture implementation
	1110	------------------------------
	1111
	1112	There are two different places where texture can be treated in GSAS-II.
	1113	One is for mitigating the effects of texture in a structural refinement.
	1114	The other is for texture characterization.
	1115
	1116	For reducing the effect of texture in a structural refinement
	1117	there are entries labeled preferred orientation in each phase's
	1118	data tab. Two different approaches can be used for this, the March-Dollase
	1119	model and spherical harmonics.
	1120
	1121	For the March-Dollase model, one axis in reciprocal space is designated as
	1122	unique (defaulting to the 001 axis) and reflections are corrected
	1123	according to the angle they make with this axis depending on
	1124	the March-Dollase ratio. (If unity, no correction is made).
	1125	The ratio can be greater than one or less than one depending on if
	1126	crystallites oriented along the designated axis are
	1127	overrepresented or underrepresented. For most crystal systems there is an
	1128	obvious choice for the direction of the unique axis and then only a single
	1129	term needs to be refined. If the number is close to 1, then the correction
	1130	is not needed.
	1131
	1132	The second method for reducing the effect of texture in a structural
	1133	refinement is to create a crystallite orientation probability surface as an
	1134	expansion in terms spherical harmonic functions. Only functions consistent with
	1135	cylindrical diffraction suymmetry and having texture symmetry
	1136	consistent with the Laue class of phase are used and are allowed,
	1137	so the higher the symmetry the fewer terms that are available for a given spherical harmonics order.
	1138	To use this correction, select the lowest order that provides
	1139	refinable terms and perform a refinement. If the texture index remains close to
	1140	one, then the correction is not needed. If a significant improvement is
	1141	noted in the profile Rwp, one may wish to see if a higher order expansion
	1142	gives an even larger improvement.
	1143
	1144	To characterize texture in a material, generally one needs data collected with the
	1145	sample at multiple orientations or, for TOF, with detectors at multiple
	1146	locations around the sample. In this case the detector orientation is given in
	1147	each histogram's Sample Parameters and the sample's orientation is described
	1148	with the Euler angles specifed on the phase's Texture tab, which is also
	1149	where the texture type (cylindrical, rolling,...) and the spherical
	1150	harmonic order is selected. This should not be used with a single dataset and
	1151	should not be used if the preferred orientations corrections are used.
	1152
	1153	The coordinate system used for texture characterization is defined where
	1154	the sample coordinates (Psi, gamma) are defined with an instrument coordinate
	1155	system (I, J, K) such that K is normal to the diffraction plane and J is coincident with the
	1156	direction of the incident radiation beam toward the source. We further define
	1157	a standard set of right-handed goniometer eulerian angles (Omega, Chi, Phi) so that Omega and Phi are
	1158	rotations about K and Chi is a rotation about J when Omega = 0. Finally, as the sample
	1159	may be mounted so that the sample coordinate system (Is, Js, Ks) does not coincide with
	1160	the 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
	1162	angles are defined so that with the goniometer angles at zero Omega-s and Phi-s are rotations
	1163	about K and Chi-s is a rotation about J.
	1164
	1165	Three typical examples:
	1166
	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
	1170
	1171	NB: The area detector azimuthal angle will equal 0 in horizontal plane to right as viewed from x-ray source and will equal
	1172	90 at vertical "up" direction.
	1173
	1174	ISODISTORT implementation
	1175	------------------------------
	1176
	1177	CIFs prepared with the ISODISTORT web site
	1178	https://stokes.byu.edu/iso/isodistort_version5.6.1/isodistort.php
	1179	[B. J. Campbell, H. T. Stokes, D. E. Tanner, and D. M. Hatch, "ISODISPLACE: An Internet Tool for Exploring Structural Distortions."
	1180	J. Appl. Cryst. 39, 607-614 (2006).] can be read into GSAS-II using import CIF. This will cause constraints to be established for
	1181	structural distortion modes read from the CIF. At present, of the five types of modes only displacive(``_iso_displacivemode``...)
	1182	and occupancy (``_iso_occupancymode``...) are processed. Not yet processed: ``_iso_magneticmode``...,
	1183	``_iso_rotationalmode``... & ``_iso_strainmode``...
	1184
	1185	The CIF importer :mod:`G2phase_CIF` implements class :class:`G2phase_CIF.CIFPhaseReader` which offers two methods associated
	1186	with ISODISTORT (ID) input. Method :meth:`G2phase_CIF.CIFPhaseReader.ISODISTORT_test` checks to see if a CIF block contains
	1187	the 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
	1189	reader object's ``.Phase`` class variable as a dict item with key ``'ISODISTORT'``.
	1190
	1191	Note 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
	1193	by addition of _n if the short name is duplicated. As each mode is processed, a constraint corresponding to that mode is
	1194	created and is added to list in the reader object's ``.Constraints`` class variable. Items placed into that list can either
	1195	be a list, which corresponds to a function (new var) type :ref:`constraint definition <Constraints_table>` entry, or an item
	1196	can be a dict, which provides help information for each constraint.
	1197
	1198	------------------------------
	1199	Displacive modes
	1200	------------------------------
	1201
	1202	The coordinate variables, as named by ISODISTORT, are placed in ``.Phase['ISODISTORT']['IsoVarList']`` and the
	1203	corresponding :class:`GSASIIobj.G2VarObj` objects for each are placed in ``.Phase['ISODISTORT']['G2VarList']``.
	1204	The mode variables, as named by ISODISTORT, are placed in ``.Phase['ISODISTORT']['IsoModeList']`` and the
	1205	corresponding :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.]
	1208
	1209	Displacive modes are a bit complex in that they relate to delta displacements, relative to an offset value for each coordinate,
	1210	and because the modes are normalized. While GSAS-II also uses displacements, these are added to the coordinates after
	1211	each refinement cycle and then the delta values are set to zero.
	1212	ISODISTORT uses fixed offsets (subtracted from the actual position
	1213	to 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']''.'
	1217
	1218	The normalization factors (which the delta values are divided by)
	1219	are taken from ``_iso_displacivemodenorm_value`` and are placed in ``.Phase['ISODISTORT']['NormList']`` in the same
	1220	order as as ``...['IsoModeList']`` and ``...['G2ModeList']``.
	1221
	1222	The CIF contains a sparse matrix, from the ``loop_`` containing ``_iso_displacivemodematrix_value`` which provides the equations
	1223	for determining the mode values from the coordinates, that matrix is placed in ``.Phase['ISODISTORT']['Mode2VarMatrix']``.
	1224	The matrix is inverted to produce ``.Phase['ISODISTORT']['Var2ModeMatrix']``, which determines how to compute the
	1225	mode values from the delta coordinate values. These values are used for the in :func:`GSASIIconstrGUI.ShowIsoDistortCalc`,
	1226	which shows coordinate and mode values, the latter with s.u. values.
	1227
	1228	------------------------------
	1229	Occupancy modes
	1230	------------------------------
	1231
	1232
	1233	The 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
	1235	in ``.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
	1237	in ``.Phase['ISODISTORT']['G2OccModeList']``.
	1238
	1239	Occupancy modes, like Displacive modes, are also refined as delta values. However, GSAS-II directly refines the fractional
	1240	occupancies. 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.)
	1242	Modes are normalized (where the mode values are divided by the normalization factor) are taken from ``_iso_occupancymodenorm_value``
	1243	and are placed in ``.Phase['ISODISTORT']['OccNormList']`` in the same order as as ``...['OccModeList']`` and
	1244	``...['G2OccModeList']``.
	1245
	1246	The CIF contains a sparse matrix, from the ``loop_`` containing ``_iso_occupancymodematrix_value``, which provides the
	1247	equations for determining the mode values from the coordinates. That matrix is placed in ``.Phase['ISODISTORT']['Occ2VarMatrix']``.
	1248	The matrix is inverted to produce ``.Phase['ISODISTORT']['Var2OccMatrix']``, which determines how to compute the
	1249	mode values from the delta coordinate values.
	1250
	1251
	1252	------------------------------
	1253	Mode Computations
	1254	------------------------------
	1255
	1256	Constraints 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``
	1258	class variable to the Constraints tree entry's ['Phase'] list (for list items defining constraints) or
	1259	the Constraints tree entry's ['_Explain'] dict (for dict items defining constraint help information)
	1260
	1261	The information in ``.Phase['ISODISTORT']`` is used in :func:`GSASIIconstrGUI.ShowIsoDistortCalc` which shows coordinate and mode
	1262	values, the latter with s.u. values. This can be called from the Constraints and Phase/Atoms tree items.
	1263
	1264	Before each refinement, constraints are processed as :ref:`described elsewhere <Constraints_processing>`. After a refinement
	1265	is complete, :func:`GSASIIstrIO.PrintIndependentVars` shows the shifts and s.u.'s on the refined modes,
	1266	using GSAS-II values, but :func:`GSASIIstrIO.PrintISOmodes` prints the ISODISTORT modes as computed in the web site.
	1267
	1268
	1269	.. _ParameterLimits:
	1270
	1271	.. index::
	1272	single: Parameter limits
	1273
	1274	Parameter Limits
	1275	------------------------------
	1276
	1277	One of the most often requested "enhancements" for GSAS-II would be the inclusion
	1278	of constraints to force parameters such as occupancies or Uiso values to stay within
	1279	expected ranges. While it is possible for users to supply their own restraints that would
	1280	perform this by supplying an appropriate expression with the "General" restraints, the
	1281	GSAS-II authors do not feel that use of restraints or constraints are a good solution for
	1282	this common problem where parameters refine to non-physical values. This is because when
	1283	this occurs, most likely one of the following cases is occurring:
	1284
	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
	1289
	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.
	1296
	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.
	1302
	1303	#. there is a systematic problem with the data (experimental error)
	1304
	1305	In all these cases, this situation needs to be reviewed by a crystallographer to decide
	1306	how to best determine a structural model for these data. An implementation with a constraint
	1307	or restraint is likely to simply hide the problem from the user, making it more probable
	1308	that a poor model choice is obtained.
	1309
	1310	What GSAS-II does implement is to allow users to specify ranges for parameters
	1311	that works by disabling
	1312	refinement of parameters that refine beyond either a lower limit or an upper limit, where
	1313	either or both may be optionally specified. Parameters limits are specified in the Controls
	1314	tree entry in dicts named as ``Controls['parmMaxDict']`` and ``Controls['parmMinDict']``, where
	1315	the keys are :class:`G2VarObj` objects corresponding to standard GSAS-II variable
	1316	(see :func:`getVarDescr` and :func:`CompileVarDesc`) names, where a
	1317	wildcard ('*') 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
	1319	to group the same parameter together different phases). Note
	1320	that :func:`prmLookup` is used to see if a name matches a wildcard. The upper or lower limit
	1321	is placed into these dicts as a float value. These values can be edited using the window
	1322	created by the Calculate/"View LS parms" menu command or in scripting with the
	1323	:meth:`GSASIIscriptable.G2Project.set_Controls` function.
	1324	In the GUI, a checkbox labeled "match all histograms/atoms" is used to insert a wildcard
	1325	into the appropriate part of the variable name.
	1326
	1327	When a refinement is conducted, routine :func:`GSASIIstrMain.dropOOBvars` is used to
	1328	find parameters that have refined to values outside their limits. If this occurs, the parameter
	1329	is 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
	1332	each 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.
	1335	This allows different variables
	1336	to be frozen in each section of a sequential fit.
	1337	Frozen parameters are not included in refinements through removal from the
	1338	list of parameters to be refined (``varyList``) in :func:`GSASIIstrMain.Refine` or
	1339	:func:`GSASIIstrMain.SeqRefine`.
	1340	The data window for the Controls tree item shows the number of Frozen variables and
	1341	the individual variables can be viewed with the Calculate/"View LS parms" menu window or
	1342	obtained with :meth:`GSASIIscriptable.G2Project.get_Frozen`.
	1343	Once a variable is frozen, it will not be refined in any
	1344	future refinements unless the the variable is removed (manually) from the list. This can also
	1345	be done with the Calculate/"View LS parms" menu window or
	1346	:meth:`GSASIIscriptable.G2Project.set_Frozen`.
	1347
	1348
	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`
	1363
	1364	GSASIIobj Classes and routines
	1365	------------------------------------
	1366
	1367
[2027]	1368	.. automodule:: GSASIIobj
	1369	:members:
[5572]	1370	:private-members:
	1371	:special-members:

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

Context Navigation

source: trunk/docs/source/GSASIIobj.rst

Download in other formats: