Ignore:
Timestamp:
Feb 19, 2018 5:57:29 PM (5 years ago)
Author:
toby
Message:

rework Scriptable docs

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/GSASIIscriptable.py

    r3290 r3292  
    1919They all inherit from :class:`G2ObjectWrapper`. The chief class is :class:`G2Project`,
    2020which represents an entire GSAS-II project and provides several methods to access
    21 phases, powder histograms, and execute Rietveld refinements. These routines are
    22 typically called by using the :ref:`CommandlineInterface` to access a number of features or
    23 the :ref:`API`, which allows much more versatile access.
    24 
    25 .. _Refinement_parameters_kinds:
     21phases, powder histograms, and execute Rietveld refinements. These routines can be
     22accessed in two ways:
     23the :ref:`CommandlineInterface` provides access a number of features without writing
     24Python scripts of from the :ref:`API`, which allows much more versatile access from
     25within Python.
     26
    2627
    2728=====================
    28 Refinement parameters
     29Overview
    2930=====================
    30 
    31 Note that parameters and refinement flags used in GSAS-II fall into three classes:
    32 
    33     * **Histogram**: There will be a set of these for each dataset loaded into a
    34       project file. The parameters available depend on the type of histogram
    35       (Bragg-Brentano, Single-Crystal, TOF,...). Typical Histogram parameters
    36       include the overall scale factor, background, instrument and sample parameters;
    37       see the :ref:`Histogram_parameters_table` table for a list of the histogram
    38       parameters where access has been provided.
    39      
    40     * **Phase**: There will be a set of these for each phase loaded into a
    41       project file. While some parameters are found in all types of phases,
    42       others are only found in certain types (modulated, magnetic, protein...).
    43       Typical phase parameters include unit cell lengths and atomic positions; see the
    44       :ref:`Phase_parameters_table` table for a list of the phase     
    45       parameters where access has been provided.
    46      
    47     * **Histogram-and-phase** (HAP): There is a set of these for every histogram
    48       that is associated with each phase, so that if there are ``N`` phases and ``M``
    49       histograms, there can be ``N*M`` total sets of "HAP" parameters sets (fewer if all
    50       histograms are not linked to all phases.) Typical HAP parameters include the
    51       phase fractions, sample microstrain and crystallite size broadening terms,
    52       hydrostatic strain pertibations of the unit cell and preferred orientation
    53       values.
    54       See the :ref:`HAP_parameters_table` table for the HAP parameters where access has
    55       been provided.
    56 
    57 There are several ways to set parameters using different objects, as described below.
    58 
    59 ------------------------
    60 Histogram/Phase objects
    61 ------------------------
    62 Each phase and powder histogram in a :class:`G2Project` object has an associated
    63 object. Parameters within each individual object can be turned on and off by calling
    64 :meth:`G2PwdrData.set_refinements` or :meth:`G2PwdrData.clear_refinements`
    65 for histogram parameters;
    66 :meth:`G2Phase.set_refinements` or :meth:`G2Phase.clear_refinements`
    67 for phase parameters; and :meth:`G2Phase.set_HAP_refinements` or
    68 :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:
    69 
    70 .. code-block::  python
    71 
    72     params = { 'Limits': [0.8, 12.0],
    73                'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
    74                'Background': {'type': 'chebyschev', 'refine': True}}
    75     some_histogram.set_refinements(params)
    76 
    77 Likewise to turn refinement flags on, use code such as this:
    78 
    79 .. code-block::  python
    80 
    81     params = { 'Instrument Parameters': ['U', 'V', 'W']}
    82     some_histogram.set_refinements(params)
    83 
    84 and to turn these refinement flags, off use this (Note that the
    85 ``.clear_refinements()`` methods will usually will turn off refinement even
    86 if a refinement parameter is set in the dict to True.):
    87 
    88 .. code-block::  python
    89 
    90     params = { 'Instrument Parameters': ['U', 'V', 'W']}
    91     some_histogram.clear_refinements(params)
    92 
    93 For phase parameters, use code such as this:
    94    
    95 .. code-block::  python
    96 
    97     params = { 'LeBail': True, 'Cell': True,
    98                'Atoms': { 'Mn1': 'X',
    99                           'O3': 'XU',
    100                           'V4': 'FXU'}}
    101     some_histogram.set_refinements(params)
    102 
    103 
    104 and here is an example for HAP parameters:
    105 
    106 .. code-block::  python
    107 
    108     params = { 'Babinet': 'BabA',
    109                'Extinction': True,
    110                'Mustrain': { 'type': 'uniaxial',
    111                              'direction': [0, 0, 1],
    112                              'refine': True}}
    113     some_phase.set_HAP_refinements(params)
    114 
    115 Note that the parameters must match the object type and method (phase vs. histogram vs. HAP).
    116 
    117 .. _Project_objects:
     31The most commonly used routines are:
     32
     33:class:`G2Project`
     34   Always needed: used to create a new project (.gpx) file or read in an existing one.
     35
     36:meth:`G2Project.add_powder_histogram`
     37   Used to read in powder diffraction data to a project file.
     38
     39:meth:`G2Project.add_simulated_powder_histogram`
     40   Defines a "dummy" powder diffraction data that will be simulated after a refinement step.
     41
     42:meth:`G2Project.save`
     43   Writes the current project to disk.
     44
     45:meth:`G2Project.do_refinements`
     46   This is passed a list of dictionaries, where each dict defines a refinement step.
     47   Passing a list with a single empty dict initiates a refinement with the current
     48   parameters and flags.
     49   
     50:meth:`G2Project.set_refinement`
     51   This is passed a single dictionaries which is used to set parameters and flags.
     52   These actions can be performed also in :meth:`G2Project.do_refinements`.
     53
     54Refinement step dicts
     55   A refinement step dict, as used in :meth:`G2Project.do_refinements` and described in
     56   :ref:`Project_dicts`,
     57   specifies parameter & refinement flag changes, which are usually followed by a refinement and
     58   optionally by calls to locally-defined Python functions. The keys used in these dicts are
     59   defined in the :ref:`Refinement_recipe` table, below.
     60
     61There are several ways to set parameters project using different level objects, as is
     62are described in sections below, but the simplest way to access parameters and flags
     63in a project is to use the above routines.
     64
     65.. _Project_dicts:
    11866
    11967-----------------------------
    12068Project-level Parameter Dict
    12169-----------------------------
    122 It is also possible to create a composite dictionary
    123 that references all three of the above types of refinement parameters.
    124 In this case dictionaries are nested with keys at the outer level, such as
    125 "set" and "clear" which determine function is used with function
    126 :meth:`G2Project.set_refinement`.
    127 
    128 Note that optionally a list of histograms and/or phases can be supplied to
    129 :meth:`G2Project.set_refinement` or :meth:`G2Project.do_refinements`,
    130 where the default is to use all phases and histograms, but more commonly for
    131 :meth:`G2Project.do_refinements` will be to define the "histograms" and "phases"
    132 items within individual dictionaries and these will override the call arguments.
    133 
     70
     71As noted below (:ref:`Refinement_parameters_kinds`), there are three types of refinement parameters,
     72which can be accessed individually by the objects that encapsulate individual phases and histograms
     73but it will be usually simplest to create a composite dictionary
     74that is used at the project-level. A dict is created with keys
     75"set" and "clear" that can be supplied to :meth:`G2Project.set_refinement`
     76(or :meth:`G2Project.do_refinements`, see :ref:`Refinement_recipe` below) that will
     77determine parameter values and will determine which parameters will be refined.
     78
     79The specific keys and subkeys that can be used are defined in tables
     80:ref:`Histogram_parameters_table`, :ref:`Phase_parameters_table` and :ref:`HAP_parameters_table`.
     81
     82Note that optionally a list of histograms and/or phases can be supplied in the call to
     83:meth:`G2Project.set_refinement`, but if not specified, the default is to use all defined
     84phases and histograms.
    13485
    13586As an example:
    … …  
    14293              'clear': {'Instrument Parameters': ['U', 'V', 'W']}}
    14394    my_project.set_refinement(pardict)
    144 
     95   
    14596.. _Refinement_recipe:
    14697   
    … …  
    14899Refinement recipe
    149100------------------------
    150 Finally, it is possible to specify a sequence of refinement actions as a list of
    151 dicts that contain :ref:`Project_objects` objects. This list is
    152 supplied as an argument to :meth:`G2Project.do_refinements`.
    153 These dicts in this list are each like those described in the
    154 :ref:`Project_objects` section,
    155 except that additional keys, as are described in the table below may be used.
     101Building on the :ref:`Project_dicts`,
     102it is possible to specify a sequence of refinement actions as a list of
     103these dicts and supplying this list
     104as an argument to :meth:`G2Project.do_refinements`.
     105
     106As an example, this code performs the same actions as in the example in the section above:
     107
     108.. code-block::  python
     109   
     110    pardict = {'set': { 'Limits': [0.8, 12.0],
     111                       'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
     112                       'Background': {'type': 'chebyschev', 'refine': True}},
     113              'clear': {'Instrument Parameters': ['U', 'V', 'W']}}
     114    my_project.do_refinements([pardict])
     115
     116However, in addition to setting a number of parameters, this example will perform a refinement as well.
     117If more than one dict is specified in the list, as is done in this example,
     118two refinement steps will be performed:
     119
     120.. code-block::  python
     121
     122    my_project.do_refinements([pardict,pardict1])
     123
     124
     125The keys defined in the following table
     126may be used in a dict supplied to :meth:`G2Project.do_refinements`. Note that now keys ``histograms``
     127and ``phases`` are used to limit actions to specific sets of parameters within the project.
    156128
    157129========== ============================================================================
    … …  
    161133                       :ref:`Refinement_parameters_fmt` section. Items listed here
    162134                       will be set to be refined.
    163 clear                  Specifies a dict as above for set, except that parameters are
     135clear                  Specifies a dict, as above for set, except that parameters are
    164136                       cleared and thus will not be refined.
    165137once                   Specifies a dict as above for set, except that parameters are
    … …  
    169141                       action(s), a refinement is started. If skip is defined as True
    170142                       (or any other value) the refinement step is not performed.
    171 output                 If a file name is specified for output is will be used for
     143output                 If a file name is specified for output is will be used to save
    172144                       the current refinement.
    173145histograms             Should contain a list of histogram(s) to be used for the
    … …  
    195167========== ============================================================================
    196168
    197 An example follows:
     169An example the performs a series of refinement steps follows:
    198170
    199171.. code-block::  python
    … …  
    218190   
    219191
    220 In this example, the list contains a set of dicts, each defined as before.
    221 A separate refinement step will be performed for each element in the list unless
    222 "skip" is included.
     192In this example, a separate refinement step will be performed for each dict in the list, since
     193"skip" is not included.
    223194Note that in the second from last refinement step, parameters are both set and cleared.
     195   
     196.. _Refinement_parameters_kinds:
     197
     198=====================
     199Refinement parameters
     200=====================
     201
     202Note that parameters and refinement flags used in GSAS-II fall into three classes:
     203
     204    * **Histogram**: There will be a set of these for each dataset loaded into a
     205      project file. The parameters available depend on the type of histogram
     206      (Bragg-Brentano, Single-Crystal, TOF,...). Typical Histogram parameters
     207      include the overall scale factor, background, instrument and sample parameters;
     208      see the :ref:`Histogram_parameters_table` table for a list of the histogram
     209      parameters where access has been provided.
     210     
     211    * **Phase**: There will be a set of these for each phase loaded into a
     212      project file. While some parameters are found in all types of phases,
     213      others are only found in certain types (modulated, magnetic, protein...).
     214      Typical phase parameters include unit cell lengths and atomic positions; see the
     215      :ref:`Phase_parameters_table` table for a list of the phase     
     216      parameters where access has been provided.
     217     
     218    * **Histogram-and-phase** (HAP): There is a set of these for every histogram
     219      that is associated with each phase, so that if there are ``N`` phases and ``M``
     220      histograms, there can be ``N*M`` total sets of "HAP" parameters sets (fewer if all
     221      histograms are not linked to all phases.) Typical HAP parameters include the
     222      phase fractions, sample microstrain and crystallite size broadening terms,
     223      hydrostatic strain pertibations of the unit cell and preferred orientation
     224      values.
     225      See the :ref:`HAP_parameters_table` table for the HAP parameters where access has
     226      been provided.
    224227
    225228.. _Refinement_parameters_fmt:
    … …  
    229232============================
    230233
    231 Refinement parameters are specified as dictionaries, supplied to any of the functions
    232 named in :ref:`Refinement_parameters_kinds`. Each method accepts a different set
    233 of keys, described below for each of the three parameter classes.
     234Refinement parameters are specified within dictionaries. The details of these dicts depends on the
     235type of parameter (see :ref:`Refinement_parameters_kinds`), with a different set
     236of keys described below for each of the three parameter classes.
    234237
    235238.. _Histogram_parameters_table:
    … …  
    240243
    241244This table describes the dictionaries supplied to :func:`G2PwdrData.set_refinements`
    242 and :func:`G2PwdrData.clear_refinements`. Note that in Instrument Parameters,
    243 to save space in the table, related profile parameters (such as U and V) are listed
    244 together, separated by commas.
     245and :func:`G2PwdrData.clear_refinements`. As an example,
     246
     247.. code-block::  python
     248
     249   hist.set_refinements({"Background": {"no.coeffs": 3, "refine": True},
     250                         "Sample Parameters": ["Scale"],
     251                         "Limits": [10000, 40000]})
     252
     253With :meth:`G2Project.do_refinements`, these parameters should be placed inside a dict with a key
     254``set``, ``clear``, or ``once``. Values will be set for all histograms, unless the ``histograms``
     255key is used to define specific histograms. As an example:
     256
     257.. code-block::  python
     258
     259  gsas_proj.do_refinements([{
     260      'set': {
     261          'Background': {'no.coeffs': 3, 'refine': True},
     262          'Sample Parameters': ['Scale'],
     263          'Limits': [10000, 40000]},
     264      'histograms': [1,2]
     265                            }])
     266
     267Note that below in Instrument Parameters,
     268related profile parameters (such as U and V) are listed
     269separated by commas to save space in the table.
    245270
    246271.. tabularcolumns:: |l|l|p{3.5in}|
    … …  
    249274key                   subkey                explanation
    250275===================== ====================  =================================================
    251 Limits                                      The 2-theta range of values to consider. Can
     276Limits                                      The range of 2-theta (degrees) or TOF (in
     277                                            microsec) range of values to use. Can
    252278                                            be either a dictionary of 'low' and/or 'high',
    253279                                            or a list of 2 items [low, high]
    … …  
    299325
    300326This table describes the dictionaries supplied to :func:`G2Phase.set_refinements`
    301 and :func:`G2Phase.clear_refinements`.
     327and :func:`G2Phase.clear_refinements`. With :meth:`G2Project.do_refinements`,
     328these parameters should be placed inside a dict with a key
     329``set``, ``clear``, or ``once``. Values will be set for all phases, unless the ``phases``
     330key is used to define specific phase(s).
     331
    302332
    303333.. tabularcolumns:: |l|p{4.5in}|
    … …  
    325355
    326356This table describes the dictionaries supplied to :func:`G2Phase.set_HAP_refinements`
    327 and :func:`G2Phase.clear_HAP_refinements`.
     357and :func:`G2Phase.clear_HAP_refinements`. When supplied to
     358:meth:`G2Project.do_refinements`, these parameters should be placed inside a dict with a key
     359``set``, ``clear``, or ``once``. Values will be set for all histograms used in each phase,
     360unless the ``histograms`` and ``phases`` keys are used to define specific phases and histograms.
    328361
    329362.. tabularcolumns:: |l|l|p{3.5in}|
    … …  
    359392                                       integers,
    360393                                       the [hkl] direction of the axis.
    361 \               refine                 A boolean, True to refine.
     394\               refine                 Boolean, True to refine.
    362395Pref.Ori.                              Boolean, True to refine
    363396Show                                   Boolean, True to refine
    … …  
    366399=============  ==========  ============================================================
    367400
     401------------------------
     402Histogram/Phase objects
     403------------------------
     404Each phase and powder histogram in a :class:`G2Project` object has an associated
     405object. Parameters within each individual object can be turned on and off by calling
     406:meth:`G2PwdrData.set_refinements` or :meth:`G2PwdrData.clear_refinements`
     407for histogram parameters;
     408:meth:`G2Phase.set_refinements` or :meth:`G2Phase.clear_refinements`
     409for phase parameters; and :meth:`G2Phase.set_HAP_refinements` or
     410: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:
     411
     412.. code-block::  python
     413
     414    params = { 'Limits': [0.8, 12.0],
     415               'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
     416               'Background': {'type': 'chebyschev', 'refine': True}}
     417    some_histogram.set_refinements(params)
     418
     419Likewise to turn refinement flags on, use code such as this:
     420
     421.. code-block::  python
     422
     423    params = { 'Instrument Parameters': ['U', 'V', 'W']}
     424    some_histogram.set_refinements(params)
     425
     426and to turn these refinement flags, off use this (Note that the
     427``.clear_refinements()`` methods will usually will turn off refinement even
     428if a refinement parameter is set in the dict to True.):
     429
     430.. code-block::  python
     431
     432    params = { 'Instrument Parameters': ['U', 'V', 'W']}
     433    some_histogram.clear_refinements(params)
     434
     435For phase parameters, use code such as this:
     436   
     437.. code-block::  python
     438
     439    params = { 'LeBail': True, 'Cell': True,
     440               'Atoms': { 'Mn1': 'X',
     441                          'O3': 'XU',
     442                          'V4': 'FXU'}}
     443    some_histogram.set_refinements(params)
     444
     445
     446and here is an example for HAP parameters:
     447
     448.. code-block::  python
     449
     450    params = { 'Babinet': 'BabA',
     451               'Extinction': True,
     452               'Mustrain': { 'type': 'uniaxial',
     453                             'direction': [0, 0, 1],
     454                             'refine': True}}
     455    some_phase.set_HAP_refinements(params)
     456
     457Note that the parameters must match the object type and method (phase vs. histogram vs. HAP).
     458
    368459.. _CommandlineInterface:
    369460
    … …  
    372463=======================================
    373464
    374 One way to access these routines is by calling this script
    375 via a command line interface as a shell command, where it is expected to be called as::
    376 
    377        python GSASIIscriptable.py <subcommand> <file.gpx> <options>
     465The routines described above are intended to be called from a Python script, but an
     466alternate way to access some of the same functionality is to
     467invoke the ``GSASIIscriptable.py`` script from
     468the command line usually from within a shell script or batch file. This
     469will usually be done with a command such as::
     470
     471       python <path/>GSASIIscriptable.py <subcommand> <file.gpx> <options>
    378472
    379473    The following subcommands are defined:
    … …  
    420514.. _API:
    421515
    422 ===================================
    423 GSASIIscriptable Application Layer
    424 ===================================
     516============================================================
     517GSASIIscriptable Application Layer 
     518============================================================
    425519
    426520This module provides a large number of classes and modules, as described below.
    … …  
    435529methods inside :class:`G2PwdrData` or :class:`G2Phase`
    436530
    437 ---------------------------------------
    438 GSASIIscriptable Classes and functions
    439 ---------------------------------------
     531---------------------------------------------------------------
     532Complete Documentation: GSASIIscriptable Classes and functions
     533---------------------------------------------------------------
    440534"""
    441535from __future__ import division, print_function
Note: See TracChangeset for help on using the changeset viewer.