Help for GSAS-II

This is where to find help on various GSAS-II windows and plots. Note that GSAS-II operates with three windows: the main GSAS-II data tree section, which provides a hierarchical view of the current project on the left and the GSAS-II data editing section, which shows the contents of a particular section of the project, where values can be examined and changed; The second is the GSAS-II Plots window, which shows graphical representations of the results. The third is a console window, which has printout information that can be selected, cut & pasted into a document.

Help Index

[see separate page]

Learning GSAS-II: Tutorials

The best way to learn about how different sections of GSAS-II is used is to work through tutorials. A list of available tutorial topics appears on a separate web page.

1. GSAS-II Data Tree

The data tree shows contents of a GSAS-II project (which can be read or saved as a .gpx file) in a hierarchical view. Clicking on any item in the tree opens that information on the right side of the window in the "Data Editing" section, where information in that item can be viewed or edited. For example, the "Sample Parameters" item under a ‘PWDR’ entry contains information about how data were collected, such as the sample temperature (see below). The arrow keys (up & down) move the selection to successive entries in the data tree; both the data window and the associated plot (if any) will change.

What can I do here?

The leftmost entries in the GSAS-II menu provide access to many features of GSAS-II. Other menu items will change depending on what type of entry is selected in the data tree. The menu commands that do not change and are described below in the main menu commands section.

2. GSAS-II Data Editing Window

Different information is displayed in the Data Editing Window, depending on which section of the data tree is selected. For example, clicking on the "Notebook" entry of the tree brings up the Notebook editing window, as described below in the data tree sections.

3. GSAS-II Plots Window

This window presents all the graphical material as a multipage tabbed set of plots utilizing the matplotlib python package. Each page has a tool with the controls

The first nine or ten icons have the following functions: Home, Back, Forward, Pan, Zoom, (Resize plot), Save, Key Press and Help, respectively and are described below. The remainder (yellow arrows) move or rescale the plot. Note that Resize plot is removed from the toolbar where matplotlib allows this and should not be used.

Home

returns the plot to the initial scaling

Back

returns the plot to the previous scaling

Forward

reverses the action in the previous press(es) of the Back button

Pan

allows you to control panning across the plot (press left mouse button) and zooming (press right mouse button),

Zoom

allows you to select a portion of the plot (press right mouse button & drag for zoom box) for the next plot.

Save

allows you to save the currently displayed plot in one of several graphical formats suitable for printing or insertion in a document.

Key Press

Shows a menu of key press commands that can be used to interact with the plot. These actions can be initiated from the menu.

Help

accesses GSASII help on the specific plot type.

{less than}

Shifts the plot to the left, relative to the axes

{greater than}

Shifts the plot to the right, relative to the axes

{up arrow}

Shifts the plot up, relative to the axes

{down arrow}

Shifts the plot down, relative to the axes

{less than}+{greater than}

Zooms in on the plot (magnifies) along the horizontal (x) direction to show more details.

{greater than}+{less than}

Zooms out on the plot (demagnifies) along the horizontal (x) direction.

{up arrow}/{down arrow}

Zooms in on the plot (magnifies) along the vertical (y) direction to show more details.

{down arrow}/{up arrow}

Zooms out on the plot (demagnifies) along the vertical (y) direction.

Below the toolbar may be a status bar that on the left may show either an instruction for a keyed input or a pull down selection of keyed input; on the right may be displayed position dependent information that is updated as the mouse is moved over the plot region.

4. Main GSAS-II menu commands

1.      Menu File

Open project…

Open a previously saved GSAS-II project file ({project}.gpx). If you currently have a project file open, you are asked if it is OK to overwrite it; Cancel will cancel the read process.

Note that as files are saved, copies of the previous version are saved as backup files, named as {project}.bak{i}.gpx, where i starts as 0 and is increased after each save operation. NB: you may open a backup .gpx file (e.g. name.bak3.gpx) to return to a previous version of your project, but if you do so, it is best to immediately use the Save As... menu command (you may wish to use name.gpx to overwrite the current version or select a new name.) If you forget specify a project name, then name.bak3 will be considered the project name and backups will then be named name.bak3.bak0.gpx, etc.

Save project

Save the current project. If this is a new project that has not yet been saved, you will be prompted for a new name in a file dialog (you may optionally change the directory in that dialog). If the file exists, you will be asked if it is OK to overwrite it. Once a file name has been used to read or save a project, the name is shown after ‘Loaded Data:’ in the first item in the data tree.

Save Project as...

Save the current project in a specified project file. You will be prompted for a new name in a file dialog (you may optionally change the directory in that dialog). If the file exists, you will be asked if it is OK to overwrite it.

New Project

Discards any changes made to the current project since the last save and creates a new empty project.

Preferences

Provides access to GSAS-II configuration settings, as described in the Configuration Variables section.

Quit

Exit the GSAS-II program. Discards any changes made to the current project since the last save. You can also exit GSAS-II by pressing the red X in the upper right (Windows) or left (Mac).

2.      Menu Data

Read Powder Pattern Peaks…

Read in a list of powder pattern peak positions as either a d-spacing table or a set of 2theta positions; these can be used in GSAS-II powder pattern indexing.

Sum powder data

Form the sum of previously read powder patterns; each with a multiplier. Can be used to accumulate data, subtract background or empty container patterns, etc. Patterns used to form the sum must be of identical range and step size. Result is a new PWDR entry in the GSAS-II data tree.

Sum image data

