Changeset 1164

Aug 17, 2011 9:13:48 AM (10 years ago)

document rigid body code

16 added
2 edited


  • branches/sandbox/doc/expgui6A.html

    r1151 r1164  
    2929<HR noshade width="75%" size="2" align="center">
    30 EXPGUI, part 6A
     30EXPGUI, part 7
    3131<HR noshade width="75%" size="2" align="center">
    34 <h3>A.6A Rigid Body Constraints panel</h3>
     34<h3>A.7 Rigid Body Introduction</h3>
    3636GSAS Rigid bodies are another way to constrain relative atomic
    37   positions. This will be documented further in the future.
     37  positions. In a rigid body fit,
     38a group of atoms are constrained so that they rotate and/or translate as a unit.
     39GSAS allows quite complex rigid bodies, with up to 9 scaling parameters and
     40when multiple rigid bodies are used with grouped parameters even more complex
     41constraints can be developed. The EXPGUI rigid body interface allows access to
     42most of the GSAS features and offers some setup features not in GSAS, but
     43expert users may need to use EXPEDT for some very complex constraint models.
     45 Use of a rigid body reduces
     46the number of parameters refined, prevents deviations from chemical
     47reasonableness and generally helps obtain a more stable refinement. This can be especially important in the
     48early stages of refinement. Rigid
     49bodies are commonly used to constrain rigid moieties such phenyl or cyclopentadienyl rings but, they can be generated for much
     50more complicated structures. Rigid bodies in GSAS are always
     51represented by a set of Cartesian coordinates describing the relative positions
     52of the atoms to be constrained. More complex frameworks can be constructed
     53using multiple sets of Cartesian coordinates with variable multipliers, for
     54more complex constraints. Even more sophisticated refinements are possible when
     55multiple rigid bodies are constrained to share an origin or positioning (Euler)
     58 Once created, the
     59rigid body framework is applied as a constraint by mapping it onto atoms in a
     60phase. The same rigid body framework can be mapped multiple times into one or
     61more phases.
     62  Once mapped, the set
     63of atoms will refine as a single body with 3 parameters describing the
     64translation of the rigid body origin (generally the centroid of mass of the
     65atomic grouping but, this is optional) and 3 parameters describing the rotation
     66of the body about the origin (Euler Angles). TLS terms (translation, libration,
     67screw) can be used to model cooperative thermal motion about the rigid
     68body. The EXPGUI rigid body routines
     69will allow the user to readily generate the rigid body framework (called matrices
     70in EXPGUI terminology) and map the rigid body to sets of atoms already present
     71in the GSAS EXP file.
     73The EXPGUI Rigid Body Panel allows for the
     74creation or viewing of rigid bodies.
     75A rough outline of the procedure to generate and refine with a rigid body
     76is as follows:
     79<LI>Define the framework of the rigid
     80body with a set of Cartesian coordinates representing the relative atomic
     81positions. This can be done by
     82manual input, loading the coordinates from an ASCII file,
     83converting Z-matrix coordinates to Cartesian or generating Cartesian coordinates
     84from fractional coordinates in an existing molecular fragment in the GSAS EXP
     87 The rigid body
     88framework must be mapped upon the crystal structure.
     89This requires that the atoms in the
     90phase be sequential and must match the order of atoms in the rigid body
     92  To change the sequential
     93order in the rigid body, the Edit Matrix routine may be used to reorder the
     94rigid body coordinates.
     95 In the
     96mapping procedure, this number of the first atom in the phase to match the
     97rigid body is designated (since the mapping then follows) and both the Euler angles
     98and rigid body origin are specified; EXPGUI can help determine values
     99  for these.
     100  This can be repeated to map the rigid
     101body framework to other parts of the structure.
     103 Once the rigid body framework
     104is mapped to the crystal structure, the refinement flags for the Euler angles
     105and Origin can be set. This will turn on the 'X' refinement flags for the
     106included atoms in the Phase Panel. It is important that these match the state
     107of the rigid body refinement flags or GENLES will crash.
     110<H3>A.7.a Main Rigid Body Panel</H3>
     112The main panel for rigid bodies presents a interface where bodies can
     113  be initially defined. When bodies have been defined, a tab appears
     114  for each defined body, where these bodies can be used or
     115  edited. This main panel is shown below and subsequent sections
     116  describe how bodies are initially defined.
     117  <BR><img src="rb001.jpg" alt="RB start panel">
     118 <BR>
     119  Rigid bodies are created
     120from one or more sets of Cartesian coordinates multiplied by a scale factor and
     121then summed to create Cartesian coordinates in Angstroms. This can be expressed
     122as a linear algebra expression,
     124 XYZ = M1*XYZ1 + M2*XYZ2 + ...
     127Where XYZ, XYZ1, ...are 3 by N matrices (3 columns by N atoms) and M1,
     129are scalars. Therefore in EXPGUI terminology, each set of Cartesian
     130coordinates is called a "Matrix." The
     131sum of these scaled matrices describes the rigid body framework that is to be
     132mapped upon the atoms of the crystal structure. Most commonly, however, only
     133one matrix is used and M1=1. In this case the matrix is simply a set of Cartesian
     134coordinates in Angstroms, which can be input by multiple methods.
     135As a reminder, note that the rigid body
     136framework will be mapped to consecutive atoms in the EXP file must be so the Cartesian
     137coordinates of the rigid body MUST be listed in a corresponding order.
     139If the ordering of the Cartesian
     140coordinates of the rigid body, as input, is incorrect, they may be rearranged
     141with the Edit Matrix panel invoked
     142from the Rigid Body Type panel.
     144Advanced refinements
     145may take advantage of the GSAS feature of multiple matrices, each with its own
     146matrix multiplier. This can result is some very advanced refinements such as
     147independently refining the C-C and C-H bond distances in a hydrocarbon
     150The "Create Rigid Body" tab offers several ways to create a rigid
     152<UL><LI>Manual rigid body definition
     153  <LI>Cartesian coordinates from ASCII text file
     154  <LI>Cartesian coordinates from a Z-matrix
     155  <LI>Compute Cartesian coordinates from EXP file (fractional coordinates)
     156  </UL>
     158 <H4>A.7.a1 Manual rigid body definition</H4>
     160  The manual definition window allows input of coordinates and
     161  multipier(s) by typing values into boxes. Number of matrices
     162  determines the number of multipliers and sets of coordinates that
     163  are added. Number of Cartesian sites is the number of atoms in the
     164  rigid body. The "Save Rigid Body" button creates a new rigid body
     165  with the specified input. The "Export Cartesian Coordinates..."
     166  writes an ASCII file with the current input.
     167  <BR><img src="rb002.jpg" alt="Manual RB creation window">
     169 <H4>A.7.a2 Cartesian coordinates from ASCII text file</H4>
     171Cartesian coordinates
     172can be read from any ASCII file containing Cartesian coordinates in a standard
     173tabular format.
     174  This routine allows
     175the user to determine which columns (separated by a delimiter) represents the X,
     176Y and Z coordinates.
     177 The user also
     178has the option to ignore any row or column that contains irrelevant
     180  Once the Cartesian
     181coordinates are isolated, and the "Continue" button is pressed,
     182  the user continues to the "Create Rigid Body" window (see above).
     183  <BR><img src="rb003.jpg" alt="ASCII RB input window">
     186  <H4>A.7.a3 Cartesian coordinates from a Z-matrix</H4>
     188Cartesian coordinates
     189can also be calculated from a Z-matrix in an appropriate ASCII format.
     190 The conversion routine will allow dummy
     191atoms to be identified and ignored in the conversion process.
     192 Upon pressing the "Continue" button, the Z-matrix
     193is converted to Cartesian coordinates and the user progresses to the
     194  "Create Rigid Body" window (see above).
     195 <BR><img src="rb004.jpg" alt="Z-matrix RB input window">
     197  <H4>A.7.a4 Compute Cartesian coordinates from EXP file (fractional coordinates)</H4>
     199  Cartesian coordinates
     200can also be determined from atoms in the EXP file.
     201  In order to generate Cartesian
     202coordinates, the number of sites in the rigid body framework must be specified
     203as well as the starting atom (remember rigid bodies are mapped consecutively).
     204  Once the number of atoms in the body is
     205set, the "Choose Start Atom" button is pressed. This creates buttons for
     206all possible choices for the first atom to define the body. Once the starting
     207atom is selected by pressing one of these button(s), the atoms to be used to
     208define the rigid body framework have been determined. The user must than select
     209which atoms will be used to define the origin (the origin will be at the
     210centroid of the atoms chosen) and must define the axes that will be used to
     211generate the x-axis and the xy plane.
     212The Cartesian coordinates can then be generated.
     213Either the defined body can be determined and mapped (with the "Save and Map
     214Rigid Body" button), or the Cartesian coordinates can exported to an
     215ASCII text file (with the "Export Cartesian Coordinates"
     217  <BR><img src="rb005.jpg" alt="Fraction Coords RB input window">
     221<H3>A.7.b Rigid Body Panel</H3>
     223 As each rigid body is
     224defined, a "Rigid Body Type N" panel will be created.<span
     226  This panel will show how the rigid body
     227is mapped, and will allow the user to map / unmap the
     228rigid body on to the crystal structure, view the rigid body (this
     229  assumes the
     230 <A HREF="">DRAWxtl</A> program is installed on their computer), edit the
     231rigid body, set refinement flags, or delete the rigid body.
     232  <BR><img src="rb006.jpg" alt="RB edit panel">
     234  <H4>A.7.b1 Plot Rigid Body</H4>
     236  <A HREF="">DRAWxtl</A>
     237  is a very useful viewing program that
     238EXPGUI can invoke, if installed. It
     239allows for the viewing of the rigid body to ensure it is correct before mapping
     240and matches the ordering of the atoms in the EXP file. The plot below
     241  was obtained from the "Plot Rigid Body" button.
     242  <BR><img src="rb007.png" alt="DRAWxtl screen">
     245 <H4>A.7.b2 Map Rigid Body</H4>
     247The rigid body must be mapped to the
     248crystal structure to define the constraint. This is done by pressing
     249  the "Map Rigid Body" button, which raises the window below.
     250  <BR><img src="rb008.png" alt="Map RB"><BR>
     251  In order to map the rigid body the user
     252will need to specify the phase and the sequence number of the first atom in the
     253.EXP file to be included.
     254  This will
     255be the atom assigned to the first set of coordinates in the rigid
     256  body.
     257 Each succeeding atom will be assigned
     258the consecutive set of coordinates.
     259The origin and Euler angles for the rigid body placement must be
     260determined; this can be done by fitting to the atoms in the
     261.EXP file using the &quot;Fit rigid body to phase&quot; button. A
     262  table of RMS (~ A distances) between the mapped rigid body placement
     263  and the initial atom placements -- this describes the quality of the fit.
     264 If the fit is poor, it is
     265likely that the ordering of Cartesian coordinates is incorrect, resulting in high
     266RMS values. If this occurs, the ordering of the Cartesian coordinates must be
     267modified with the Edit Matrix routine.
     268  <BR><img src="rb010.png" alt=""><BR>
     269 <img src="rb009.png" alt="" ALIGN="RIGHT">
     270 The fit can be visually examined with
     271the &quot;Plot rigid body &amp; phase&quot; button with results as
     272  show to the right.
     273  The rigid body is shown in
     274red and the .EXP file coordinates are shown in green. Note that it is often
     275easier to understand what is being plotted, when bonds are drawn. The input in
     276the "Bonds" box specifies ranges of distances where 0.9-1.1, 1.3-1.6 draws bonds
     277between atoms spaced 0.9 to 1.1 A (typical C-H bonds) and 1.3 to 1.6 A (typical
     278organic molecule bonds). You may wish to specify different
     279  ranges where other types of bonding are present. One can also change
     280  the display from the DRAWxtl menus.
     281<BR Clear="all">
     282  </DL>
     283 <H4>A.7.b3 Edit Rigid Body</H4>
     284  <DL>
     286Pressing the "Edit Matrix" button on the "Rigid Body Type N" panel
     287    provides an interface that will allow the Cartesian coordinates to be modified by
     288sorting, swapping, adding or deleting matrix elements.
     289   It will also allow for setting the refinement flag for Matrix
     291  <BR><img src="rb011.jpg" alt=""><BR>
     292 <img src="rb012.png" alt="" ALIGN="RIGHT">
     293   Note that repeating the previous
     294mapping, after reordering
     295of the Cartesian coordinates, the following fit of a cyclopentadienyl
     296ligand is accomplished and the RMS differences in the
     297fitting procedure are small.
     298    Below
     299shows the correct fit.
     300  <BR><img src="rb013.png" alt=""><BR>
     301  <BR><img src="rb014.png" alt=""><BR>
     305<H3>A.7.c Setting Rigid Body Refinement Flags</H3>
     307 The "Refinement Flags" button opens a window that allows the
     308user to set flags to refine various parameters.
     309Parameters can be set up to refine as
     310free variables or constrained variables.
     311The TLS (translation, librations, screw) terms describe the rigid body
     312thermal motions and are normally off.
     313They should only be turned on if the user has a strong understanding of
     314the relationships between the TLS terms.
     315Note: if an Origin or Euler angle
     316flag is enabled, the appropriate atom X refinement flag on the phase panel will
     317be set.
     318  GENLES will have errors if
     319rigid body parameters are refined, but not the positions of the corresponding
     322 Note that in EXPEDT,
     323rigid body parameters can be grouped by assigning them the same variable
     324number. The same feature is possible via a graphical interface by "tagging" (pressing
     325the appropriate button for) items to vary and then using the following buttons:
     327 "Set Free Variables" - will assign each tagged parameter as
     328an unconstrained variable by providing a unique variable number.
     330 <LI>Do Not Refine Variables - will turn off the refinement flag
     331for all tagged parameters.
     333 <LI>Set Constrained variables - will constrain all tagged parameters
     334and assign a single variable for refinement.
     335 <LI>Clear All Variables - will clear all refinement flags.
     337<LI>Assign Variables and Save - will assign variable numbers to each
     338unique parameter to be refined and close the Refinement Flag window.
     339  <BR><img src="rb015.png" alt=""><BR>
     340  <BR><img src="rb016.png" alt=""><BR>
     342The above Phase Panel shows the 'X'
     343refinement flags active allowing the rigid body refinement to
     344  commence.
     345 These flags were set automatically when
     346the rigid body position parameter were set to be refined. If these flags are
     347turned off, it is likely that GENLES will crash.
    39349  </DL></DL>
  • branches/sandbox/doc/expgui7.html

    r1150 r1164  
    2929<HR noshade width="75%" size="2" align="center">
    30 EXPGUI, part 7
     30EXPGUI, part 8
    3131<HR noshade width="75%" size="2" align="center">
    34 <h3>A.7 Preferential Orientation Panel</h3></a>
     34<h3>A.8 Preferential Orientation Panel</h3></a>
    3636The Preferential Orientation Panel is used to control parameters related
    4444<a name="MD"></a>
    45 <h4>A.7.a March-Dollase</H4>
     45<h4>A.8.a March-Dollase</H4>
    4747In this model one or more axes are designated
    6868<a name="ODF"></a>
    69 <H4>A.7.b Spherical harmonic</H4>
     69<H4>A.8.b Spherical harmonic</H4>
    7171The spherical harmonic formulation, also referred to as an "orientation
Note: See TracChangeset for help on using the changeset viewer.