I. INTRODUCTION
Learning to use any computer package requires a time investment to master the program's functionality. This is particularly true for scientific software, because methodology, nomenclature, and theory may all need to be mastered. At present, modern crystallographic analysis is hard to imagine without relying on computer systems, so software is integral to the technique. The approach provided for new users to learn a crystallographic package impacts significantly on the utility of that software. The General Structure Analysis System (GSAS-II) software package, discussed here, is a truly modern crystallographic and materials characterization program, developed with a new software methodology. This article describes new approaches that have been employed to provide pedagogical materials for GSAS-II.
GSAS-II provides comprehensive data analysis capabilities for powder and single-crystal diffraction from all types of instruments, including laboratory, synchrotron, and both constant-wavelength and time-of-flight neutron sources (Toby and Von Dreele, Reference Toby and Von Dreele2013). For powder diffraction crystallography and materials characterization, it supports the analysis process beginning-to-end: starting with area detector data calibration and integration, then peak fitting, indexing, structure solution, Rietveld refinement, exploration of the structure through distance and bond angle computation and visualization, and finally pdCIF export (Toby, Reference Toby, Hall and McMahon2005; Hester, Reference Hester2006). It has a unique mode for fitting and extracting results from parametric data sequences, such as operando or in situ experiments, where a number of variables can be associated with each diffractogram, including three user-defined fields. There is no limit to the number of datasets that can be used in a parametric fit and this mode has been used to fit many thousands of patterns in a sequence. GSAS-II provides extensive visualization capabilities to help interpret complex fitted parameters, including probability surfaces and pole figures. More specialized capabilities in GSAS-II include stacking fault modeling, structure solution and structure fitting with rigid-body models (where orientation and torsional modes can be refined), texture measurements, applied stress from distortion of Bragg rings in images, and twinned single-crystal dataset treatment. Analysis for small-angle scattering and reflectometry are also provided (Von Dreele, Reference Von Dreele2014). Capabilities that have been added recently include treatment of 3 + 1 superspace-group modulated structures, magnetic structures, including derivation of all compatible color subgroups (Perez-Mato et al., Reference Perez-Mato, Gallego, Elcoro, Tasci and Aroyo2016), and fitting of instrumental profile parameters from fundamental parameters. Another recent addition is a module that allows a growing range of GSAS-II capabilities to be accessed from Python scripts or shell/batch scripts (O'Donnell et al., Reference O'Donnell, Dreele, Chan and Toby2018).
The predecessor packages to GSAS-II, known as GSAS and EXPGUI, (Toby, Reference Toby2001; Larson and Von Dreele, Reference Larson and Von Dreele2004) have been used widely, and have commonly been selected for initial instruction on Rietveld refinement, because of the wide range of potential types of analyses, the ease of installation and use, and wide range of supported computers (Toby, Reference Toby2007, Reference Toby2010; Lake and Toby, Reference Lake and Toby2011). However, GSAS and EXPGUI require aging compilers/script language interpreters and are no longer being updated. They function with contemporary computer hardware and operating systems, but may not with newer systems. Users of GSAS/EXPGUI are encouraged to switch to GSAS-II. GSAS-II is largely written in Python, is compatible with both Python 2.7 and 3.6+. GSAS-II offers much better visualization capabilities than GSAS/EXPGUI and all capabilities in GSAS-II are supported in the graphical user interface (GUI). Like GSAS/EXPGUI, GSAS-II, runs on Windows, Mac, and Linux and has a simple to use installer. GSAS-II is freely distributed, including all source code, and there are no restrictions or costs for any type of use.
GSAS-II has been developed in a manner different than many older software projects. Traditionally, a set of goals is defined and then software is written to satisfy them. For non-commercial software, it is typical for documentation to be prepared only once the coding is complete. However, GSAS-II has been developed using an “agile” development strategy, where software versions are made available as they are developed and where experience gained through use of the software drives further development. When first made available, GSAS-II had rather limited capabilities, but over a period of more than 5 years, the software has been expanded considerably. Feedback from users has been a valuable contribution to this process.
A significant challenge in such an agile development process is how to instruct users on how to use the program in its current state, but in a way that can be expanded easily as capabilities are added. While a GUI can make use of software more clear, it will still not be obvious to users what capabilities are provided. If a traditional software manual for GSAS-II had been written when the first versions of GSAS-II were made available, it would have needed nearly constant review and revision, adding sections to address expanded capabilities. Further, many scientists now prefer web access for gathering information to printed reports and manuals. This agile development strategy has resulted in a different approach that has been used to provide educational materials for GSAS-II, as described here.
II. GSAS-II TRAINING MATERIALS
As changes are made to the GSAS-II software, they are placed into a subversion (svn) version tracking system. Each set of changes is retained and each set of revisions is assigned a consecutive version number. The files on the subversion server are publically available; this means when changes are placed on the svn server, users can immediately download them. This has allowed GSAS-II development to be extremely responsive to user problem reports, where updates may be posted within hours of when an issue is known. Users are able to check if a newer version of GSAS-II is available and download it from within the GSAS-II help menu, as shown in Figure 1. A similar menu command allows one to reinstall (regress to) a previous version of the software, in case a new bug is present or suspected. Updates usually require small downloads, as only the changes are downloaded, rather than an entire distribution. The svn server also includes a Trac information management system; this system provides a wiki site (http://bit.ly/GSASII) that is used to provide general introductory and overview materials on GSAS-II, including documentation on software installation.
(color online) A view of the main GSAS-II graphical user interface along with the Help menu.
The approach that has been developed to provide users with documentation, since new features have been steadily added to GSAS-II during the years of its development, has been to create a series of tutorial documents, where a new tutorial is created that demonstrates each major new capability as added to the software. Each tutorial is provided as a web page that usually begins with an introduction summarizing the focus of the tutorial, followed by step-by-step instructions that go through an analysis process, including an extensive number of screen images. At present, nearly 40 tutorials have been created. Access to these tutorials is integrated into the GSAS-II help menu (see Figures 1 and 2) and tutorials are viewed in a web browser. The sample data and screen images for all the tutorials require more than three times the disk space needed for the GSAS-II software, so tutorials are downloaded only as selected by the user. Tutorials may be browsed without downloading, either from inside the GSAS-II program, or from the GSAS-II website, but more commonly, users will download a tutorial, along with screen images and any input files, using the GSAS-II tutorials menu command, which also provides an option to download all tutorials.
(color online) The GSAS-II tutorial dialog window (accessed from the help menu) showing different modes for access to the tutorials.
Another document, provided in place of a traditional software manual, is in the form of a larger web page, which has been written to explain the use of the major sections of the GSAS-II GUI and graphics displays. Figure 3(a) shows the beginning of this web page, which describes the GUI layout and function and the actions of menu items and graphics controls. The GUI is designed around the GSAS-II data structure (which is called the data tree). For each section in the tree, there is a matching web page section with an entry that describes what can be done and/or visualized in the GUI section that is displayed when that tree entry is selected; web page sections have headings such as “What can I do here?” Likewise, for graphics windows, the web pages have headings such as “What is plotted here?” or “What can I do with the plot?” While documentation has not yet been completed for all sections of the program, this web page already requires ~40 pages when printed, so GSAS-II provides navigation assistance via context-sensitive help: The help menu offers an item labeled “Help on currently displayed…” and a help button (labeled with a red question mark) is available on the graphics window. When either is used, the help document is opened in a browser and scrolled to the appropriate documentation section. An example of help information, showing part of the documentation for the Covariance data tree entry and associated plot, is given as Figure 3(b).
(color online) The beginning of the GSAS-II help page, where later sections contain context-specific information accessed by the GSAS-II help.
(color online) An example of the context-specific help information available for one section within the GSAS-II program.
Finally, since GSAS-II is open source, and the scientific community is welcomed to read, reuse and/or extend the code, there is also a ~250 page manual for software developers. This is generated via specially formatted comments that are placed within the code using the Sphinx documentation builder, which also creates cross-references and an index. The Readthedocs.org website (http://gsas-ii.rtfd.org) is used to build and host this, and this is where the software developer's manual can be downloaded or browsed. A book is planned to create a comprehensive guide to the mathematics implemented in GSAS-II, as was done in the manual for GSAS.
III. MORE MODERN APPROACHES TO TRAINING MATERIALS
Written documentation, albeit here modernized through web delivery, is the traditional approach to software documentation. However, experience with instructing potential users on GSAS, EXPGUI and GSAS-II has made it clear that written tutorials lack something in comparison to live demonstrations. Potential users benefit from seeing an instructor go through an exercise before they perform it themselves. The tutorials provide the exercises typically used for teaching about GSAS-II, but the provided screen images cannot show all the details for use of the GUI. In previous work, it was noted that web-delivered videos were quite advantageous as educational materials (Toby, Reference Toby2010). Since then, video-only journals such as JoVE (https://www.jove.com) have been introduced (Pasquali, Reference Pasquali2007; Kousha et al., Reference Kousha, Thelwall and Abdoli2012). Instructional videos that show the presenter's computer screen seemingly “allows the viewer to look over the shoulder of the instructor”, seeing the mouse and typing actions used to operate the GUI. The accompanying audio narration of the tutorial text is much easier for many to follow. Contemporary students, who are sometimes called “digital natives” because of their extensive exposure to many forms of computer content, often express a preference for video materials. Such recordings also have the advantage over live presentations because students can view material at their own pace, pausing and repeating sections where needed. Further, when a student performs the tutorial, while comparing their results to the video, it becomes immediately obvious when an error is made because the user's computer screen no longer matches the video. Because of these advantages, most of the GSAS-II introductory tutorials and some of the more advanced tutorials, now have accompanying video versions. These video tutorials vary in duration from 6 to 22 min. Table I provides a list of the tutorials that now have videos available.
Tutorials with video-recorded examples. These videos can be viewed on web page https://subversion.xray.aps.anl.gov/pyGSAS/trunk/help/Tutorials.html.
An intermediate approach between video technology and static screen images, animated graphics, has also been employed in two newer tutorials, Area Detector Calibration with Multiple Distances: Determine Wavelength and Area Detector Calibration with Multiple Distances: Calibrate Detector Distances. In these, multiple screen images have been combined into dynamic images, stored as animated GIFs, which show a progression of events. These moving images can be included in web pages and bridge a gap between a static document and a full video tutorial; it is hoped that this can decrease confusion and gaps in understanding among those learning GSAS-II.
IV. CONCLUSIONS
Modern software development techniques prompt the development of new approaches for documenting and teaching use of that software. Tutorials make GSAS-II easier to learn and use and allow the documentation process to keep pace with the evolution of the software. Video versions of tutorials and use of animated graphics addresses some of the preferences by younger scientists and may make the process more effective for all. While the main focus for the developers will continue to be bug correction and introduction of new features, enhancements of tutorials will be one area where the community can contribute to the effectiveness of these materials. The addition of captioning can allow access to those unable to use audio materials. Translation of tutorials to other languages would also provide greater access.
ACKNOWLEDGEMENTS
The authors would like to thank the Argonne Education and Outreach Programs Division for making it possible for K.G. and C.H. to participate in this project. BHT thanks Diane Pies Toby, Ph.D., for a critical reading of this work.
FUNDING INFORMATION
This work was performed at the Advanced Photon Source, an Office of Science User Facility operated for the US Department of Energy (DOE) Office of Science by Argonne National Laboratory, and was supported by the US DOE under Contract No. DE-AC02-06CH11357.
