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