Form the sum of previously read 2-D images; each with a multiplier. Can be used to accumulate data, subtract background or empty container patterns, etc. Images used to form the sum must be of identical size and source. Result is a new IMG entry in the GSAS-II data tree, and a GSAS-II image file is written for future use.

Add new phase

This begins the creation of a new phase in the data tree (under Phases). You are first prompted in a dialog box for a name to be assigned to the new phase. Then the Phase/General tab is opened for this phase, where you should first select the phase type, the enter the space group symbol and then the lattice parameters.
Note that nonstandard space group symbols are permitted; space group names must have spaces between the axial fields (e.g. use ‘P n a 21’ not ‘Pna21’).

Delete phase

This will remove a phase from the data tree. A dialog box will present the list of phases; pick one (or more) to delete.

Rename tree item

Rename a histogram entry. This should only be done before the histogram is used in any phases: e.g. only rename data immediately after reading.

Delete tree item

This will remove an item from the data tree. A dialog box with a list of choices for histograms is presented. Be sure to remove a histograms from all phases before deleting it from the tree.

Expand tree item

This will show child entries for specified type of items (Images, Powder patterns, etc.)

Move tree item

Move classes of Tree items around in the tree. Individual top-level tree items can be moved using the left mouse button.

3.      Menu Calculate

Setup PDFs

This creates the pair distribution function (PDF) controls for each powder pattern selected in the dialog box, but does not compute the PDF, which must be done from PDF tree entries. See PDF Controls for information on the PDF input.

View LS parms

This shows a dialog box with all the parameters for your project; those to be refined are flagged ‘True’, otherwise ‘False’. Blanks indicate parameters that are not refinable. The total number of refined parameters is also shown at the top of the list. The value of each parameter is also given. The parameter names are of the form ‘p:h:name:id’ where ‘p’ is the phase index, ‘h’ is the histogram index and ‘id’ is the item index (if needed). Indexes all begin with ‘0’ (zero).

Note that for atom positions, the coordinate values (named as ‘p::Aw:n’, where p is the phase number, n is the atom number and w is x, y or z) is not a refinable parameter, but the shift in the value is. The refined parameters are ‘p::Aw:n’. The reason this is done is that by treating an atom position as x+dx,y+dy,z+dz where the “d” values indicate shifts from the starting position and the shifts are refined rather than the x,y, or z values is that this simplifies symmetry constraints. As an example, suppose we have an atom on a symmetry constrained site, x,1/2-x,z. The process needed to define this constraint, so that if x moves positively y has to move negatively by the same amount would be messy. With refinement of shifts, all we need to do is constrain dy (‘0::dAy:n’) to be equal to -dx (-1*‘0::dAx:n’).

Press the window exit button to exit this dialog box.

Refine

This performs the refinement (Pawley/Rietveld or single crystal) according to the controls set in the Controls data tree item.

Sequential refine

This starts a sequential refinement with the data sets selected in the Controls data tree item.

4. Menu Import

GSAS-II uses separate routines to read in information from external files that can be created and customized easily. See the GSAS-II Import Modules section of the Programmers documentation for more information on this. Since it is easy to support new formats, the documentation below may not list all supported formats.

Image

Read in 2-D powder diffraction images (multiple patterns can be selected). A sub menu appears with choices for import of data. Each entry when selected with the mouse shows further submenus with specific imports that are available. Any of these files can be accessed from a zip file. GSAS-II can read many different image file formats including MAR345 files, Quantum ADSC files, and tiff files from Perkin-Elmer, Pilatus, and GE. Although many of these formats have data fields that should contain relevant information for the exposure (e.g. wavelength), these are rarely filled in correctly by the data acquisition software. Thus, you should have separately noted this information as it will be needed

Phase

Creates a new phase by reading unit cell/symmetry/atom coordinate information. GSAS-II can read information from a number of different format files including:

GSAS .EXP

This reads one phase from a (old) GSAS experiment file (name.EXP). The file name is found in a directory dialog; you can change directories as needed. Only .EXP (or .exp) file names are shown. If the selected file has more than one phase, a dialog is shown with the choices; only one can be chosen. If you want more than one, redo this command. After selecting a phase, a dialog box is shown with the proposed phase name. You can change it if desired.

PDB file

This reads the macromolecular phase information from a Protein Data Base file (name.PDB or name.ENT). The file name is found in a directory dialog; you can change directories as needed. Only .PDB (or .pdb) or .ENT (or .ent) file names are shown. Be careful that the space group symbol on the ‘CRYST1’ record in the PDB file follows the GSAS-II conventions (e.g. with spaces between axial fields). A dialog box is shown with the proposed phase name. You can change it if desired.

CIF file

