Running a GSAS-II Refinement from the Command Line

  • Exercise files are found here

    In this training example we show a unix script that duplicates the Python Scripting GSAS-II tutorial (which shows how to script the GSAS-II CW Combined Refinement tutorial refinement.)


    This exercise assumes that the reader has reviewed the software documentation on the GSASIIscriptable module ( with special attention to the Command-line Interface section. Note that this tutorial duplicates the Single Step Approach section of the Scripting GSAS-II tutorial, which should be reviewed before this tutorial is read. It may also be useful to review the GSAS-II CW Combined Refinement tutorial that this exercise is modeled upon, which explains why each refinement step is being used.

    The exercise can be performed by placing all of the shell commands into a script, (which can also be downloaded here), but it is also possible to use copy and paste to execute the commands into a terminal window on a Mac or Linux computer (this likely works but has not been tried with Windows Subsystem for Linux).

    Finally, download from the following files: "PBSO4.XRA", "INST_XRY.PRM", "PBSO4.CWN", "inst_d1a.prm" and "PbSO4-Wyckoff.cif" and make a note of their location for the next step.

    0: Create variables for paths

    To simplify the subsequent commands, let's define variables with the path of the data files and the path to where GSAS-II is installed:
    Note that we will run the Python found in the path. If Python needs to be executed from a different location, it might be useful to also define a variable that points to that.

    1: Create a GSAS-II project and add a phase and histogram

    The first step in this exercise is to create the GSAS-II project and then add this two powder datasets and a phase to the project. Note that in this example, it is possible to do all this in a single step, but this is done here with two commands, in part to demonstrate command options only available with the "add" command (-hf, -pf and -l, which select formats for the histogram and phase files, as well as, designate which histograms are linked to the phase, respectively.)
    Note since the "add" command offers the "-l" (or "--histlist") option and "create" does not, if the added phase(s) will be linked to only some histograms, the "add" command is required.

    2: Create a JSON file to conduct the refinement

    The following single command creates a JSON file. This contains a representation of Python dict structure. JSON syntax is quite close to Python, except that the boolean key words (true and false) are all lower case and that while use of extra commas at ends of dicts and lists is allowed in Python, it is not in JSON.
    This code example requires a fair amount of explaination. Note that the first and last lines (cat and EOF) are used to create the file (example.json) from the shell and could be eliminated if the file were to be created directly in an editor.

    There are two entries in the dict, refinements, which defines the steps to be followed in the refinement, and code, which defines Python code to be executed after the GSAS-II project is read in, but before the refinement is performed.

    Performs the same actions as are described in steps 5-10 in the Scripting GSAS-II tutorial. The Single Step section shows these steps collapsed to a list of dicts.
    Note that since JSON does not offer a method to quote multiline strings, this dict entry is defined as a list of strings, which are concatenated as separate Python lines. This Python code will be evaluated [using expr()] inside function refine where variable proj is defined as the current G2Project.

    In this example, the function HistStats is defined as before, but now a global statement is needed so that this function is visible where it will be used. Note that the two statements used to set GSAS-II parameters directly (from steps 4 and 9 in the Scripting GSAS-II tutorial) are moved here and are referenced with the variable proj rather than gpx.

    3: Execute the refinement

    The final command executes the contents of the JSON file:

    Command Line Scripts in Windows

    While scripting is more commonly done in unix-type environments (Mac and Linux), it is also possible to use the GSASIIscriptable capability from a Windows batch (.bat) file. Note that the syntax is slightly different, but follows the same general rules. The following commands reproduce the above exercise in Windows.
    Note that for simplicity, it is assumed that the example.JSON file has been created in a text editor or has been downloaded along with the required data files (download link).
    Last modified: Mon Jun 1 15:08:36 CDT 2020