Changeset 4127


Ignore:
Timestamp:
Aug 31, 2019 2:57:51 PM (2 years ago)
Author:
toby
Message:

fix indent

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/GSASIIscriptable.py

    r4126 r4127  
    1     #!/usr/bin/env python
    2     # -*- coding: utf-8 -*-
    3     ########### SVN repository information ###################
    4     # $Date$
    5     # $Author$
    6     # $Revision$
    7     # $URL$
    8     # $Id$
    9     ########### SVN repository information ###################
    10     #
    11     """
    12     *GSASIIscriptable: Scripting Interface*
    13     =======================================
    14 
    15     Routines to use an increasing amount of GSAS-II's capabilities from scripts,
    16     without use of the graphical user interface (GUI). GSASIIscriptable can create and access
    17     GSAS-II project (.gpx) files and can directly perform image handling and refinements. 
    18     The module defines wrapper classes (inheriting from :class:`G2ObjectWrapper`) for a growing number
    19     of data tree items.
    20 
    21     GSASIIscriptable can be used in two ways. It offers a command-line mode
    22     (see :ref:`CommandlineInterface`) that
    23     provides access a number of features without writing Python scripts
    24     via shell/batch commands. The more powerful mode of GSASIIscriptable is
    25     use is through Python scripts that
    26     call the module's application interface (API), see API summary that follows or the :ref:`API`
    27     section.
    28 
    29     ==================================================
    30     Application Interface (API) Summary
    31     ==================================================
    32     This section of the documentation provides an overview to API, with full documentation
    33     in the :ref:`API` section. The typical API use will be with a Python script, such as this:
    34 
    35     .. code-block::  python
    36 
    37         from __future__ import division, print_function
    38         import os,sys
    39         sys.path.insert(0,'/Users/toby/software/G2/GSASII') # needed to "find" GSAS-II modules
    40         import GSASIIscriptable as G2sc
    41         datadir = "/Users/Scratch/"
    42         gpx = G2sc.G2Project(os.path.join(datadir,'test2.gpx'))
    43         gpx.histogram(0).add_back_peak(4.5,30000,5000,0)
    44         pardict = {'set': {'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
    45                            'Background': {'type': 'chebyschev', 'refine': True,
    46                                           'peaks':[[0,True]]}}}
    47         gpx.set_refinement(pardict)
    48 
    49     Most functionality is provided via the objects and methods described in this section.
    50 
    51     ---------------------
    52     Functions
    53     ---------------------
    54 
    55     A small amount of the Scriptable code does not require use of objects.
    56 
    57     ==================================================    ===============================================================================================================
    58     method                                                Use
    59     ==================================================    ===============================================================================================================
    60     :func:`GenerateReflections`                            Generates a list of unique powder reflections
    61     :func:`SetPrintLevel`                                  Sets the amout of output generated when running a script
    62     ==================================================    ===============================================================================================================
    63 
    64     ---------------------
    65     :class:`G2Project`
    66     ---------------------
    67 
    68       All GSASIIscriptable scripts will need to create a :class:`G2Project` object
    69       either for a new GSAS-II project or to read in an existing project (.gpx) file.
    70       The most commonly used routines in this object are:
    71 
    72     .. tabularcolumns:: |l|p{3.5in}|
    73 
    74     ==================================================    ===============================================================================================================
    75     method                                                Use
    76     ==================================================    ===============================================================================================================
    77     :meth:`G2Project.save`                                Writes the current project to disk.
    78 
    79     :meth:`G2Project.add_powder_histogram`                Used to read in powder diffraction data into a project file.
    80 
    81     :meth:`G2Project.add_simulated_powder_histogram`      Defines a "dummy" powder diffraction data that will be simulated after a refinement step.
    82 
    83     :meth:`G2Project.add_image`                           Reads in an image into a project.
    84 
    85     :meth:`G2Project.add_phase`                           Adds a phase to a project
    86 
    87     :meth:`G2Project.add_PDF`                             Adds a PDF entry to a project (does not compute it)
    88 
    89     :meth:`G2Project.histograms`                          Provides a list of histograms in the current project, as :class:`G2PwdrData` objects
    90 
    91     :meth:`G2Project.phases`                              Provides a list of phases defined in the current project, as :class:`G2Phase` objects
    92 
    93     :meth:`G2Project.images`                              Provides a list of images in the current project, as :class:`G2Image` objects
    94 
    95     :meth:`G2Project.pdfs`                                Provides a list of PDFs in the current project, as :class:`G2PDF` objects
    96 
    97     :meth:`G2Project.seqref`                              Returns a :class:`G2SeqRefRes` object if there are Sequential Refinement results
    98 
    99     :meth:`G2Project.do_refinements`                      This is passed a list of dictionaries, where each dict defines a refinement step.
    100                                                           Passing a list with a single empty dict initiates a refinement with the current
    101                                                           parameters and flags. A refinement dict sets up a single refinement step
    102                                                           (as described in :ref:`Project_dicts`). Also see :ref:`Refinement_recipe`.
    103 
    104     :meth:`G2Project.set_refinement`                      This is passed a single dict which is used to set parameters and flags.
    105                                                           These actions can be performed also in :meth:`G2Project.do_refinements`.
    106     :meth:`G2Project.get_Variable`                        Retrieves the value and esd for a parameter
    107     :meth:`G2Project.get_Covariance`                      Retrieves values and covariance for a set of refined parameters
    108     :meth:`G2Project.set_Controls`                        Set overall GSAS-II control settings such as number of cycles and to set up a sequential
    109                                                           fit. (Also see :meth:`G2Project.get_Controls` to read values.)
    110     ==================================================    ===============================================================================================================
    111 
    112     ---------------------
    113     :class:`G2Phase`
    114     ---------------------
    115 
    116       Another common object in GSASIIscriptable scripts is :class:`G2Phase`, used to encapsulate each phase in a project, with commonly used methods:
    117 
    118     .. tabularcolumns:: |l|p{3.5in}|
    119 
    120     ==================================================    ===============================================================================================================
    121     method                                                Use
    122     ==================================================    ===============================================================================================================
    123     :meth:`G2Phase.set_refinements`                       Provides a mechanism to set values and refinement flags for the phase. See :ref:`Phase_parameters_table`
    124                                                           for more details. This information also can be supplied within a call to :meth:`G2Project.do_refinements`
    125                                                           or :meth:`G2Project.set_refinement`.
    126     :meth:`G2Phase.clear_refinements`                     Unsets refinement flags for the phase.
    127     :meth:`G2Phase.set_HAP_refinements`                   Provides a mechanism to set values and refinement flags for parameters specific to both this phase and
    128                                                           one of its histograms. See :ref:`HAP_parameters_table`. This information also can be supplied within
    129                                                           a call to :meth:`G2Project.do_refinements` or :meth:`G2Project.set_refinement`.
    130     :meth:`G2Phase.clear_HAP_refinements`                 Clears refinement flags specific to both this phase and one of its histograms.
    131     :meth:`G2Phase.getHAPvalues`                          Returns values of parameters specific to both this phase and one of its histograms.
    132     :meth:`G2Phase.copyHAPvalues`                         Copies HAP settings between from one phase/histogram and to other histograms in same phase.
    133     :meth:`G2Phase.atoms`                                 Returns a list of atoms in the phase
    134     :meth:`G2Phase.atom`                                  Returns an atom from its label
    135     :meth:`G2Phase.histograms`                            Returns a list of histograms linked to the phase
    136     :meth:`G2Phase.get_cell`                              Returns unit cell parameters (also see :meth:`G2Phase.get_cell_and_esd`)
    137     :meth:`G2Phase.export_CIF`                            Writes a CIF for the phase
    138     ==================================================    ===============================================================================================================
    139 
    140     ---------------------
    141     :class:`G2PwdrData`
    142     ---------------------
    143 
    144       Another common object in GSASIIscriptable scripts is :class:`G2PwdrData`, which encapsulate each powder diffraction histogram in a project, with commonly used methods:
    145 
    146     .. tabularcolumns:: |l|p{3.5in}|
    147 
    148     ==================================================    ===============================================================================================================
    149     method                                                Use
    150     ==================================================    ===============================================================================================================
    151     :meth:`G2PwdrData.set_refinements`                    Provides a mechanism to set values and refinement flags for the powder histogram. See
    152                                                           :ref:`Histogram_parameters_table` for details. 
    153     :meth:`G2PwdrData.clear_refinements`                  Unsets refinement flags for the the powder histogram.
    154     :meth:`G2PwdrData.residuals`                          Reports R-factors etc. for the the powder histogram (also see :meth:`G2PwdrData.get_wR`)
    155     :meth:`G2PwdrData.add_back_peak`                      Adds a background peak to the histogram. Also see :meth:`G2PwdrData.del_back_peak` and
    156                                                           :meth:`G2PwdrData.ref_back_peak`.
    157     :meth:`G2PwdrData.fit_fixed_points`                   Fits background to the specified fixed points.
    158     :meth:`G2PwdrData.getdata`                            Provides access to the diffraction data associated with the histogram.
    159     :meth:`G2PwdrData.reflections`                        Provides access to the reflection lists for the histogram.
    160     :meth:`G2PwdrData.Export`                             Writes the diffraction data or reflection list into a file
    161     :meth:`G2PwdrData.add_peak`                           Adds a peak to the peak list. Also see :ref:`PeakRefine`.
    162     :meth:`G2PwdrData.set_peakFlags`                      Sets refinement flags for peaks
    163     :meth:`G2PwdrData.refine_peaks`                       Starts a peak/background fitting cycle
    164     :attr:`G2PwdrData.Peaks`                              Provides access to the peak list data structure
    165     :attr:`G2PwdrData.PeakList`                           Provides the peak list parameter values
    166     :meth:`G2PwdrData.Export_peaks`                       Writes the peak parameters to a text file
    167     ==================================================    ===============================================================================================================
    168 
    169     ---------------------
    170     :class:`G2Image`
    171     ---------------------
    172 
    173       When working with images, there will be a :class:`G2Image` object for each image (also see :meth:`G2Project.add_image`  and :meth:`G2Project.images`).
    174 
    175     .. tabularcolumns:: |l|p{3.5in}|
    176 
    177     ==================================================    ===============================================================================================================
    178     method                                                Use
    179     ==================================================    ===============================================================================================================
    180     :meth:`G2Image.Recalibrate`                           Invokes a recalibration fit starting from the current Image Controls calibration coefficients.
    181     :meth:`G2Image.Integrate`                             Invokes an image integration All parameters Image Controls will have previously been set.
    182     :meth:`G2Image.setControl`                            Set an Image Controls parameter in the current image.
    183     :meth:`G2Image.getControl`                            Return an Image Controls parameter in the current image.
    184     :meth:`G2Image.findControl`                           Get the names of Image Controls parameters.
    185     :meth:`G2Image.loadControls`                          Load controls from a .imctrl file (also see :meth:`G2Image.saveControls`).
    186     :meth:`G2Image.loadMasks`                             Load masks from a .immask file.
    187     :meth:`G2Image.setVary`                               Set a refinement flag for Image Controls parameter in the current image. (Also see :meth:`G2Image.getVary`)
    188     :meth:`G2Image.setCalibrant`                          Set a calibrant type (or show choices) for the current image.
    189     :meth:`G2Image.setControlFile`                        Set a image to be used as a background/dark/gain map image.
    190     ==================================================    ===============================================================================================================
    191 
    192 
    193     ---------------------
    194     :class:`G2PDF`
    195     ---------------------
    196 
    197       To work with PDF entries, object :class:`G2PDF`, encapsulates a PDF entry with methods:
    198 
    199     .. tabularcolumns:: |l|p{3.5in}|
    200 
    201     ==================================================    ===============================================================================================================
    202     method                                                Use
    203     ==================================================    ===============================================================================================================
    204     :meth:`G2PDF.export`                                   Used to write G(r), etc. as a file
    205     :meth:`G2PDF.calculate`                                Computes the PDF using parameters in the object
    206     :meth:`G2PDF.optimize`                                 Optimizes selected PDF parameters
    207     :meth:`G2PDF.set_background`                           Sets the histograms used for sample background, container, etc.
    208     :meth:`G2PDF.set_formula`                              Sets the chemical formula for the sample
    209     ==================================================    ===============================================================================================================
    210 
    211     ---------------------
    212     :class:`G2SeqRefRes`
    213     ---------------------
    214 
    215       To work with Sequential Refinement results, object :class:`G2SeqRefRes`, encapsulates the sequential refinement table with methods:
    216 
    217     .. tabularcolumns:: |l|p{3.5in}|
    218 
    219     ==================================================    ===============================================================================================================
    220     method                                                Use
    221     ==================================================    ===============================================================================================================
    222     :meth:`G2SeqRefRes.histograms`                         Provides a list of histograms used in the Sequential Refinement
    223     :meth:`G2SeqRefRes.get_cell_and_esd`                   Returns cell dimensions and standard uncertainies for a phase and histogram from the Sequential Refinement
    224     :meth:`G2SeqRefRes.get_Variable`                       Retrieves the value and esd for a parameter from a particular histogram in the Sequential Refinement
    225     :meth:`G2SeqRefRes.get_Covariance`                     Retrieves values and covariance for a set of refined parameters for a particular histogram
    226     ==================================================    ===============================================================================================================
    227 
    228     ----------------------
    229     :class:`G2AtomRecord`
    230     ----------------------
    231 
    232       When working with phases, :class:`G2AtomRecord` objects provide access to the contents of each atom in a phase. This provides access to "properties" that can be
    233       used to get values of much of the atoms associated settings: label, type, refinement_flags, coordinates, occupancy, ranId, adp_flag, and uiso. In addition,
    234       refinement_flags, occupancy and uiso can be used to set values. See the :class:`G2AtomRecord` docs and source code.
    235 
    236     .. _Refinement_dicts:
    237 
    238     =====================
    239     Refinement parameters
    240     =====================
    241     While scripts can be written that setup refinements by changing individual parameters
    242     through calls to the methods associated with objects that wrap each data tree item,
    243     many of these actions can be combined into fairly complex dict structures to conduct refinement
    244     steps. Use of these dicts is required with the :ref:`CommandlineInterface`. This section of the
    245     documentation describes these dicts.
    246 
    247     .. _Project_dicts:
    248 
    249     -----------------------------
    250     Project-level Parameter Dict
    251     -----------------------------
    252 
    253     As noted below (:ref:`Refinement_parameters_kinds`), there are three types of refinement parameters,
    254     which can be accessed individually by the objects that encapsulate individual phases and histograms
    255     but it will often be simplest to create a composite dictionary
    256     that is used at the project-level. A dict is created with keys
    257     "set" and "clear" that can be supplied to :meth:`G2Project.set_refinement`
    258     (or :meth:`G2Project.do_refinements`, see :ref:`Refinement_recipe` below) that will
    259     determine parameter values and will determine which parameters will be refined.
    260 
    261     The specific keys and subkeys that can be used are defined in tables
    262     :ref:`Histogram_parameters_table`, :ref:`Phase_parameters_table` and :ref:`HAP_parameters_table`.
    263 
    264     Note that optionally a list of histograms and/or phases can be supplied in the call to
    265     :meth:`G2Project.set_refinement`, but if not specified, the default is to use all defined
    266     phases and histograms.
    267 
    268     As an example:
    269 
    270     .. code-block::  python
    271 
    272         pardict = {'set': { 'Limits': [0.8, 12.0],
    273                            'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
    274                            'Background': {'type': 'chebyschev', 'refine': True,
    275                                           'peaks':[[0,True],[1,1,1]] }},
    276                   'clear': {'Instrument Parameters': ['U', 'V', 'W']}}
    277         my_project.set_refinement(pardict)
    278 
    279     .. _Refinement_recipe:
    280 
    281     ------------------------
    282     Refinement recipe
    283     ------------------------
    284     Building on the :ref:`Project_dicts`,
    285     it is possible to specify a sequence of refinement actions as a list of
    286     these dicts and supplying this list
    287     as an argument to :meth:`G2Project.do_refinements`.
    288 
    289     As an example, this code performs the same actions as in the example in the section above:
    290 
    291     .. code-block::  python
    292 
    293         pardict = {'set': { 'Limits': [0.8, 12.0],
    294                            'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
    295                            'Background': {'type': 'chebyschev', 'refine': True}},
    296                   'clear': {'Instrument Parameters': ['U', 'V', 'W']}}
    297         my_project.do_refinements([pardict])
    298 
    299     However, in addition to setting a number of parameters, this example will perform a refinement as well,
    300     after setting the parameters. More than one refinement can be performed by including more
    301     than one dict in the list.
    302 
    303     In this example, two refinement steps will be performed:
    304 
    305     .. code-block::  python
    306 
    307         my_project.do_refinements([pardict,pardict1])
    308 
    309 
    310     The keys defined in the following table
    311     may be used in a dict supplied to :meth:`G2Project.do_refinements`. Note that keys ``histograms``
    312     and ``phases`` are used to limit actions to specific sets of parameters within the project.
    313 
    314     ========== ============================================================================
    315     key         explanation
    316     ========== ============================================================================
    317     set                    Specifies a dict with keys and subkeys as described in the
    318                            :ref:`Refinement_parameters_fmt` section. Items listed here
    319                            will be set to be refined.
    320     clear                  Specifies a dict, as above for set, except that parameters are
    321                            cleared and thus will not be refined.
    322     once                   Specifies a dict as above for set, except that parameters are
    323                            set for the next cycle of refinement and are cleared once the
    324                            refinement step is completed.
    325     skip                   Normally, once parameters are processed with a set/clear/once
    326                            action(s), a refinement is started. If skip is defined as True
    327                            (or any other value) the refinement step is not performed.
    328     output                 If a file name is specified for output is will be used to save
    329                            the current refinement.
    330     histograms             Should contain a list of histogram(s) to be used for the
    331                            set/clear/once action(s) on :ref:`Histogram_parameters_table` or
    332                            :ref:`HAP_parameters_table`. Note that this will be
    333                            ignored for :ref:`Phase_parameters_table`. Histograms may be
    334                            specified as a list of strings [('PWDR ...'),...], indices
    335                            [0,1,2] or as list of objects [hist1, hist2].
    336     phases                 Should contain a list of phase(s) to be used for the
    337                            set/clear/once action(s) on :ref:`Phase_parameters_table` or
    338                            :ref:`HAP_parameters_table`. Note that this will be
    339                            ignored for :ref:`Histogram_parameters_table`.
    340                            Phases may be specified as a list of strings
    341                            [('Phase name'),...], indices [0,1,2] or as list of objects
    342                            [phase0, phase2].
    343     call                   Specifies a function to call after a refinement is completed.
    344                            The value supplied can be the object (typically a function)
    345                            that will be called or a string that will evaluate (in the
    346                            namespace inside :meth:`G2Project.iter_refinements` where
    347                            ``self`` references the project.)
    348                            Nothing is called if this is not specified.
    349     callargs               Provides a list of arguments that will be passed to the function
    350                            in call (if any). If call is defined and callargs is not, the
    351                            current <tt>G2Project</tt> is passed as a single argument.
    352     ========== ============================================================================
    353 
    354     An example that performs a series of refinement steps follows:
    355 
    356     .. code-block::  python
    357 
    358         reflist = [
    359                 {"set": { "Limits": { "low": 0.7 },
    360                           "Background": { "no. coeffs": 3,
    361                                           "refine": True }}},
    362                 {"set": { "LeBail": True,
    363                           "Cell": True }},
    364                 {"set": { "Sample Parameters": ["DisplaceX"]}},
    365                 {"set": { "Instrument Parameters": ["U", "V", "W", "X", "Y"]}},
    366                 {"set": { "Mustrain": { "type": "uniaxial",
    367                                         "refine": "equatorial",
    368                                         "direction": [0, 0, 1]}}},
    369                 {"set": { "Mustrain": { "type": "uniaxial",
    370                                         "refine": "axial"}}},
    371                 {"clear": { "LeBail": True},
    372                  "set": { "Atoms": { "Mn": "X" }}},
    373                 {"set": { "Atoms": { "O1": "X", "O2": "X" }}},]
    374         my_project.do_refinements(reflist)
    375 
    376 
    377     In this example, a separate refinement step will be performed for each dict in the list. The keyword
    378     "skip" can be used to specify a dict that should not include a refinement.
    379     Note that in the second from last refinement step, parameters are both set and cleared.
    380 
    381     .. _Refinement_parameters_kinds:
    382 
    383     ----------------------------
    384     Refinement parameter types
    385     ----------------------------
    386 
    387     Note that parameters and refinement flags used in GSAS-II fall into three classes:
    388 
    389         * **Histogram**: There will be a set of these for each dataset loaded into a
    390           project file. The parameters available depend on the type of histogram
    391           (Bragg-Brentano, Single-Crystal, TOF,...). Typical Histogram parameters
    392           include the overall scale factor, background, instrument and sample parameters;
    393           see the :ref:`Histogram_parameters_table` table for a list of the histogram
    394           parameters where access has been provided.
    395 
    396         * **Phase**: There will be a set of these for each phase loaded into a
    397           project file. While some parameters are found in all types of phases,
    398           others are only found in certain types (modulated, magnetic, protein...).
    399           Typical phase parameters include unit cell lengths and atomic positions; see the
    400           :ref:`Phase_parameters_table` table for a list of the phase     
    401           parameters where access has been provided.
    402 
    403         * **Histogram-and-phase** (HAP): There is a set of these for every histogram
    404           that is associated with each phase, so that if there are ``N`` phases and ``M``
    405           histograms, there can be ``N*M`` total sets of "HAP" parameters sets (fewer if all
    406           histograms are not linked to all phases.) Typical HAP parameters include the
    407           phase fractions, sample microstrain and crystallite size broadening terms,
    408           hydrostatic strain perturbations of the unit cell and preferred orientation
    409           values.
    410           See the :ref:`HAP_parameters_table` table for the HAP parameters where access has
    411           been provided.
    412 
    413     .. _Refinement_parameters_fmt:
    414 
    415     =================================
    416     Specifying Refinement Parameters
    417     =================================
    418 
    419     Refinement parameter values and flags to turn refinement on and off are specified within dictionaries,
    420     where the details of these dicts are organized depends on the
    421     type of parameter (see :ref:`Refinement_parameters_kinds`), with a different set
    422     of keys (as described below) for each of the three types of parameters.
    423 
    424     .. _Histogram_parameters_table:
    425 
    426     --------------------
    427     Histogram parameters
    428     --------------------
    429 
    430     This table describes the dictionaries supplied to :func:`G2PwdrData.set_refinements`
    431     and :func:`G2PwdrData.clear_refinements`. As an example,
    432 
    433     .. code-block::  python
    434 
    435        hist.set_refinements({"Background": {"no.coeffs": 3, "refine": True},
    436                              "Sample Parameters": ["Scale"],
    437                              "Limits": [10000, 40000]})
    438 
    439     With :meth:`G2Project.do_refinements`, these parameters should be placed inside a dict with a key
    440     ``set``, ``clear``, or ``once``. Values will be set for all histograms, unless the ``histograms``
    441     key is used to define specific histograms. As an example:
    442 
    443     .. code-block::  python
    444 
    445       gsas_proj.do_refinements([
    446           {'set': {
    447               'Background': {'no.coeffs': 3, 'refine': True},
    448               'Sample Parameters': ['Scale'],
    449               'Limits': [10000, 40000]},
    450           'histograms': [1,2]}
    451                                 ])
    452 
    453     Note that below in the Instrument Parameters section,
    454     related profile parameters (such as U and V) are grouped together but
    455     separated by commas to save space in the table.
    456 
    457     .. tabularcolumns:: |l|l|p{3.5in}|
    458 
    459     ===================== ====================  =================================================
    460     key                   subkey                explanation
    461     ===================== ====================  =================================================
    462     Limits                                      The range of 2-theta (degrees) or TOF (in
    463                                                 microsec) range of values to use. Can
    464                                                 be either a dictionary of 'low' and/or 'high',
    465                                                 or a list of 2 items [low, high]
    466     \                     low                   Sets the low limit
    467     \                     high                  Sets the high limit
    468 
    469     Sample Parameters                           Should be provided as a **list** of subkeys
    470                                                 to set or clear, e.g. ['DisplaceX', 'Scale']
    471     \                     Absorption
    472     \                     Contrast
    473     \                     DisplaceX             Sample displacement along the X direction
    474     \                     DisplaceY             Sample displacement along the Y direction
    475     \                     Scale                 Histogram Scale factor
    476 
    477     Background                                  Sample background. Value will be a dict or
    478                                                 a boolean. If True or False, the refine
    479                                                 parameter for background is set to that.
    480                                                 Note that background peaks are not handled
    481                                                 via this; see
    482                                                 :meth:`G2PwdrData.ref_back_peak` instead.
    483                                                 When value is a dict,
    484                                                 supply any of the following keys:
    485     \                     type                  The background model, e.g. 'chebyschev'
    486     \                     refine                The value of the refine flag, boolean
    487     \                     no. coeffs            Number of coefficients to use, integer
    488     \                     coeffs                List of floats, literal values for background
    489     \                     FixedPoints           List of (2-theta, intensity) values for fixed points
    490     \                     fit fixed points      If True, triggers a fit to the fixed points to
    491                                                 be calculated. It is calculated when this key is
    492                                                 detected, regardless of calls to refine.
    493                           peaks                 Specifies a set of flags for refining
    494                                                 background peaks as a nested list. There may
    495                                                 be an item for each defined background peak
    496                                                 (or fewer) and each item is a list with the flag
    497                                                 values for pos,int,sig & gam (fewer than 4 values
    498                                                 are allowed).
    499 
    500     Instrument Parameters                       As in Sample Paramters, provide as a **list** of
    501                                                 subkeys to
    502                                                 set or clear, e.g. ['X', 'Y', 'Zero', 'SH/L']
    503     \                     U, V, W               Gaussian peak profile terms
    504     \                     X, Y, Z               Lorentzian peak profile terms
    505     \                     alpha, beta-0,        TOF profile terms
    506                           beta-1, beta-q,
    507     \                     sig-0, sig-1,         TOF profile terms
    508                           sig-2, sig-q
    509     \                     difA, difB, difC      TOF Calibration constants
    510     \                     Zero                  Zero shift
    511     \                     SH/L                  Finger-Cox-Jephcoat low-angle peak asymmetry
    512     \                     Polariz.              Polarization parameter
    513     \                     Lam                   Lambda, the incident wavelength
    514     ===================== ====================  =================================================
    515 
    516     .. _Phase_parameters_table:
    517 
    518     ----------------
    519     Phase parameters
    520     ----------------
    521 
    522     This table describes the dictionaries supplied to :func:`G2Phase.set_refinements`
    523     and :func:`G2Phase.clear_refinements`. With :meth:`G2Project.do_refinements`,
    524     these parameters should be placed inside a dict with a key
    525     ``set``, ``clear``, or ``once``. Values will be set for all phases, unless the ``phases``
    526     key is used to define specific phase(s).
    527 
    528 
    529     .. tabularcolumns:: |l|p{4.5in}|
    530 
    531     ======= ==========================================================
    532     key                   explanation
    533     ======= ==========================================================
    534     Cell                  Whether or not to refine the unit cell.
    535     Atoms                 Dictionary of atoms and refinement flags.
    536                           Each key should be an atom label, e.g.
    537                           'O3', 'Mn5', and each value should be
    538                           a string defining what values to refine.
    539                           Values can be any combination of 'F'
    540                           for fractional occupancy, 'X' for position,
    541                           and 'U' for Debye-Waller factor
    542     LeBail                Enables LeBail intensity extraction.
    543     ======= ==========================================================
    544 
    545 
    546     .. _HAP_parameters_table:
    547 
    548 
    549     Histogram-and-phase parameters
    550     ------------------------------
    551 
    552     This table describes the dictionaries supplied to :func:`G2Phase.set_HAP_refinements`
    553     and :func:`G2Phase.clear_HAP_refinements`. When supplied to
    554     :meth:`G2Project.do_refinements`, these parameters should be placed inside a dict with a key
    555     ``set``, ``clear``, or ``once``. Values will be set for all histograms used in each phase,
    556     unless the ``histograms`` and ``phases`` keys are used to define specific phases and histograms.
    557 
    558     .. tabularcolumns:: |l|l|p{3.5in}|
    559 
    560     =============  ==========  ============================================================
    561     key             subkey                 explanation
    562     =============  ==========  ============================================================
    563     Babinet                                Should be a **list** of the following
    564                                            subkeys. If not, assumes both
    565                                            BabA and BabU
    566     \               BabA
    567     \               BabU
    568     Extinction                             Boolean, True to refine.
    569     HStrain                                Boolean or list/tuple, True to refine all
    570                                            appropriate D\ :sub:`ij` terms or False
    571                                            to not refine any. If a list/tuple, will
    572                                            be a set of True & False values for each
    573                                            D\ :sub:`ij` term; number of items must
    574                                            match number of terms.
    575     Mustrain
    576     \               type                   Mustrain model. One of 'isotropic',
    577                                            'uniaxial', or 'generalized'. **Should always
    578                                            be included when Mustrain is used.**
    579     \              direction               For uniaxial only. A list of three
    580                                            integers,
    581                                            the [hkl] direction of the axis.
    582     \               refine                 Usually boolean, set to True to refine.
    583                                            or False to clear.
    584                                            For uniaxial model, can specify a value
    585                                            of 'axial' or 'equatorial' to set that flag
    586                                            to True or a single
    587                                            boolean sets both axial and equatorial.
    588     Size                                   
    589     \               type                   Size broadening model. One of 'isotropic',
    590                                            'uniaxial', or 'ellipsoid'. **Should always
    591                                            be specified when Size is used.**
    592     \              direction               For uniaxial only. A list of three
    593                                            integers,
    594                                            the [hkl] direction of the axis.
    595     \               refine                 Boolean, True to refine.
    596     \               value                  float, size value in microns
    597     Pref.Ori.                              Boolean, True to refine
    598     Show                                   Boolean, True to refine
    599     Use                                    Boolean, True to refine
    600     Scale                                  Phase fraction; Boolean, True to refine
    601     =============  ==========  ============================================================
    602 
    603     ------------------------
    604     Histogram/Phase objects
    605     ------------------------
    606     Each phase and powder histogram in a :class:`G2Project` object has an associated
    607     object. Parameters within each individual object can be turned on and off by calling
    608     :meth:`G2PwdrData.set_refinements` or :meth:`G2PwdrData.clear_refinements`
    609     for histogram parameters;
    610     :meth:`G2Phase.set_refinements` or :meth:`G2Phase.clear_refinements`
    611     for phase parameters; and :meth:`G2Phase.set_HAP_refinements` or
    612     :meth:`G2Phase.clear_HAP_refinements`. As an example, if some_histogram is a histogram object (of type :class:`G2PwdrData`), use this to set parameters in that histogram:
    613 
    614     .. code-block::  python
    615 
    616         params = { 'Limits': [0.8, 12.0],
    617                    'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
    618                    'Background': {'type': 'chebyschev', 'refine': True}}
    619         some_histogram.set_refinements(params)
    620 
    621     Likewise to turn refinement flags on, use code such as this:
    622 
    623     .. code-block::  python
    624 
    625         params = { 'Instrument Parameters': ['U', 'V', 'W']}
    626         some_histogram.set_refinements(params)
    627 
    628     and to turn these refinement flags, off use this (Note that the
    629     ``.clear_refinements()`` methods will usually will turn off refinement even
    630     if a refinement parameter is set in the dict to True.):
    631 
    632     .. code-block::  python
    633 
    634         params = { 'Instrument Parameters': ['U', 'V', 'W']}
    635         some_histogram.clear_refinements(params)
    636 
    637     For phase parameters, use code such as this:
    638 
    639     .. code-block::  python
    640 
    641         params = { 'LeBail': True, 'Cell': True,
    642                    'Atoms': { 'Mn1': 'X',
    643                               'O3': 'XU',
    644                               'V4': 'FXU'}}
    645         some_histogram.set_refinements(params)
    646 
    647 
    648     and here is an example for HAP parameters:
    649 
    650     .. code-block::  python
    651 
    652         params = { 'Babinet': 'BabA',
    653                    'Extinction': True,
    654                    'Mustrain': { 'type': 'uniaxial',
    655                                  'direction': [0, 0, 1],
    656                                  'refine': True}}
    657         some_phase.set_HAP_refinements(params)
    658 
    659     Note that the parameters must match the object type and method (phase vs. histogram vs. HAP).
    660 
    661     =================================
    662     Code Examples
    663     =================================
    664 
    665     .. _PeakRefine:
    666 
    667     --------------------
    668     Peak Fitting
    669     --------------------
    670 
    671     Peak refinement is performed with routines
    672     :meth:`G2PwdrData.add_peak`, :meth:`G2PwdrData.set_peakFlags` and
    673     :meth:`G2PwdrData.refine_peaks`. Method :meth:`G2PwdrData.Export_peaks` and
    674     properties :attr:`G2PwdrData.Peaks` and :attr:`G2PwdrData.PeakList`
    675     provide ways to access the results. Note that when peak parameters are
    676     refined with :meth:`~G2PwdrData.refine_peaks`, the background may also
    677     be refined. Use :meth:`G2PwdrData.set_refinements` to change background
    678     settings and the range of data used in the fit. See below for an example
    679     peak refinement script, where the data files are taken from the
    680     "Rietveld refinement with CuKa lab Bragg-Brentano powder data" tutorial
    681     (in https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/LabData/data/).
    682 
    683     .. code-block::  python
    684 
    685         from __future__ import division, print_function
    686         import os,sys
    687         sys.path.insert(0,'/Users/toby/software/G2/GSASII') # needed to "find" GSAS-II modules
    688         import GSASIIscriptable as G2sc
    689         datadir = os.path.expanduser("~/Scratch/peakfit")
    690         PathWrap = lambda fil: os.path.join(datadir,fil)
    691         gpx = G2sc.G2Project(newgpx=PathWrap('pkfit.gpx'))
    692         hist = gpx.add_powder_histogram(PathWrap('FAP.XRA'), PathWrap('INST_XRY.PRM'),
    693                                         fmthint='GSAS powder')
    694         hist.set_refinements({'Limits': [16.,24.],
    695               'Background': {"no. coeffs": 2,'type': 'chebyschev', 'refine': True}
    696                              })
    697         peak1 = hist.add_peak(1, ttheta=16.8)
    698         peak2 = hist.add_peak(1, ttheta=18.9)
    699         peak3 = hist.add_peak(1, ttheta=21.8)
    700         peak4 = hist.add_peak(1, ttheta=22.9)
    701         hist.set_peakFlags(area=True)
    702         hist.refine_peaks()
    703         hist.set_peakFlags(area=True,pos=True)
    704         hist.refine_peaks()
    705         hist.set_peakFlags(area=True, pos=True, sig=True, gam=True)
    706         hist.refine_peaks()
    707         print('peak positions: ',[i[0] for i in hist.PeakList])
    708         for i in range(len(hist.Peaks['peaks'])):
    709             print('peak',i,'pos=',hist.Peaks['peaks'][i][0],'sig=',hist.Peaks['sigDict']['pos'+str(i)])
    710         hist.Export_peaks('pkfit.txt')
    711         #gpx.save()  # gpx file is not written without this
    712 
    713     --------------------
    714     Pattern Simulation
    715     --------------------
    716 
    717     This shows an example where a structure is read from a CIF, a
    718     pattern is computed using a instrument parameter file to specify the
    719     probe type (neutrons here) and wavelength.
    720     The pattern and reflection list are computed.
    721     Data files are found
    722     `here <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/PythonScript/data/>`.
    723 
    724     .. code-block::  python
    725 
    726         import os,sys
    727         sys.path.insert(0,'/Users/toby/software/G2/GSASII')
    728         import GSASIIscriptable as G2sc
    729         datadir = "/Users/toby/software/G2/Tutorials/PythonScript/data"
    730         PathWrap = lambda fil: os.path.join(datadir,fil)
    731         gpx = G2sc.G2Project(filename='PbSO4sim.gpx') # create a project
    732         # add a phase to the project
    733         phase0 = gpx.add_phase(PathWrap("PbSO4-Wyckoff.cif"),
    734                  phasename="PbSO4",fmthint='CIF')
    735         # add a simulated histogram and link it to the previous phase(s)
    736         hist1 = gpx.add_simulated_powder_histogram("PbSO4 simulation",
    737                     PathWrap("inst_d1a.prm"),5.,120.,0.01,
    738                     phases=gpx.phases())
    739         # Set the scale factor to adjust the y scale
    740         hist1.SampleParameters['Scale'][0] = 1000000.
    741         # parameter optimization and calculate pattern
    742         gpx.data['Controls']['data']['max cyc'] = 0 # refinement not needed
    743         gpx.do_refinements([{}])
    744         gpx.save()
    745         # save results
    746         gpx.histogram(0).Export('PbSO4data','.csv','hist') # data
    747         gpx.histogram(0).Export('PbSO4refl','.csv','refl') # reflections
    748 
    749     ----------------------
    750     Sequential Refinement
    751     ----------------------
    752 
    753     GSASIIscriptable can be used to setup and perform sequential refinements. This example script
    754     is used to take the single-dataset fit at the end of Step 1 of the
    755     `Sequential Refinement tutorial <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/SeqRefine/SequentialTutorial.htm>`
    756     and turn on and off refinement flags, add histograms and setup the sequential fit, which is then run:
    757 
    758     .. code-block::  python
    759 
    760         import os,sys,glob
    761         sys.path.insert(0,'/Users/toby/software/G2/GSASII')
    762         import GSASIIscriptable as G2sc
    763         datadir = os.path.expanduser("~/Scratch/SeqTut2019Mar")
    764         PathWrap = lambda fil: os.path.join(datadir,fil)
    765         # load and rename project
    766         gpx = G2sc.G2Project(PathWrap('7Konly.gpx'))
    767         gpx.save(PathWrap('SeqRef.gpx'))
    768         # turn off some variables; turn on Dijs
    769         for p in gpx.phases():
    770             p.set_refinements({"Cell": False})
    771         gpx.phase(0).set_HAP_refinements(
    772             {'Scale': False,
    773              "Size": {'type':'isotropic', 'refine': False},
    774              "Mustrain": {'type':'uniaxial', 'refine': False},
    775              "HStrain":True,})
    776         gpx.phase(1).set_HAP_refinements({'Scale': False})
    777         gpx.histogram(0).clear_refinements({'Background':False,
    778                          'Sample Parameters':['DisplaceX'],})
    779         gpx.histogram(0).ref_back_peak(0,[])
    780         gpx.phase(1).set_HAP_refinements({"HStrain":(1,1,1,0)})
    781         for fil in sorted(glob.glob(PathWrap('*.fxye'))): # load in remaining fxye files
    782             if '00' in fil: continue
    783             gpx.add_powder_histogram(fil, PathWrap('OH_00.prm'), fmthint="GSAS powder",phases='all')
    784         # copy HAP values, background, instrument params. & limits, not sample params.
    785         gpx.copyHistParms(0,'all',['b','i','l'])
    786         for p in gpx.phases(): p.copyHAPvalues(0,'all')
    787         # setup and launch sequential fit
    788         gpx.set_Controls('sequential',gpx.histograms())
    789         gpx.set_Controls('cycles',10)
    790         gpx.set_Controls('seqCopy',True)
    791         gpx.refine() 
    792 
    793     ----------------------
    794     Image Processing
    795     ----------------------
    796 
    797     A sample script where an image is read, assigned calibration values from a file
    798     and then integrated follows.
    799     The data files are found
    800     `here <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/PythonScript/data/>`.
    801 
    802     .. code-block::  python
    803 
    804         import os,sys
    805         sys.path.insert(0,'/Users/toby/software/G2/GSASII')
    806         import GSASIIscriptable as G2sc
    807         datadir = "/tmp"
    808         PathWrap = lambda fil: os.path.join(datadir,fil)
    809 
    810         gpx = G2sc.G2Project(filename=PathWrap('inttest.gpx'))
    811         imlst = gpx.add_image(PathWrap('Si_free_dc800_1-00000.tif'),fmthint="TIF")
    812         imlst[0].loadControls(PathWrap('Si_free_dc800_1-00000.imctrl'))
    813         pwdrList = imlst[0].Integrate()
    814         gpx.save()
    815 
    816     This example shows a computation similar to what is done in tutorial
    817     `Area Detector Calibration with Multiple Distances <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/DeterminingWavelength/DeterminingWavelength.html>`
    818 
    819     .. code-block::  python
    820 
    821         import os,sys,glob
    822         sys.path.insert(0,'/Users/toby/software/G2/GSASII')
    823         import GSASIIscriptable as G2sc
    824         PathWrap = lambda fil: os.path.join(
    825             "/Users/toby/wp/Active/MultidistanceCalibration/multimg",
    826             fil)
    827 
    828         gpx = G2sc.G2Project(filename='/tmp/img.gpx')
    829         for f in glob.glob(PathWrap('*.tif')):
    830             im = gpx.add_image(f,fmthint="TIF")
    831         # image parameter settings
    832         defImgVals = {'wavelength': 0.24152, 'center': [206., 205.],
    833           'pixLimit': 2,  'cutoff': 5.0, 'DetDepth': 0.055,'calibdmin': 1.,}
    834         # set controls and vary options, then fit
    835         for img in gpx.images():
    836             img.setCalibrant('Si    SRM640c')
    837             img.setVary('*',False)
    838             img.setVary(['det-X', 'det-Y', 'phi', 'tilt', 'wave'], True)
    839             img.setControls(defImgVals)
    840             img.Recalibrate()
    841             img.Recalibrate() # 2nd run better insures convergence
    842         gpx.save()
    843         # make dict of images for sorting
    844         images = {img.getControl('setdist'):img for img in gpx.images()}
    845         # show values
    846         for key in sorted(images.keys()):
    847             img = images[key]
    848             c = img.getControls()
    849             print(c['distance'],c['wavelength'])
    850 
    851     This example performs a number of cycles of constrained fitting.
    852     A project is created with the images found in a directory, setting initial
    853     parameters as the images are read. The initial values
    854     for the calibration are not very good, so a :meth:`G2Image.recalibrate` is done
    855     to quickly improve the fit. Once that is done, a fit of all images is performed
    856     where the wavelength, an offset and detector orientation are constrained to
    857     be the same for all images. The detector penetration correction is then added.
    858     Note that as the calibration values improve, the algorithm is able to find more
    859     points on diffraction rings to use for calibration and the number of "ring picks"
    860     increase. The calibration is repeated until that stops increasing significantly (<10%).
    861     Detector control files are then created.
    862     The files used for this exercise are found
    863     `here <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/DeterminingWavelength/data/>`
    864     (the
    865     `Area Detector Calibration with Multiple Distances <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/DeterminingWavelength/DeterminingWavelength.html>`
    866     tutorial).
     1#!/usr/bin/env python
     2# -*- coding: utf-8 -*-
     3########### SVN repository information ###################
     4# $Date$
     5# $Author$
     6# $Revision$
     7# $URL$
     8# $Id$
     9########### SVN repository information ###################
     10#
     11"""
     12*GSASIIscriptable: Scripting Interface*
     13=======================================
     14
     15Routines to use an increasing amount of GSAS-II's capabilities from scripts,
     16without use of the graphical user interface (GUI). GSASIIscriptable can create and access
     17GSAS-II project (.gpx) files and can directly perform image handling and refinements. 
     18The module defines wrapper classes (inheriting from :class:`G2ObjectWrapper`) for a growing number
     19of data tree items.
     20
     21GSASIIscriptable can be used in two ways. It offers a command-line mode
     22(see :ref:`CommandlineInterface`) that
     23provides access a number of features without writing Python scripts
     24via shell/batch commands. The more powerful mode of GSASIIscriptable is
     25use is through Python scripts that
     26call the module's application interface (API), see API summary that follows or the :ref:`API`
     27section.
     28
     29==================================================
     30Application Interface (API) Summary
     31==================================================
     32This section of the documentation provides an overview to API, with full documentation
     33in the :ref:`API` section. The typical API use will be with a Python script, such as this:
     34
     35.. code-block::  python
     36
     37    from __future__ import division, print_function
     38    import os,sys
     39    sys.path.insert(0,'/Users/toby/software/G2/GSASII') # needed to "find" GSAS-II modules
     40    import GSASIIscriptable as G2sc
     41    datadir = "/Users/Scratch/"
     42    gpx = G2sc.G2Project(os.path.join(datadir,'test2.gpx'))
     43    gpx.histogram(0).add_back_peak(4.5,30000,5000,0)
     44    pardict = {'set': {'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
     45                       'Background': {'type': 'chebyschev', 'refine': True,
     46                                      'peaks':[[0,True]]}}}
     47    gpx.set_refinement(pardict)
     48
     49Most functionality is provided via the objects and methods described in this section.
     50
     51---------------------
     52Functions
     53---------------------
     54
     55A small amount of the Scriptable code does not require use of objects.
     56
     57==================================================    ===============================================================================================================
     58method                                                Use
     59==================================================    ===============================================================================================================
     60:func:`GenerateReflections`                            Generates a list of unique powder reflections
     61:func:`SetPrintLevel`                                  Sets the amout of output generated when running a script
     62==================================================    ===============================================================================================================
     63
     64---------------------
     65:class:`G2Project`
     66---------------------
     67
     68  All GSASIIscriptable scripts will need to create a :class:`G2Project` object
     69  either for a new GSAS-II project or to read in an existing project (.gpx) file.
     70  The most commonly used routines in this object are:
     71
     72.. tabularcolumns:: |l|p{3.5in}|
     73
     74==================================================    ===============================================================================================================
     75method                                                Use
     76==================================================    ===============================================================================================================
     77:meth:`G2Project.save`                                Writes the current project to disk.
     78
     79:meth:`G2Project.add_powder_histogram`                Used to read in powder diffraction data into a project file.
     80
     81:meth:`G2Project.add_simulated_powder_histogram`      Defines a "dummy" powder diffraction data that will be simulated after a refinement step.
     82
     83:meth:`G2Project.add_image`                           Reads in an image into a project.
     84
     85:meth:`G2Project.add_phase`                           Adds a phase to a project
     86
     87:meth:`G2Project.add_PDF`                             Adds a PDF entry to a project (does not compute it)
     88
     89:meth:`G2Project.histograms`                          Provides a list of histograms in the current project, as :class:`G2PwdrData` objects
     90
     91:meth:`G2Project.phases`                              Provides a list of phases defined in the current project, as :class:`G2Phase` objects
     92
     93:meth:`G2Project.images`                              Provides a list of images in the current project, as :class:`G2Image` objects
     94
     95:meth:`G2Project.pdfs`                                Provides a list of PDFs in the current project, as :class:`G2PDF` objects
     96
     97:meth:`G2Project.seqref`                              Returns a :class:`G2SeqRefRes` object if there are Sequential Refinement results
     98
     99:meth:`G2Project.do_refinements`                      This is passed a list of dictionaries, where each dict defines a refinement step.
     100                                                      Passing a list with a single empty dict initiates a refinement with the current
     101                                                      parameters and flags. A refinement dict sets up a single refinement step
     102                                                      (as described in :ref:`Project_dicts`). Also see :ref:`Refinement_recipe`.
     103
     104:meth:`G2Project.set_refinement`                      This is passed a single dict which is used to set parameters and flags.
     105                                                      These actions can be performed also in :meth:`G2Project.do_refinements`.
     106:meth:`G2Project.get_Variable`                        Retrieves the value and esd for a parameter
     107:meth:`G2Project.get_Covariance`                      Retrieves values and covariance for a set of refined parameters
     108:meth:`G2Project.set_Controls`                        Set overall GSAS-II control settings such as number of cycles and to set up a sequential
     109                                                      fit. (Also see :meth:`G2Project.get_Controls` to read values.)
     110==================================================    ===============================================================================================================
     111
     112---------------------
     113:class:`G2Phase`
     114---------------------
     115
     116  Another common object in GSASIIscriptable scripts is :class:`G2Phase`, used to encapsulate each phase in a project, with commonly used methods:
     117
     118.. tabularcolumns:: |l|p{3.5in}|
     119
     120==================================================    ===============================================================================================================
     121method                                                Use
     122==================================================    ===============================================================================================================
     123:meth:`G2Phase.set_refinements`                       Provides a mechanism to set values and refinement flags for the phase. See :ref:`Phase_parameters_table`
     124                                                      for more details. This information also can be supplied within a call to :meth:`G2Project.do_refinements`
     125                                                      or :meth:`G2Project.set_refinement`.
     126:meth:`G2Phase.clear_refinements`                     Unsets refinement flags for the phase.
     127:meth:`G2Phase.set_HAP_refinements`                   Provides a mechanism to set values and refinement flags for parameters specific to both this phase and
     128                                                      one of its histograms. See :ref:`HAP_parameters_table`. This information also can be supplied within
     129                                                      a call to :meth:`G2Project.do_refinements` or :meth:`G2Project.set_refinement`.
     130:meth:`G2Phase.clear_HAP_refinements`                 Clears refinement flags specific to both this phase and one of its histograms.
     131:meth:`G2Phase.getHAPvalues`                          Returns values of parameters specific to both this phase and one of its histograms.
     132:meth:`G2Phase.copyHAPvalues`                         Copies HAP settings between from one phase/histogram and to other histograms in same phase.
     133:meth:`G2Phase.atoms`                                 Returns a list of atoms in the phase
     134:meth:`G2Phase.atom`                                  Returns an atom from its label
     135:meth:`G2Phase.histograms`                            Returns a list of histograms linked to the phase
     136:meth:`G2Phase.get_cell`                              Returns unit cell parameters (also see :meth:`G2Phase.get_cell_and_esd`)
     137:meth:`G2Phase.export_CIF`                            Writes a CIF for the phase
     138==================================================    ===============================================================================================================
     139
     140---------------------
     141:class:`G2PwdrData`
     142---------------------
     143
     144  Another common object in GSASIIscriptable scripts is :class:`G2PwdrData`, which encapsulate each powder diffraction histogram in a project, with commonly used methods:
     145
     146.. tabularcolumns:: |l|p{3.5in}|
     147
     148==================================================    ===============================================================================================================
     149method                                                Use
     150==================================================    ===============================================================================================================
     151:meth:`G2PwdrData.set_refinements`                    Provides a mechanism to set values and refinement flags for the powder histogram. See
     152                                                      :ref:`Histogram_parameters_table` for details. 
     153:meth:`G2PwdrData.clear_refinements`                  Unsets refinement flags for the the powder histogram.
     154:meth:`G2PwdrData.residuals`                          Reports R-factors etc. for the the powder histogram (also see :meth:`G2PwdrData.get_wR`)
     155:meth:`G2PwdrData.add_back_peak`                      Adds a background peak to the histogram. Also see :meth:`G2PwdrData.del_back_peak` and
     156                                                      :meth:`G2PwdrData.ref_back_peak`.
     157:meth:`G2PwdrData.fit_fixed_points`                   Fits background to the specified fixed points.
     158:meth:`G2PwdrData.getdata`                            Provides access to the diffraction data associated with the histogram.
     159:meth:`G2PwdrData.reflections`                        Provides access to the reflection lists for the histogram.
     160:meth:`G2PwdrData.Export`                             Writes the diffraction data or reflection list into a file
     161:meth:`G2PwdrData.add_peak`                           Adds a peak to the peak list. Also see :ref:`PeakRefine`.
     162:meth:`G2PwdrData.set_peakFlags`                      Sets refinement flags for peaks
     163:meth:`G2PwdrData.refine_peaks`                       Starts a peak/background fitting cycle
     164:attr:`G2PwdrData.Peaks`                              Provides access to the peak list data structure
     165:attr:`G2PwdrData.PeakList`                           Provides the peak list parameter values
     166:meth:`G2PwdrData.Export_peaks`                       Writes the peak parameters to a text file
     167==================================================    ===============================================================================================================
     168
     169---------------------
     170:class:`G2Image`
     171---------------------
     172
     173  When working with images, there will be a :class:`G2Image` object for each image (also see :meth:`G2Project.add_image`  and :meth:`G2Project.images`).
     174
     175.. tabularcolumns:: |l|p{3.5in}|
     176
     177==================================================    ===============================================================================================================
     178method                                                Use
     179==================================================    ===============================================================================================================
     180:meth:`G2Image.Recalibrate`                           Invokes a recalibration fit starting from the current Image Controls calibration coefficients.
     181:meth:`G2Image.Integrate`                             Invokes an image integration All parameters Image Controls will have previously been set.
     182:meth:`G2Image.setControl`                            Set an Image Controls parameter in the current image.
     183:meth:`G2Image.getControl`                            Return an Image Controls parameter in the current image.
     184:meth:`G2Image.findControl`                           Get the names of Image Controls parameters.
     185:meth:`G2Image.loadControls`                          Load controls from a .imctrl file (also see :meth:`G2Image.saveControls`).
     186:meth:`G2Image.loadMasks`                             Load masks from a .immask file.
     187:meth:`G2Image.setVary`                               Set a refinement flag for Image Controls parameter in the current image. (Also see :meth:`G2Image.getVary`)
     188:meth:`G2Image.setCalibrant`                          Set a calibrant type (or show choices) for the current image.
     189:meth:`G2Image.setControlFile`                        Set a image to be used as a background/dark/gain map image.
     190==================================================    ===============================================================================================================
     191
     192
     193---------------------
     194:class:`G2PDF`
     195---------------------
     196
     197  To work with PDF entries, object :class:`G2PDF`, encapsulates a PDF entry with methods:
     198
     199.. tabularcolumns:: |l|p{3.5in}|
     200
     201==================================================    ===============================================================================================================
     202method                                                Use
     203==================================================    ===============================================================================================================
     204:meth:`G2PDF.export`                                   Used to write G(r), etc. as a file
     205:meth:`G2PDF.calculate`                                Computes the PDF using parameters in the object
     206:meth:`G2PDF.optimize`                                 Optimizes selected PDF parameters
     207:meth:`G2PDF.set_background`                           Sets the histograms used for sample background, container, etc.
     208:meth:`G2PDF.set_formula`                              Sets the chemical formula for the sample
     209==================================================    ===============================================================================================================
     210
     211---------------------
     212:class:`G2SeqRefRes`
     213---------------------
     214
     215  To work with Sequential Refinement results, object :class:`G2SeqRefRes`, encapsulates the sequential refinement table with methods:
     216
     217.. tabularcolumns:: |l|p{3.5in}|
     218
     219==================================================    ===============================================================================================================
     220method                                                Use
     221==================================================    ===============================================================================================================
     222:meth:`G2SeqRefRes.histograms`                         Provides a list of histograms used in the Sequential Refinement
     223:meth:`G2SeqRefRes.get_cell_and_esd`                   Returns cell dimensions and standard uncertainies for a phase and histogram from the Sequential Refinement
     224:meth:`G2SeqRefRes.get_Variable`                       Retrieves the value and esd for a parameter from a particular histogram in the Sequential Refinement
     225:meth:`G2SeqRefRes.get_Covariance`                     Retrieves values and covariance for a set of refined parameters for a particular histogram
     226==================================================    ===============================================================================================================
     227
     228----------------------
     229:class:`G2AtomRecord`
     230----------------------
     231
     232  When working with phases, :class:`G2AtomRecord` objects provide access to the contents of each atom in a phase. This provides access to "properties" that can be
     233  used to get values of much of the atoms associated settings: label, type, refinement_flags, coordinates, occupancy, ranId, adp_flag, and uiso. In addition,
     234  refinement_flags, occupancy and uiso can be used to set values. See the :class:`G2AtomRecord` docs and source code.
     235
     236.. _Refinement_dicts:
     237
     238=====================
     239Refinement parameters
     240=====================
     241While scripts can be written that setup refinements by changing individual parameters
     242through calls to the methods associated with objects that wrap each data tree item,
     243many of these actions can be combined into fairly complex dict structures to conduct refinement
     244steps. Use of these dicts is required with the :ref:`CommandlineInterface`. This section of the
     245documentation describes these dicts.
     246
     247.. _Project_dicts:
     248
     249-----------------------------
     250Project-level Parameter Dict
     251-----------------------------
     252
     253As noted below (:ref:`Refinement_parameters_kinds`), there are three types of refinement parameters,
     254which can be accessed individually by the objects that encapsulate individual phases and histograms
     255but it will often be simplest to create a composite dictionary
     256that is used at the project-level. A dict is created with keys
     257"set" and "clear" that can be supplied to :meth:`G2Project.set_refinement`
     258(or :meth:`G2Project.do_refinements`, see :ref:`Refinement_recipe` below) that will
     259determine parameter values and will determine which parameters will be refined.
     260
     261The specific keys and subkeys that can be used are defined in tables
     262:ref:`Histogram_parameters_table`, :ref:`Phase_parameters_table` and :ref:`HAP_parameters_table`.
     263
     264Note that optionally a list of histograms and/or phases can be supplied in the call to
     265:meth:`G2Project.set_refinement`, but if not specified, the default is to use all defined
     266phases and histograms.
     267
     268As an example:
     269
     270.. code-block::  python
     271
     272    pardict = {'set': { 'Limits': [0.8, 12.0],
     273                       'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
     274                       'Background': {'type': 'chebyschev', 'refine': True,
     275                                      'peaks':[[0,True],[1,1,1]] }},
     276              'clear': {'Instrument Parameters': ['U', 'V', 'W']}}
     277    my_project.set_refinement(pardict)
     278
     279.. _Refinement_recipe:
     280
     281------------------------
     282Refinement recipe
     283------------------------
     284Building on the :ref:`Project_dicts`,
     285it is possible to specify a sequence of refinement actions as a list of
     286these dicts and supplying this list
     287as an argument to :meth:`G2Project.do_refinements`.
     288
     289As an example, this code performs the same actions as in the example in the section above:
     290
     291.. code-block::  python
     292
     293    pardict = {'set': { 'Limits': [0.8, 12.0],
     294                       'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
     295                       'Background': {'type': 'chebyschev', 'refine': True}},
     296              'clear': {'Instrument Parameters': ['U', 'V', 'W']}}
     297    my_project.do_refinements([pardict])
     298
     299However, in addition to setting a number of parameters, this example will perform a refinement as well,
     300after setting the parameters. More than one refinement can be performed by including more
     301than one dict in the list.
     302
     303In this example, two refinement steps will be performed:
     304
     305.. code-block::  python
     306
     307    my_project.do_refinements([pardict,pardict1])
     308
     309
     310The keys defined in the following table
     311may be used in a dict supplied to :meth:`G2Project.do_refinements`. Note that keys ``histograms``
     312and ``phases`` are used to limit actions to specific sets of parameters within the project.
     313
     314========== ============================================================================
     315key         explanation
     316========== ============================================================================
     317set                    Specifies a dict with keys and subkeys as described in the
     318                       :ref:`Refinement_parameters_fmt` section. Items listed here
     319                       will be set to be refined.
     320clear                  Specifies a dict, as above for set, except that parameters are
     321                       cleared and thus will not be refined.
     322once                   Specifies a dict as above for set, except that parameters are
     323                       set for the next cycle of refinement and are cleared once the
     324                       refinement step is completed.
     325skip                   Normally, once parameters are processed with a set/clear/once
     326                       action(s), a refinement is started. If skip is defined as True
     327                       (or any other value) the refinement step is not performed.
     328output                 If a file name is specified for output is will be used to save
     329                       the current refinement.
     330histograms             Should contain a list of histogram(s) to be used for the
     331                       set/clear/once action(s) on :ref:`Histogram_parameters_table` or
     332                       :ref:`HAP_parameters_table`. Note that this will be
     333                       ignored for :ref:`Phase_parameters_table`. Histograms may be
     334                       specified as a list of strings [('PWDR ...'),...], indices
     335                       [0,1,2] or as list of objects [hist1, hist2].
     336phases                 Should contain a list of phase(s) to be used for the
     337                       set/clear/once action(s) on :ref:`Phase_parameters_table` or
     338                       :ref:`HAP_parameters_table`. Note that this will be
     339                       ignored for :ref:`Histogram_parameters_table`.
     340                       Phases may be specified as a list of strings
     341                       [('Phase name'),...], indices [0,1,2] or as list of objects
     342                       [phase0, phase2].
     343call                   Specifies a function to call after a refinement is completed.
     344                       The value supplied can be the object (typically a function)
     345                       that will be called or a string that will evaluate (in the
     346                       namespace inside :meth:`G2Project.iter_refinements` where
     347                       ``self`` references the project.)
     348                       Nothing is called if this is not specified.
     349callargs               Provides a list of arguments that will be passed to the function
     350                       in call (if any). If call is defined and callargs is not, the
     351                       current <tt>G2Project</tt> is passed as a single argument.
     352========== ============================================================================
     353
     354An example that performs a series of refinement steps follows:
     355
     356.. code-block::  python
     357
     358    reflist = [
     359            {"set": { "Limits": { "low": 0.7 },
     360                      "Background": { "no. coeffs": 3,
     361                                      "refine": True }}},
     362            {"set": { "LeBail": True,
     363                      "Cell": True }},
     364            {"set": { "Sample Parameters": ["DisplaceX"]}},
     365            {"set": { "Instrument Parameters": ["U", "V", "W", "X", "Y"]}},
     366            {"set": { "Mustrain": { "type": "uniaxial",
     367                                    "refine": "equatorial",
     368                                    "direction": [0, 0, 1]}}},
     369            {"set": { "Mustrain": { "type": "uniaxial",
     370                                    "refine": "axial"}}},
     371            {"clear": { "LeBail": True},
     372             "set": { "Atoms": { "Mn": "X" }}},
     373            {"set": { "Atoms": { "O1": "X", "O2": "X" }}},]
     374    my_project.do_refinements(reflist)
     375
     376
     377In this example, a separate refinement step will be performed for each dict in the list. The keyword
     378"skip" can be used to specify a dict that should not include a refinement.
     379Note that in the second from last refinement step, parameters are both set and cleared.
     380
     381.. _Refinement_parameters_kinds:
     382
     383----------------------------
     384Refinement parameter types
     385----------------------------
     386
     387Note that parameters and refinement flags used in GSAS-II fall into three classes:
     388
     389    * **Histogram**: There will be a set of these for each dataset loaded into a
     390      project file. The parameters available depend on the type of histogram
     391      (Bragg-Brentano, Single-Crystal, TOF,...). Typical Histogram parameters
     392      include the overall scale factor, background, instrument and sample parameters;
     393      see the :ref:`Histogram_parameters_table` table for a list of the histogram
     394      parameters where access has been provided.
     395
     396    * **Phase**: There will be a set of these for each phase loaded into a
     397      project file. While some parameters are found in all types of phases,
     398      others are only found in certain types (modulated, magnetic, protein...).
     399      Typical phase parameters include unit cell lengths and atomic positions; see the
     400      :ref:`Phase_parameters_table` table for a list of the phase     
     401      parameters where access has been provided.
     402
     403    * **Histogram-and-phase** (HAP): There is a set of these for every histogram
     404      that is associated with each phase, so that if there are ``N`` phases and ``M``
     405      histograms, there can be ``N*M`` total sets of "HAP" parameters sets (fewer if all
     406      histograms are not linked to all phases.) Typical HAP parameters include the
     407      phase fractions, sample microstrain and crystallite size broadening terms,
     408      hydrostatic strain perturbations of the unit cell and preferred orientation
     409      values.
     410      See the :ref:`HAP_parameters_table` table for the HAP parameters where access has
     411      been provided.
     412
     413.. _Refinement_parameters_fmt:
     414
     415=================================
     416Specifying Refinement Parameters
     417=================================
     418
     419Refinement parameter values and flags to turn refinement on and off are specified within dictionaries,
     420where the details of these dicts are organized depends on the
     421type of parameter (see :ref:`Refinement_parameters_kinds`), with a different set
     422of keys (as described below) for each of the three types of parameters.
     423
     424.. _Histogram_parameters_table:
     425
     426--------------------
     427Histogram parameters
     428--------------------
     429
     430This table describes the dictionaries supplied to :func:`G2PwdrData.set_refinements`
     431and :func:`G2PwdrData.clear_refinements`. As an example,
     432
     433.. code-block::  python
     434
     435   hist.set_refinements({"Background": {"no.coeffs": 3, "refine": True},
     436                         "Sample Parameters": ["Scale"],
     437                         "Limits": [10000, 40000]})
     438
     439With :meth:`G2Project.do_refinements`, these parameters should be placed inside a dict with a key
     440``set``, ``clear``, or ``once``. Values will be set for all histograms, unless the ``histograms``
     441key is used to define specific histograms. As an example:
     442
     443.. code-block::  python
     444
     445  gsas_proj.do_refinements([
     446      {'set': {
     447          'Background': {'no.coeffs': 3, 'refine': True},
     448          'Sample Parameters': ['Scale'],
     449          'Limits': [10000, 40000]},
     450      'histograms': [1,2]}
     451                            ])
     452
     453Note that below in the Instrument Parameters section,
     454related profile parameters (such as U and V) are grouped together but
     455separated by commas to save space in the table.
     456
     457.. tabularcolumns:: |l|l|p{3.5in}|
     458
     459===================== ====================  =================================================
     460key                   subkey                explanation
     461===================== ====================  =================================================
     462Limits                                      The range of 2-theta (degrees) or TOF (in
     463                                            microsec) range of values to use. Can
     464                                            be either a dictionary of 'low' and/or 'high',
     465                                            or a list of 2 items [low, high]
     466\                     low                   Sets the low limit
     467\                     high                  Sets the high limit
     468
     469Sample Parameters                           Should be provided as a **list** of subkeys
     470                                            to set or clear, e.g. ['DisplaceX', 'Scale']
     471\                     Absorption
     472\                     Contrast
     473\                     DisplaceX             Sample displacement along the X direction
     474\                     DisplaceY             Sample displacement along the Y direction
     475\                     Scale                 Histogram Scale factor
     476
     477Background                                  Sample background. Value will be a dict or
     478                                            a boolean. If True or False, the refine
     479                                            parameter for background is set to that.
     480                                            Note that background peaks are not handled
     481                                            via this; see
     482                                            :meth:`G2PwdrData.ref_back_peak` instead.
     483                                            When value is a dict,
     484                                            supply any of the following keys:
     485\                     type                  The background model, e.g. 'chebyschev'
     486\                     refine                The value of the refine flag, boolean
     487\                     no. coeffs            Number of coefficients to use, integer
     488\                     coeffs                List of floats, literal values for background
     489\                     FixedPoints           List of (2-theta, intensity) values for fixed points
     490\                     fit fixed points      If True, triggers a fit to the fixed points to
     491                                            be calculated. It is calculated when this key is
     492                                            detected, regardless of calls to refine.
     493                      peaks                 Specifies a set of flags for refining
     494                                            background peaks as a nested list. There may
     495                                            be an item for each defined background peak
     496                                            (or fewer) and each item is a list with the flag
     497                                            values for pos,int,sig & gam (fewer than 4 values
     498                                            are allowed).
     499
     500Instrument Parameters                       As in Sample Paramters, provide as a **list** of
     501                                            subkeys to
     502                                            set or clear, e.g. ['X', 'Y', 'Zero', 'SH/L']
     503\                     U, V, W               Gaussian peak profile terms
     504\                     X, Y, Z               Lorentzian peak profile terms
     505\                     alpha, beta-0,        TOF profile terms
     506                      beta-1, beta-q,
     507\                     sig-0, sig-1,         TOF profile terms
     508                      sig-2, sig-q
     509\                     difA, difB, difC      TOF Calibration constants
     510\                     Zero                  Zero shift
     511\                     SH/L                  Finger-Cox-Jephcoat low-angle peak asymmetry
     512\                     Polariz.              Polarization parameter
     513\                     Lam                   Lambda, the incident wavelength
     514===================== ====================  =================================================
     515
     516.. _Phase_parameters_table:
     517
     518----------------
     519Phase parameters
     520----------------
     521
     522This table describes the dictionaries supplied to :func:`G2Phase.set_refinements`
     523and :func:`G2Phase.clear_refinements`. With :meth:`G2Project.do_refinements`,
     524these parameters should be placed inside a dict with a key
     525``set``, ``clear``, or ``once``. Values will be set for all phases, unless the ``phases``
     526key is used to define specific phase(s).
     527
     528
     529.. tabularcolumns:: |l|p{4.5in}|
     530
     531======= ==========================================================
     532key                   explanation
     533======= ==========================================================
     534Cell                  Whether or not to refine the unit cell.
     535Atoms                 Dictionary of atoms and refinement flags.
     536                      Each key should be an atom label, e.g.
     537                      'O3', 'Mn5', and each value should be
     538                      a string defining what values to refine.
     539                      Values can be any combination of 'F'
     540                      for fractional occupancy, 'X' for position,
     541                      and 'U' for Debye-Waller factor
     542LeBail                Enables LeBail intensity extraction.
     543======= ==========================================================
     544
     545
     546.. _HAP_parameters_table:
     547
     548
     549Histogram-and-phase parameters
     550------------------------------
     551
     552This table describes the dictionaries supplied to :func:`G2Phase.set_HAP_refinements`
     553and :func:`G2Phase.clear_HAP_refinements`. When supplied to
     554:meth:`G2Project.do_refinements`, these parameters should be placed inside a dict with a key
     555``set``, ``clear``, or ``once``. Values will be set for all histograms used in each phase,
     556unless the ``histograms`` and ``phases`` keys are used to define specific phases and histograms.
     557
     558.. tabularcolumns:: |l|l|p{3.5in}|
     559
     560=============  ==========  ============================================================
     561key             subkey                 explanation
     562=============  ==========  ============================================================
     563Babinet                                Should be a **list** of the following
     564                                       subkeys. If not, assumes both
     565                                       BabA and BabU
     566\               BabA
     567\               BabU
     568Extinction                             Boolean, True to refine.
     569HStrain                                Boolean or list/tuple, True to refine all
     570                                       appropriate D\ :sub:`ij` terms or False
     571                                       to not refine any. If a list/tuple, will
     572                                       be a set of True & False values for each
     573                                       D\ :sub:`ij` term; number of items must
     574                                       match number of terms.
     575Mustrain
     576\               type                   Mustrain model. One of 'isotropic',
     577                                       'uniaxial', or 'generalized'. **Should always
     578                                       be included when Mustrain is used.**
     579\              direction               For uniaxial only. A list of three
     580                                       integers,
     581                                       the [hkl] direction of the axis.
     582\               refine                 Usually boolean, set to True to refine.
     583                                       or False to clear.
     584                                       For uniaxial model, can specify a value
     585                                       of 'axial' or 'equatorial' to set that flag
     586                                       to True or a single
     587                                       boolean sets both axial and equatorial.
     588Size                                   
     589\               type                   Size broadening model. One of 'isotropic',
     590                                       'uniaxial', or 'ellipsoid'. **Should always
     591                                       be specified when Size is used.**
     592\              direction               For uniaxial only. A list of three
     593                                       integers,
     594                                       the [hkl] direction of the axis.
     595\               refine                 Boolean, True to refine.
     596\               value                  float, size value in microns
     597Pref.Ori.                              Boolean, True to refine
     598Show                                   Boolean, True to refine
     599Use                                    Boolean, True to refine
     600Scale                                  Phase fraction; Boolean, True to refine
     601=============  ==========  ============================================================
     602
     603------------------------
     604Histogram/Phase objects
     605------------------------
     606Each phase and powder histogram in a :class:`G2Project` object has an associated
     607object. Parameters within each individual object can be turned on and off by calling
     608:meth:`G2PwdrData.set_refinements` or :meth:`G2PwdrData.clear_refinements`
     609for histogram parameters;
     610:meth:`G2Phase.set_refinements` or :meth:`G2Phase.clear_refinements`
     611for phase parameters; and :meth:`G2Phase.set_HAP_refinements` or
     612:meth:`G2Phase.clear_HAP_refinements`. As an example, if some_histogram is a histogram object (of type :class:`G2PwdrData`), use this to set parameters in that histogram:
     613
     614.. code-block::  python
     615
     616    params = { 'Limits': [0.8, 12.0],
     617               'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
     618               'Background': {'type': 'chebyschev', 'refine': True}}
     619    some_histogram.set_refinements(params)
     620
     621Likewise to turn refinement flags on, use code such as this:
     622
     623.. code-block::  python
     624
     625    params = { 'Instrument Parameters': ['U', 'V', 'W']}
     626    some_histogram.set_refinements(params)
     627
     628and to turn these refinement flags, off use this (Note that the
     629``.clear_refinements()`` methods will usually will turn off refinement even
     630if a refinement parameter is set in the dict to True.):
     631
     632.. code-block::  python
     633
     634    params = { 'Instrument Parameters': ['U', 'V', 'W']}
     635    some_histogram.clear_refinements(params)
     636
     637For phase parameters, use code such as this:
     638
     639.. code-block::  python
     640
     641    params = { 'LeBail': True, 'Cell': True,
     642               'Atoms': { 'Mn1': 'X',
     643                          'O3': 'XU',
     644                          'V4': 'FXU'}}
     645    some_histogram.set_refinements(params)
     646
     647
     648and here is an example for HAP parameters:
     649
     650.. code-block::  python
     651
     652    params = { 'Babinet': 'BabA',
     653               'Extinction': True,
     654               'Mustrain': { 'type': 'uniaxial',
     655                             'direction': [0, 0, 1],
     656                             'refine': True}}
     657    some_phase.set_HAP_refinements(params)
     658
     659Note that the parameters must match the object type and method (phase vs. histogram vs. HAP).
     660
     661=================================
     662Code Examples
     663=================================
     664
     665.. _PeakRefine:
     666
     667--------------------
     668Peak Fitting
     669--------------------
     670
     671Peak refinement is performed with routines
     672:meth:`G2PwdrData.add_peak`, :meth:`G2PwdrData.set_peakFlags` and
     673:meth:`G2PwdrData.refine_peaks`. Method :meth:`G2PwdrData.Export_peaks` and
     674properties :attr:`G2PwdrData.Peaks` and :attr:`G2PwdrData.PeakList`
     675provide ways to access the results. Note that when peak parameters are
     676refined with :meth:`~G2PwdrData.refine_peaks`, the background may also
     677be refined. Use :meth:`G2PwdrData.set_refinements` to change background
     678settings and the range of data used in the fit. See below for an example
     679peak refinement script, where the data files are taken from the
     680"Rietveld refinement with CuKa lab Bragg-Brentano powder data" tutorial
     681(in https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/LabData/data/).
     682
     683.. code-block::  python
     684
     685    from __future__ import division, print_function
     686    import os,sys
     687    sys.path.insert(0,'/Users/toby/software/G2/GSASII') # needed to "find" GSAS-II modules
     688    import GSASIIscriptable as G2sc
     689    datadir = os.path.expanduser("~/Scratch/peakfit")
     690    PathWrap = lambda fil: os.path.join(datadir,fil)
     691    gpx = G2sc.G2Project(newgpx=PathWrap('pkfit.gpx'))
     692    hist = gpx.add_powder_histogram(PathWrap('FAP.XRA'), PathWrap('INST_XRY.PRM'),
     693                                    fmthint='GSAS powder')
     694    hist.set_refinements({'Limits': [16.,24.],
     695          'Background': {"no. coeffs": 2,'type': 'chebyschev', 'refine': True}
     696                         })
     697    peak1 = hist.add_peak(1, ttheta=16.8)
     698    peak2 = hist.add_peak(1, ttheta=18.9)
     699    peak3 = hist.add_peak(1, ttheta=21.8)
     700    peak4 = hist.add_peak(1, ttheta=22.9)
     701    hist.set_peakFlags(area=True)
     702    hist.refine_peaks()
     703    hist.set_peakFlags(area=True,pos=True)
     704    hist.refine_peaks()
     705    hist.set_peakFlags(area=True, pos=True, sig=True, gam=True)
     706    hist.refine_peaks()
     707    print('peak positions: ',[i[0] for i in hist.PeakList])
     708    for i in range(len(hist.Peaks['peaks'])):
     709        print('peak',i,'pos=',hist.Peaks['peaks'][i][0],'sig=',hist.Peaks['sigDict']['pos'+str(i)])
     710    hist.Export_peaks('pkfit.txt')
     711    #gpx.save()  # gpx file is not written without this
     712
     713--------------------
     714Pattern Simulation
     715--------------------
     716
     717This shows an example where a structure is read from a CIF, a
     718pattern is computed using a instrument parameter file to specify the
     719probe type (neutrons here) and wavelength.
     720The pattern and reflection list are computed.
     721Data files are found
     722`here <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/PythonScript/data/>`.
     723
     724.. code-block::  python
     725
     726    import os,sys
     727    sys.path.insert(0,'/Users/toby/software/G2/GSASII')
     728    import GSASIIscriptable as G2sc
     729    datadir = "/Users/toby/software/G2/Tutorials/PythonScript/data"
     730    PathWrap = lambda fil: os.path.join(datadir,fil)
     731    gpx = G2sc.G2Project(filename='PbSO4sim.gpx') # create a project
     732    # add a phase to the project
     733    phase0 = gpx.add_phase(PathWrap("PbSO4-Wyckoff.cif"),
     734             phasename="PbSO4",fmthint='CIF')
     735    # add a simulated histogram and link it to the previous phase(s)
     736    hist1 = gpx.add_simulated_powder_histogram("PbSO4 simulation",
     737                PathWrap("inst_d1a.prm"),5.,120.,0.01,
     738                phases=gpx.phases())
     739    # Set the scale factor to adjust the y scale
     740    hist1.SampleParameters['Scale'][0] = 1000000.
     741    # parameter optimization and calculate pattern
     742    gpx.data['Controls']['data']['max cyc'] = 0 # refinement not needed
     743    gpx.do_refinements([{}])
     744    gpx.save()
     745    # save results
     746    gpx.histogram(0).Export('PbSO4data','.csv','hist') # data
     747    gpx.histogram(0).Export('PbSO4refl','.csv','refl') # reflections
     748
     749----------------------
     750Sequential Refinement
     751----------------------
     752
     753GSASIIscriptable can be used to setup and perform sequential refinements. This example script
     754is used to take the single-dataset fit at the end of Step 1 of the
     755`Sequential Refinement tutorial <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/SeqRefine/SequentialTutorial.htm>`
     756and turn on and off refinement flags, add histograms and setup the sequential fit, which is then run:
     757
     758.. code-block::  python
     759
     760    import os,sys,glob
     761    sys.path.insert(0,'/Users/toby/software/G2/GSASII')
     762    import GSASIIscriptable as G2sc
     763    datadir = os.path.expanduser("~/Scratch/SeqTut2019Mar")
     764    PathWrap = lambda fil: os.path.join(datadir,fil)
     765    # load and rename project
     766    gpx = G2sc.G2Project(PathWrap('7Konly.gpx'))
     767    gpx.save(PathWrap('SeqRef.gpx'))
     768    # turn off some variables; turn on Dijs
     769    for p in gpx.phases():
     770        p.set_refinements({"Cell": False})
     771    gpx.phase(0).set_HAP_refinements(
     772        {'Scale': False,
     773         "Size": {'type':'isotropic', 'refine': False},
     774         "Mustrain": {'type':'uniaxial', 'refine': False},
     775         "HStrain":True,})
     776    gpx.phase(1).set_HAP_refinements({'Scale': False})
     777    gpx.histogram(0).clear_refinements({'Background':False,
     778                     'Sample Parameters':['DisplaceX'],})
     779    gpx.histogram(0).ref_back_peak(0,[])
     780    gpx.phase(1).set_HAP_refinements({"HStrain":(1,1,1,0)})
     781    for fil in sorted(glob.glob(PathWrap('*.fxye'))): # load in remaining fxye files
     782        if '00' in fil: continue
     783        gpx.add_powder_histogram(fil, PathWrap('OH_00.prm'), fmthint="GSAS powder",phases='all')
     784    # copy HAP values, background, instrument params. & limits, not sample params.
     785    gpx.copyHistParms(0,'all',['b','i','l'])
     786    for p in gpx.phases(): p.copyHAPvalues(0,'all')
     787    # setup and launch sequential fit
     788    gpx.set_Controls('sequential',gpx.histograms())
     789    gpx.set_Controls('cycles',10)
     790    gpx.set_Controls('seqCopy',True)
     791    gpx.refine() 
     792
     793----------------------
     794Image Processing
     795----------------------
     796
     797A sample script where an image is read, assigned calibration values from a file
     798and then integrated follows.
     799The data files are found
     800`here <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/PythonScript/data/>`.
     801
     802.. code-block::  python
     803
     804    import os,sys
     805    sys.path.insert(0,'/Users/toby/software/G2/GSASII')
     806    import GSASIIscriptable as G2sc
     807    datadir = "/tmp"
     808    PathWrap = lambda fil: os.path.join(datadir,fil)
     809
     810    gpx = G2sc.G2Project(filename=PathWrap('inttest.gpx'))
     811    imlst = gpx.add_image(PathWrap('Si_free_dc800_1-00000.tif'),fmthint="TIF")
     812    imlst[0].loadControls(PathWrap('Si_free_dc800_1-00000.imctrl'))
     813    pwdrList = imlst[0].Integrate()
     814    gpx.save()
     815
     816This example shows a computation similar to what is done in tutorial
     817`Area Detector Calibration with Multiple Distances <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/DeterminingWavelength/DeterminingWavelength.html>`
     818
     819.. code-block::  python
     820
     821    import os,sys,glob
     822    sys.path.insert(0,'/Users/toby/software/G2/GSASII')
     823    import GSASIIscriptable as G2sc
     824    PathWrap = lambda fil: os.path.join(
     825        "/Users/toby/wp/Active/MultidistanceCalibration/multimg",
     826        fil)
     827
     828    gpx = G2sc.G2Project(filename='/tmp/img.gpx')
     829    for f in glob.glob(PathWrap('*.tif')):
     830        im = gpx.add_image(f,fmthint="TIF")
     831    # image parameter settings
     832    defImgVals = {'wavelength': 0.24152, 'center': [206., 205.],
     833      'pixLimit': 2,  'cutoff': 5.0, 'DetDepth': 0.055,'calibdmin': 1.,}
     834    # set controls and vary options, then fit
     835    for img in gpx.images():
     836        img.setCalibrant('Si    SRM640c')
     837        img.setVary('*',False)
     838        img.setVary(['det-X', 'det-Y', 'phi', 'tilt', 'wave'], True)
     839        img.setControls(defImgVals)
     840        img.Recalibrate()
     841        img.Recalibrate() # 2nd run better insures convergence
     842    gpx.save()
     843    # make dict of images for sorting
     844    images = {img.getControl('setdist'):img for img in gpx.images()}
     845    # show values
     846    for key in sorted(images.keys()):
     847        img = images[key]
     848        c = img.getControls()
     849        print(c['distance'],c['wavelength'])
     850
     851This example performs a number of cycles of constrained fitting.
     852A project is created with the images found in a directory, setting initial
     853parameters as the images are read. The initial values
     854for the calibration are not very good, so a :meth:`G2Image.recalibrate` is done
     855to quickly improve the fit. Once that is done, a fit of all images is performed
     856where the wavelength, an offset and detector orientation are constrained to
     857be the same for all images. The detector penetration correction is then added.
     858Note that as the calibration values improve, the algorithm is able to find more
     859points on diffraction rings to use for calibration and the number of "ring picks"
     860increase. The calibration is repeated until that stops increasing significantly (<10%).
     861Detector control files are then created.
     862The files used for this exercise are found
     863`here <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/DeterminingWavelength/data/>`
     864(the
     865`Area Detector Calibration with Multiple Distances <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/DeterminingWavelength/DeterminingWavelength.html>`
     866tutorial).
     867
     868.. code-block::  python
    867869
    868870    import os,sys,glob
     
    909911    gpx.save()
    910912
    911     .. _CommandlineInterface:
    912 
    913     =======================================
    914     GSASIIscriptable Command-line Interface
    915     =======================================
    916 
    917     The routines described above are intended to be called from a Python script, but an
    918     alternate way to access some of the same functionality is to
    919     invoke the ``GSASIIscriptable.py`` script from
    920     the command line usually from within a shell script or batch file. This
    921     will usually be done with a command such as::
    922 
    923            python <path/>GSASIIscriptable.py <subcommand> <file.gpx> <options>
    924 
    925     The following subcommands are defined:
    926 
    927             * create, see :func:`create`
    928             * add, see :func:`add`
    929             * dump, see :func:`dump`
    930             * refine, see :func:`refine`
    931             * export, :func:`export`
    932             * browse, see :func:`IPyBrowse`
    933 
    934     Run::
    935 
    936        python GSASIIscriptable.py --help
    937 
    938     to show the available subcommands, and inspect each subcommand with
    939     `python GSASIIscriptable.py <subcommand> --help` or see the documentation for each of the above routines.
    940 
    941     .. _JsonFormat:
    942 
    943     -------------------------
    944     Parameters in JSON files
    945     -------------------------
    946 
    947     The refine command requires two inputs: an existing GSAS-II project (.gpx) file and
    948     a JSON format file
    949     (see `Introducing JSON <http://json.org/>`_) that contains a single dict.
    950     This dict may have two keys:
    951 
    952     refinements:
    953       This defines the a set of refinement steps in a JSON representation of a
    954       :ref:`Refinement_recipe` list.
    955 
    956     code:
    957       This optionally defines Python code that will be executed after the project is loaded,
    958       but before the refinement is started. This can be used to execute Python code to change
    959       parameters that are not accessible via a :ref:`Refinement_recipe` dict (note that the
    960       project object is accessed with variable ``proj``) or to define code that will be called
    961       later (see key ``call`` in the :ref:`Refinement_recipe` section.)
    962 
    963     JSON website: `Introducing JSON <http://json.org/>`_.
    964 
    965     .. _API:
    966 
    967     ============================================================
    968     API: Complete Documentation
    969     ============================================================
    970 
    971     The large number of classes and modules in this module are described below.
    972     A script will have one or more G2Project objects using :class:`G2Project` and then
    973     perform actions such as adding a histogram (method :meth:`G2Project.add_powder_histogram`),
    974     adding a phase (method :meth:`G2Project.add_phase`),
    975     or setting parameters and performing a refinement
    976     (method :meth:`G2Project.do_refinements`).
    977 
    978     To change settings within histograms, images and phases, one usually needs to use
    979     methods inside :class:`G2PwdrData`, :class:`G2Image` or :class:`G2Phase`.
    980     """
    981 
    982     #============================================================================
    983     # adding a new object type
    984     # 1) add a new object class (e.g. G2PDF)
    985     # 2) add the wrapper into G2Project (e.g. _pdfs, pdf, pdfs)
    986     # 3) add a new method to add the object into a project (G2Project.add_PDF)
    987     # 4) add to documentation in section :class:`G2Project`
    988     # 5) add a new documentation section for the new class
    989     #============================================================================
    990 
    991     from __future__ import division, print_function
    992     import argparse
    993     import os.path as ospath
    994     import datetime as dt
    995     import sys
    996     import platform
    997     if '2' in platform.python_version_tuple()[0]:
    998         import cPickle
    999         strtypes = (str,unicode)
    1000     else:
    1001         import pickle as cPickle
    1002         strtypes = (str,bytes)
     913.. _CommandlineInterface:
     914
     915=======================================
     916GSASIIscriptable Command-line Interface
     917=======================================
     918
     919The routines described above are intended to be called from a Python script, but an
     920alternate way to access some of the same functionality is to
     921invoke the ``GSASIIscriptable.py`` script from
     922the command line usually from within a shell script or batch file. This
     923will usually be done with a command such as::
     924
     925       python <path/>GSASIIscriptable.py <subcommand> <file.gpx> <options>
     926
     927The following subcommands are defined:
     928
     929        * create, see :func:`create`
     930        * add, see :func:`add`
     931        * dump, see :func:`dump`
     932        * refine, see :func:`refine`
     933        * export, :func:`export`
     934        * browse, see :func:`IPyBrowse`
     935
     936Run::
     937
     938   python GSASIIscriptable.py --help
     939
     940to show the available subcommands, and inspect each subcommand with
     941`python GSASIIscriptable.py <subcommand> --help` or see the documentation for each of the above routines.
     942
     943.. _JsonFormat:
     944
     945-------------------------
     946Parameters in JSON files
     947-------------------------
     948
     949The refine command requires two inputs: an existing GSAS-II project (.gpx) file and
     950a JSON format file
     951(see `Introducing JSON <http://json.org/>`_) that contains a single dict.
     952This dict may have two keys:
     953
     954refinements:
     955  This defines the a set of refinement steps in a JSON representation of a
     956  :ref:`Refinement_recipe` list.
     957
     958code:
     959  This optionally defines Python code that will be executed after the project is loaded,
     960  but before the refinement is started. This can be used to execute Python code to change
     961  parameters that are not accessible via a :ref:`Refinement_recipe` dict (note that the
     962  project object is accessed with variable ``proj``) or to define code that will be called
     963  later (see key ``call`` in the :ref:`Refinement_recipe` section.)
     964
     965JSON website: `Introducing JSON <http://json.org/>`_.
     966
     967.. _API:
     968
     969============================================================
     970API: Complete Documentation
     971============================================================
     972
     973The large number of classes and modules in this module are described below.
     974A script will have one or more G2Project objects using :class:`G2Project` and then
     975perform actions such as adding a histogram (method :meth:`G2Project.add_powder_histogram`),
     976adding a phase (method :meth:`G2Project.add_phase`),
     977or setting parameters and performing a refinement
     978(method :meth:`G2Project.do_refinements`).
     979
     980To change settings within histograms, images and phases, one usually needs to use
     981methods inside :class:`G2PwdrData`, :class:`G2Image` or :class:`G2Phase`.
     982"""
     983
     984#============================================================================
     985# adding a new object type
     986# 1) add a new object class (e.g. G2PDF)
     987# 2) add the wrapper into G2Project (e.g. _pdfs, pdf, pdfs)
     988# 3) add a new method to add the object into a project (G2Project.add_PDF)
     989# 4) add to documentation in section :class:`G2Project`
     990# 5) add a new documentation section for the new class
     991#============================================================================
     992
     993from __future__ import division, print_function
     994import argparse
     995import os.path as ospath
     996import datetime as dt
     997import sys
     998import platform
     999if '2' in platform.python_version_tuple()[0]:
     1000    import cPickle
     1001    strtypes = (str,unicode)
     1002else:
     1003    import pickle as cPickle
     1004    strtypes = (str,bytes)
    10031005import imp
    10041006import copy
Note: See TracChangeset for help on using the changeset viewer.