Changeset 4126


Ignore:
Timestamp:
Aug 31, 2019 2:44:16 PM (4 years ago)
Author:
toby
Message:

finish multi-distance fitting and example

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/GSASIIscriptable.py

    r4124 r4126  
    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 Refinement
    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 and the pattern and reflection list are computed.
    719 
    720 .. code-block::  python
    721 
    722     import os,sys
    723     sys.path.insert(0,'/Users/toby/software/G2/GSASII')
    724     import GSASIIscriptable as G2sc
    725     datadir = "/Users/toby/software/G2/Tutorials/PythonScript/data"
    726     PathWrap = lambda fil: os.path.join(datadir,fil)
    727     gpx = G2sc.G2Project(filename='PbSO4sim.gpx') # create a project
    728     # add a phase to the project
    729     phase0 = gpx.add_phase(PathWrap("PbSO4-Wyckoff.cif"),
    730              phasename="PbSO4",fmthint='CIF')
    731     # add a simulated histogram and link it to the previous phase(s)
    732     hist1 = gpx.add_simulated_powder_histogram("PbSO4 simulation",
    733                 PathWrap("inst_d1a.prm"),5.,120.,0.01,
    734                 phases=gpx.phases())
    735     # Set the scale factor to adjust the y scale
    736     hist1.SampleParameters['Scale'][0] = 1000000.
    737     # parameter optimization and calculate pattern
    738     gpx.data['Controls']['data']['max cyc'] = 0 # refinement not needed
    739     gpx.do_refinements([{}])
    740     gpx.save()
    741     # save results
    742     gpx.histogram(0).Export('PbSO4data','.csv','hist') # data
    743     gpx.histogram(0).Export('PbSO4refl','.csv','refl') # reflections
    744 
    745 ----------------------
    746 Sequential Refinement
    747 ----------------------
    748 
    749 GSASIIscriptable can be used to setup and perform sequential refinements. This example script
    750 is used to take the single-dataset fit at the end of Step 1 of the
    751 `Sequential Refinement tutorial <https://subversion.xray.aps.anl.gov/pyGSAS/Tutorials/SeqRefine/SequentialTutorial.htm>`
    752 and turn on and off refinement flags, add histograms and setup the sequential fit, which is then run:
    753 
    754 .. code-block::  python
     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).
    755867
    756868    import os,sys,glob
    757869    sys.path.insert(0,'/Users/toby/software/G2/GSASII')
    758870    import GSASIIscriptable as G2sc
    759     datadir = os.path.expanduser("~/Scratch/SeqTut2019Mar")
    760     PathWrap = lambda fil: os.path.join(datadir,fil)
    761     # load and rename project
    762     gpx = G2sc.G2Project(PathWrap('7Konly.gpx'))
    763     gpx.save(PathWrap('SeqRef.gpx'))
    764     # turn off some variables; turn on Dijs
    765     for p in gpx.phases():
    766         p.set_refinements({"Cell": False})
    767     gpx.phase(0).set_HAP_refinements(
    768         {'Scale': False,
    769          "Size": {'type':'isotropic', 'refine': False},
    770          "Mustrain": {'type':'uniaxial', 'refine': False},
    771          "HStrain":True,})
    772     gpx.phase(1).set_HAP_refinements({'Scale': False})
    773     gpx.histogram(0).clear_refinements({'Background':False,
    774                      'Sample Parameters':['DisplaceX'],})
    775     gpx.histogram(0).ref_back_peak(0,[])
    776     gpx.phase(1).set_HAP_refinements({"HStrain":(1,1,1,0)})
    777     for fil in sorted(glob.glob(PathWrap('*.fxye'))): # load in remaining fxye files
    778         if '00' in fil: continue
    779         gpx.add_powder_histogram(fil, PathWrap('OH_00.prm'), fmthint="GSAS powder",phases='all')
    780     # copy HAP values, background, instrument params. & limits, not sample params.
    781     gpx.copyHistParms(0,'all',['b','i','l'])
    782     for p in gpx.phases(): p.copyHAPvalues(0,'all')
    783     # setup and launch sequential fit
    784     gpx.set_Controls('sequential',gpx.histograms())
    785     gpx.set_Controls('cycles',10)
    786     gpx.set_Controls('seqCopy',True)
    787     gpx.refine() 
    788 
    789 .. _CommandlineInterface:
    790 
    791 =======================================
    792 GSASIIscriptable Command-line Interface
    793 =======================================
    794 
    795 The routines described above are intended to be called from a Python script, but an
    796 alternate way to access some of the same functionality is to
    797 invoke the ``GSASIIscriptable.py`` script from
    798 the command line usually from within a shell script or batch file. This
    799 will usually be done with a command such as::
    800 
    801        python <path/>GSASIIscriptable.py <subcommand> <file.gpx> <options>
    802 
    803 The following subcommands are defined:
    804 
    805         * create, see :func:`create`
    806         * add, see :func:`add`
    807         * dump, see :func:`dump`
    808         * refine, see :func:`refine`
    809         * export, :func:`export`
    810         * browse, see :func:`IPyBrowse`
    811        
    812 Run::
    813 
    814    python GSASIIscriptable.py --help
    815 
    816 to show the available subcommands, and inspect each subcommand with
    817 `python GSASIIscriptable.py <subcommand> --help` or see the documentation for each of the above routines.
    818 
    819 .. _JsonFormat:
    820 
    821 -------------------------
    822 Parameters in JSON files
    823 -------------------------
    824 
    825 The refine command requires two inputs: an existing GSAS-II project (.gpx) file and
    826 a JSON format file
    827 (see `Introducing JSON <http://json.org/>`_) that contains a single dict.
    828 This dict may have two keys:
    829 
    830 refinements:
    831   This defines the a set of refinement steps in a JSON representation of a
    832   :ref:`Refinement_recipe` list.
    833 
    834 code:
    835   This optionally defines Python code that will be executed after the project is loaded,
    836   but before the refinement is started. This can be used to execute Python code to change
    837   parameters that are not accessible via a :ref:`Refinement_recipe` dict (note that the
    838   project object is accessed with variable ``proj``) or to define code that will be called
    839   later (see key ``call`` in the :ref:`Refinement_recipe` section.)
    840    
    841 JSON website: `Introducing JSON <http://json.org/>`_.
    842 
    843 .. _API:
    844 
    845 ============================================================
    846 API: Complete Documentation
    847 ============================================================
    848 
    849 The large number of classes and modules in this module are described below.
    850 A script will have one or more G2Project objects using :class:`G2Project` and then
    851 perform actions such as adding a histogram (method :meth:`G2Project.add_powder_histogram`),
    852 adding a phase (method :meth:`G2Project.add_phase`),
    853 or setting parameters and performing a refinement
    854 (method :meth:`G2Project.do_refinements`).
    855 
    856 To change settings within histograms, images and phases, one usually needs to use
    857 methods inside :class:`G2PwdrData`, :class:`G2Image` or :class:`G2Phase`.
    858 """
    859 
    860 #============================================================================
    861 # adding a new object type
    862 # 1) add a new object class (e.g. G2PDF)
    863 # 2) add the wrapper into G2Project (e.g. _pdfs, pdf, pdfs)
    864 # 3) add a new method to add the object into a project (G2Project.add_PDF)
    865 # 4) add to documentation in section :class:`G2Project`
    866 # 5) add a new documentation section for the new class
    867 #============================================================================
    868 
    869 from __future__ import division, print_function
    870 import argparse
    871 import os.path as ospath
    872 import datetime as dt
    873 import sys
    874 import platform
    875 if '2' in platform.python_version_tuple()[0]:
    876     import cPickle
    877     strtypes = (str,unicode)
    878 else:
    879     import pickle as cPickle
    880     strtypes = (str,bytes)
     871    PathWrap = lambda fil: os.path.join(
     872        "/Users/toby/wp/Active/MultidistanceCalibration/multimg",
     873        fil)
     874
     875    gpx = G2sc.G2Project(filename='/tmp/calib.gpx')
     876    for f in glob.glob(PathWrap('*.tif')):
     877        im = gpx.add_image(f,fmthint="TIF")
     878    # starting image parameter settings
     879    defImgVals = {'wavelength': 0.240, 'center': [206., 205.],
     880      'pixLimit': 2,  'cutoff': 5.0, 'DetDepth': 0.03,'calibdmin': 0.5,}
     881    # set controls and vary options, then initial fit
     882    for img in gpx.images():
     883        img.setCalibrant('Si    SRM640c')
     884        img.setVary('*',False)
     885        img.setVary(['det-X', 'det-Y', 'phi', 'tilt', 'wave'], True)
     886        img.setControls(defImgVals)
     887        if img.getControl('setdist') > 900:
     888            img.setControls({'calibdmin': 1.,})
     889        img.Recalibrate()
     890    G2sc.SetPrintLevel('warn') # cut down on output
     891    result,covData = gpx.imageMultiDistCalib()
     892    print('1st global fit: initial ring picks',covData['obs'])
     893    print({i:result[i] for i in result if '-' not in i})
     894    # add parameter to all images & refit multiple times
     895    for img in gpx.images(): img.setVary('dep',True)
     896    ringpicks = covData['obs']
     897    delta = ringpicks
     898    while delta > ringpicks/10:
     899        result,covData = gpx.imageMultiDistCalib(verbose=False)
     900        delta = covData['obs'] - ringpicks
     901        print('ring picks went from',ringpicks,'to',covData['obs'])
     902        print({i:result[i] for i in result if '-' not in i})
     903        ringpicks = covData['obs']
     904    # once more for good measure & printout
     905    result,covData = gpx.imageMultiDistCalib(verbose=True)
     906    # create image control files
     907    for img in gpx.images():
     908        img.saveControls(os.path.splitext(img.name)[0]+'.imctrl')
     909    gpx.save()
     910
     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)
    8811003import imp
    8821004import copy
    … …  
    13061428    :param float wave: wavelength in Angstroms for use with TTmax (ignored
    13071429       otherwise.)
     1430    :returns: a list of reflections, where each reflection contains four items:
     1431       h, k, l, d, where d is the d-space (Angstroms)
     1432
     1433    Example:
     1434
     1435    >>> import os,sys
     1436    >>> sys.path.insert(0,'/Users/toby/software/G2/GSASII')
     1437    >>> import GSASIIscriptable as G2sc
     1438    GSAS-II binary directory: /Users/toby/software/G2/GSASII/bin
     1439    17 values read from config file /Users/toby/software/G2/GSASII/config.py
     1440    >>> refs = G2sc.GenerateReflections('P 1',
     1441    ...                     (5.,6.,7.,90.,90.,90),
     1442    ...                     TTmax=20,wave=1)
     1443    >>> for r in refs: print(r)
     1444    ...
     1445    [0, 0, 1, 7.0]
     1446    [0, 1, 0, 6.0]
     1447    [1, 0, 0, 5.0]
     1448    [0, 1, 1, 4.55553961419178]
     1449    [0, 1, -1, 4.55553961419178]
     1450    [1, 0, 1, 4.068667356033675]
     1451    [1, 0, -1, 4.068667356033674]
     1452    [1, 1, 0, 3.8411063979868794]
     1453    [1, -1, 0, 3.8411063979868794]
    13081454    """
    13091455
    … …  
    27302876                Data['Flat Bkg'] = 0.0
    27312877                Data['Oblique'] = [0.5,False]
     2878            Data['varyList'] = {'dist':True,'det-X':True,'det-Y':True,'tilt':True,'phi':True,'dep':False,'wave':False}
    27322879            Data['setDefault'] = False
    27332880            Data['range'] = [(0,Imax),[0,Imax]]
    … …  
    27432890        return objlist
    27442891   
     2892    def imageMultiDistCalib(self,imageList=None,verbose=False):
     2893        '''Invokes a global calibration fit (same as Image Controls/Calibration/Multi-distance Recalibrate
     2894        menu command) with images as multiple distance settings.
     2895        Note that for this to work properly, the initial calibration parameters
     2896        (center, wavelength, distance & tilts) must be close enough to converge.
     2897        This may produce a better result if run more than once.
     2898
     2899        :param str imageList: the images to include in the fit, if not specified
     2900          all images in the project will be included.
     2901
     2902        :returns: parmDict,covData where parmDict has the refined parameters
     2903          and their values and covData is a dict containing the covariance matrix ('covMatrix'),
     2904          the number of ring picks ('obs') the reduced Chi-squared ('chisq'),
     2905          the names of the variables ('varyList') and their values ('variables')
     2906        '''
     2907        if imageList is None:
     2908            imageList = self.images()
     2909
     2910        # code based on GSASIIimgGUI..OnDistRecalib
     2911        obsArr = np.array([]).reshape(0,4)
     2912        parmDict = {}
     2913        varList = []
     2914        HKL = {}
     2915
     2916        for img in imageList:
     2917            name = img.name
     2918            G2fil.G2Print ('getting rings for',name)
     2919            Data = img.data['Image Controls']
     2920            key = str(int(Data['setdist']))
     2921            # create a parameter dict for combined fit
     2922            if 'wavelength' not in parmDict:
     2923                parmDict['wavelength'] = Data['wavelength']
     2924                if Data['varyList']['wave']:
     2925                    varList += ['wavelength']
     2926                if Data['varyList']['dist']:
     2927                    raise Exception(
     2928                                'You cannot vary individual detector positions and the global wavelength.\n\nChange flags for 1st image.',
     2929                                'Conflicting vars')
     2930                parmDict['dep'] = Data['DetDepth']
     2931                if Data['varyList']['dep']:
     2932                    varList += ['dep']
     2933                # distance flag determines if individual values are refined
     2934                if not Data['varyList']['dist']:
     2935                    # starts as zero, single variable, always refined
     2936                    parmDict['deltaDist'] = 0.
     2937                    varList += ['deltaDist']
     2938                parmDict['phi'] = Data['rotation']
     2939                if Data['varyList']['phi']:
     2940                    varList += ['phi']
     2941                parmDict['tilt'] = Data['tilt']
     2942                if Data['varyList']['tilt']:
     2943                    varList += ['tilt']
     2944
     2945            ImageZ = _getCorrImage(Readers['Image'],self,img)
     2946            Data['setRings'] = True
     2947            Masks = img.data['Masks']
     2948            result = G2img.ImageRecalibrate(None,ImageZ,Data,Masks,getRingsOnly=True)
     2949            if not len(result):
     2950                raise Exception('calibrant missing from local image calibrants files')
     2951            rings,HKL[key] = result
     2952            # add detector set dist into data array, create a single really large array
     2953            distarr = np.zeros_like(rings[:,2:3])
     2954            if 'setdist' not in Data:
     2955                raise Exception('Distance (setdist) not in image metadata')
     2956            distarr += Data['setdist']
     2957            obsArr = np.concatenate((
     2958                        obsArr,
     2959                        np.concatenate((rings[:,0:2],distarr,rings[:,2:3]),axis=1)),axis=0)
     2960            if 'deltaDist' not in parmDict:
     2961                # starts as zero, variable refined for each image
     2962                parmDict['delta'+key] = 0
     2963                varList += ['delta'+key]
     2964            for i,z in enumerate(['X','Y']):
     2965                v = 'det-'+z
     2966                if v+key in parmDict:
     2967                    raise Exception('Error: two images with setdist ~=',key)
     2968                parmDict[v+key] = Data['center'][i]
     2969                if Data['varyList'][v]:
     2970                    varList += [v+key]
     2971        #GSASIIpath.IPyBreak()
     2972        G2fil.G2Print('\nFitting',obsArr.shape[0],'ring picks and',len(varList),'variables...')
     2973        result = G2img.FitMultiDist(obsArr,varList,parmDict,covar=True,Print=verbose)
     2974       
     2975        for img in imageList: # update GPX info with fit results
     2976            name = img.name
     2977            #print ('updating',name)
     2978            Data = img.data['Image Controls']
     2979            Data['wavelength'] = parmDict['wavelength']
     2980            key = str(int(Data['setdist']))
     2981            Data['center'] = [parmDict['det-X'+key],parmDict['det-Y'+key]]
     2982            if 'deltaDist' in parmDict:
     2983                Data['distance'] = Data['setdist'] - parmDict['deltaDist']
     2984            else:
     2985                Data['distance'] = Data['setdist'] - parmDict['delta'+key]
     2986            Data['rotation'] = np.mod(parmDict['phi'],360.0)
     2987            Data['tilt'] = parmDict['tilt']
     2988            Data['DetDepth'] = parmDict['dep']
     2989            N = len(Data['ellipses'])
     2990            Data['ellipses'] = []           #clear away individual ellipse fits
     2991            for H in HKL[key][:N]:
     2992                ellipse = G2img.GetEllipse(H[3],Data)
     2993                Data['ellipses'].append(copy.deepcopy(ellipse+('b',)))
     2994               
     2995        covData = {'title':'Multi-distance recalibrate','covMatrix':result[3],
     2996                       'obs':obsArr.shape[0],'chisq':result[0],
     2997                       'varyList':varList,'variables':result[1]}
     2998        return parmDict,covData
     2999               
    27453000    def get_Controls(self, control):
    27463001        '''Return project controls settings
    … …  
    29263181
    29273182class G2AtomRecord(G2ObjectWrapper):
    2928     """Wrapper for an atom record. Has convenient accessors via @property.
    2929 
    2930     Available accessors: label, type, refinement_flags, coordinates,
    2931         occupancy, ranId, id, adp_flag, uiso
     3183    """Wrapper for an atom record. Has convenient accessors via @property:
     3184    label, type, refinement_flags, coordinates, occupancy, ranId, id, adp_flag, uiso
    29323185
    29333186    Example:
    … …  
    47535006
    47545007class G2Image(G2ObjectWrapper):
    4755     """Wrapper for an IMG tree entry, containing an image and various metadata.
     5008    '''Wrapper for an IMG tree entry, containing an image and associated metadata.
     5009
    47565010    Note that in a GSASIIscriptable script, instances of G2Image will be created by
    4757     calls to :meth:`G2Project.add_image` or :meth:`G2Project.images`, not via calls
    4758     to :meth:`G2Image.__init__`.
     5011    calls to :meth:`G2Project.add_image` or :meth:`G2Project.images`.
     5012    Scripts will not use ``G2Image()`` to call :meth:`G2Image.__init__` directly.
    47595013
    47605014    Example use of G2Image:
    … …  
    47695023    >>> pwdrList = imlst[0].Integrate()
    47705024
    4771 
    4772     Sample script using an image:   
    4773 
    4774 .. code-block::  python
    4775 
    4776     import os,sys
    4777     sys.path.insert(0,'/Users/toby/software/G2/GSASII')
    4778     import GSASIIscriptable as G2sc
    4779     datadir = "/tmp/V4343_IntegrationError/"
    4780     PathWrap = lambda fil: os.path.join(datadir,fil)
    4781 
    4782     gpx = G2sc.G2Project(filename=PathWrap('inttest.gpx'))
    4783     imlst = gpx.add_image(PathWrap('Si_free_dc800_1-00000.tif'),fmthint="TIF")
    4784     imlst[0].loadControls(PathWrap('Si_free_dc800_1-00000.imctrl'))
    4785     pwdrList = imlst[0].Integrate()
    4786     gpx.save()
    4787 
    4788     """
     5025    '''
    47895026    # parameters in that can be accessed via setControl. This may need future attention
    47905027    ControlList = {
    … …  
    50535290        '''Set a refinement flag for Image Controls parameter in the
    50545291        current image.
    5055         If the parameter is not found an exception is raised.
     5292        If the parameter is not '*' or found, an exception is raised.
    50565293
    50575294        :param str arg: the name of a refinement parameter in the
    50585295          varyList for the image. The name should be one of
    5059           'dep', 'det-X', 'det-Y', 'dist', 'phi', 'tilt', or 'wave'
    5060         :param str arg: the name of a parameter (dict entry) in the
    5061           image. The parameter must be found in :data:`ControlList`
    5062           or an exception is raised.
     5296          'dep', 'det-X', 'det-Y', 'dist', 'phi', 'tilt', or 'wave',
     5297          or it may be a list or tuple of names,
     5298          or it may be '*' in which all parameters are set accordingly.
    50635299        :param value: the value to set the parameter. The value is
    50645300          cast as the appropriate type from :data:`ControlList`.
    50655301        '''
    5066         if arg in self.data['Image Controls']['varyList']:
    5067             self.data['Image Controls']['varyList'][arg] = bool(value)
    5068         else:
    5069             raise Exception('arg {} not defined in G2Image.setVary'.format(arg))
     5302        if arg == '*':
     5303            for a in self.data['Image Controls']['varyList']:
     5304                self.data['Image Controls']['varyList'][a] = bool(value)
     5305            return
     5306        if not isinstance(arg,tuple) and not isinstance(arg,list):
     5307            arg = [arg]
     5308        for a in arg:
     5309            if a in self.data['Image Controls']['varyList']:
     5310                self.data['Image Controls']['varyList'][a] = bool(value)
     5311            else:
     5312                raise Exception('arg {} not defined in G2Image.setVary'.format(a))
    50705313
    50715314    def Recalibrate(self):
    50725315        '''Invokes a recalibration fit (same as Image Controls/Calibration/Recalibrate
    50735316        menu command). Note that for this to work properly, the calibration
    5074         coefficients (center, wavelength, ditance & tilts) must be fairly close.
     5317        coefficients (center, wavelength, distance & tilts) must be fairly close.
    50755318        This may produce a better result if run more than once.
    50765319        '''
Note: See TracChangeset for help on using the changeset viewer.