Ignore:
Timestamp:
Sep 19, 2017 4:27:01 PM (5 years ago)
Author:
odonnell
Message:

more documentation for G2Project

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/GSASIIscriptable.py

    r3090 r3091  
    1414Routines for reading, writing, modifying and creating GSAS-II project (.gpx) files.
    1515
    16 Supports a command line interface as well.
    17 
    18 Look at :class:`G2Project` to start.
     16Supports a command line interface as well. Run `python GSASIIscriptable.py --help` to
     17show the available subcommands, and inspect each subcommand with
     18`python GSASIIscriptable.py <subcommand> --help`.
     19
     20This file specifies several wrapper classes around GSAS-II data representations.
     21They all inherit from :class:`G2ObjectWrapper`. The chief class is :class:`G2Project`,
     22which represents an entire GSAS-II project and provides several methods to access
     23phases, powder histograms, and execute Rietveld refinements.
     24
     25.. _Refinement_parameters_kinds:
    1926
    2027=====================
    … …  
    2431There are three classes of refinement parameters:
    2532
    26     * Histogram. Turned on and off through :func:`~G2PwdrData.set_refinements`
    27       and :func:`~G2PwdrData.clear_refinements`
    28     * Phase. Turned on and off through :func:`~G2Phase.set_refinements`
    29       and :func:`~G2Phase.clear_refinements`
     33    * Histogram. Turned on and off through :func:`G2PwdrData.set_refinements`
     34      and :func:`G2PwdrData.clear_refinements`
     35    * Phase. Turned on and off through :func:`G2Phase.set_refinements`
     36      and :func:`G2Phase.clear_refinements`
    3037    * Histogram-and-phase (HAP). Turned on and off through
    31       :func:`~G2Phase.set_HAP_refinements` and :func:`~G2Phase.clear_HAP_refinements`
     38      :func:`G2Phase.set_HAP_refinements` and :func:`G2Phase.clear_HAP_refinements`
    3239
    3340
    … …  
    3643============================
    3744
     45Refinement parameters are specified as dictionaries, supplied to any of the functions
     46named in :ref:`Refinement_parameters_kinds`. Each method accepts a different set
     47of keys, described below for each of the three parameter classes.
     48
    3849.. _Histogram_parameters_table:
    3950
    … …  
    4253--------------------
    4354
    44 This table describes the dictionaries supplied to :func:`~G2PwdrData.set_refinements`
    45 and :func:`~G2PwdrData.clear_refinements`.
    46 
    47 .. tabularcolumns:: |l|p|
     55This table describes the dictionaries supplied to :func:`G2PwdrData.set_refinements`
     56and :func:`G2PwdrData.clear_refinements`.
     57
     58Example:
     59
     60.. code-block::  python
     61
     62    params = {'set': { 'Limits': [0.8, 12.0],
     63                       'Sample Parameters': ['Absorption', 'Contrast', 'DisplaceX'],
     64                       'Background': {'type': 'chebyschev', 'refine': True}},
     65              'clear': {'Instrument Parameters': ['U', 'V', 'W']}}
     66    some_histogram.set_refinements(params['set'])
     67    some_histogram.clear_refinements(params['clear'])
     68
     69.. tabularcolumns:: |l|p|p|
    4870
    4971===================== ====================  ====================
    … …  
    5173===================== ====================  ====================
    5274Limits                                      The 2-theta range of values to consider. Can
    53                                             be either a dictionary of 'low' and 'high',
     75                                            be either a dictionary of 'low' and/or 'high',
    5476                                            or a list of 2 items [low, high]
    5577\                     low                   Sets the low limit
    … …  
    89111----------------
    90112
    91 This table describes the dictionaries supplied to :func:`~G2Phase.set_refinements`
    92 and :func:`~G2Phase.clear_refinements`.
     113This table describes the dictionaries supplied to :func:`G2Phase.set_refinements`
     114and :func:`G2Phase.clear_refinements`.
     115
     116Example:
     117
     118.. code-block::  python
     119
     120    params = { 'LeBail': True, 'Cell': True,
     121               'Atoms': { 'Mn1': 'X',
     122                          'O3': 'XU',
     123                          'V4': 'FXU'}}
     124    some_histogram.set_refinements(params)
     125
     126.. tabularcolumns:: |l|p|
    93127
    94128===================== ====================
    … …  
    112146------------------------------
    113147
    114 This table describes the dictionaries supplied to :func:`~G2Phase.set_HAP_refinements`
    115 and :func:`~G2Phase.clear_HAP_refinements`.
    116 
    117 ===================== ===================== ====================
    118 key                   subkey                explanation
    119 ===================== ===================== ====================
    120 Babinet                                     Should be a **list** of the following
    121                                             subkeys. If not, assumes both
    122                                             BabA and BabU
     148This table describes the dictionaries supplied to :func:`G2Phase.set_HAP_refinements`
     149and :func:`G2Phase.clear_HAP_refinements`.
     150
     151Example:
     152
     153.. code-block::  python
     154
     155    params = { 'Babinet': 'BabA',
     156               'Extinction': True,
     157               'Mustrain': { 'type': 'uniaxial',
     158                             'direction': [0, 0, 1],
     159                             'refine': True}}
     160    some_phase.set_HAP_refinements(params)
     161
     162.. tabularcolumns:: |l|p|p|
     163
     164===================== =====================  ====================
     165key                   subkey                 explanation
     166===================== =====================  ====================
     167Babinet                                      Should be a **list** of the following
     168                                             subkeys. If not, assumes both
     169                                             BabA and BabU
    123170\                     BabA
    124171\                     BabU
    125 Extinction                                  Should be boolean, whether or not to
    126                                             refine.
    127 HStrain                                     Should be boolean, whether or not to
    128                                             refine.
     172Extinction                                   Should be boolean, whether or not to
     173                                             refine.
     174HStrain                                      Should be boolean, whether or not to
     175                                             refine.
    129176Mustrain
    130 \                     type                  Mustrain model. One of 'isotropic',
    131                                             'uniaxial', or 'generalized'
    132 \                     direction             For uniaxial. A list of three integers,
    133                                             the [hkl] direction of the axis.
    134 \                     refine                Usually boolean, whether or not to refine.
    135                                             When in doubt, set it to true.
    136                                             For uniaxial model, can specify list
    137                                             of 'axial' or 'equatorial'. If boolean
    138                                             given sets both axial and equatorial.
    139 Pref.Ori.                                   Boolean, whether to refine
    140 Show                                        Boolean, whether to refine
    141 Size                                        Not implemented
    142 Use                                         Boolean, whether to refine
    143 Scale                                       Boolean, whether to refine
    144 ===================== ===================== ====================
     177\                     type                   Mustrain model. One of 'isotropic',
     178                                             'uniaxial', or 'generalized'
     179\                     direction              For uniaxial. A list of three integers,
     180                                             the [hkl] direction of the axis.
     181\                     refine                 Usually boolean, whether or not to refine.
     182                                             When in doubt, set it to true.
     183                                             For uniaxial model, can specify list
     184                                             of 'axial' or 'equatorial'. If boolean
     185                                             given sets both axial and equatorial.
     186Pref.Ori.                                    Boolean, whether to refine
     187Show                                         Boolean, whether to refine
     188Size                                         Not implemented
     189Use                                          Boolean, whether to refine
     190Scale                                        Boolean, whether to refine
     191===================== =====================  ====================
    145192
    146193============================
    … …  
    782829
    783830class G2Project(G2ObjectWrapper):
    784     """Represents an entire GSAS-II project."""
     831    """
     832    Represents an entire GSAS-II project.
     833
     834    There are two ways to initialize it:
     835
     836    >>> # Load an existing project file
     837    >>> proj = G2Project('filename.gpx')
     838    >>> # Create a new project
     839    >>> proj = G2Project(filename='new_file.gpx')
     840    >>> # Specify an author
     841    >>> proj = G2Project(author='Dr. So-And-So', filename='my_data.gpx')
     842
     843    Histograms can be accessed easily.
     844
     845    >>> # By name
     846    >>> hist = proj.histogram('PWDR my-histogram-name')
     847    >>> # Or by index
     848    >>> hist = proj.histogram(0)
     849    >>> assert hist.id == 0
     850    >>> # Or by random id
     851    >>> assert hist == proj.histogram(hist.ranId)
     852
     853    Phases can be accessed the same way.
     854
     855    >>> phase = proj.phase('name of phase')
     856
     857    New data can also be loaded via :func:`~G2Project.add_phase` and
     858    :func:`~G2Project.add_powder_histogram`.
     859
     860    >>> hist = proj.add_powder_histogram('some_data_file.chi',
     861                                         'instrument_parameters.prm')
     862    >>> phase = proj.add_phase('my_phase.cif', histograms=[hist])
     863
     864    Parameters for Rietveld refinement can be turned on and off as well.
     865    See :func:`~G2Project.set_refinement`, :func:`~G2Project.refine`,
     866    :func:`~G2Project.iter_refinements`, :func:`~G2Project.do_refinements`.
     867    """
    785868    def __init__(self, gpxfile=None, author=None, filename=None):
    786869        """Loads a GSAS-II project from a specified filename.
    … …  
    22322315    result.func(result)
    22332316
    2234     # argv = sys.argv
    2235     # if len(argv) > 1 and argv[1] in subcommands:
    2236     #     subcommands[argv[1]](*argv[2:])
    2237     # elif len(argv) == 1 or argv[1] in ('help', '--help', '-h'):
    2238     #     # TODO print usage
    2239     #     subcommand_names = ' | '.join(sorted(subcommands.keys()))
    2240     #     print("USAGE: {} [ {} ] ...".format(argv[0], subcommand_names))
    2241     # else:
    2242     #     print("Unknown subcommand: {}".format(argv[1]))
    2243     #     print("Available subcommands:")
    2244     #     for name in sorted(subcommands.keys()):
    2245     #         print("\t{}".format(name))
    2246     #     sys.exit(-1)
    2247     # sys.exit(0)
    2248 
    22492317if __name__ == '__main__':
    22502318    main()
    2251 
    2252 
    2253     # from refinements.py
    2254 #      USAGE = """USAGE: {} datafile instparams phasefile projectname refinements
    2255 
    2256 # datafile:    Input powder data
    2257 # intparams:   Corresponding instrument parameter file
    2258 # phasefile:   Phase to refine against data
    2259 # projectname: Project file to be created, should end in .gpx
    2260 # refinements: JSON file of refinements to be executed
    2261 # """
    2262 #     try:
    2263 #         datafile, instprm, phasefile, projectname, refinements = sys.argv[1:]
    2264 #     except ValueError:
    2265 #         print(USAGE.format(sys.argv[0]))
    2266 #         sys.exit(-1)
    2267 
    2268 #     try:
    2269 #         with open(refinements) as f:
    2270 #             refinements = json.load(f)
    2271 #     except IOError:
    2272 #         print("No such refinements file: {}".format(refinements))
    2273 
    2274 #     print("Creating project file \"{}\"...".format(projectname))
    2275 #     proj = G2Project(filename=projectname)
    2276 #     # Add the histogram
    2277 #     hist = proj.add_powder_histogram(datafile, instprm)
    2278 #     # Add the phase, and associate it with the histogram
    2279 #     proj.add_phase(phasefile, histograms=[hist.name])
    2280 
    2281 #     proj.do_refinements(refinements['refinements'])
    2282 #     proj.save()
    2283 
    2284 
    2285     # from gpx_dumper
    2286     # import IPython.lib.pretty as pretty
    2287     # proj, nameList = LoadDictFromProjFile(sys.argv[1])
    2288     # print("names:", nameList)
    2289     # for key, val in proj.items():
    2290     #     print(key, ":", sep='')
    2291     #     pretty.pprint(val)
Note: See TracChangeset for help on using the changeset viewer.