15. GSASIIscriptable: Scripting Interface¶
Routines to use an increasing amount of GSAS-II’s capabilities from scripts,
without use of the graphical user interface (GUI). GSASIIscriptable can create and access
GSAS-II project (.gpx) files and can directly perform image handling and refinements.
The module defines wrapper classes (inheriting from G2ObjectWrapper
) for a growing number
of data tree items.
GSASIIscriptable can be used in two ways. It offers a command-line mode (see Installation of GSASIIscriptable) that provides access a number of features without writing Python scripts via shell/batch commands. The more widely used and more powerful mode of GSASIIscriptable is use is through Python scripts that call the module’s application interface (API), see API summary that follows or the API: Complete Documentation section.
15.1. Application Interface (API) Summary¶
This section of the documentation provides an overview to API, with full documentation in the API: Complete Documentation section. The typical API use will be with a Python script, such as what is found in Code Examples. Most functionality is provided via the objects and methods summarized below.
15.1.1. Overview of Classes¶
class | Encapsulates |
---|---|
G2Project |
A GSAS-II project file, provides references to objects below,
each corresponding to a tree item
(exception is G2AtomRecord ) |
G2Phase |
Provides phase information access
(also provides access to atom info via G2AtomRecord ) |
G2AtomRecord |
Access to an atom within a phase |
G2PwdrData |
Access to powder histogram info |
G2Image |
Access to image info |
G2PDF |
PDF histogram info |
G2SeqRefRes |
The sequential results table |
15.1.2. Functions¶
A small amount of the Scriptable code does not require use of objects.
method | Use |
---|---|
GenerateReflections() |
Generates a list of unique powder reflections |
SetPrintLevel() |
Sets the amout of output generated when running a script |
15.1.3. Class G2Project
¶
All GSASIIscriptable scripts will need to create aG2Project
object either for a new GSAS-II project or to read in an existing project (.gpx) file. The most commonly used routines in this object are:
method | Use |
---|---|
G2Project.save() |
Writes the current project to disk. |
G2Project.add_powder_histogram() |
Used to read in powder diffraction data into a project file. |
G2Project.add_simulated_powder_histogram() |
Defines a “dummy” powder diffraction data that will be simulated after a refinement step. |
G2Project.add_image() |
Reads in an image into a project. |
G2Project.add_phase() |
Adds a phase to a project |
G2Project.add_PDF() |
Adds a PDF entry to a project (does not compute it) |
G2Project.histograms() |
Provides a list of histograms in the current project, as G2PwdrData objects |
G2Project.phases() |
Provides a list of phases defined in the current project, as G2Phase objects |
G2Project.images() |
Provides a list of images in the current project, as G2Image objects |
G2Project.pdfs() |
Provides a list of PDFs in the current project, as G2PDF objects |
G2Project.seqref() |
Returns a G2SeqRefRes object if there are Sequential Refinement results |
G2Project.do_refinements() |
This is passed a list of dictionaries, where each dict defines a refinement step. Passing a list with a single empty dict initiates a refinement with the current parameters and flags. A refinement dict sets up a single refinement step (as described in Project-level Parameter Dict). Also see Refinement recipe. |
G2Project.set_refinement() |
This is passed a single dict which is used to set parameters and flags.
These actions can be performed also in G2Project.do_refinements() . |
G2Project.get_Variable() |
Retrieves the value and esd for a parameter |
G2Project.get_Covariance() |
Retrieves values and covariance for a set of refined parameters |
G2Project.set_Controls() |
Set overall GSAS-II control settings such as number of cycles and to set up a sequential
fit. (Also see G2Project.get_Controls() to read values.) |
G2Project.imageMultiDistCalib() |
Performs a global calibration fit with images at multiple distance settings. |
G2Project.get_Constraints() |
Retrieves constraint definition entries. |
G2Project.add_HoldConstr() |
Adds a hold constraint on one or more variables |
G2Project.add_EquivConstr() |
Adds an equivalence constraint on two or more variables |
G2Project.add_EqnConstr() |
Adds an equation-type constraint on two or more variables |
G2Project.add_NewVarConstr() |
Adds an new variable as a constraint on two or more variables |
15.1.4. Class G2Phase
¶
Another common object in GSASIIscriptable scripts isG2Phase
, used to encapsulate each phase in a project, with commonly used methods:
method | Use |
---|---|
G2Phase.set_refinements() |
Provides a mechanism to set values and refinement flags for the phase. See Phase parameters
for more details. This information also can be supplied within a call to G2Project.do_refinements()
or G2Project.set_refinement() . |
G2Phase.clear_refinements() |
Unsets refinement flags for the phase. |
G2Phase.set_HAP_refinements() |
Provides a mechanism to set values and refinement flags for parameters specific to both this phase and
one of its histograms. See Histogram-and-phase parameters. This information also can be supplied within
a call to G2Project.do_refinements() or G2Project.set_refinement() . |
G2Phase.clear_HAP_refinements() |
Clears refinement flags specific to both this phase and one of its histograms. |
G2Phase.getHAPvalues() |
Returns values of parameters specific to both this phase and one of its histograms. |
G2Phase.copyHAPvalues() |
Copies HAP settings between from one phase/histogram and to other histograms in same phase. |
G2Phase.atoms() |
Returns a list of atoms in the phase |
G2Phase.atom() |
Returns an atom from its label |
G2Phase.histograms() |
Returns a list of histograms linked to the phase |
G2Phase.get_cell() |
Returns unit cell parameters (also see G2Phase.get_cell_and_esd() ) |
G2Phase.export_CIF() |
Writes a CIF for the phase |
G2Phase.setSampleProfile() |
Sets sample broadening parameters |
15.1.5. Class G2PwdrData
¶
Another common object in GSASIIscriptable scripts isG2PwdrData
, which encapsulate each powder diffraction histogram in a project, with commonly used methods:
method | Use |
---|---|
G2PwdrData.set_refinements() |
Provides a mechanism to set values and refinement flags for the powder histogram. See Histogram parameters for details. |
G2PwdrData.clear_refinements() |
Unsets refinement flags for the the powder histogram. |
G2PwdrData.residuals() |
Reports R-factors etc. for the the powder histogram (also see G2PwdrData.get_wR() ) |
G2PwdrData.add_back_peak() |
Adds a background peak to the histogram. Also see G2PwdrData.del_back_peak() and
G2PwdrData.ref_back_peak() . |
G2PwdrData.fit_fixed_points() |
Fits background to the specified fixed points. |
G2PwdrData.getdata() |
Provides access to the diffraction data associated with the histogram. |
G2PwdrData.reflections() |
Provides access to the reflection lists for the histogram. |
G2PwdrData.Export() |
Writes the diffraction data or reflection list into a file |
G2PwdrData.add_peak() |
Adds a peak to the peak list. Also see Peak Fitting. |
G2PwdrData.set_peakFlags() |
Sets refinement flags for peaks |
G2PwdrData.refine_peaks() |
Starts a peak/background fitting cycle, returns refinement results |
G2PwdrData.Peaks |
Provides access to the peak list data structure |
G2PwdrData.PeakList |
Provides the peak list parameter values |
G2PwdrData.Export_peaks() |
Writes the peak parameters to a text file |
15.1.6. Class G2Image
¶
When working with images, there will be aG2Image
object for each image (also seeG2Project.add_image()
andG2Project.images()
).
method | Use |
---|---|
G2Image.Recalibrate() |
Invokes a recalibration fit starting from the current Image Controls calibration coefficients. |
G2Image.Integrate() |
Invokes an image integration All parameters Image Controls will have previously been set. |
G2Image.setControl() |
Set an Image Controls parameter in the current image. |
G2Image.getControl() |
Return an Image Controls parameter in the current image. |
G2Image.findControl() |
Get the names of Image Controls parameters. |
G2Image.loadControls() |
Load controls from a .imctrl file (also see G2Image.saveControls() ). |
G2Image.loadMasks() |
Load masks from a .immask file. |
G2Image.setVary() |
Set a refinement flag for Image Controls parameter in the current image. (Also see G2Image.getVary() ) |
G2Image.setCalibrant() |
Set a calibrant type (or show choices) for the current image. |
G2Image.setControlFile() |
Set a image to be used as a background/dark/gain map image. |
15.1.7. Class G2PDF
¶
To work with PDF entries, objectG2PDF
, encapsulates a PDF entry with methods:
method | Use |
---|---|
G2PDF.export() |
Used to write G(r), etc. as a file |
G2PDF.calculate() |
Computes the PDF using parameters in the object |
G2PDF.optimize() |
Optimizes selected PDF parameters |
G2PDF.set_background() |
Sets the histograms used for sample background, container, etc. |
G2PDF.set_formula() |
Sets the chemical formula for the sample |
15.1.8. Class G2SeqRefRes
¶
To work with Sequential Refinement results, objectG2SeqRefRes
, encapsulates the sequential refinement table with methods:
method | Use |
---|---|
G2SeqRefRes.histograms() |
Provides a list of histograms used in the Sequential Refinement |
G2SeqRefRes.get_cell_and_esd() |
Returns cell dimensions and standard uncertainies for a phase and histogram from the Sequential Refinement |
G2SeqRefRes.get_Variable() |
Retrieves the value and esd for a parameter from a particular histogram in the Sequential Refinement |
G2SeqRefRes.get_Covariance() |
Retrieves values and covariance for a set of refined parameters for a particular histogram |
15.1.9. Class G2AtomRecord
¶
When working with phases,G2AtomRecord
objects provide access to the contents of each atom in a phase. This provides access to “properties” that can be used to get values of much of the atoms associated settings: label, type, refinement_flags, coordinates, occupancy, ranId, adp_flag, and uiso. In addition, refinement_flags, occupancy and uiso can be used to set values. See theG2AtomRecord
docs and source code.
15.2. Refinement parameters¶
While scripts can be written that setup refinements by changing individual parameters through calls to the methods associated with objects that wrap each data tree item, many of these actions can be combined into fairly complex dict structures to conduct refinement steps. Use of these dicts is required with the Installation of GSASIIscriptable. This section of the documentation describes these dicts.
15.2.1. Project-level Parameter Dict¶
As noted below (Refinement parameter types), there are three types of refinement parameters,
which can be accessed individually by the objects that encapsulate individual phases and histograms
but it will often be simplest to create a composite dictionary
that is used at the project-level. A dict is created with keys
“set” and “clear” that can be supplied to G2Project.set_refinement()
(or G2Project.do_refinements()
, see Refinement recipe below) that will
determine parameter values and will determine which parameters will be refined.
The specific keys and subkeys that can be used are defined in tables Histogram parameters, Phase parameters and Histogram-and-phase parameters.
Note that optionally a list of histograms and/or phases can be supplied in the call to
G2Project.set_refinement()
, but if not specified, the default is to use all defined
phases and histograms.
As an example:
pardict = {'set': { 'Limits': [0.8, 12.0],
'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
'Background': {'type': 'chebyschev-1', 'refine': True,
'peaks':[[0,True],[1,1,1]] }},
'clear': {'Instrument Parameters': ['U', 'V', 'W']}}
my_project.set_refinement(pardict)
15.2.2. Refinement recipe¶
Building on the Project-level Parameter Dict,
it is possible to specify a sequence of refinement actions as a list of
these dicts and supplying this list
as an argument to G2Project.do_refinements()
.
As an example, this code performs the same actions as in the example in the section above:
pardict = {'set': { 'Limits': [0.8, 12.0],
'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
'Background': {'type': 'chebyschev-1', 'refine': True}},
'clear': {'Instrument Parameters': ['U', 'V', 'W']}}
my_project.do_refinements([pardict])
However, in addition to setting a number of parameters, this example will perform a refinement as well, after setting the parameters. More than one refinement can be performed by including more than one dict in the list.
In this example, two refinement steps will be performed:
my_project.do_refinements([pardict,pardict1])
The keys defined in the following table
may be used in a dict supplied to G2Project.do_refinements()
. Note that keys histograms
and phases
are used to limit actions to specific sets of parameters within the project.
key | explanation |
---|---|
set | Specifies a dict with keys and subkeys as described in the Specifying Refinement Parameters section. Items listed here will be set to be refined. |
clear | Specifies a dict, as above for set, except that parameters are cleared and thus will not be refined. |
once | Specifies a dict as above for set, except that parameters are set for the next cycle of refinement and are cleared once the refinement step is completed. |
skip | Normally, once parameters are processed with a set/clear/once action(s), a refinement is started. If skip is defined as True (or any other value) the refinement step is not performed. |
output | If a file name is specified for output is will be used to save the current refinement. |
histograms | Should contain a list of histogram(s) to be used for the set/clear/once action(s) on Histogram parameters or Histogram-and-phase parameters. Note that this will be ignored for Phase parameters. Histograms may be specified as a list of strings [(‘PWDR …’),…], indices [0,1,2] or as list of objects [hist1, hist2]. |
phases | Should contain a list of phase(s) to be used for the set/clear/once action(s) on Phase parameters or Histogram-and-phase parameters. Note that this will be ignored for Histogram parameters. Phases may be specified as a list of strings [(‘Phase name’),…], indices [0,1,2] or as list of objects [phase0, phase2]. |
call | Specifies a function to call after a refinement is completed.
The value supplied can be the object (typically a function)
that will be called or a string that will evaluate (in the
namespace inside G2Project.iter_refinements() where
self references the project.)
Nothing is called if this is not specified. |
callargs | Provides a list of arguments that will be passed to the function in call (if any). If call is defined and callargs is not, the current <tt>G2Project</tt> is passed as a single argument. |
An example that performs a series of refinement steps follows:
reflist = [
{"set": { "Limits": { "low": 0.7 },
"Background": { "no. coeffs": 3,
"refine": True }}},
{"set": { "LeBail": True,
"Cell": True }},
{"set": { "Sample Parameters": ["DisplaceX"]}},
{"set": { "Instrument Parameters": ["U", "V", "W", "X", "Y"]}},
{"set": { "Mustrain": { "type": "uniaxial",
"refine": "equatorial",
"direction": [0, 0, 1]}}},
{"set": { "Mustrain": { "type": "uniaxial",
"refine": "axial"}}},
{"clear": { "LeBail": True},
"set": { "Atoms": { "Mn": "X" }}},
{"set": { "Atoms": { "O1": "X", "O2": "X" }}},]
my_project.do_refinements(reflist)
In this example, a separate refinement step will be performed for each dict in the list. The keyword “skip” can be used to specify a dict that should not include a refinement. Note that in the second from last refinement step, parameters are both set and cleared.
15.2.3. Refinement parameter types¶
Note that parameters and refinement flags used in GSAS-II fall into three classes:
- Histogram: There will be a set of these for each dataset loaded into a project file. The parameters available depend on the type of histogram (Bragg-Brentano, Single-Crystal, TOF,…). Typical Histogram parameters include the overall scale factor, background, instrument and sample parameters; see the Histogram parameters table for a list of the histogram parameters where access has been provided.
- Phase: There will be a set of these for each phase loaded into a project file. While some parameters are found in all types of phases, others are only found in certain types (modulated, magnetic, protein…). Typical phase parameters include unit cell lengths and atomic positions; see the Phase parameters table for a list of the phase parameters where access has been provided.
- Histogram-and-phase (HAP): There is a set of these for every histogram that is associated with each phase, so that if there are
N
phases andM
histograms, there can beN*M
total sets of “HAP” parameters sets (fewer if all histograms are not linked to all phases.) Typical HAP parameters include the phase fractions, sample microstrain and crystallite size broadening terms, hydrostatic strain perturbations of the unit cell and preferred orientation values. See the Histogram-and-phase parameters table for the HAP parameters where access has been provided.
15.3. Specifying Refinement Parameters¶
Refinement parameter values and flags to turn refinement on and off are specified within dictionaries, where the details of these dicts are organized depends on the type of parameter (see Refinement parameter types), with a different set of keys (as described below) for each of the three types of parameters.
15.3.1. Histogram parameters¶
This table describes the dictionaries supplied to G2PwdrData.set_refinements()
and G2PwdrData.clear_refinements()
. As an example,
hist.set_refinements({"Background": {"no.coeffs": 3, "refine": True},
"Sample Parameters": ["Scale"],
"Limits": [10000, 40000]})
With G2Project.do_refinements()
, these parameters should be placed inside a dict with a key
set
, clear
, or once
. Values will be set for all histograms, unless the histograms
key is used to define specific histograms. As an example:
gsas_proj.do_refinements([
{'set': {
'Background': {'no.coeffs': 3, 'refine': True},
'Sample Parameters': ['Scale'],
'Limits': [10000, 40000]},
'histograms': [1,2]}
])
Note that below in the Instrument Parameters section, related profile parameters (such as U and V) are grouped together but separated by commas to save space in the table.
key | subkey | explanation |
---|---|---|
Limits | The range of 2-theta (degrees) or TOF (in microsec) range of values to use. Can be either a dictionary of ‘low’ and/or ‘high’, or a list of 2 items [low, high] | |
low | Sets the low limit | |
high | Sets the high limit | |
Sample Parameters | Should be provided as a list of subkeys to set or clear,e.g. [‘DisplaceX’, ‘Scale’] | |
Absorption | ||
Contrast | ||
DisplaceX | Sample displacement along the X direction | |
DisplaceY | Sample displacement along the Y direction | |
Scale | Histogram Scale factor | |
Background | Sample background. Value will be a dict or
a boolean. If True or False, the refine
parameter for background is set to that.
Note that background peaks are not handled
via this; see
G2PwdrData.ref_back_peak() instead.
When value is a dict,
supply any of the following keys: |
|
type | The background model, e.g. ‘chebyschev-1’ | |
refine | The value of the refine flag, boolean | |
‘no. coeffs’ | Number of coefficients to use, integer | |
coeffs | List of floats, literal values for background | |
FixedPoints | List of (2-theta, intensity) values for fixed points | |
‘fit fixed points’ | If True, triggers a fit to the fixed points to be calculated. It is calculated when this key is detected, regardless of calls to refine. | |
peaks | Specifies a set of flags for refining background peaks as a nested list. There may be an item for each defined background peak (or fewer) and each item is a list with the flag values for pos,int,sig & gam (fewer than 4 values are allowed). | |
Instrument Parameters | As in Sample Paramters, provide as a list of subkeys to set or clear, e.g. [‘X’, ‘Y’, ‘Zero’, ‘SH/L’] | |
U, V, W | Gaussian peak profile terms | |
X, Y, Z | Lorentzian peak profile terms | |
alpha, beta-0, beta-1, beta-q, | TOF profile terms | |
sig-0, sig-1, sig-2, sig-q | TOF profile terms | |
difA, difB, difC | TOF Calibration constants | |
Zero | Zero shift | |
SH/L | Finger-Cox-Jephcoat low-angle peak asymmetry | |
Polariz. | Polarization parameter | |
Lam | Lambda, the incident wavelength |
15.3.2. Phase parameters¶
This table describes the dictionaries supplied to G2Phase.set_refinements()
and G2Phase.clear_refinements()
. With G2Project.do_refinements()
,
these parameters should be placed inside a dict with a key
set
, clear
, or once
. Values will be set for all phases, unless the phases
key is used to define specific phase(s).
key | explanation |
---|---|
Cell | Whether or not to refine the unit cell. |
Atoms | Dictionary of atoms and refinement flags. Each key should be an atom label, e.g. ‘O3’, ‘Mn5’, and each value should be a string defining what values to refine. Values can be any combination of ‘F’ for site fraction, ‘X’ for position, and ‘U’ for Debye-Waller factor |
LeBail | Enables LeBail intensity extraction. |
15.3.2.1. Histogram-and-phase parameters¶
This table describes the dictionaries supplied to G2Phase.set_HAP_refinements()
and G2Phase.clear_HAP_refinements()
. When supplied to
G2Project.do_refinements()
, these parameters should be placed inside a dict with a key
set
, clear
, or once
. Values will be set for all histograms used in each phase,
unless the histograms
and phases
keys are used to define specific phases and histograms.
key | subkey | explanation |
---|---|---|
Babinet | Should be a list of the following subkeys. If not, assumes both BabA and BabU | |
BabA | ||
BabU | ||
Extinction | Boolean, True to refine. | |
HStrain | Boolean or list/tuple, True to refine all appropriate Dij terms or False to not refine any. If a list/tuple, will be a set of True & False values for each Dij term; number of items must match number of terms. | |
Mustrain | ||
type |
|
|
direction |
|
|
refine |
|
|
Size | ||
type |
|
|
direction |
|
|
refine | Boolean, True to refine. | |
value | float, size value in microns | |
Pref.Ori. | Boolean, True to refine | |
Show | Boolean, True to refine | |
Use | Boolean, True to refine | |
Scale | Phase fraction; Boolean, True to refine |
15.3.3. Histogram/Phase objects¶
Each phase and powder histogram in a G2Project
object has an associated
object. Parameters within each individual object can be turned on and off by calling
G2PwdrData.set_refinements()
or G2PwdrData.clear_refinements()
for histogram parameters;
G2Phase.set_refinements()
or G2Phase.clear_refinements()
for phase parameters; and G2Phase.set_HAP_refinements()
or
G2Phase.clear_HAP_refinements()
. As an example, if some_histogram is a histogram object (of type G2PwdrData
), use this to set parameters in that histogram:
params = { 'Limits': [0.8, 12.0],
'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
'Background': {'type': 'chebyschev-1', 'refine': True}}
some_histogram.set_refinements(params)
Likewise to turn refinement flags on, use code such as this:
params = { 'Instrument Parameters': ['U', 'V', 'W']}
some_histogram.set_refinements(params)
and to turn these refinement flags, off use this (Note that the
.clear_refinements()
methods will usually will turn off refinement even
if a refinement parameter is set in the dict to True.):
params = { 'Instrument Parameters': ['U', 'V', 'W']}
some_histogram.clear_refinements(params)
For phase parameters, use code such as this:
params = { 'LeBail': True, 'Cell': True,
'Atoms': { 'Mn1': 'X',
'O3': 'XU',
'V4': 'FXU'}}
some_histogram.set_refinements(params)
and here is an example for HAP parameters:
params = { 'Babinet': 'BabA',
'Extinction': True,
'Mustrain': { 'type': 'uniaxial',
'direction': [0, 0, 1],
'refine': True}}
some_phase.set_HAP_refinements(params)
Note that the parameters must match the object type and method (phase vs. histogram vs. HAP).
15.4. Access to other parameter settings¶
There are several hundred different types of values that can be stored in a
GSAS-II project (.gpx) file. All can be changed from the GUI but only a
subset have direct mechanism implemented for change from the GSASIIscriptable
API. In practice all parameters in a .gpx file can be edited via scripting,
but sometimes determining what should be set to implement a parameter
change can be complex.
Several routines, G2Phase.getHAPentryList()
,
G2Phase.getPhaseEntryList()
and G2PwdrData.getHistEntryList()
(and their related get…Value and set.Value entries),
provide a mechanism to discover what the GUI is changing inside a .gpx file.
As an example, a user in changing the data type for a histogram from Debye-Scherrer mode to Bragg-Brentano. This capability is not directly exposed in the API. To find out what changes when the histogram type is changed we can create a short script that displays the contents of all the histogram settings:
from __future__ import division, print_function
import os,sys
sys.path.insert(0,'/Users/toby/software/G2/GSASII')
import GSASIIscriptable as G2sc
gpx = G2sc.G2Project('/tmp/test.gpx')
h = gpx.histograms()[0]
for h in h.getHistEntryList():
print(h)
This can be run with a command like this:
python test.py > before.txt
(This will create file before.txt
, which will contain hundreds of lines.)
At this point open the project file, test.gpx
in the GSAS-II GUI and
change in Histogram/Sample Parameters the diffractometer type from Debye-Scherrer
mode to Bragg-Brentano and then save the file.
Rerun the previous script creating a new file:
python test.py > after.txt
Finally look for the differences between files before.txt
and after.txt
using a tool
such as diff (on Linux/OS X) or fc (in Windows).
in Windows:
Z:\>fc before.txt after.txt
Comparing files before.txt and after.txt
***** before.txt
fill_value = 1e+20)
, 'PWDR Co_PCP_Act_d900-00030.fxye Bank 1', 'PWDR Co_PCP_Act_d900-00030.fxye Ban
k 1'])
(['Comments'], <class 'list'>, ['Co_PCP_Act_d900-00030.tif #0001 Azm= 180.00'])
***** AFTER.TXT
fill_value = 1e+20)
, 'PWDR Co_PCP_Act_d900-00030.fxye Bank 1', 'PWDR Co_PCP_Act_d900-00030.fxye Ban
k 1', 'PWDR Co_PCP_Act_d900-00030.fxye Bank 1']
(['Comments'], <class 'list'>, ['Co_PCP_Act_d900-00030.tif #0001 Azm= 180.00'])
*****
***** before.txt
(['Sample Parameters', 'Scale'], <class 'list'>, [1.276313196832068, True])
(['Sample Parameters', 'Type'], <class 'str'>, 'Debye-Scherrer')
(['Sample Parameters', 'Absorption'], <class 'list'>, [0.0, False])
***** AFTER.TXT
(['Sample Parameters', 'Scale'], <class 'list'>, [1.276313196832068, True])
(['Sample Parameters', 'Type'], <class 'str'>, 'Bragg-Brentano')
(['Sample Parameters', 'Absorption'], <class 'list'>, [0.0, False])
*****
in Linux/Mac:
bht14: toby$ diff before.txt after.txt
103c103
< , 'PWDR Co_PCP_Act_d900-00030.fxye Bank 1', 'PWDR Co_PCP_Act_d900-00030.fxye Bank 1'])
---
> , 'PWDR Co_PCP_Act_d900-00030.fxye Bank 1', 'PWDR Co_PCP_Act_d900-00030.fxye Bank 1', 'PWDR Co_PCP_Act_d900-00030.fxye Bank 1'])
111c111
< (['Sample Parameters', 'Type'], <class 'str'>, 'Debye-Scherrer')
---
> (['Sample Parameters', 'Type'], <class 'str'>, 'Bragg-Brentano')
From this we can see there are two changes that took place. One is fairly obscure, where the histogram name is added to a list, which can be ignored, but the second change occurs in a straight-forward way and we discover that a simple call:
h.setHistEntryValue(['Sample Parameters', 'Type'], 'Bragg-Brentano')
can be used to change the histogram type.
15.5. Code Examples¶
15.5.1. Peak Fitting¶
Peak refinement is performed with routines
G2PwdrData.add_peak()
, G2PwdrData.set_peakFlags()
and
G2PwdrData.refine_peaks()
. Method G2PwdrData.Export_peaks()
and
properties G2PwdrData.Peaks
and G2PwdrData.PeakList
provide ways to access the results. Note that when peak parameters are
refined with refine_peaks()
, the background may also
be refined. Use G2PwdrData.set_refinements()
to change background
settings and the range of data used in the fit. See below for an example
peak refinement script, where the data files are taken from the
“Rietveld refinement with CuKa lab Bragg-Brentano powder data” tutorial
(in https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/LabData/data/).
from __future__ import division, print_function
import os,sys
sys.path.insert(0,'/Users/toby/software/G2/GSASII') # needed to "find" GSAS-II modules
import GSASIIscriptable as G2sc
datadir = os.path.expanduser("~/Scratch/peakfit")
PathWrap = lambda fil: os.path.join(datadir,fil)
gpx = G2sc.G2Project(newgpx=PathWrap('pkfit.gpx'))
hist = gpx.add_powder_histogram(PathWrap('FAP.XRA'), PathWrap('INST_XRY.PRM'),
fmthint='GSAS powder')
hist.set_refinements({'Limits': [16.,24.],
'Background': {"no. coeffs": 2,'type': 'chebyschev-1', 'refine': True}
})
peak1 = hist.add_peak(1, ttheta=16.8)
peak2 = hist.add_peak(1, ttheta=18.9)
peak3 = hist.add_peak(1, ttheta=21.8)
peak4 = hist.add_peak(1, ttheta=22.9)
hist.set_peakFlags(area=True)
hist.refine_peaks()
hist.set_peakFlags(area=True,pos=True)
hist.refine_peaks()
hist.set_peakFlags(area=True, pos=True, sig=True, gam=True)
res = hist.refine_peaks()
print('peak positions: ',[i[0] for i in hist.PeakList])
for i in range(len(hist.Peaks['peaks'])):
print('peak',i,'pos=',hist.Peaks['peaks'][i][0],'sig=',hist.Peaks['sigDict']['pos'+str(i)])
hist.Export_peaks('pkfit.txt')
#gpx.save() # gpx file is not written without this
15.5.2. Pattern Simulation¶
This shows two examples where a structure is read from a CIF, a pattern is computed using a instrument parameter file to specify the probe type (neutrons here) and wavelength.
The first example uses a CW neutron instrument parameter file. The pattern is computed over a 2θ range of 5 to 120 degrees with 1000 points. The pattern and reflection list are written into files. Data files are found in the Scripting Tutorial.
import os,sys
sys.path.insert(0,'/Users/toby/software/G2/GSASII')
import GSASIIscriptable as G2sc
datadir = "/Users/toby/software/G2/Tutorials/PythonScript/data"
PathWrap = lambda fil: os.path.join(datadir,fil)
gpx = G2sc.G2Project(newgpx='PbSO4sim.gpx') # create a project
phase0 = gpx.add_phase(PathWrap("PbSO4-Wyckoff.cif"),
phasename="PbSO4",fmthint='CIF') # add a phase to the project
# add a simulated histogram and link it to the previous phase(s)
hist1 = gpx.add_simulated_powder_histogram("PbSO4 simulation",
PathWrap("inst_d1a.prm"),5.,120.,Npoints=1000,
phases=gpx.phases(),scale=500000.)
gpx.do_refinements() # calculate pattern
gpx.save()
# save results
gpx.histogram(0).Export('PbSO4data','.csv','hist') # data
gpx.histogram(0).Export('PbSO4refl','.csv','refl') # reflections
This example uses bank#2 from a TOF neutron instrument parameter file. The pattern is computed over a TOF range of 14 to 35 milliseconds with the default of 2500 points. This uses the same CIF as in the example before, but the instrument is found in the TOF-CW Joint Refinement Tutorial tutorial.
import os,sys
sys.path.insert(0,'/Users/toby/software/G2/GSASII')
import GSASIIscriptable as G2sc
cifdir = "/Users/toby/software/G2/Tutorials/PythonScript/data"
datadir = "/Users/toby/software/G2/Tutorials/TOF-CW Joint Refinement/data"
gpx = G2sc.G2Project(newgpx='/tmp/PbSO4simT.gpx') # create a project
phase0 = gpx.add_phase(os.path.join(cifdir,"PbSO4-Wyckoff.cif"),
phasename="PbSO4",fmthint='CIF') # add a phase to the project
hist1 = gpx.add_simulated_powder_histogram("PbSO4 simulation",
os.path.join(datadir,"POWGEN_1066.instprm"),14.,35.,
phases=gpx.phases(),ibank=2)
gpx.do_refinements([{}])
gpx.save()
15.5.3. Simple Refinement¶
GSASIIscriptable can be used to setup and perform simple refinements. This example reads in an existing project (.gpx) file, adds a background peak, changes some refinement flags and performs a refinement.
from __future__ import division, print_function
import os,sys
sys.path.insert(0,'/Users/toby/software/G2/GSASII') # needed to "find" GSAS-II modules
import GSASIIscriptable as G2sc
datadir = "/Users/Scratch/"
gpx = G2sc.G2Project(os.path.join(datadir,'test2.gpx'))
gpx.histogram(0).add_back_peak(4.5,30000,5000,0)
pardict = {'set': {'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
'Background': {'type': 'chebyschev-1', 'refine': True,
'peaks':[[0,True]]}}}
gpx.set_refinement(pardict)
15.5.4. Sequential Refinement¶
GSASIIscriptable can be used to setup and perform sequential refinements. This example script is used to take the single-dataset fit at the end of Step 1 of the Sequential Refinement tutorial and turn on and off refinement flags, add histograms and setup the sequential fit, which is then run:
import os,sys,glob
sys.path.insert(0,'/Users/toby/software/G2/GSASII')
import GSASIIscriptable as G2sc
datadir = os.path.expanduser("~/Scratch/SeqTut2019Mar")
PathWrap = lambda fil: os.path.join(datadir,fil)
# load and rename project
gpx = G2sc.G2Project(PathWrap('7Konly.gpx'))
gpx.save(PathWrap('SeqRef.gpx'))
# turn off some variables; turn on Dijs
for p in gpx.phases():
p.set_refinements({"Cell": False})
gpx.phase(0).set_HAP_refinements(
{'Scale': False,
"Size": {'type':'isotropic', 'refine': False},
"Mustrain": {'type':'uniaxial', 'refine': False},
"HStrain":True,})
gpx.phase(1).set_HAP_refinements({'Scale': False})
gpx.histogram(0).clear_refinements({'Background':False,
'Sample Parameters':['DisplaceX'],})
gpx.histogram(0).ref_back_peak(0,[])
gpx.phase(1).set_HAP_refinements({"HStrain":(1,1,1,0)})
for fil in sorted(glob.glob(PathWrap('*.fxye'))): # load in remaining fxye files
if '00' in fil: continue
gpx.add_powder_histogram(fil, PathWrap('OH_00.prm'), fmthint="GSAS powder",phases='all')
# copy HAP values, background, instrument params. & limits, not sample params.
gpx.copyHistParms(0,'all',['b','i','l'])
for p in gpx.phases(): p.copyHAPvalues(0,'all')
# setup and launch sequential fit
gpx.set_Controls('sequential',gpx.histograms())
gpx.set_Controls('cycles',10)
gpx.set_Controls('seqCopy',True)
gpx.refine()
15.5.5. Image Processing¶
A sample script where an image is read, assigned calibration values from a file and then integrated follows. The data files are found in the Scripting Tutorial.
import os,sys
sys.path.insert(0,'/Users/toby/software/G2/GSASII')
import GSASIIscriptable as G2sc
datadir = "/tmp"
PathWrap = lambda fil: os.path.join(datadir,fil)
gpx = G2sc.G2Project(newgpx=PathWrap('inttest.gpx'))
imlst = gpx.add_image(PathWrap('Si_free_dc800_1-00000.tif'),fmthint="TIF")
imlst[0].loadControls(PathWrap('Si_free_dc800_1-00000.imctrl'))
pwdrList = imlst[0].Integrate()
gpx.save()
This example shows a computation similar to what is done in tutorial Area Detector Calibration with Multiple Distances
import os,sys,glob
sys.path.insert(0,'/Users/toby/software/G2/GSASII')
import GSASIIscriptable as G2sc
PathWrap = lambda fil: os.path.join(
"/Users/toby/wp/Active/MultidistanceCalibration/multimg",
fil)
gpx = G2sc.G2Project(newgpx='/tmp/img.gpx')
for f in glob.glob(PathWrap('*.tif')):
im = gpx.add_image(f,fmthint="TIF")
# image parameter settings
defImgVals = {'wavelength': 0.24152, 'center': [206., 205.],
'pixLimit': 2, 'cutoff': 5.0, 'DetDepth': 0.055,'calibdmin': 1.,}
# set controls and vary options, then fit
for img in gpx.images():
img.setCalibrant('Si SRM640c')
img.setVary('*',False)
img.setVary(['det-X', 'det-Y', 'phi', 'tilt', 'wave'], True)
img.setControls(defImgVals)
img.Recalibrate()
img.Recalibrate() # 2nd run better insures convergence
gpx.save()
# make dict of images for sorting
images = {img.getControl('setdist'):img for img in gpx.images()}
# show values
for key in sorted(images.keys()):
img = images[key]
c = img.getControls()
print(c['distance'],c['wavelength'])
15.5.6. Image Calibration¶
This example performs a number of cycles of constrained fitting.
A project is created with the images found in a directory, setting initial
parameters as the images are read. The initial values
for the calibration are not very good, so a G2Image.Recalibrate()
is done
to quickly improve the fit. Once that is done, a fit of all images is performed
where the wavelength, an offset and detector orientation are constrained to
be the same for all images. The detector penetration correction is then added.
Note that as the calibration values improve, the algorithm is able to find more
points on diffraction rings to use for calibration and the number of “ring picks”
increase. The calibration is repeated until that stops increasing significantly (<10%).
Detector control files are then created.
The files used for this exercise are found in the
Area Detector Calibration Tutorial
(see
Area Detector Calibration with Multiple Distances ).
import os,sys,glob
sys.path.insert(0,'/Users/toby/software/G2/GSASII')
import GSASIIscriptable as G2sc
PathWrap = lambda fil: os.path.join(
"/Users/toby/wp/Active/MultidistanceCalibration/multimg",
fil)
gpx = G2sc.G2Project(newgpx='/tmp/calib.gpx')
for f in glob.glob(PathWrap('*.tif')):
im = gpx.add_image(f,fmthint="TIF")
# starting image parameter settings
defImgVals = {'wavelength': 0.240, 'center': [206., 205.],
'pixLimit': 2, 'cutoff': 5.0, 'DetDepth': 0.03,'calibdmin': 0.5,}
# set controls and vary options, then initial fit
for img in gpx.images():
img.setCalibrant('Si SRM640c')
img.setVary('*',False)
img.setVary(['det-X', 'det-Y', 'phi', 'tilt', 'wave'], True)
img.setControls(defImgVals)
if img.getControl('setdist') > 900:
img.setControls({'calibdmin': 1.,})
img.Recalibrate()
G2sc.SetPrintLevel('warn') # cut down on output
result,covData = gpx.imageMultiDistCalib()
print('1st global fit: initial ring picks',covData['obs'])
print({i:result[i] for i in result if '-' not in i})
# add parameter to all images & refit multiple times
for img in gpx.images(): img.setVary('dep',True)
ringpicks = covData['obs']
delta = ringpicks
while delta > ringpicks/10:
result,covData = gpx.imageMultiDistCalib(verbose=False)
delta = covData['obs'] - ringpicks
print('ring picks went from',ringpicks,'to',covData['obs'])
print({i:result[i] for i in result if '-' not in i})
ringpicks = covData['obs']
# once more for good measure & printout
result,covData = gpx.imageMultiDistCalib(verbose=True)
# create image control files
for img in gpx.images():
img.saveControls(os.path.splitext(img.name)[0]+'.imctrl')
gpx.save()
15.5.7. Histogram Export¶
This example shows how to export a series of histograms from a collection of
.gpx (project) files. The Python glob()
function is used to find all files
matching a wildcard in the specified directory (dataloc
). For each file
there is a loop over histograms in that project and for each histogram
G2PwdrData.Export()
is called to write out the contents of that histogram
as CSV (comma-separated variable) file that contains data positions,
observed, computed and backgroun intensities as well as weighting for each
point and Q. Note that for the Export call, there is more than one choice of
exporter that can write .csv
extension files, so the export hint must
be specified.
import os,sys,glob
sys.path.insert(0,'/Users/toby/software/G2/GSASII') # change this
import GSASIIscriptable as G2sc
dataloc = "/Users/toby/Scratch/" # where to find data
PathWrap = lambda fil: os.path.join(dataloc,fil) # EZ way 2 add dir to filename
for f in glob.glob(PathWrap('bkg*.gpx')): # put filename prefix here
print(f)
gpx = G2sc.G2Project(f)
for i,h in enumerate(gpx.histograms()):
hfil = os.path.splitext(f)[0]+'_'+str(i) # file to write
print(' ',h.name,hfil+'.csv')
h.Export(hfil,'.csv','histogram CSV')
15.6. Installation of GSASIIscriptable¶
It is assumed that most people using GSASIIscriptable will also want to use the GUI, for this the standard installation instructions should be followed. The GUI includes all files needed to run scriptable. Noting that not all GSAS-II capabilities are not available by scripting – yet. Even if the scripting API were to be fully completed, there will still be some things that GSAS-II does with the GUI would be almost impossible to implement without a interactive graphical view of the data.
Nonetheless, there may be times where it does make sense to install GSAS-II without all of the GUI components, for example on a compute server. As described here the minimal python requirements are only numpy and scipy. It is assumed that anyone able to use scripting is well posed to install from the command line. Below are example commands to install GSAS-II for use for scripting only.
Installing a minimal Python configuration: Note I have chosen below
to use the free
miniconda installer from Anaconda, Inc., but there are also plenty of
other ways to install Python, Numpy and Scipy on Linux, Windows and MacOS.
For Linux a reasonable alternative is to install these packages
(and perhaps others as below) using the Linux dist (apt-get
etc.).
bash ~/Downloads/Miniconda3-latest-<platform>-x86_64.sh -b -p /loc/pyg2script
source /loc/pyg2script/bin/activate
conda install numpy scipy matplotlib pillow h5py hdf5 svn
Some discussion on these commands follows:
- the 1st command (bash) assumes that the appropriate version of Miniconda has been downloaded from https://docs.conda.io/en/latest/miniconda.html and
/loc/pyg2script
is where I have selected for python to be installed. You might want to use something like~/pyg2script
. - the 2nd command (source) is needed to access Python with miniconda.
- the 3rd command (conda) installs all possible packages that might be used by scripting, but matplotlib, pillow, and hdf5 are not commonly needed and could be omitted. The svn package is not needed (for example on Linux) where this has been installed in another way.
Once svn and Python has been installed and is in the path, use these commands to install GSAS-II:
svn co https://subversion.xray.aps.anl.gov/pyGSAS/trunk /loc/GSASII
python /loc/GSASII/GSASIIscriptable.py
Notes on these commands:
- the 1st command (svn) is used to download the GSAS-II software.
/loc/GSASII
is the location where I decided to install the software. You can select something different. - the 2nd command (python) is used to invoke GSAS-II scriptable for the first time, which is needed to load the binary files from the server.
15.7. GSASIIscriptable Command-line Interface¶
The routines described above are intended to be called from a Python script, but an
alternate way to access some of the same functionality is to
invoke the GSASIIscriptable.py
script from
the command line usually from within a shell script or batch file.
This mode of accessing GSAS-II scripting does not appear to get much use and
is no longer being developed. Please do communicate to the developers if
keeping this mode of access would be of value in your work.
To use the command-line mode is done with a command like this:
python <path/>GSASIIscriptable.py <subcommand> <file.gpx> <options>
The following subcommands are defined:
Run:
python GSASIIscriptable.py --help
to show the available subcommands, and inspect each subcommand with python GSASIIscriptable.py <subcommand> –help or see the documentation for each of the above routines.
15.7.1. Parameters in JSON files¶
The refine command requires two inputs: an existing GSAS-II project (.gpx) file and a JSON format file (see Introducing JSON) that contains a single dict. This dict may have two keys:
- refinements:
- This defines the a set of refinement steps in a JSON representation of a Refinement recipe list.
- code:
- This optionally defines Python code that will be executed after the project is loaded,
but before the refinement is started. This can be used to execute Python code to change
parameters that are not accessible via a Refinement recipe dict (note that the
project object is accessed with variable
proj
) or to define code that will be called later (see keycall
in the Refinement recipe section.)
JSON website: Introducing JSON.
15.8. API: Complete Documentation¶
The classes and modules in this module are described below.
A script will create one or more G2Project
objects by reading
a GSAS-II project (.gpx) file or creating a new one and will then
perform actions such as adding a histogram (method G2Project.add_powder_histogram()
),
adding a phase (method G2Project.add_phase()
),
or setting parameters and performing a refinement
(method G2Project.do_refinements()
).
To change settings within histograms, images and phases, one usually needs to use
methods inside G2PwdrData
, G2Image
or G2Phase
.
-
class
GSASIIscriptable.
G2AtomRecord
(data, indices, proj)[source]¶ Wrapper for an atom record. Has convenient accessors via @property: label, type, refinement_flags, coordinates, occupancy, ranId, id, adp_flag, uiso
Example:
>>> atom = some_phase.atom("O3") >>> # We can access the underlying data format >>> atom.data ['O3', 'O-2', '', ... ] >>> # We can also use wrapper accessors >>> atom.coordinates (0.33, 0.15, 0.5) >>> atom.refinement_flags u'FX' >>> atom.ranId 4615973324315876477 >>> atom.occupancy 1.0
-
adp_flag
¶ Get the associated atom’s iso/aniso setting, ‘I’ or ‘A’
-
coordinates
¶ Get the associated atom’s coordinates
-
element
¶ Get the associated atom’s element symbol
-
label
¶ Get the associated atom’s label
-
mult
¶ Get the associated atom’s multiplicity value
-
occupancy
¶ Get or set the associated atom’s site fraction
-
ranId
¶ Get the associated atom’s Random Id number
-
refinement_flags
¶ Get or set refinement flags for the associated atom
-
type
¶ Get the associated atom’s type
-
uiso
¶ Get or set the associated atom’s Uiso or Uaniso value(s)
-
-
class
GSASIIscriptable.
G2Image
(data, name, proj)[source]¶ Wrapper for an IMG tree entry, containing an image and associated metadata.
Note that in a GSASIIscriptable script, instances of G2Image will be created by calls to
G2Project.add_image()
orG2Project.images()
. Scripts will not useG2Image()
to callG2Image.__init__()
directly. The object contains these class variables:- G2Image.proj: contains a reference to the
G2Project
object that contains this image - G2Image.name: contains the name of the image
- G2Image.data: contains the image’s associated data in a dict, as documented for the Image Data Structure.
Example use of G2Image:
>>> gpx = G2sc.G2Project(newgpx='itest.gpx') >>> imlst = gpx.add_image(idata,fmthint="TIF") >>> imlst[0].loadControls('stdSettings.imctrl') >>> imlst[0].setCalibrant('Si SRM640c') >>> imlst[0].loadMasks('stdMasks.immask') >>> imlst[0].Recalibrate() >>> imlst[0].setControl('outAzimuths',3) >>> pwdrList = imlst[0].Integrate()
More detailed image processing examples are shown at Image Processing.
-
ControlList
= {'bool': ['setRings', 'setDefault', 'centerAzm', 'fullIntegrate', 'DetDepthRef', 'showLines'], 'dict': ['varyList'], 'float': ['cutoff', 'setdist', 'wavelength', 'Flat Bkg', 'azmthOff', 'tilt', 'calibdmin', 'rotation', 'distance', 'DetDepth'], 'int': ['calibskip', 'pixLimit', 'edgemin', 'outChannels', 'outAzimuths'], 'list': ['GonioAngles', 'IOtth', 'LRazimuth', 'Oblique', 'PolaVal', 'SampleAbs', 'center', 'ellipses', 'linescan', 'pixelSize', 'range', 'ring', 'rings', 'size'], 'str': ['SampleShape', 'binType', 'formatName', 'color', 'type']}¶ Defines the items known to exist in the Image Controls tree section and the item’s data types. A few are not included here (‘background image’, ‘dark image’, ‘Gain map’, and ‘calibrant’) because these items have special set routines, where references to entries are checked to make sure their values are correct.
-
Integrate
(name=None, MaskMap=None, ThetaAzimMap=None)[source]¶ Invokes an image integration (same as Image Controls/Integration/Integrate menu command). All parameters will have previously been set with Image Controls so no input is needed here. However, the optional parameters MaskMap and ThetaAzimMap may be supplied to save computing these items more than once, speeding integration of multiple images with the same image/mask parameters.
Note that if integration is performed on an image more than once, histogram entries may be overwritten. Use the name parameter to prevent this if desired.
Parameters: - name (str) – base name for created histogram(s). If None (default), the histogram name is taken from the image name.
- MaskMap (list) – from
calcMaskMap()
- ThetaAzimMap (list) – from
calcThetaAzimMap()
Returns: a list of created histogram (
G2PwdrData
) objects.
-
Recalibrate
()[source]¶ Invokes a recalibration fit (same as Image Controls/Calibration/Recalibrate menu command). Note that for this to work properly, the calibration coefficients (center, wavelength, distance & tilts) must be fairly close. This may produce a better result if run more than once.
-
findControl
(arg='')[source]¶ Finds the Image Controls parameter(s) in the current image that match the string in arg. Default is ‘’ which returns all parameters.
Example:
>>> findControl('calib') [['calibskip', 'int'], ['calibdmin', 'float'], ['calibrant', 'str']]
Parameters: arg (str) – a string containing part of the name of a parameter (dict entry) in the image’s Image Controls. Returns: a list of matching entries in form [[‘item’,’type’], [‘item’,’type’],…] where each ‘item’ string contains the sting in arg.
-
getControl
(arg)[source]¶ Return an Image Controls parameter in the current image. If the parameter is not found an exception is raised.
Parameters: arg (str) – the name of a parameter (dict entry) in the image. Returns: the value as a int, float, list,…
-
getControls
(clean=False)[source]¶ returns current Image Controls as a dict
Parameters: clean (bool) – causes the calbration information to be deleted
-
getVary
(*args)[source]¶ Return the refinement flag(s) for Image Controls parameter(s) in the current image. If the parameter is not found, an exception is raised.
Parameters: - arg (str) – the name of a refinement parameter in the varyList for the image. The name should be one of ‘dep’, ‘det-X’, ‘det-Y’, ‘dist’, ‘phi’, ‘tilt’, or ‘wave’
- arg1 (str) – the name of a parameter (dict entry) as before, optional
Returns: a list of bool value(s)
-
loadControls
(filename=None, imgDict=None)[source]¶ load controls from a .imctrl file
Parameters: - filename (str) – specifies a file to be read, which should end with .imctrl (defaults to None, meaning parameters are input with imgDict.)
- imgDict (dict) – contains a set of image parameters (defaults to None, meaning parameters are input with filename.)
-
loadMasks
(filename, ignoreThreshold=False)[source]¶ load masks from a .immask file
Parameters: - filename (str) – specifies a file to be read, which should end with .immask
- ignoreThreshold (bool) – If True, masks are loaded with threshold masks. Default is False which means any Thresholds in the file are ignored.
-
saveControls
(filename)[source]¶ write current controls values to a .imctrl file
Parameters: filename (str) – specifies a file to write, which should end with .imctrl
-
setCalibrant
(calib)[source]¶ Set a calibrant for the current image
Parameters: calib (str) – specifies a calibrant name which must be one of the entries in file ImageCalibrants.py. This is validated and an error provides a list of valid choices.
-
setControl
(arg, value)[source]¶ Set an Image Controls parameter in the current image. If the parameter is not found an exception is raised.
Parameters: - arg (str) – the name of a parameter (dict entry) in the
image. The parameter must be found in
ControlList
or an exception is raised. - value – the value to set the parameter. The value is
cast as the appropriate type from
ControlList
.
- arg (str) – the name of a parameter (dict entry) in the
image. The parameter must be found in
-
setControlFile
(typ, imageRef, mult=None)[source]¶ Set a image to be used as a background/dark/gain map image
Parameters: - typ (str) – specifies image type, which must be one of: ‘background image’, ‘dark image’, ‘gain map’; N.B. only the first four characters must be specified and case is ignored.
- imageRef – A reference to the desired image. Either the Image
tree name (str), the image’s index (int) or
a image object (
G2Image
) - mult (float) – a multiplier to be applied to the image (not used for ‘Gain map’; required for ‘background image’, ‘dark image’
-
setControls
(controlsDict)[source]¶ uses dict from
getControls()
to set Image Controls for current image
-
setMasks
(maskDict, resetThresholds=False)[source]¶ load masks dict (from
getMasks()
) into current IMG recordParameters: - maskDict (dict) – specifies a dict with image parameters,
from
getMasks()
- resetThresholds (bool) – If True, Threshold Masks in the dict are ignored. The default is False which means Threshold Masks are retained.
- maskDict (dict) – specifies a dict with image parameters,
from
-
setVary
(arg, value)[source]¶ Set a refinement flag for Image Controls parameter in the current image. If the parameter is not ‘*’ or found, an exception is raised.
Parameters: - arg (str) – the name of a refinement parameter in the varyList for the image. The name should be one of ‘dep’, ‘det-X’, ‘det-Y’, ‘dist’, ‘phi’, ‘tilt’, or ‘wave’, or it may be a list or tuple of names, or it may be ‘*’ in which all parameters are set accordingly.
- value – the value to set the parameter. The value is
cast as the appropriate type from
ControlList
.
- G2Image.proj: contains a reference to the
-
class
GSASIIscriptable.
G2ObjectWrapper
(datadict)[source]¶ Base class for all GSAS-II object wrappers.
The underlying GSAS-II format can be accessed as wrapper.data. A number of overrides are implemented so that the wrapper behaves like a dictionary.
Author: Jackson O’Donnell (jacksonhodonnell .at. gmail.com)
-
class
GSASIIscriptable.
G2PDF
(data, name, proj)[source]¶ Wrapper for a PDF tree entry, containing the information needed to compute a PDF and the S(Q), G(r) etc. after the computation is done. Note that in a GSASIIscriptable script, instances of G2PDF will be created by calls to
G2Project.add_PDF()
orG2Project.pdf()
, not via calls toG2PDF.__init__()
.Example use of
G2PDF
:gpx.add_PDF('250umSiO2.pdfprm',0) pdf.set_formula(['Si',1],['O',2]) pdf.set_background('Container',1,-0.21) for i in range(5): if pdf.optimize(): break pdf.calculate() pdf.export(gpx.filename,'S(Q), pdfGUI') gpx.save('pdfcalc.gpx')
See also
-
calculate
(xydata=None, limits=None, inst=None)[source]¶ Compute the PDF using the current parameters. Results are set in the PDF object arrays (self.data[‘PDF Controls’][‘G(R)’] etc.). Note that if
xydata
, is specified, the background histograms(s) will not be accessed from the project file associated with the current PDF entry. Iflimits
andinst
are both specified, no histograms need be in the current project. However, the self.data[‘PDF Controls’] sections (‘Sample’, ‘Sample Bkg.’,’Container Bkg.’) must be non-blank for the corresponding items to be used from``xydata``.Parameters: - xydata (dict) – an array containing the Sample’s I vs Q, and any or none of the Sample Background, the Container scattering and the Container Background. If xydata is None (default), the values are taken from histograms, as named in the PDF’s self.data[‘PDF Controls’] entries with keys ‘Sample’, ‘Sample Bkg.’,’Container Bkg.’ & ‘Container’.
- limits (list) – upper and lower Q values to be used for PDF computation. If None (default), the values are taken from the Sample histogram’s .data[‘Limits’][1] values.
- inst (dict) – The Sample histogram’s instrument parameters to be used for PDF computation. If None (default), the values are taken from the Sample histogram’s .data[‘Instrument Parameters’][0] values.
-
export
(fileroot, formats)[source]¶ Write out the PDF-related data (G(r), S(Q),…) into files
Parameters: - fileroot (str) – name of file(s) to be written. The extension will be ignored and set to .iq, .sq, .fq or .gr depending on the formats selected.
- formats (str) – string specifying the file format(s) to be written, should contain at least one of the following keywords: I(Q), S(Q), F(Q), G(r) and/or PDFgui (capitalization and punctuation is ignored). Note that G(r) and PDFgui should not be specifed together.
-
optimize
(showFit=True, maxCycles=5, xydata=None, limits=None, inst=None)[source]¶ Optimize the low R portion of G(R) to minimize selected parameters. Note that this updates the parameters in the settings (self.data[‘PDF Controls’]) but does not update the PDF object arrays (self.data[‘PDF Controls’][‘G(R)’] etc.) with the computed values, use
calculate()
after a fit to do that.Parameters: - showFit (bool) – if True (default) the optimized parameters are shown before and after the fit, as well as the RMS value in the minimized region.
- maxCycles (int) – the maximum number of least-squares cycles; defaults to 5.
- xydata (dict) – an array containing the Sample’s I vs Q, and any or none of the Sample Background, the Container scattering and the Container Background. If xydata is None (default), the values are taken from histograms, as named in the PDF’s self.data[‘PDF Controls’] entries with keys ‘Sample’, ‘Sample Bkg.’,’Container Bkg.’ & ‘Container’.
- limits (list) – upper and lower Q values to be used for PDF computation. If None (default), the values are taken from the Sample histogram’s .data[‘Limits’][1] values.
- inst (dict) – The Sample histogram’s instrument parameters to be used for PDF computation. If None (default), the values are taken from the Sample histogram’s .data[‘Instrument Parameters’][0] values.
Returns: the result from the optimizer as True or False, depending on if the refinement converged.
-
set_background
(btype, histogram, mult=-1.0, refine=False)[source]¶ Sets a histogram to be used as the ‘Sample Background’, the ‘Container’ or the ‘Container Background.’
Parameters: - btype (str) – Type of background to set, must contain the string ‘samp’ for Sample Background’, ‘cont’ and ‘back’ for the ‘Container Background’ or only ‘cont’ for the ‘Container’. Note that capitalization and extra characters are ignored, so the full strings (such as ‘Sample Background’ & ‘Container Background’) can be used.
- histogram – A reference to a histogram, which can be reference by object, name, or number.
- mult (float) – a multiplier for the histogram; defaults to -1.0
- refine (bool) – a flag to enable refinement (only implemented for ‘Sample Background’); defaults to False
-
set_formula
(*args)[source]¶ Set the chemical formula for the PDF computation. Use pdf.set_formula([‘Si’,1],[‘O’,2]) for SiO2.
Parameters: - item1 (list) – The element symbol and number of atoms in formula for first element
- item2 (list) – The element symbol and number of atoms in formula for second element,…
repeat parameters as needed for all elements in the formula.
-
-
class
GSASIIscriptable.
G2Phase
(data, name, proj)[source]¶ A wrapper object around a given phase. The object contains these class variables:
- G2Phase.proj: contains a reference to the
G2Project
object that contains this phase - G2Phase.name: contains the name of the phase
- G2Phase.data: contains the phases’s associated data in a dict, as documented for the Phase Tree items.
Author: Jackson O’Donnell (jacksonhodonnell .at. gmail.com)
-
atom
(atomlabel)[source]¶ Returns the atom specified by atomlabel, or None if it does not exist.
Parameters: atomlabel (str) – The name of the atom (e.g. “O2”) Returns: A G2AtomRecord
object representing the atom.
-
atoms
()[source]¶ Returns a list of atoms present in the current phase.
Returns: A list of G2AtomRecord
objects.See also
-
clear_HAP_refinements
(refs, histograms='all')[source]¶ Clears the given HAP refinement parameters between this phase and the given histograms.
Parameters: - refs (dict) – A dictionary of the parameters to be cleared. See the the Histogram-and-phase parameters table for what can be specified.
- histograms – Either ‘all’ (default) or a list of the histograms by index, name or object. The index number is relative to all histograms in the tree, not to those in the phase. Histograms not associated with the current phase will be ignored. whose HAP parameters will be set with this phase. Histogram and phase must already be associated
Returns: None
-
clear_refinements
(refs)[source]¶ Clears a given set of parameters.
Parameters: refs (dict) – The parameters to clear. See the Phase parameters table for what can be specified.
-
composition
¶ Provides a dict where keys are atom types and values are the number of atoms of that type in cell (such as {‘H’: 2.0, ‘O’: 1.0})
-
copyHAPvalues
(sourcehist, targethistlist='all', skip=[], use=None)[source]¶ Copies HAP parameters for one histogram to a list of other histograms. Use skip or use to select specific entries to be copied or not used.
Parameters: - sourcehist – is a histogram object (
G2PwdrData
) or a histogram name or the index number of the histogram to copy parameters from. The index number is relative to all histograms in the tree, not to those in the phase. - targethistlist (list) – a list of histograms where each item in the
list can be a histogram object (
G2PwdrData
), a histogram name or the index number of the histogram. If the string ‘all’ (default), then all histograms in the phase are used. - skip (list) – items in the HAP dict that should not be
copied. The default is an empty list, which causes all items
to be copied. To see a list of items in the dict, use
getHAPvalues()
or use an invalid item, such as ‘?’. - use (list) – specifies the items in the HAP dict should be copied. The default is None, which causes all items to be copied.
examples:
ph0.copyHAPvalues(0,[1,2,3]) ph0.copyHAPvalues(0,use=['HStrain','Size'])
The first example copies all HAP parameters from the first histogram to the second, third and fourth histograms (as listed in the project tree). The second example copies only the ‘HStrain’ (Dij parameters and refinement flags) and the ‘Size’ (crystallite size settings, parameters and refinement flags) from the first histogram to all histograms.
- sourcehist – is a histogram object (
-
density
¶ Provides a scalar with the density of the phase. In case of a powder this assumes a 100% packing fraction.
-
export_CIF
(outputname, quickmode=True)[source]¶ Write this phase to a .cif file named outputname
Parameters: - outputname (str) – The name of the .cif file to write to
- quickmode (bool) – Currently ignored. Carryover from exports.G2export_CIF
-
getHAPentryList
(histname=None, keyname='')[source]¶ Returns a dict with HAP values. Optionally a histogram may be selected.
Parameters: - histname – is a histogram object (
G2PwdrData
) or a histogram name or the index number of the histogram. The index number is relative to all histograms in the tree, not to those in the phase. If no histogram is specified, all histograms are selected. - keyname (str) – an optional string. When supplied only entries where at least one key contains the specified string are reported. Case is ignored, so ‘sg’ will find entries where one of the keys is ‘SGdata’, etc.
Returns: a set of HAP dict keys.
Example:
>>> p.getHAPentryList(0,'Scale') [(['PWDR test Bank 1', 'Scale'], list, [1.0, False])]
See also
- histname – is a histogram object (
-
getHAPentryValue
(keylist)[source]¶ Returns the HAP value associated with a list of keys. Where the value returned is a list, it may be used as the target of an assignment (as in
getHAPentryValue(...)[...] = val
) to set a value inside a list.Parameters: keylist (list) – a list of dict keys, typically as returned by getHAPentryList()
. Note the first entry is a histogram name. Example:['PWDR hist1.fxye Bank 1', 'Scale']
Returns: HAP value Example:
>>> sclEnt = p.getHAPentryList(0,'Scale')[0] >>> sclEnt [(['PWDR test Bank 1', 'Scale'], list, [1.0, False])] >>> p.getHAPentryValue(sclEnt[0]) [1.0, False] >>> p.getHAPentryValue(sclEnt[0])[1] = True >>> p.getHAPentryValue(sclEnt[0]) [1.0, True]
-
getHAPvalues
(histname)[source]¶ Returns a dict with HAP values for the selected histogram
Parameters: histogram – is a histogram object ( G2PwdrData
) or a histogram name or the index number of the histogram. The index number is relative to all histograms in the tree, not to those in the phase.Returns: HAP value dict
-
getPhaseEntryList
(keyname='')[source]¶ Returns a dict with control values.
Parameters: keyname (str) – an optional string. When supplied only entries where at least one key contains the specified string are reported. Case is ignored, so ‘sg’ will find entries where one of the keys is ‘SGdata’, etc. Returns: a set of phase dict keys. Note that HAP items, while technically part of the phase entries, are not included. See
getHAPentryList()
for a related example.See also
-
getPhaseEntryValue
(keylist)[source]¶ Returns the value associated with a list of keys. Where the value returned is a list, it may be used as the target of an assignment (as in
getPhaseEntryValue(...)[...] = val
) to set a value inside a list.Parameters: keylist (list) – a list of dict keys, typically as returned by getPhaseEntryList()
.Returns: a phase setting; may be a int, float, bool, list,… See
getHAPentryValue()
for a related example.
-
get_cell
()[source]¶ - Returns a dictionary of the cell parameters, with keys:
- ‘length_a’, ‘length_b’, ‘length_c’, ‘angle_alpha’, ‘angle_beta’, ‘angle_gamma’, ‘volume’
Returns: a dict See also
-
get_cell_and_esd
()[source]¶ Returns a pair of dictionaries, the first representing the unit cell, the second representing the estimated standard deviations of the unit cell.
Returns: a tuple of two dictionaries See also
-
histograms
()[source]¶ Returns a list of histogram names associated with the current phase ordered as they appear in the tree (see
G2Project.histograms()
).
-
mu
(wave)[source]¶ Provides mu values for a phase at the supplied wavelength in A. Uses GSASIImath.XScattDen which seems to be off by an order of magnitude, which has been corrected here.
-
setHAPentryValue
(keylist, newvalue)[source]¶ Sets an HAP value associated with a list of keys.
Parameters: - keylist (list) – a list of dict keys, typically as returned by
getHAPentryList()
. Note the first entry is a histogram name. Example:['PWDR hist1.fxye Bank 1', 'Scale']
- newvalue – a new value for the HAP setting. The type must be the same as the initial value, but if the value is a container (list, tuple, np.array,…) the elements inside are not checked.
Example:
>>> sclEnt = p.getHAPentryList(0,'Scale')[0] >>> p.getHAPentryValue(sclEnt[0]) [1.0, False] >>> p.setHAPentryValue(sclEnt[0], (1, True)) GSASIIscriptable.G2ScriptException: setHAPentryValue error: types do not agree for keys ['PWDR test.fxye Bank 1', 'Scale'] >>> p.setHAPentryValue(sclEnt[0], [1, True]) >>> p.getHAPentryValue(sclEnt[0]) [1, True]
- keylist (list) – a list of dict keys, typically as returned by
-
setHAPvalues
(HAPdict, targethistlist='all', skip=[], use=None)[source]¶ Copies HAP parameters for one histogram to a list of other histograms. Use skip or use to select specific entries to be copied or not used. Note that
HStrain
and sometimesMustrain
values can be specific to a Laue class and should be copied with care between phases of different symmetry. A “sanity check” on the number of Dij terms is made ifHStrain
values are copied.Parameters: - HAPdict (dict) – is a dict returned by
getHAPvalues()
containing HAP parameters. - targethistlist (list) – a list of histograms where each item in the
list can be a histogram object (
G2PwdrData
), a histogram name or the index number of the histogram. The index number is relative to all histograms in the tree, not to those in the phase. If the string ‘all’ (default), then all histograms in the phase are used. - skip (list) – items in the HAP dict that should not be
copied. The default is an empty list, which causes all items
to be copied. To see a list of items in the dict, use
getHAPvalues()
or use an invalid item, such as ‘?’. - use (list) – specifies the items in the HAP dict should be copied. The default is None, which causes all items to be copied.
example:
HAPdict = ph0.getHAPvalues(0) ph1.setHAPvalues(HAPdict,use=['HStrain','Size'])
This copies the Dij (hydrostatic strain) HAP parameters and the crystallite size broadening terms from the first histogram in phase
ph0
to all histograms in phaseph1
.- HAPdict (dict) – is a dict returned by
-
setPhaseEntryValue
(keylist, newvalue)[source]¶ Sets a phase control value associated with a list of keys.
Parameters: - keylist (list) – a list of dict keys, typically as returned by
getPhaseEntryList()
. - newvalue – a new value for the phase setting. The type must be the same as the initial value, but if the value is a container (list, tuple, np.array,…) the elements inside are not checked.
See
setHAPentryValue()
for a related example.- keylist (list) – a list of dict keys, typically as returned by
-
setSampleProfile
(histname, parmType, mode, val1, val2=None, axis=None, LGmix=None)[source]¶ Sets sample broadening parameters for a histogram associated with the current phase. This currently supports isotropic and uniaxial broadening modes only.
Parameters: - histogram – is a histogram object (
G2PwdrData
) or a histogram name or the index number of the histogram. The index number is relative to all histograms in the tree, not to those in the phase. - parmType (str) – should be ‘size’ or ‘microstrain’ (can be abbreviated to ‘s’ or ‘m’)
- mode (str) – should be ‘isotropic’ or ‘uniaxial’ (can be abbreviated to ‘i’ or ‘u’)
- val1 (float) – value for isotropic size (in \(\mu m\)) or microstrain (unitless, \(\Delta Q/Q \times 10^6\)) or the equatorial value in the uniaxial case
- val2 (float) – value for axial size (in \(\mu m\)) or axial microstrain (unitless, \(\Delta Q/Q \times 10^6\)) in uniaxial case; not used for isotropic
- axis (list) – tuple or list with three values indicating the preferred direction for uniaxial broadening; not used for isotropic
- LGmix (float) – value for broadening type (1=Lorentzian, 0=Gaussian or a value between 0 and 1. Default value (None) is ignored.
Examples:
phase0.setSampleProfile(0,'size','iso',1.2) phase0.setSampleProfile(0,'micro','isotropic',1234) phase0.setSampleProfile(0,'m','u',1234,4567,[1,1,1],.5) phase0.setSampleProfile(0,'s','uni',1.2,2.3,[0,0,1])
- histogram – is a histogram object (
-
set_HAP_refinements
(refs, histograms='all')[source]¶ Sets the given HAP refinement parameters between the current phase and the specified histograms.
Parameters: - refs (dict) – A dictionary of the parameters to be set. See the Histogram-and-phase parameters table for a description of this dictionary.
- histograms – Either ‘all’ (default) or a list of the histograms by index, name or object. The index number is relative to all histograms in the tree, not to those in the phase. Histograms not associated with the current phase will be ignored. whose HAP parameters will be set with this phase. Histogram and phase must already be associated.
Returns: None
-
set_refinements
(refs)[source]¶ Sets the phase refinement parameter ‘key’ to the specification ‘value’
Parameters: refs (dict) – A dictionary of the parameters to be set. See the Phase parameters table for a description of this dictionary. Returns: None
- G2Phase.proj: contains a reference to the
-
class
GSASIIscriptable.
G2Project
(gpxfile=None, author=None, filename=None, newgpx=None)[source]¶ Represents an entire GSAS-II project. The object contains these class variables:
G2Project.filename: contains the .gpx filename
G2Project.names: contains the contents of the project “tree” as a list of lists. Each top-level entry in the tree is an item in the list. The name of the top-level item is the first item in the inner list. Children of that item, if any, are subsequent entries in that list.
G2Project.data: contains the entire project as a dict. The keys for the dict are the top-level names in the project tree (initial items in the G2Project.names inner lists) and each top-level item is stored as a dict.
- The contents of Top-level entries will be found in the item
named ‘data’, as an example,
G2Project.data['Notebook']['data']
- The contents of child entries will be found in the item
using the names of the parent and child, for example
G2Project.data['Phases']['NaCl']
- The contents of Top-level entries will be found in the item
named ‘data’, as an example,
Parameters: - gpxfile (str) – Existing .gpx file to be loaded. If nonexistent, creates an empty project.
- author (str) – Author’s name (not yet implemented)
- newgpx (str) – The filename the project should be saved to in the future. If both newgpx and gpxfile are present, the project is loaded from the file named by gpxfile and then when saved will be written to the file named by newgpx.
- filename (str) – To be deprecated. Serves the same function as newgpx, which has a somewhat more clear name. (Do not specify both newgpx and filename).
There are two ways to initialize this object:
>>> # Load an existing project file >>> proj = G2Project('filename.gpx')
>>> # Create a new project >>> proj = G2Project(newgpx='new_file.gpx')
Histograms can be accessed easily.
>>> # By name >>> hist = proj.histogram('PWDR my-histogram-name')
>>> # Or by index >>> hist = proj.histogram(0) >>> assert hist.id == 0
>>> # Or by random id >>> assert hist == proj.histogram(hist.ranId)
Phases can be accessed the same way.
>>> phase = proj.phase('name of phase')
New data can also be loaded via
add_phase()
andadd_powder_histogram()
.>>> hist = proj.add_powder_histogram('some_data_file.chi', 'instrument_parameters.prm') >>> phase = proj.add_phase('my_phase.cif', histograms=[hist])
Parameters for Rietveld refinement can be turned on and off as well. See
set_refinement()
,clear_refinements()
,iter_refinements()
,do_refinements()
.-
add_EqnConstr
(total, varlist, multlist=[], reloadIdx=True)[source]¶ Set a constraint equation on a list of variables.
Note that this will cause the project to be saved if not already done so. It will always save the .gpx file before creating a constraint if reloadIdx is True.
Parameters: - total (float) – A value that the constraint must equal
- varlist (list) – A list of variables to use in the equation.
Each value in the list may be one of the following three items:
(A) a
GSASIIobj.G2VarObj
object, (B) a variable name (str), or (C) a list/tuple of arguments formake_var_obj()
. - multlist (list) – a list of multipliers for each variable in varlist. If there are fewer values than supplied for varlist then missing values will be set to 1. The default is [] which means that all multipliers are 1.
- reloadIdx (bool) – If True (default) the .gpx file will be saved and indexed prior to use. This is essential if atoms, phases or histograms have been added to the project.
Example:
gpx.add_EqnConstr(1.0,('0::Ax:0','0::Ax:1'),[1,1])
-
add_EquivConstr
(varlist, multlist=[], reloadIdx=True)[source]¶ Set a equivalence on a list of variables.
Note that this will cause the project to be saved if not already done so. It will always save the .gpx file before creating a constraint if reloadIdx is True.
Parameters: - varlist (list) – A list of variables to make equivalent to the
first item in the list.
Each value in the list may be one of the following three items:
(A) a
GSASIIobj.G2VarObj
object, (B) a variable name (str), or (C) a list/tuple of arguments formake_var_obj()
. - multlist (list) – a list of multipliers for each variable in varlist. If there are fewer values than supplied for varlist then missing values will be set to 1. The default is [] which means that all multipliers are 1.
- reloadIdx (bool) – If True (default) the .gpx file will be saved and indexed prior to use. This is essential if atoms, phases or histograms have been added to the project.
Examples:
gpx.add_EquivConstr(('0::AUiso:0','0::AUiso:1','0::AUiso:2')) gpx.add_EquivConstr(('0::dAx:0','0::dAx:1'),[1,-1])
- varlist (list) – A list of variables to make equivalent to the
first item in the list.
Each value in the list may be one of the following three items:
(A) a
-
add_HoldConstr
(varlist, reloadIdx=True)[source]¶ Set a hold constraint on a list of variables.
Note that this will cause the project to be saved if not already done so. It will always save the .gpx file before creating constraint(s) if reloadIdx is True.
Parameters: - varlist (list) – A list of variables to hold.
Each value in the list may be one of the following three items:
(A) a
GSASIIobj.G2VarObj
object, (B) a variable name (str), or (C) a list/tuple of arguments formake_var_obj()
. - reloadIdx (bool) – If True (default) the .gpx file will be saved and indexed prior to use. This is essential if atoms, phases or histograms have been added to the project.
Example:
gpx.add_HoldConstr(('0::A4','0:1:D12',':0:Lam'))
- varlist (list) – A list of variables to hold.
Each value in the list may be one of the following three items:
(A) a
-
add_NewVarConstr
(varlist, multlist=[], name=None, vary=False, reloadIdx=True)[source]¶ Set a new-variable constraint from a list of variables to create a new parameter from two or more predefined parameters.
Note that this will cause the project to be saved, if not already done so. It will always save the .gpx file before creating a constraint if reloadIdx is True.
Parameters: - varlist (list) – A list of variables to use in the expression.
Each value in the list may be one of the following three items:
(A) a
GSASIIobj.G2VarObj
object, (B) a variable name (str), or (C) a list/tuple of arguments formake_var_obj()
. - multlist (list) – a list of multipliers for each variable in varlist. If there are fewer values than supplied for varlist then missing values will be set to 1. The default is [] which means that all multipliers are 1.
- name (str) – An optional string to be supplied as a name for this new parameter.
- vary (bool) – Determines if the new variable should be flagged to be refined.
- reloadIdx (bool) – If True (default) the .gpx file will be saved and indexed prior to use. This is essential if atoms, phases or histograms have been added to the project.
Examples:
gpx.add_NewVarConstr(('0::AFrac:0','0::AFrac:1'),[0.5,0.5],'avg',True) gpx.add_NewVarConstr(('0::AFrac:0','0::AFrac:1'),[1,-1],'diff',False,False)
The example above is a way to treat two variables that are closely correlated. The first variable, labeled as avg, allows the two variables to refine in tandem while the second variable (diff) tracks their difference. In the initial stages of refinement only avg would be refined, but in the final stages, it might be possible to refine diff. The second False value in the second example prevents the .gpx file from being saved.
- varlist (list) – A list of variables to use in the expression.
Each value in the list may be one of the following three items:
(A) a
-
add_PDF
(prmfile, histogram)[source]¶ Creates a PDF entry that can be used to compute a PDF. Note that this command places an entry in the project, but
G2PDF.calculate()
must be used to actually perform the computation.Parameters: - datafile (str) – The powder data file to read, a filename.
- histogram – A reference to a histogram, which can be reference by object, name, or number.
Returns: A
G2PDF
object for the PDF entry
-
add_constraint_raw
(cons_scope, constr)[source]¶ Adds a constraint to the project.
Parameters: - cons_scope (str) – should be one of “Hist”, “Phase”, “HAP”, or “Global”.
- constr (list) – a constraint coded with
GSASIIobj.G2VarObj
objects as described in the constraint definition descriptions.
WARNING this function does not check the constraint is well-constructed. Please use
G2Project.add_HoldConstr()
orG2Project.add_EquivConstr()
(etc.) instead, unless you are really certain you know what you are doing.
-
add_image
(imagefile, fmthint=None, defaultImage=None, indexList=None)[source]¶ Load an image into a project
Parameters: - imagefile (str) – The image file to read, a filename.
- fmthint (str) – If specified, only importers where the format name (reader.formatName, as shown in Import menu) contains the supplied string will be tried as importers. If not specified, all importers consistent with the file extension will be tried (equivalent to “guess format” in menu).
- defaultImage (str) – The name of an image to use as a default for setting parameters for the image file to read.
- indexList (list) – specifies the image numbers (counting from zero)
to be used from the file when a file has multiple images. A value of
[0,2,3]
will cause the only first, third and fourth images in the file to be included in the project.
Returns: a list of
G2Image
object(s) for the added image(s)
-
add_phase
(phasefile, phasename=None, histograms=[], fmthint=None, mag=False)[source]¶ Loads a phase into the project from a .cif file
Parameters: - phasefile (str) – The CIF file from which to import the phase.
- phasename (str) – The name of the new phase, or None for the default
- histograms (list) – The names of the histograms to associate with this phase. Use proj.histograms() to add to all histograms.
- fmthint (str) – If specified, only importers where the format name (reader.formatName, as shown in Import menu) contains the supplied string will be tried as importers. If not specified, all importers consistent with the file extension will be tried (equivalent to “guess format” in menu).
- mag (bool) – Set to True to read a magCIF
Returns: A
G2Phase
object representing the new phase.
-
add_powder_histogram
(datafile, iparams, phases=[], fmthint=None, databank=None, instbank=None)[source]¶ Loads a powder data histogram into the project.
Automatically checks for an instrument parameter file, or one can be provided. Note that in unix fashion, “~” can be used to indicate the home directory (e.g. ~/G2data/data.fxye).
Note that the data type (x-ray/CW neutron/TOF) for the histogram will be set from the instrument parameter file. The instrument geometry is assumed to be Debye-Scherrer except for dual-wavelength x-ray, where Bragg-Brentano is assumed.
Parameters: - datafile (str) – The powder data file to read, a filename.
- iparams (str) – The instrument parameters file, a filename.
- phases (list) – A list of phases to link to the new histogram, phases can be references by object, name, rId or number. Alternately, use ‘all’ to link to all phases in the project.
- fmthint (str) – If specified, only importers where the format name (reader.formatName, as shown in Import menu) contains the supplied string will be tried as importers. If not specified, all importers consistent with the file extension will be tried (equivalent to “guess format” in menu).
- databank (int) – Specifies a dataset number to read, if file contains more than set of data. This should be 1 to read the first bank in the file (etc.) regardless of the number on the Bank line, etc. Default is None which means there should only be one dataset in the file.
- instbank (int) – Specifies an instrument parameter set to read, if the instrument parameter file contains more than set of parameters. This will match the INS # in an GSAS type file so it will typically be 1 to read the first parameter set in the file (etc.) Default is None which means there should only be one parameter set in the file.
Returns: A
G2PwdrData
object representing the histogram
-
add_simulated_powder_histogram
(histname, iparams, Tmin, Tmax, Tstep=None, wavelength=None, scale=None, phases=[], ibank=None, Npoints=None)[source]¶ Create a simulated powder data histogram for the project.
Requires an instrument parameter file. Note that in unix fashion, “~” can be used to indicate the home directory (e.g. ~/G2data/data.prm). The instrument parameter file will determine if the histogram is x-ray, CW neutron, TOF, etc. as well as the instrument type.
Parameters: - histname (str) – A name for the histogram to be created.
- iparams (str) – The instrument parameters file, a filename.
- Tmin (float) – Minimum 2theta or TOF (millisec) for dataset to be simulated
- Tmax (float) – Maximum 2theta or TOF (millisec) for dataset to be simulated
- Tstep (float) – Step size in 2theta or deltaT/T (TOF) for simulated dataset. Default is to compute this from Npoints.
- wavelength (float) – Wavelength for CW instruments, overriding the value in the instrument parameters file if specified.
- scale (float) – Histogram scale factor which multiplies the pattern. Note that simulated noise is added to the pattern, so that if the maximum intensity is small, the noise will mask the computed pattern. The scale needs to be a large number for CW neutrons. The default, None, provides a scale of 1 for x-rays and TOF; 10,000 for CW neutrons and 100,000 for TOF.
- phases (list) – Phases to link to the new histogram. Use proj.phases() to link to all defined phases.
- ibank (int) – provides a bank number for the instrument parameter file. The default is None, corresponding to load the first bank.
- Νpoints (int) – the number of data points to be used for computing the diffraction pattern. Defaults as None, which sets this to 2500. Do not specify both Npoints and Tstep. Due to roundoff the actual nuber of points used may differ by +-1 from Npoints. Must be below 25,000.
Returns: A
G2PwdrData
object representing the histogram
-
clone_powder_histogram
(histref, newname, Y, Yerr=None)[source]¶ Creates a copy of a powder diffraction histogram with new Y values. The X values are not changed. The number of Y values must match the number of X values.
Parameters: - histref – The histogram object, the name of the histogram (str), or ranId or histogram index.
- newname (str) – The name to be assigned to the new histogram
- Y (list) – A set of intensity values
- Yerr (list) – A set of uncertainties for the intensity values (may be None, sets all weights to unity)
Returns: the new histogram object (type G2PwdrData)
-
copyHistParms
(sourcehist, targethistlist='all', modelist='all')[source]¶ Copy histogram information from one histogram to others
Parameters: - sourcehist – is a histogram object (
G2PwdrData
) or a histogram name or the index number of the histogram - targethistlist (list) – a list of histograms where each item in the
list can be a histogram object (
G2PwdrData
), a histogram name or the index number of the histogram. if the string ‘all’ (default value), then all histograms in the project are used. - modelist (list) – May be a list of sections to copy, which may include ‘Background’, ‘Instrument Parameters’, ‘Limits’ and ‘Sample Parameters’ (items may be shortened to uniqueness and capitalization is ignored, so [‘b’,’i’,’L’,’s’] will work.) The default value, ‘all’ causes the listed sections to
- sourcehist – is a histogram object (
-
copy_PDF
(PDFobj, histogram)[source]¶ Creates a PDF entry that can be used to compute a PDF as a copy of settings in an existing PDF (
G2PDF
) object. This places an entry in the project butG2PDF.calculate()
must be used to actually perform the PDF computation.Parameters: - PDFobj – A
G2PDF
object which may be in a separate project or the dict associated with the PDF object (G2PDF.data). - histogram – A reference to a histogram, which can be reference by object, name, or number.
Returns: A
G2PDF
object for the PDF entry- PDFobj – A
-
do_refinements
(refinements=[{}], histogram='all', phase='all', outputnames=None, makeBack=False)[source]¶ - Conducts one or a series of refinements according to the
- input provided in parameter refinements. This is a wrapper
around
iter_refinements()
Parameters: - refinements (list) – A list of dictionaries specifiying changes to be made to
parameters before refinements are conducted.
See the Refinement recipe section for how this is defined.
If not specified, the default value is
[{}]
, which performs a single refinement step is performed with the current refinement settings. - histogram (str) – Name of histogram for refinements to be applied to, or ‘all’; note that this can be overridden for each refinement step via a “histograms” entry in the dict.
- phase (str) – Name of phase for refinements to be applied to, or ‘all’; note that this can be overridden for each refinement step via a “phases” entry in the dict.
- outputnames (list) – Provides a list of project (.gpx) file names
to use for each refinement step (specifying None skips the save step).
See
save()
. Note that this can be overridden using an “output” entry in the dict. - makeBack (bool) – determines if a backup ).bckX.gpx) file is made before a refinement is performed. The default is False.
To perform a single refinement without changing any parameters, use this call:
my_project.do_refinements([])
-
classmethod
from_dict_and_names
(gpxdict, names, filename=None)[source]¶ Creates a
G2Project
directly from a dictionary and a list of names. If in doubt, do not use this.Returns: a G2Project
-
get_Constraints
(ctype)[source]¶ Returns a list of constraints of the type selected.
Parameters: ctype (str) – one of the following keywords: ‘Hist’, ‘HAP’, ‘Phase’, ‘Global’ Returns: a list of constraints, see the constraint definition descriptions. Note that if this list is changed (for example by deleting elements or by changing them) the constraints in the project are changed.
-
get_Controls
(control, variable=None)[source]¶ Return project controls settings
Parameters: - control (str) – the item to be returned. See below for allowed values.
- variable (str) – a variable name as a str or
(as a
GSASIIobj.G2VarObj
object). Used only with control set to “parmMin” or “parmMax”.
Returns: The value for the control.
Allowed values for parameter control:
- cycles: the maximum number of cycles (returns int)
- sequential: the histograms used for a sequential refinement as a list of histogram names or an empty list when in non-sequential mode.
- Reverse Seq: returns True or False. True indicates that fitting of the sequence of histograms proceeds in reversed order.
- seqCopy: returns True or False. True indicates that results from each sequential fit are used as the starting point for the next histogram.
- parmMin & parmMax: retrieves a maximum or minimum value for a refined parameter. Note that variable will be a GSAS-II variable name, optionally with * specified for a histogram or atom number. Return value will be a float. (See Parameter Limits description.)
- Anything else returns the value in the Controls dict, if present. An exception is raised if the control value is not present.
See also
-
get_Covariance
(varList)[source]¶ Returns the values and covariance matrix for a series of variable parameters. as defined in the last refinement cycle
Parameters: varList (tuple) – a list of variable names of form ‘<p>:<h>:<name>’ Returns: (valueList,CovMatrix) where valueList contains the (n) values in the same order as varList (also length n) and CovMatrix is a (n x n) matrix. If any variable name is not found in the varyList then None is returned. Use this code, where sig provides standard uncertainties for parameters and where covArray provides the correlation between off-diagonal terms:
sig = np.sqrt(np.diag(covMatrix)) xvar = np.outer(sig,np.ones_like(sig)) covArray = np.divide(np.divide(covMatrix,xvar),xvar.T)
-
get_Frozen
(histogram=None)[source]¶ Gets a list of Frozen variables. (See Parameter Limits description.) Note that use of this will cause the project to be saved if not already done so.
Parameters: histogram – A reference to a histogram, which can be reference by object, name, or number. Used for sequential fits only. If left as the default (None) for a sequential fit, all Frozen variables in all histograms are returned. Returns: a list containing variable names, as str values
-
get_ParmList
()[source]¶ Returns a list of all the parameters defined in the last refinement cycle
Returns: a list of parameters or None if no refinement has been performed.
-
get_Variable
(var)[source]¶ Returns the value and standard uncertainty (esd) for a variable parameters, as defined in the last refinement cycle
Parameters: var (str) – a variable name of form ‘<p>:<h>:<name>’, such as ‘:0:Scale’ Returns: (value,esd) if the parameter is refined or (value, None) if the variable is in a constraint or is not refined or None if the parameter is not found.
-
get_VaryList
()[source]¶ Returns a list of the refined variables in the last refinement cycle
Returns: a list of variables or None if no refinement has been performed.
-
histogram
(histname)[source]¶ Returns the histogram named histname, or None if it does not exist.
Parameters: histname – The name of the histogram (str), or ranId or index. Returns: A G2PwdrData
object, or None if the histogram does not existSee also
-
histograms
(typ=None)[source]¶ Return a list of all histograms, as
G2PwdrData
objectsFor now this only finds Powder/Single Xtal histograms, since that is all that is currently implemented in this module.
Parameters: typ (ste) – The prefix (type) the histogram such as ‘PWDR ‘. If None (the default) all known histograms types are found. Returns: a list of objects See also
-
hold_many
(vars, ctype)[source]¶ Apply holds for all the variables in vars, for constraint of a given type. This routine has been superceeded by
add_Hold()
Parameters: - vars (list) – A list of variables to hold. Each may be a
GSASIIobj.G2VarObj
object, a variable name (str), or a list/tuple of arguments formake_var_obj()
. - ctype (str) – A string constraint type specifier, passed directly to
add_constraint_raw()
as consType. Should be one of “Hist”, “Phase”, or “HAP” (“Global” not implemented).
- vars (list) – A list of variables to hold. Each may be a
-
image
(imageRef)[source]¶ Gives an object representing the specified image in this project.
Parameters: imageRef (str) – A reference to the desired image. Either the Image tree name (str), the image’s index (int) or a image object ( G2Image
)Returns: A G2Image
objectRaises: KeyError See also
-
imageMultiDistCalib
(imageList=None, verbose=False)[source]¶ Invokes a global calibration fit (same as Image Controls/Calibration/Multi-distance Recalibrate menu command) with images as multiple distance settings. Note that for this to work properly, the initial calibration parameters (center, wavelength, distance & tilts) must be close enough to converge. This may produce a better result if run more than once.
See Image Calibration for example code.
Parameters: imageList (str) – the images to include in the fit, if not specified all images in the project will be included. Returns: parmDict,covData where parmDict has the refined parameters and their values and covData is a dict containing the covariance matrix (‘covMatrix’), the number of ring picks (‘obs’) the reduced Chi-squared (‘chisq’), the names of the variables (‘varyList’) and their values (‘variables’)
-
images
()[source]¶ Returns a list of all the images in the project.
Returns: A list of G2Image
objects
-
iter_refinements
(refinements, histogram='all', phase='all', outputnames=None, makeBack=False)[source]¶ Conducts a series of refinements, iteratively. Stops after every refinement and yields this project, to allow error checking or logging of intermediate results. Parameter use is the same as for
do_refinements()
(which calls this method).>>> def checked_refinements(proj): ... for p in proj.iter_refinements(refs): ... # Track intermediate results ... log(p.histogram('0').residuals) ... log(p.phase('0').get_cell()) ... # Check if parameter diverged, nonsense answer, or whatever ... if is_something_wrong(p): ... raise Exception("I need a human!")
-
make_var_obj
(phase=None, hist=None, varname=None, atomId=None, reloadIdx=True)[source]¶ Wrapper to create a G2VarObj. Takes either a string representation (“p:h:name:a”) or individual names of phase, histogram, varname, and atomId.
Automatically converts string phase, hist, or atom names into the ID required by G2VarObj.
Note that this will cause the project to be saved if not already done so.
-
pdf
(pdfRef)[source]¶ Gives an object representing the specified PDF entry in this project.
Parameters: pdfRef – A reference to the desired image. Either the PDF tree name (str), the pdf’s index (int) or a PDF object ( G2PDF
)Returns: A G2PDF
objectRaises: KeyError
-
phase
(phasename)[source]¶ Gives an object representing the specified phase in this project.
Parameters: phasename (str) – A reference to the desired phase. Either the phase name (str), the phase’s ranId, the phase’s index (both int) or a phase object ( G2Phase
)Returns: A G2Phase
objectRaises: KeyError See also
-
phases
()[source]¶ Returns a list of all the phases in the project.
Returns: A list of G2Phase
objectsSee also
-
refine
(newfile=None, printFile=None, makeBack=False)[source]¶ Invoke a refinement for the project. The project is written to the currently selected gpx file and then either a single or sequential refinement is performed depending on the setting of ‘Seq Data’ in Controls (set in
get_Controls()
).
-
save
(filename=None)[source]¶ Saves the project, either to the current filename, or to a new file.
Updates self.filename if a new filename provided
-
seqref
()[source]¶ Returns a sequential refinement results object, if present
Returns: A G2SeqRefRes
object or None if not present
-
set_Controls
(control, value, variable=None)[source]¶ Set project controls.
Note that use of this with control set to parmMin or parmMax will cause the project to be saved if not already done so.
Parameters: - control (str) – the item to be set. See below for allowed values.
- value – the value to be set.
- variable (str) – used only with control set to “parmMin” or “parmMax”
Allowed values for control parameter:
'cycles'
: sets the maximum number of cycles (value must be int)'sequential'
: sets the histograms to be used for a sequential refinement. Use an empty list to turn off sequential fitting. The values in the list may be the name of the histogram (a str), or a ranId or index (int values), seehistogram()
.'seqCopy'
: when True, the results from each sequential fit are used as the starting point for the next. After each fit is is set to False. Ignored for non-sequential fits.'Reverse Seq'
: when True, sequential refinement is performed on the reversed list of histograms.'parmMin'
&'parmMax'
: set a maximum or minimum value for a refined parameter. Note that variable will be a GSAS-II variable name, optionally with * specified for a histogram or atom number and value must be a float. (See Parameter Limits description.)
See also
-
set_Frozen
(variable=None, histogram=None, mode='remove')[source]¶ Removes one or more Frozen variables (or adds one) (See Parameter Limits description.) Note that use of this will cause the project to be saved if not already done so.
Parameters: - variable (str) – a variable name as a str or
(as a
GSASIIobj.G2VarObj
object). Should not contain wildcards. If None (default), all frozen variables are deleted from the project, unless a sequential fit and a histogram is specified. - histogram – A reference to a histogram, which can be reference by object, name, or number. Used for sequential fits only.
- mode (str) – The default mode is to remove variables from the appropriate Frozen list, but if the mode is specified as ‘add’, the variable is added to the list.
Returns: True if the variable was added or removed, False otherwise. Exceptions are generated with invalid requests.
- variable (str) – a variable name as a str or
(as a
-
set_refinement
(refinement, histogram='all', phase='all')[source]¶ Apply specified refinements to a given histogram(s) or phase(s).
Parameters: - refinement (dict) – The refinements to be conducted
- histogram – Specifies either ‘all’ (default), a single histogram or
a list of histograms. Histograms may be specified as histogram objects
(see
G2PwdrData
), the histogram name (str) or the index number (int) of the histogram in the project, numbered starting from 0. Omitting the parameter or the string ‘all’ indicates that parameters in all histograms should be set. - phase – Specifies either ‘all’ (default), a single phase or
a list of phases. Phases may be specified as phase objects
(see
G2Phase
), the phase name (str) or the index number (int) of the phase in the project, numbered starting from 0. Omitting the parameter or the string ‘all’ indicates that parameters in all phases should be set.
Note that refinement parameters are categorized as one of three types:
- Histogram parameters
- Phase parameters
- Histogram-and-Phase (HAP) parameters
-
class
GSASIIscriptable.
G2PwdrData
(data, proj, name)[source]¶ Wraps a Powder Data Histogram. The object contains these class variables:
- G2PwdrData.proj: contains a reference to the
G2Project
object that contains this histogram - G2PwdrData.name: contains the name of the histogram
- G2PwdrData.data: contains the histogram’s associated data in a dict, as documented for the Powder Diffraction Tree. The actual histogram values are contained in the ‘data’ dict item, as documented for Data.
-
Background
¶ Provides a list with with the Background parameters for this histogram.
Returns: list containing a list and dict with background values
-
EditSimulated
(Tmin, Tmax, Tstep=None, Npoints=None)[source]¶ Change the parameters for an existing simulated powder histogram. This will reset the previously computed “observed” pattern.
Parameters: - Tmin (float) – Minimum 2theta or TOF (microsec) for dataset to be simulated
- Tmax (float) – Maximum 2theta or TOF (usec) for dataset to be simulated
- Tstep (float) – Step size in 2theta or TOF (usec) for dataset to be simulated Default is to compute this from Npoints.
- Νpoints (int) – the number of data points to be used for computing the diffraction pattern. Defaults as None, which sets this to 2500. Do not specify both Npoints and Tstep. Due to roundoff the actual nuber of points used may differ by +-1 from Npoints. Must be below 25,000.
-
Export
(fileroot, extension, fmthint=None)[source]¶ Write the histogram into a file. The path is specified by fileroot and extension.
Parameters: - fileroot (str) – name of the file, optionally with a path (extension is ignored)
- extension (str) – includes ‘.’, must match an extension in global exportersByExtension[‘powder’] or a Exception is raised.
- fmthint (str) – If specified, the first exporter where the format name (obj.formatName, as shown in Export menu) contains the supplied string will be used. If not specified, an error will be generated showing the possible choices.
Returns: name of file that was written
-
Export_peaks
(filename)[source]¶ Write the peaks file. The path is specified by filename extension.
Parameters: filename (str) – name of the file, optionally with a path, includes an extension Returns: name of file that was written
-
InstrumentParameters
¶ Provides a dictionary with with the Instrument Parameters for this histogram.
-
LoadProfile
(filename, bank=0)[source]¶ Reads a GSAS-II (new style) .instprm file and overwrites the current parameters
Parameters: - filename (str) – instrument parameter file name, extension ignored if not .instprm
- bank (int) – bank number to read, defaults to zero
-
PeakList
¶ Provides a list of peaks parameters for this histogram.
Returns: a list of peaks, where each peak is a list containing [pos,area,sig,gam] (position, peak area, Gaussian width, Lorentzian width)
-
Peaks
¶ Provides a dict with the Peak List parameters for this histogram.
Returns: dict with two elements where item ‘peaks’ is a list of peaks where each element is [pos,pos-ref,area,area-ref,sig,sig-ref,gam,gam-ref], where the -ref items are refinement flags and item ‘sigDict’ is a dict with possible items ‘Back;#’, ‘pos#’, ‘int#’, ‘sig#’, ‘gam#’
-
SampleParameters
¶ Provides a dictionary with with the Sample Parameters for this histogram.
-
add_back_peak
(pos, int, sig, gam, refflags=[])[source]¶ Adds a background peak to the Background parameters
Parameters: - pos (float) – position of peak, a 2theta or TOF value
- int (float) – integrated intensity of background peak, usually large
- sig (float) – Gaussian width of background peak, usually large
- gam (float) – Lorentzian width of background peak, usually unused (small)
- refflags (list) – a list of 1 to 4 boolean refinement flags for pos,int,sig & gam, respectively (use [0,1] to refine int only). Defaults to [] which means nothing is refined.
-
add_peak
(area, dspace=None, Q=None, ttheta=None)[source]¶ Adds a single peak to the peak list :param float area: peak area :param float dspace: peak position as d-space (A) :param float Q: peak position as Q (A-1) :param float ttheta: peak position as 2Theta (deg)
Note: only one of the parameters: dspace, Q or ttheta may be specified. See Peak Fitting for an example.
-
clear_refinements
(refs)[source]¶ Clears the refinement parameter ‘key’ and its associated value.
Parameters: refs (dict) – A dictionary of parameters to clear. See the Histogram parameters table for what can be specified.
-
del_back_peak
(peaknum)[source]¶ Removes a background peak from the Background parameters
Parameters: peaknum (int) – the number of the peak (starting from 0)
-
fit_fixed_points
()[source]¶ Attempts to apply a background fit to the fixed points currently specified.
-
getHistEntryList
(keyname='')[source]¶ Returns a dict with histogram setting values.
Parameters: keyname (str) – an optional string. When supplied only entries where at least one key contains the specified string are reported. Case is ignored, so ‘sg’ will find entries where one of the keys is ‘SGdata’, etc. Returns: a set of histogram dict keys. See
G2Phase.getHAPentryList()
for a related example.See also
-
getHistEntryValue
(keylist)[source]¶ Returns the histogram control value associated with a list of keys. Where the value returned is a list, it may be used as the target of an assignment (as in
getHistEntryValue(...)[...] = val
) to set a value inside a list.Parameters: keylist (list) – a list of dict keys, typically as returned by getHistEntryList()
.Returns: a histogram setting; may be a int, float, bool, list,… See
G2Phase.getHAPentryValue()
for a related example.
-
get_wR
()[source]¶ returns the overall weighted profile R factor for a histogram
Returns: a wR value as a percentage or None if not defined
-
getdata
(datatype)[source]¶ Provides access to the histogram data of the selected data type
Parameters: datatype (str) – must be one of the following values (case is ignored)
- ’X’: the 2theta or TOF values for the pattern
- ’Yobs’: the observed intensity values
- ’Yweight’: the weights for each data point (1/sigma**2)
- ’Ycalc’: the computed intensity values
- ’Background’: the computed background values
- ’Residual’: the difference between Yobs and Ycalc (obs-calc)
Returns: an numpy MaskedArray with data values of the requested type
-
ref_back_peak
(peaknum, refflags=[])[source]¶ Sets refinement flag for a background peak
Parameters: - peaknum (int) – the number of the peak (starting from 0)
- refflags (list) – a list of 1 to 4 boolean refinement flags for pos,int,sig & gam, respectively. If a flag is not specified it defaults to False (use [0,1] to refine int only). Defaults to [] which means nothing is refined.
-
refine_peaks
(mode='useIP')[source]¶ Causes a refinement of peak position, background and instrument parameters
Parameters: mode (str) – this determines how peak widths are determined. If the value is ‘useIP’ (the default) then the width parameter values (sigma, gamma, alpha,…) are computed from the histogram’s instrument parameters. If the value is ‘hold’, then peak width parameters are not overridden. In this case, it is not possible to refine the instrument parameters associated with the peak widths and an attempt to do so will result in an error. Returns: a list of dicts with refinement results. Element 0 has uncertainties on refined values (also placed in self.data[‘Peak List’][‘sigDict’]) element 1 has the peak fit result, element 2 has the peak fit uncertainties and element 3 has r-factors from the fit. (These are generated in GSASIIpwd.DoPeakFit()
).
-
reflections
()[source]¶ Returns a dict with an entry for every phase in the current histogram. Within each entry is a dict with keys ‘RefList’ (reflection list, see Powder Reflections), ‘Type’ (histogram type), ‘FF’ (form factor information), ‘Super’ (True if this is superspace group).
-
residuals
¶ Provides a dictionary with with the R-factors for this histogram. Includes the weighted and unweighted profile terms (R, Rb, wR, wRb, wRmin) as well as the Bragg R-values for each phase (ph:H:Rf and ph:H:Rf^2).
-
setHistEntryValue
(keylist, newvalue)[source]¶ Sets a histogram control value associated with a list of keys.
SeeG2Phase.setHAPentryValue()
for a related example.Parameters: keylist (list) – - a list of dict keys, typically as returned by
getHistEntryList()
.
param newvalue: a new value for the hist setting. The type must be the same as the initial value, but if the value is a container (list, tuple, np.array,…) the elements inside are not checked.
-
set_background
(key, value)[source]¶ Set background parameters (this serves a similar function as in
set_refinements()
, but with a simplified interface).Parameters: - key (str) –
a string that defines the background parameter that will be changed. Must appear in the table below.
key name type of value meaning of value fixedHist int, str, None or G2PwdrData reference to a histogram in the current project or None to remove the reference. fixedFileMult float multiplier applied to intensities in the background histogram where a value of -1.0 means full subtraction of the background histogram. - value – a value to set the selected background parameter. The meaning and type for this parameter is listed in the table above.
- key (str) –
-
set_peakFlags
(peaklist=None, area=None, pos=None, sig=None, gam=None, alp=None, bet=None)[source]¶ Set refinement flags for peaks
Parameters: - peaklist (list) – a list of peaks to change flags. If None (default), changes are made to all peaks.
- area (bool) – Sets or clears the refinement flag for the peak area value. If None (the default), no change is made.
- pos (bool) – Sets or clears the refinement flag for the peak position value. If None (the default), no change is made.
- sig (bool) – Sets or clears the refinement flag for the peak sigma (Gaussian width) value. If None (the default), no change is made.
- gam (bool) – Sets or clears the refinement flag for the peak gamma (Lorentzian width) value. If None (the default), no change is made.
- alp (bool) – Sets or clears the refinement flag for the peak alpha (TOF width) value. If None (the default), no change is made.
- bet (bool) – Sets or clears the refinement flag for the peak beta (TOF width) value. If None (the default), no change is made.
Note that when peaks are first created the area flag is on and the other flags are initially off.
Example:
set_peakFlags(sig=False,gam=True)
causes the sig refinement flag to be cleared and the gam flag to be set, in both cases for all peaks. The position and area flags are not changed from their previous values.
-
set_refinements
(refs)[source]¶ Sets the histogram refinement parameter ‘key’ to the specification ‘value’.
Parameters: refs (dict) – A dictionary of the parameters to be set. See the Histogram parameters table for a description of what these dictionaries should be. Returns: None
- G2PwdrData.proj: contains a reference to the
-
class
GSASIIscriptable.
G2SeqRefRes
(data, proj)[source]¶ Wrapper for a Sequential Refinement Results tree entry, containing the results for a refinement
As an example:
from __future__ import division, print_function import os,sys sys.path.insert(0,'/Users/toby/software/G2/GSASII') PathWrap = lambda fil: os.path.join('/Users/toby/Scratch/SeqTut2019Mar',fil) import GSASIIscriptable as G2sc gpx = G2sc.G2Project(PathWrap('scr4.gpx')) seq = gpx.seqref() lbl = ('a','b','c','alpha','beta','gamma','Volume') for j,h in enumerate(seq.histograms()): cell,cellU,uniq = seq.get_cell_and_esd(1,h) print(h) print([cell[i] for i in list(uniq)+[6]]) print([cellU[i] for i in list(uniq)+[6]]) print('') print('printed',[lbl[i] for i in list(uniq)+[6]])
See also
-
RefData
(hist)[source]¶ Provides access to the output from a particular histogram
Parameters: hist – Specify a histogram or using the histogram name (str) or the index number (int) of the histogram in the sequential refinement (not the project), numbered as in the project tree starting from 0. Returns: a list of dicts where the first element has sequential refinement results and the second element has the contents of the histogram tree items.
-
get_Covariance
(hist, varList)[source]¶ Returns the values and covariance matrix for a series of variable parameters, as defined for the selected histogram in the last sequential refinement cycle
Parameters: - hist – Specify a histogram or using the histogram name (str) or the index number (int) of the histogram in the sequential refinement (not the project), numbered as in the project tree starting from 0.
- varList (tuple) – a list of variable names of form ‘<p>:<h>:<name>’
Returns: (valueList,CovMatrix) where valueList contains the (n) values in the same order as varList (also length n) and CovMatrix is a (n x n) matrix. If any variable name is not found in the varyList then None is returned.
Use this code, where sig provides standard uncertainties for parameters and where covArray provides the correlation between off-diagonal terms:
sig = np.sqrt(np.diag(covMatrix)) xvar = np.outer(sig,np.ones_like(sig)) covArray = np.divide(np.divide(covMatrix,xvar),xvar.T)
-
get_ParmList
(hist)[source]¶ Returns a list of all the parameters defined in the last refinement cycle for the selected histogram
Parameters: hist – Specify a histogram or using the histogram name (str) or the index number (int) of the histogram in the sequential refinement (not the project), numbered as in the project tree starting from 0. Returns: a list of parameters or None if no refinement has been performed.
-
get_Variable
(hist, var)[source]¶ Returns the value and standard uncertainty (esd) for a variable parameters, as defined for the selected histogram in the last sequential refinement cycle
Parameters: - hist – Specify a histogram or using the histogram name (str) or the index number (int) of the histogram in the sequential refinement (not the project), numbered as in the project tree starting from 0.
- var (str) – a variable name of form ‘<p>:<h>:<name>’, such as ‘:0:Scale’
Returns: (value,esd) if the parameter is refined or (value, None) if the variable is in a constraint or is not refined or None if the parameter is not found.
-
get_VaryList
(hist)[source]¶ Returns a list of the refined variables in the last refinement cycle for the selected histogram
Parameters: hist – Specify a histogram or using the histogram name (str) or the index number (int) of the histogram in the sequential refinement (not the project), numbered starting from 0. Returns: a list of variables or None if no refinement has been performed.
-
get_cell_and_esd
(phase, hist)[source]¶ Returns a vector of cell lengths and esd values
Parameters: - phase – A phase, which may be specified as a phase object
(see
G2Phase
), the phase name (str) or the index number (int) of the phase in the project, numbered starting from 0. - hist – Specify a histogram or using the histogram name (str) or the index number (int) of the histogram in the sequential refinement (not the project), numbered as in in the project tree starting from 0.
Returns: cell,cellESD,uniqCellIndx where cell (list) with the unit cell parameters (a,b,c,alpha,beta,gamma,Volume); cellESD are the standard uncertainties on the 7 unit cell parameters; and uniqCellIndx is a tuple with indicies for the unique (non-symmetry determined) unit parameters (e.g. [0,2] for a,c in a tetragonal cell)
- phase – A phase, which may be specified as a phase object
(see
-
-
GSASIIscriptable.
GenerateReflections
(spcGrp, cell, Qmax=None, dmin=None, TTmax=None, wave=None)[source]¶ Generates the crystallographically unique powder diffraction reflections for a lattice and space group (see
GSASIIlattice.GenHLaue()
).Parameters: - spcGrp (str) – A GSAS-II formatted space group (with spaces between
axial fields, e.g. ‘P 21 21 21’ or ‘P 42/m m c’). Note that non-standard
space groups, such as ‘P 21/n’ or ‘F -1’ are allowed (see
GSASIIspc.SpcGroup()
). - cell (list) – A list/tuple with six unit cell constants, (a, b, c, alpha, beta, gamma) with values in Angstroms/degrees. Note that the cell constants are not checked for consistency with the space group.
- Qmax (float) – Reflections up to this Q value are computed (do not use with dmin or TTmax)
- dmin (float) – Reflections with d-space above this value are computed (do not use with Qmax or TTmax)
- TTmax (float) – Reflections up to this 2-theta value are computed (do not use with dmin or Qmax, use of wave is required.)
- wave (float) – wavelength in Angstroms for use with TTmax (ignored otherwise.)
Returns: a list of reflections, where each reflection contains four items: h, k, l, d, where d is the d-space (Angstroms)
Example:
>>> import os,sys >>> sys.path.insert(0,'/Users/toby/software/G2/GSASII') >>> import GSASIIscriptable as G2sc GSAS-II binary directory: /Users/toby/software/G2/GSASII/bin 17 values read from config file /Users/toby/software/G2/GSASII/config.py >>> refs = G2sc.GenerateReflections('P 1', ... (5.,6.,7.,90.,90.,90), ... TTmax=20,wave=1) >>> for r in refs: print(r) ... [0, 0, 1, 7.0] [0, 1, 0, 6.0] [1, 0, 0, 5.0] [0, 1, 1, 4.55553961419178] [0, 1, -1, 4.55553961419178] [1, 0, 1, 4.068667356033675] [1, 0, -1, 4.068667356033674] [1, 1, 0, 3.8411063979868794] [1, -1, 0, 3.8411063979868794]
- spcGrp (str) – A GSAS-II formatted space group (with spaces between
axial fields, e.g. ‘P 21 21 21’ or ‘P 42/m m c’). Note that non-standard
space groups, such as ‘P 21/n’ or ‘F -1’ are allowed (see
-
GSASIIscriptable.
IPyBrowse
(args)[source]¶ Load a .gpx file and then open a IPython shell to browse it:
usage: GSASIIscriptable.py browse [-h] files [files ...]
positional arguments:
files list of files to browse
optional arguments:
-h, --help show this help message and exit
-
GSASIIscriptable.
LoadDictFromProjFile
(ProjFile)[source]¶ Read a GSAS-II project file and load items to dictionary
Parameters: ProjFile (str) – GSAS-II project (name.gpx) full file name Returns: Project,nameList, where - Project (dict) is a representation of gpx file following the GSAS-II tree structure for each item: key = tree name (e.g. ‘Controls’,’Restraints’,etc.), data is dict data dict = {‘data’:item data whch may be list, dict or None,’subitems’:subdata (if any)}
- nameList (list) has names of main tree entries & subentries used to reconstruct project file
Example for fap.gpx:
Project = { #NB:dict order is not tree order 'Phases':{'data':None,'fap':{phase dict}}, 'PWDR FAP.XRA Bank 1':{'data':[histogram data list],'Comments':comments,'Limits':limits, etc}, 'Rigid bodies':{'data': {rigid body dict}}, 'Covariance':{'data':{covariance data dict}}, 'Controls':{'data':{controls data dict}}, 'Notebook':{'data':[notebook list]}, 'Restraints':{'data':{restraint data dict}}, 'Constraints':{'data':{constraint data dict}}] } nameList = [ #NB: reproduces tree order ['Notebook',], ['Controls',], ['Covariance',], ['Constraints',], ['Restraints',], ['Rigid bodies',], ['PWDR FAP.XRA Bank 1', 'Comments', 'Limits', 'Background', 'Instrument Parameters', 'Sample Parameters', 'Peak List', 'Index Peak List', 'Unit Cells List', 'Reflection Lists'], ['Phases', 'fap'] ]
-
GSASIIscriptable.
LoadG2fil
()[source]¶ Setup GSAS-II importers. Delay importing this module when possible, it is slow. Multiple calls are not. Only the first does anything.
-
GSASIIscriptable.
PreSetup
(data)[source]¶ Create part of an initial (empty) phase dictionary
from GSASIIphsGUI.py, near end of UpdatePhaseData
Author: Jackson O’Donnell (jacksonhodonnell .at. gmail.com)
-
GSASIIscriptable.
Readers
= {'Image': [], 'Phase': [], 'Pwdr': []}¶ Readers by reader type
-
GSASIIscriptable.
SaveDictToProjFile
(Project, nameList, ProjFile)[source]¶ Save a GSAS-II project file from dictionary/nameList created by LoadDictFromProjFile
Parameters: - Project (dict) – representation of gpx file following the GSAS-II tree structure as described for LoadDictFromProjFile
- nameList (list) – names of main tree entries & subentries used to reconstruct project file
- ProjFile (str) – full file name for output project.gpx file (including extension)
-
GSASIIscriptable.
SetDefaultDData
(dType, histoName, NShkl=0, NDij=0)[source]¶ Create an initial Histogram dictionary
Author: Jackson O’Donnell (jacksonhodonnell .at. gmail.com)
-
GSASIIscriptable.
SetPrintLevel
(level)[source]¶ Set the level of output from calls to
GSASIIfiles.G2Print()
, which should be used in place of print() where possible. This is a wrapper forGSASIIfiles.G2SetPrintLevel()
so that this routine is documented here.Parameters: level (str) – a string used to set the print level, which may be ‘all’, ‘warn’, ‘error’ or ‘none’. Note that capitalization and extra letters in level are ignored, so ‘Warn’, ‘warnings’, etc. will all set the mode to ‘warn’
-
GSASIIscriptable.
add
(args)[source]¶ Implements the add command-line subcommand. This adds histograms and/or phases to GSAS-II project:
usage: GSASIIscriptable.py add [-h] [-d HISTOGRAMS [HISTOGRAMS ...]] [-i IPARAMS [IPARAMS ...]] [-hf HISTOGRAMFORMAT] [-p PHASES [PHASES ...]] [-pf PHASEFORMAT] [-l HISTLIST [HISTLIST ...]] filename
positional arguments:
filename the project file to open. Should end in .gpx
optional arguments:
-h, --help show this help message and exit -d HISTOGRAMS [HISTOGRAMS ...], --histograms HISTOGRAMS [HISTOGRAMS ...] list of datafiles to add as histograms -i IPARAMS [IPARAMS ...], --iparams IPARAMS [IPARAMS ...] instrument parameter file, must be one for every histogram -hf HISTOGRAMFORMAT, --histogramformat HISTOGRAMFORMAT format hint for histogram import. Applies to all histograms -p PHASES [PHASES ...], --phases PHASES [PHASES ...] list of phases to add. phases are automatically associated with all histograms given. -pf PHASEFORMAT, --phaseformat PHASEFORMAT format hint for phase import. Applies to all phases. Example: -pf CIF -l HISTLIST [HISTLIST ...], --histlist HISTLIST [HISTLIST ...] list of histgram indices to associate with added phases. If not specified, phases are associated with all previously loaded histograms. Example: -l 2 3 4
-
GSASIIscriptable.
blkSize
= 256¶ Integration block size; 256 seems to be optimal, must be <=1024 (for polymask)
-
GSASIIscriptable.
calcMaskMap
(imgprms, mskprms)[source]¶ Computes the mask array for a set of image controls and mask parameters
-
GSASIIscriptable.
calcThetaAzimMap
(imgprms)[source]¶ Computes the array for theta-azimuth mapping for a set of image controls
-
GSASIIscriptable.
create
(args)[source]¶ Implements the create command-line subcommand. This creates a GSAS-II project, optionally adding histograms and/or phases:
usage: GSASIIscriptable.py create [-h] [-d HISTOGRAMS [HISTOGRAMS ...]] [-i IPARAMS [IPARAMS ...]] [-p PHASES [PHASES ...]] filename
positional arguments:
filename the project file to create. should end in .gpx
optional arguments:
-h, --help show this help message and exit -d HISTOGRAMS [HISTOGRAMS ...], --histograms HISTOGRAMS [HISTOGRAMS ...] list of datafiles to add as histograms -i IPARAMS [IPARAMS ...], --iparams IPARAMS [IPARAMS ...] instrument parameter file, must be one for every histogram -p PHASES [PHASES ...], --phases PHASES [PHASES ...] list of phases to add. phases are automatically associated with all histograms given.
-
GSASIIscriptable.
dictDive
(d, search='', keylist=[], firstcall=True, l=None)[source]¶ Recursive routine to scan a nested dict. Reports a list of keys and the associated type and value for that key.
Parameters: - d (dict) – a dict that will be scanned
- search (str) – an optional search string. If non-blank, only entries where one of the keys constains search (case ignored)
- keylist (list) – a list of keys to apply to the dict.
- firstcall (bool) – do not specify
- l (list) – do not specify
Returns: a list of keys located by this routine in form [([keylist], type, value),…] where if keylist is [‘a’,’b’,’c’] then d[[‘a’][‘b’][‘c’] will have the value.
This routine can be called in a number of ways, as are shown in a few examples:
>>> for i in G2sc.dictDive(p.data['General'],'paw'): print(i) ... (['Pawley dmin'], <class 'float'>, 1.0) (['doPawley'], <class 'bool'>, False) (['Pawley dmax'], <class 'float'>, 100.0) (['Pawley neg wt'], <class 'float'>, 0.0) >>> >>> for i in G2sc.dictDive(p.data,'paw',['General']): print(i) ... (['General', 'Pawley dmin'], <class 'float'>, 1.0) (['General', 'doPawley'], <class 'bool'>, False) (['General', 'Pawley dmax'], <class 'float'>, 100.0) (['General', 'Pawley neg wt'], <class 'float'>, 0.0) >>> >>> for i in G2sc.dictDive(p.data,'',['General','doPawley']): print(i) ... (['General', 'doPawley'], <class 'bool'>, False)
-
GSASIIscriptable.
dump
(args)[source]¶ Implements the dump command-line subcommand, which shows the contents of a GSAS-II project:
usage: GSASIIscriptable.py dump [-h] [-d] [-p] [-r] files [files ...]
positional arguments:
files
optional arguments:
-h, --help show this help message and exit -d, --histograms list histograms in files, overrides --raw -p, --phases list phases in files, overrides --raw -r, --raw dump raw file contents, default
-
GSASIIscriptable.
export
(args)[source]¶ Implements the export command-line subcommand: Exports phase as CIF:
usage: GSASIIscriptable.py export [-h] gpxfile phase exportfile
positional arguments:
gpxfile the project file from which to export phase identifier of phase to export exportfile the .cif file to export to
optional arguments:
-h, --help show this help message and exit
-
GSASIIscriptable.
exportersByExtension
= {}¶ Specifies the list of extensions that are supported for Powder data export
-
GSASIIscriptable.
import_generic
(filename, readerlist, fmthint=None, bank=None)[source]¶ Attempt to import a filename, using a list of reader objects.
Returns the first reader object which worked.
-
GSASIIscriptable.
load_iprms
(instfile, reader, bank=None)[source]¶ Loads instrument parameters from a file, and edits the given reader.
Returns a 2-tuple of (Iparm1, Iparm2) parameters
-
GSASIIscriptable.
load_pwd_from_reader
(reader, instprm, existingnames=[], bank=None)[source]¶ Loads powder data from a reader object, and assembles it into a GSASII data tree.
Returns: (name, tree) - 2-tuple of the histogram name (str), and data Author: Jackson O’Donnell (jacksonhodonnell .at. gmail.com)
-
GSASIIscriptable.
main
()[source]¶ The command-line interface for calling GSASIIscriptable as a shell command, where it is expected to be called as:
python GSASIIscriptable.py <subcommand> <file.gpx> <options>
The following subcommands are defined:
-
GSASIIscriptable.
make_empty_project
(author=None, filename=None)[source]¶ Creates an dictionary in the style of GSASIIscriptable, for an empty project.
If no author name or filename is supplied, ‘no name’ and <current dir>/test_output.gpx are used , respectively.
Returns: project dictionary, name list
Author: Jackson O’Donnell (jacksonhodonnell .at. gmail.com)
-
GSASIIscriptable.
patchControls
(Controls)[source]¶ patch routine to convert variable names used in parameter limits to G2VarObj objects (See Parameter Limits description.)
-
GSASIIscriptable.
refine
(args)[source]¶ - Implements the refine command-line subcommand:
conducts refinements on GSAS-II projects according to a JSON refinement dict:
usage: GSASIIscriptable.py refine [-h] gpxfile [refinements]
positional arguments:
gpxfile the project file to refine refinements json file of refinements to apply. if not present refines file as-is
optional arguments:
-h, --help show this help message and exit