This reads one phase from a Crystallographic Information File ({name}.CIF (or .cif). The file name is found in a directory dialog; you can change directories as needed. If the selected file has more than one phase, a dialog is shown with the choices; only one can be chosen. If you want more than one, redo this command. After selecting a phase, a dialog box is shown with the proposed phase name. You can change it if desired.

GSAS-II .gpx file

This reads one phase from a GSAS-II project file ({name}.gpx). The file name is found in a directory dialog; you can change directories as needed. If the selected file has more than one phase, a dialog is shown with the choices; If you want more than one, redo this command. After selecting a phase, a dialog box is shown with the proposed phase name. You can change it if desired.

guess format from file

This attempts to read one phase from a file trying the formats as described above. On occasion, this command may not succeed in correctly determining a file format. If it fails, retry by selecting the correct format from the list.

Powder Data

Reads a powder diffraction data set in a variety of formats. Results are placed in the GSAS-II data tree as ‘PWDR file name'. Information needed for processing a powder diffraction data set, such as data type, calibration constants (such as wavelength) and default profile parameters are read from a separate file, either a (old) GSAS instrument parameter file (usually .prm, .ins or .inst extension) or a new GSAS-II .instparm file.

Note that it is possible to apply corrections to the 2-theta, intensity or weight values by adding a Python command(s) to the instrument (.instprm) parameter with a variable named CorrectionCode. See the CorrectionCode.instprm.sample file provided in the GSAS-II source directory for an example of how this is done.

CIF file

This reads one powder pattern (histogram) from a Crystallographic Information File ({name}.CIF). The file name is found in a directory dialog; you can change directories as needed. Only one .cif can be chosen. If you want more than one, redo this command.

GSAS-II .gpx file

This reads powder patterns from a previously created GSAS-II gpx project file. If the selected file has more than one powder pattern, a dialog is shown with the choices; one or more can be selected. It will ask for an appropriate instrument parameter file to go with the selected powder data sets.

GSAS .fxye files

This reads powder patterns (histograms) from the defined GSAS format powder data files. GSAS file types STD, ESD, FXY and FXYE are recognized. Neutron TOF data with a ‘TIME-MAP’ are also recognized. The file names are found in a directory dialog; you can change directories as needed. If the selected files have more than one powder pattern, a dialog is shown with the choice(s).

TOPAS .xye files.

This format is a simple 3-column (2-theta, intensity & sig) text file. The file names are found in a directory dialog; you can change directories as needed.

guess format from file

This attempts to read one data set from a file trying the formats as described above. On occasion, this command may not succeed in correctly determining a file format. If it fails, retry by selecting the correct format from the list.

Structure Factor

Reads single crystal input from a variety of file types. Results are placed in the GSAS-II data tree as ‘HKLF file name’

F**2 HKL file

This reads squared structure factors (as F**2) and sig(F**2) from a SHELX format .hkl file. The file names are found in a directory dialog; you can change directories as needed. You must know the file contains structure factors (as F**2) as the file itself has no internal indication of this.

F HKL file

This reads structure factors (as F) and sig(F) from a SHELX format .hkl file. The file names are found in a directory dialog; you can change directories as needed. You must know the file contains structure factors (as F values) as the file itself has no internal indication of this.

CIF file

This reads structure factors (as F**2 or F) and sig(F**2 or F) from a .CIF (or .cif) or .FCF (or .fcf) format file. The file names are found in a directory dialog; you can change directories as needed. The internal structure of this file indicates in which form the structure factors are used.

guess format from file

This attempts to read one data set from a file trying the formats as described above. However, since it cannot be determined if SHELX format .hkl contaings F or F**2 values, do not use this command for those files. On occasion, this command may not succeed in correctly determining a file format. If it fails, retry by selecting the correct format from the list.

Small Angle Data

Reads small angle scattering data from files. At present these formats are not documented; See the importer routines (file .../GSASII/imports/G2sad_xye.py) for more details.

5. Menu Export

GSAS-II uses separate routines to write out files with information inside GSAS-II. These routines can be created and customized easily. See the GSAS-II Export Modules section of the Programmers documentation for more information on this. Since it is easy to support new formats, the documentation below may not list all supported formats.

Entire project as

At present the only supported format for a project is a Full CIF file. This brings up a separate window where information such as ranges for bond distances and angles can be selected.

Phase as

Phases can be exported in a variety of formats including a simplified CIF file that contains only the unit cell, symmetry and coordinates.

Powder data as

Powder data can be exported in number of formats. Note that this menu can also be used to export reflection lists from Rietveld and Pawley fits.

Single crystal data as

Single crystal reflection lists can be exported as text files or as a simplified CIF file that contains only structure factors.

Image data

This exports selected images as a portable networks graphics format (PNG) file. Alternately, the image controls and masks can be written for selected images. If strain analysis has been performed on images, the results can also be exported here as a spreadsheet (.csv file).

Maps as

Fourier maps can be exported here.

Export all Peak Lists...

This allows peak lists from selected powder histograms to be written to a simple text file. There will be a heading for each PWDR GSAS-II tree item and columns of values for position, intensity, sigma and gamma follow.

Export HKLs

This allows single crystal reflection lists from selected histograms to be written to a file.

Export PDF...

This allows computed PDFs peak lists from selected histograms to be written as two simple text files, {name}.gr and {name}.sq, containing g(r) and s(q), respectively as 2 columns of data; a header on each indicated the source file name and the column headings. The file name comes from the PDF entry in the GSAS-II data tree.

5. GSAS-II data tree items

Notebook

This window provides a place for you to enter whatever text commentary you wish. Each time you enter this window, a date/time entry is provided for you. A possibly useful technique is to select a portion of the project.lst file after a refinement completes (it will contain refinement results with residuals, new values & esds) and paste it into this Notebook window so it becomes a part of your project file.

What can I do here?

Use the notebook to keep track of information related to how you use GSAS-II.

Controls

This window provides access to the controls that determine how GSAS-II performs minimizations as well as few global parameters for GSAS-II. Note that many other customization settings are set as configuration variables in the Preferences menu. (See the Programmer's documentation for a description of those.)

Refinement Controls: These controls determine how refinements are performed. The first determines the computational engine used to minimize the structure.

Refinement type

This determines how refinements are performed. The choices are:

·         analytic Hessian: This is the default option and is usually the most useful. It uses a custom-developed least-squares minimizer that uses singular-value decomposition (SVD) to reduce the errors caused by correlated variables and the Levenberg-Marquardt algorithm to up-weight diagonal Hessian terms when refinements fail to lower χ².

·         analytic Jacobian: This uses a numpy-provided leastsq minimizer, which not applicable for problem with a large number of histograms as it requires much more memory than the Hessian routines. This because it creates a Jacobian matrix that is shaped N x M (N parameters x M observations) while the Hessian methods create a Jacobian matrix only each histogram.

·         numeric: This also uses the numpy leastsq minimizer, and is also not applicable for larger problems. Unlike, the "analytic Jacobian", numerical derivatives are computed rather than use the analytical derivatives that are coded directly into GSAS-II. This will be slower than the analytical derivatives and will is often less accurate which results in slower convergence. It is typically used for code development to check the accuracy of the analytical derivative formulations.

·         Hessian SVD: This is very similar to analytic Hessian but does not include the Levenberg-Marquardt algorithm. It can be faster, but is more prone to diverge when severe correlation is present. It is possible that it might be better for single-crystal refinements.

Note that the Jacobian refinement tools are the Fortran MINPACK lmdif and lmder algorithms wrapped in python as provided in the Scipy package. The Hessian routines are were developed for GSAS-II based on routines in numpy and scipy and using the material in Numerical Recipes (Press, Flannery, Teulosky & Vetterling) for the Levenberg-Marquardt. The purpose is to minimize the sum of the squares of M nonlinear functions in N variables by a modification of the Levenberg-Marquardt algorithm. The lmdif and lmder routines were written by Burton S. Garbow, Kenneth E. Hillstrom, Jorge J. More (Argonne National Laboratory, 1980).

Min delta-M/M

A refinement will stop when the change in the minimization function (M=Σ[w(Io-Ic)²]) is less than this value. The allowed range is 10^-9 to 1.0, with a default of 0.001. A value of 1.0 stops the refinement after a single cycle. Values less than 10^-4 cause refinements to continue even if there is no meaningful improvement.

Max cycles

This determines the maximum number of refinement cycles that will be performed. This is only available with the "Hessian" minimizers.

Initial lambda

Note that here λ is the Marquardt coefficient, where a weight of 1+λ is applied to the diagonal elements of the Hessian. When λ is large, this down-weights the significance of the off-diagonal terms in the Hessian. Thus, when λ is large, the refinement is effectively one of steepest-descents, where correlation between variables is ignored. Note that steepest-descents minimization is typically slow and may not always find the local minimum. This is only available with the "analytical Hessian" minimizer.

SVD zero tolerance

This determines the level where SVD considers values to be the same. Default is 10^-6. Make larger to where problems occur due to correlation. This is only available with the "Hessian" minimizers.

Initial shift factor

A “damping multiplier” applied during the first refinement cycle, for Jacobean/numeric refinements only. Should be in interval (0.1, 100). See the SciPy leastsq docs for more information.

Single Crystal: A set of controls is provided for control of single-crystal refinements. These only appear when single crystal (HKLF) histograms are present in the project.

Refine HKLF as F^2?

When checked, refinements are against F² rather than |F|.

Min obs/sig

Conventional cutoff for single crystal refinements as to what reflections should be considered observed, typical values are 2.0 (2σ) or 3.0 (3σ).

Min extinct.

(needs further work)

Max delt-F/sig

Removes reflections that are very poorly fit. Should be used only with extreme care, since poorly-fit reflections could be an indication that the structure is wrong.

Max d-spacing

Reflections with d-space values larger than this value are ignored.

Min d-spacing

Reflections with d-space values smaller than this value are ignored.

Sequential Settings: A set of controls is for sequential refinement. Settings here determine if a "normal" or "sequential" refinement is performed. If no datasets are selected here, then all histograms linked to phases in the project and that are flagged as "used" are included in one potentially large (combined) refinement. However, if any number of histograms are selected here, then a sequential refinement is performed, where a fit is made to the structural model(s) fitting each selected histogram in turn. Only the first item below is shown in "normal" mode.

Select datasets/Reselect Datasets

This brings up a menu where histograms can be selected, which potentially switches between a normal and a sequential refinement. If one or more histograms are selected, a sequential refinement is used. If none are selected, then the refinement be set as "normal". The button is labeled "Select" when in normal refinement mode and "Reselect" in sequential refinement mode.

Reverse order?

Normally, in a sequential histograms are fit in the order they are in the data tree (which can be reordered by dragging tree items), but when this option is selected, the sequential fit is performed with the last tree entry first.

Copy results to next histogram?

When this option is selected, the fitted parameters from each refinement are copied to the next histogram, so that the starting point for each refinement will be the results from fitting the previous. This works well for parametric experiments where parameters such as the lattice parameters change gradually over the course of successive measurements. This option is usually used only for the initial refinement after a sequential fit is started and the setting is reset once that refinement is completed. For subsequent refinements, it is usually better to start with the results from the previous fit.

Clear previous seq. results

When this button is pressed, the "Sequential Results" entry with the results from the last sequential fit is deleted from the tree.

Global Settings: This is a location for parameters that apply to an entire project. At present there is only one.

CIF Author

The value provided here is used when creating a CIF of an entire project.

What can I do here?

This offers a place to change how GSAS-II performs refinements, but has no specific menu commands or graphics.

Covariance

This window contains final residual information; the GSASII Plots window ‘Covariance’ shows a graphical representation of the variance-covariance matrix. A text window is displayed with statistical values and goodness of fit parameters.

What is plotted here?

The variance-covariance matrix as a color coded array is shown on this page. The color bar to the right shows the range of covariances (-1 to 1) and corresponding colors. The parameter names are to the right and the parameter numbers are below the plot.

What can I do with the plot?

Move the mouse cursor across the plot. If on a diagonal cell, the parameter name, value and esd is shown both as a tool tip and in the right hand portion of the status bar. If the cursor is off the diagonal, the two parameter names and their covariance are shown in the tool tip and the status bar.

Use the Zoom and Pan buttons to focus on some section of the variance-covariance matrix.

Press ‘s’ – A color scheme selection dialog is shown. Select a color scheme and press OK, the new color scheme will be plotted. The default is ‘RdYlGn’.

Press ‘p’ – Saves the covariance values in a text file.

Constraints

This window shows the constraints to be used in a refinement. It is organized into three tabbed pages. ‘Phase constraints’ contain those involving parameters that describe aspects of the crystalline phases to be used in the refinement (e.g. atom coordinates, thermal motion and site fraction parameters). ‘Histogram/Phase constraints’ are those which describe aspects of the pattern that depend on both the phase and the data set used in the refinement (e.g. microstrain and crystallite size parameters). ‘Histogram constraints’ are those that depend only on the data set (e.g. profile coefficients U, V, W, X and Y).

What can I do here?

1.      Select the tab for the parameter types you wish to constrain. Each will have the same possibilities in the ‘Edit’ menu.

2.      Menu ‘Edit’ –

a.       Add Hold – select a parameter that you wish to remain fixed although other parameters of the same type may be selected as a group for refinement. For example, if the space group for a phase has a polar axis (e.g. the b-axis in P2₁), then one atom y-parameter is arbitrary and should be selected for a Hold to keep the structure from drifting up or down the y-axis during refinement. If selected, a dialog box will appear showing the list of available parameters; select one and then OK to implement it, Cancel will cancel the operation. The held parameter will be shown in the constraint window with the keyword ‘FIXED’. A Delete button can be used to remove it.

b.      Add equivalence – select a list of parameters that should have the same value (possibly with a non-unitary multiplier for some). Examples are a list of atoms with the same thermal motion Uiso, sets of profile coefficients U,V,W across multiple data sets. If selected, a dialog box will appear with a list of the available parameters. Select one and press OK; a second dialog box will appear with only those parameters that can be made equivalent to the first one. Choose those and press OK. Cancel in either dialog will cancel the operation. The equivalenced parameters will show as an equation of the form M₁*P₁+M₂*P₂=0; usually M1=1.0 and M2=-1.0, but can be changed via the ‘Edit’ button. The keyword ‘EQUIV’ marks it as an equivalence. A Delete button can be used to remove it.

c.       Add constraint – select a list of parameters whose sum (with possible non-unitary multipliers) is fixed. For example, the sum of site fractions for atoms on the same site could be fixed to unity. If selected, a dialog box will appear with a list of the available parameters. Select one and press OK; a second dialog box will appear with only those parameters that can be used in a constraint with the first one. Choose those and press OK. Cancel in either dialog will cancel the operation. The equivalenced parameters will show as an equation of the form M₁*P₁+M₂*P₂+…=C; the multipliers M1, M2, … and C can be changed via the ‘Edit’ button. The keyword ‘CONSTR’ marks it as a constraint. A Delete button can be used to remove it.

d.      Add function – this is very similar the “Add constraint” type except that the result of the sum can be varied in the refinement. The keyword ‘FUNCT’ marks it as a function; the ‘Refine?’ box indicates your choice to refine the result of the sum. A Delete button can be used to remove it.

Restraints

This window shows the restraints to be used in a refinement. It is organized into several tabbed pages, one page for each type of restraint. Restraints are developed for an individual phase and act as additional observations to be “fitted” during the refinement.

What can I do here?

1.      Select the tab for the restraint type you wish to use. Each will have the same possibilities in the ‘Edit’ menu.

2.      You can change the Restraint weight factor – this is used to scale the weights for the entire set of restraints of this type. Default value for the weight factor is 1.0.

3.      You can choose to use or not use the restraints in subsequent refinements. Default is to use the restraints.

4.      You can change the search range used to find the bonds/angles that meet your criteria for restraint.

5.      You can examine the table of restraints and change individual values; grayed out regions cannot be changed. The ‘calc’ values are determined from the atom positions in your structure, ‘obs’ values are the target values for the restraint and ‘esd’ is the uncertainty used to weight the restraint in the refinement (multiplied by the weight factor).

6.      Menu ‘Edit’ – some entries may be grayed out if not appropriate for your phase or for the selected restraint.

a.       Select phase – active if there is more than one phase in your project. A dialog box will appear with a list of the phases, select the one you want for restraint development.

b.      Add restraints – this takes you through a sequence of dialog boxes which ask for the identities of the atoms involved in the restraint and the value to be assigned to the restraint. The esd is given a default value which can be changed after the restraints are created.

c.       Add residue restraints – if the phase is a ‘macromolecule’ then develop the restraints from a selected ‘macro’ file based on those used in GSAS for this purpose. A file dialog box is shown directed to /GSASIImacros; be sure to select the correct file.

d.      Plot residue restraints – if the phase is a ‘macromolecule’ and the restraint type is either ‘Torsion restraints’ or ‘Ramachandran restraints’, then a plot will be made of the restraint distribution; torsions as 1-D plots of angle vs. pseudopotential energy and Ramachandran ones as 2-D plot of psi vs phi. In each case a dialog box will appear asking for the residue types or specific torsion angles to plot. Each plot will show the observed distribution (blue) obtained from a wide variety of high resolution protein structures and those found (red dots) for your structure. The restraints are based on a pseudopotential (red curve or contours – favorable values at the peaks) which has been developed from the observed distributions for each residue type.

e.       Change value – this changes the ‘obsd’ value for selected restraints; a dialog box will appear asking for the new value.

f.        Change esd – this changes the ‘esd’ value for selected restraints; a dialog box will appear asking for the new value.

g.      Delete restraints – this deletes selected restraints from the list. A single click in the blank box in the upper left corner of the table will select/deselect all restraints.

Rigid bodies

This window shows the rigid body models that have been entered into GSAS-II for this project. There are two tabs; one is for vector style rigid bodies and the other is for flexible “Residue” rigid bodies. Note that these rigid bodies must be inserted into one of the phases before it can take effect in the crystal structure description.

What can I do here?

1.      Select the tab for the rigid body type you wish to use. Each will have the different possibilities in the ‘Edit’ menu depending on whether a rigid body has been defined.

2.      Menu ‘Edit’ – the entries listed below depend on which type of rigid body is selected.

a.      Add rigid body – (Vector rigid bodies) this creates a vector description of a rigid body. A dialog box asks the number of atoms (>2) and the number of vectors required to create the rigid body. An entry will be created showing a magnitude with the vector set to be applied for each vector needed to develop the rigid body.

b.      Import XYZ – (Residue rigid bodies) this reads a text file containing a set of Cartesian coordinates describing a rigid body model. Each line has atom type (e.g. C, Na, etc.) and Cartesian X, Y and Z.

c.       Define sequence – (Residue rigid bodies) this defines a variable torsion angle in a sequence of dialog boxes. The first one asks for the origin and the second asks for the pivot atom for the torsion from the nearest neighbors to the origin atom; the atoms that ride on the selected torsion are automatically found from their bond lengths.

d.      Import residues – (Residue rigid bodies) this reads a predetermined macro file that contains standard (Engh & Huber) coordinates for the amino acids found in natural proteins along with predetermined variable torsion angle definitions.

3.      Once a rigid body is defined you can plot it, change its name or manipulate any torsion angle to see the effect on the plot.

4.      The translation magnitudes in a vector rigid body can be refined.

Sequential refinement results

This tree entry is available after a sequential refinement has been run. (See the Controls tree item to set the histograms to be used in a sequential refinement and use the Calculate/Sequential refine menu command to run the refinement.) When this is selected, the window tabulates the sequential refinement results. The columns are the parameter names; the naming convention is ‘p:h:name:n’ where ‘p’ is the phase number,’ h’ is the histogram number, ‘name’ is the parameter name, and ‘n’ (if needed) is the item number (e.g. atom number). The rows are the data sets used in the sequential refinement.

What can I do here?

1.      Select a row – this will display the variance-covariance matrix for the refinement with that data set.

2.      Select a column – this will display a plot of that parameter across the sequence of data sets. Error bars for each value are also shown.

3.      Menu ‘Background’ –

a.       Save – this will create a text file of selected columns with values and corresponding esds. A file dialog box will appear; give a suitable file name; you may change directory if desired.

6. Histogram data tree items

These are shown in the data tree with a prefix of ‘PWDR’, ’HKLF’, ‘IMG’, or ‘PDF’ and usually a file name. These constitute the data sets (‘Histograms’) to be used by GSAS-II for analysis. Selection of these items does not produce any information in the data window but does display the data in the Plots Window. They are described below.

6A. Powder Histograms - type PWDR

[see separate page]

6B. Single Crystal Histograms – type HKLF

Instrument Parameters

This window shows the histogram type (SXC or SNC) and the wavelength. You may change the wavelength but rarely will need to do so.

HKL Plot Controls

This controls the display of the single crystal reflections on the plot. If available a green ring is shown for F-observed, a blue ring for F-calculated and a central disk for ΔF (green for Fo>Fc and red for Fo<Fc).

What can I do here?

1.      Change the scale – move the slider, the rings will change their radius accordingly.

2.      Select the zone – select between 100, 010 or 001; plot axes will be labeled accordingly.

3.      Select plot type – the choices are either F or F², ΔF²/σ(F²), ΔF²>σ(F²) or ΔF²>3σ(F²).

4.      Select layer – move the slider for upper layers for the selected zone.

Reflection List

This window shows the reflections for this single crystal data set.

6C. Pair Distribution Functions - type PDF

A PDF entry is created from a powder histogram (PWDR entry) using the Setup PDFs entry in the Calculate menu. The main PDF data tree item displays the same window as the PDF Controls, below. When this item is selected, the S(Q) function is plotted, see below.

PDF Controls

This window provides parameters for computing the pair distribution function [PDF, G(r)] from the I(Q) function. This can only be done when a chemical formula and appropriate control values are provided. If so, clicking on this menu item causes the I(Q), S(Q), F(Q) and G(R) functions to be plotted, as described below.

The Optimize PDF button can be used to refine the values of the "Flat Bkg", "Background ratio" and "Ruland width" parameters to best agree with the -4*pi*r line that is plotted for r < Rmin. Rmin should be set to a distance below the shortest expected interatomic distance for the material.

What can I do here?

The PDF parameters can be changed, triggering recomputation of the I(Q), S(Q), F(Q) and G(R) functions. Available menu commands are:

Add element

Adds a new element to the chemical formula by clicking on a periodic table. Note that the number of atoms of this type in the empirical formula must still be entered.

Delete element

Removes a previously-entered element from the chemical formula.

Copy Controls

Copies the current PDF control values to other PDF data entries

Load Controls

Replaces the current PDF control values with values read from a file (see Save controls).

Save Controls

Saves the current PDF control values into a file.

Compute PDF

Recomputes the PDF for the current entry. This is usually done automatically when values are changed, but if not this can be forced with this menu item.

Compute all PDFs

Recomputes the PDFs for all selected PDF entries. This is usually done after Copy Controls is used. By default PDFs are optimized to reduce the low G(r) region, but this can be turned off.

What is plotted here?

When a chemical formula and appropriate control values are provided, clicking on this menu item causes the I(Q), S(Q), F(Q) and G(R) functions to be plotted, as described separately, below.

What can I do with the plot?

For each of the plots, the following keyboard shortcuts are available:

For line plots with more than one powder pattern:

c: contour on/off

if multiple PDFs are available, then a contour plot is shown for the displayed function. All data sets must be the same length as the first one to be included in the contour plot.

m: toggle multiple plot

for multiple PDFs, this will show only the one selected from the data tree. The offset options are not active. Or all selected items will be plotted on a single axis.

s: toggle single plot

for multiple PDFs, this will show only the one selected from the data tree. The offset options are not active. Or all selected items will be plotted on a single axis.

f: select data

Allows only some PDFs to be plotted, rather than all.

t: toggle legend

provides a legend with the line type and name for each PDF.

For line plots in waterfall mode (multiple patterns are shown) these key press items are defined:

t: toggle legend

provides a legend with the line type and name for each PDF.

l: offset left

for a waterfall plot of multiple powder profiles, increase the offset so that later plots are shifted more to the left relative to previous plots.

r: offset right

for a waterfall plot of multiple powder profiles, increase the offset to the right (or decrease the left offset.)

d: offset down

for a waterfall plot of multiple powder profiles, increase the offset down.

u: offset up

for a waterfall plot of multiple powder profiles, increase the offset up.

o: reset offset

for a waterfall plot of multiple powder profiles, reset to no offset.

I(Q) Function

This shows the I(Q) function. See the PDF Controls for information on menu commands and plot options,

S(Q) Function

This shows the S(Q) function. See the PDF Controls for information on menu commands and plot options,

F(Q) Function

This shows the F(Q) function. See the PDF Controls for information on menu commands and plot options,

G(r) Function

This shows the PDF, G(r) function. See the PDF Controls for information on menu commands and plot options,

6D. 2-D Images – type IMG

Comments

This window shows whatever comment lines found in a “metadata” file when the image data file was read by GSAS-II. If you are lucky, there will be useful information here (e.g. sample name, date collected, wavelength used, etc.). If not, this window will be blank. The text is read-only.

Image Controls

This window displays calibration values needed to convert pixel locations to two-theta and azimuth. Also shown are controls that determine how integration is performed.

Menu command for this window are used to perform calibration (fitting the calibration values from a diffraction pattern image taken with a calibrant) and for integration. Other menu commands allow the values on the window to be saved to a file, read from a file or copied to other images. The "Xfer Angles" menu command scales the current integration range for other images located at different detector distances.

Masks

Image masks are used designate areas of an image that should not be included in the integration, typically used due to detector irregularities, shadows of the beamstop, single-crystal peaks from a mounting, etc. Masks can be created with a menu command or with keyboard/mouse shortcuts. There are five types of masks:

1.      Spot masks: occlude a circle with a selected center and diameter in image coordinates (mm).

2.      Ring masks: occludes a specific Bragg reflection (a ring placed relative to the image center). The location and thickness of the ring are specified in degrees 2-theta.

3.      Arc masks: occlude a section of a Bragg reflection, similar to a ring mask, except that in addition to the location and thickness of the ring, the mask has a starting and ending azimuthal angle.

4.      Polygon masks: occlude an arbitary region created by line segments joining a series of points specified in image coordinates (mm). Pixels inside the polygon mask are not used for integration.

5.      The Frame mask: occludes an arbitary region created by line segments joining a series of points specified in image coordinates (mm). Typically a point is placed near each corner of the image. Only pixels inside the frame mask are used for integration. Only one frame mask can be defined.

What can I do here?

Masks of each type are created using the appropriate menu commands and then clicking as described in the section on "What can I do with the plot?" below, or by using keyboard shortcuts, also described in that section.

What is plotted here?

The image is shown, as described above. Note that The frame mask, if defined, is displayed in green, while the other types of masks are shown in red.

What can I do with the plot?

There are menu commands to create masks as well as keyboard shortcuts. If a menu command is used, then use left and right mouse clicks as described below.

1.      Spot masks:

Create Spot masks after a menu command by clicking on the location on the image that should be masked. There are also two ways to create spot masks with the keyboard:

o    Press the 's' key and then left-click successively on multiple locations for spot masks. Press the 's' key again or right-click* to stop adding spot masks.

o    Alternately, move the mouse to the position for a new spot mask and press the 't' key. (Note that this can be used while the plot is in Zoom or Pan mode.)

The default size for newly-created spot masks is determined by the Spot_mask_diameter configuration variable or 1.0 mm, if not specified.

Edit Spot mask location by left-clicking inside or on the edge the of the mask and then drag the spot mask to a new location.

Edit Spot mask radius by right-clicking* inside the mask and then dragging to change the mask size.

2.      Ring masks:

Create Ring masks with a menu command and then by left-clicking on the mask center; Or, by pressing the 'r' key and then left-clicking. (Right-click* to cancel.)

The default thickness for newly-created ring masks is determined by the Ring_mask_thickness configuration variable or 0.1 degrees (2theta) if not specified.

Edit Ring mask location by left-clicking on either the inner or outer circle and drag the circle to the new radius.

Edit Ring mask thickness by right-clicking* either on the inner or outer circle and drag the the circle change spacing between the inner and outer circle.

3.      Arc masks: occludes a section of a Bragg reflection, similar to a ring mask, except that in addition to the location and thickness of the ring, the mask has a starting and ending azimuthal angle.

Create Arc masks with a menu command and then by left-clicking on at the mask center; Or, by pressing the 'a' key and then left-clicking. (Right-click* to cancel.)

The default size for newly-created ring masks is determined by configuration variables
thickness: Ring_mask_thickness (0.1 degrees 2theta if not specified) and
azimuthal range: Arc_mask_azimuth (10.0 degrees if not specified.)

Edit Arc mask location by left-clicking on either the inner or outer circle and drag the circle to the new radius. Alternately, left-click on the upper or lower arc limit (the straight lines) and drag them to rotate the center of the arc azimuthal range to a new position.

Edit Arc mask thickness or range by right-clicking* either on the inner or outer circle and drag the the circle change spacing between the inner and outer circle. Alternately, right-click* on the upper or lower arc limit (the straight lines) and drag them to change the arc azimuthal range.

4.      Polygon masks: occludes an arbitary region created by line segments joining a series of points specified in image coordinates (mm). Pixels inside the polygon mask are not used for integration.

Create Polygon masks with a menu command and then by left-clicking successively on the vertices of the polygon shape surrounding pixels to be excluded. After the last point is defined, right-click* anywhere to close the mask. Alternately, press the 'p' key and then left-click, as before, to define the mask and right-click* anywhere to close the mask.

Edit Polygon mask by left-clicking on any point at a vertex in the polygon mask and drag that point to a new position. If the vertex is dragged to the same position as any other vertex in the mask the dragged point is deleted.

Add a point to Polygon mask by right-clicking* on any vertex and dragging. A new point is added to the mask immediately after the selected point at the position where the mouse is released.

5.      The Frame mask: occludes an arbitary region created by line segments joining a series of points specified in image coordinates (mm). Typically a point is placed near each corner of the image. Only pixels inside the frame mask are used for integration. Only one frame mask can be defined.

Create a Frame mask with a menu command and then by left-clicking successively on the vertices of a polygon. After the last point is defined, right-click* anywhere to close the frame mask. Alternately, press the 'f' key and then left-click, as before, to define the mask and right-click* anywhere to close the mask. Note that if a Frame mask already exists, using the 'f' key or the "Create Frame" menu item causes the existing frame mask to be deleted.

Edit the Frame mask by left-clicking on any point at a vertex in the frame mask and drag that point to a new position. If the vertex is dragged to the same position as any other vertex in the mask the dragged point is deleted.

Add a point to the Frame mask by right-clicking* on any vertex and dragging. A new point is added to the mask immediately after the selected point at the position where the mouse is released.

* Note that on a Mac with a one-button mouse, a right-click is generated by pressing the control button while clicking the mouse.

Stress/Strain

What can I do here?

...

What is plotted here?

...

What can I do with the plot?

...

6E. Powder Peaks – type PKS

6F. Small Angle Scattering – type SASD

7. Phase data tree items

[see separate page]

Macintosh notes:

GSAS-II can be run on Windows, Linux and Macintosh/OS X computers, but the GUI follows the native style of Mac OS X. On Windows and some versions of Linux, the menu bars appears on top of the main window. On the Mac, the menu appears at the location that has been configured for menus (usually at the top of the screen). GSAS-II defines actions for both the left and right buttons on a two-button mouse, If a two or three-button mouse is used with a Mac, these mouse buttons will work as intended. If using a Mac touchpad or single-button mouse, clicking the touchpad or mouse button will generate a "left button" click. Hold down the control-key to generate a "right button" click.

Configuration Variables:

GSAS-II provides a number of configuration settings that can be changed via variables that can be set and saved. These are controlled in the File/Preferences menu item (on Mac the Preferences menu is found in the usual place on Macs, in the main application menu). These settings are optionally saved from for subsequent runs in a file named config.py. More information about this can be found in the appropriate section of the Programmer's documentation.

Programmers documentation

The routines and classes used within GSAS-II are documented in a set of web pages and in a PDF document. This documentation is created from the Python source code files using Sphinx.

Access to fullrmc

The fullrmc program is a large-box pair distribution function modeling library developed by Bachir Aoun ["Fullrmc, a Rigid Body Reverse Monte Carlo Modeling Package Enabled with Machine Learning and Artificial Intelligence", B. Aoun, Jour. Comp. Chem. (2016), 37, 1102-1111. DOI: 10.1002/jcc.24304]. Extensive information about fullrmc is found, including a number of explanatory videos, along with the source code on GitHub: https://bachiraoun.github.io/fullrmc/. Use of fullrmc requires a set of Python packages that can be installed along with the packages needed for GSAS-II, but Windows and MacOS users will likely find it easier to install a pre-compiled version of fullrmc by downloading it from here. To locate a version of Python containing fullrmc, the following locations are checked (in the order specified):

1.      The GSAS-II configuration variable fullrmc_exec can point to a Python image.

2.      The Python interpreter running GSAS-II is checked if fullrmc can be imported

3.      The location where GSAS-II is installed, the location where Python is installed, the location where the GSAS-II binaries are found, the current default location and all directories in the system path are all checked for a file named "fullrmc*macOS*i386-64bit" (MacOS), "fullrmc*.exe" (Windows) or "fullrmc*" (Linux).

Last modified: Sun Jun 20 09:16:21 CDT 2021