WIP: partial edits to ISO tutorial (not yet in index)

Author: briantoby

MDtutorials/.gitignore

@@ -0,0 +1,3 @@
+docs/
+mkdocs.yml
+requirements.txt

MDtutorials/k_vec_isodistort/k_vec_isodistort.md

@@ -1,5 +1,5 @@
 ---
-title: Use the k-vector searched with GSAS-II to talk to ISODISTORT
+# Tutorial: Use of  ISODISTORT with a k-vector found by GSAS-II
 ---
 <!--- Don't change the HTML version of this file; edit the .md version -->
 
@@ -9,31 +9,44 @@ title: Use the k-vector searched with GSAS-II to talk to ISODISTORT
 
 ## Intro
 
-When the symmetry of a system is lowering through a group-subgroup pathway while going through a phase transition, one can try to use the emerging satellite peaks in the diffraction pattern to search for a k-vector that best explains the satellite peak positions. Refer to the two tutorials regarding the k-vector search in GSAS-II, [here](https://advancedphotonsource.github.io/GSAS-II-tutorials/k_vec_tutorial/k_vec_tutorial.html) and [here](https://advancedphotonsource.github.io/GSAS-II-tutorials/k_vec_tutorial_non_zero/k_vec_tutorial_non_zero.html). Once we obtain the alternative k-vector, we can move forward to use the k-vector to talk to ISODISTORT to search for all the isotropic subgroups that are compatible with the k-vector. It covers all the irreducible representations (IRs) compatible with the k-vector and the order parameters associated with each IR. An exhaustive refinement can then be performed for each of the candidate subgroup against the experimental diffraction data of the low symmetry phase. In this tutorial, we will demonstrate how to use the implementation in GSAS-II regarding this. Going through the steps to be presented here, we are expecting a series of GSAS-II project file, each for a specific subgroup candidate.
+When the symmetry of a system is lowered while going through a phase transition, it is usually through a group-subgroup pathway. One can try to use the emerging satellite peaks in the diffraction pattern to search for a magnetic [k-vector (propogation vector)](https://conference.sns.gov/event/176/attachments/242/1921/Magnetic_Symmetry_an_overview_of_Representational_Analysis_and_Magnetic_Space_groups.pdf) that best describes the relation between the nuclear and magnetic unit cells. See the two tutorials, [k-vector searching #1 (all-zero vector)](https://advancedphotonsource.github.io/GSAS-II-tutorials/k_vec_tutorial/k_vec_tutorial.html) and [k-vector searching #2 (non-zero vector)](https://advancedphotonsource.github.io/GSAS-II-tutorials/k_vec_tutorial_non_zero/k_vec_tutorial_non_zero.html), for more on k-vector searching in GSAS-II.
+Once we obtain the alternative <!-- why alternative? --> 
+k-vector, we can move forward providing the k-vector within the ISODISTORT web server to search for all the isotropic subgroups that are compatible with the k-vector. This locates all the irreducible representations (IRs) compatible with the k-vector and the order parameters associated with each IR. An exhaustive set of refinements can then be performed for each candidate subgroup against the experimental diffraction data to determine the optimal symmetry for the low symmetry magnetic phase. In this tutorial, we will demonstrate how to use the implementation in GSAS-II to do this. To perform the steps to be presented here, we will need a GSAS-II project (.gpx) file for the parent chemical ("nuclear") structure and will then generate new project file(s) for each candiate subgroup structure.
 
-For the demonstration purpose, here we are using the SrTiO${}_3$ structure as the parent and an arbitrarily generated subgroup (space group: $P4/mmm$) with a k-vector of (0, 1/2, 0). We simulated the powder diffraction data for both, with a typical instrument parameter file from the POWGEN diffractometer at SNS, ORNL. We will then use the simulated data to conduct a 'reverse engineering'. Namely, we can fit the simulated data from the subgroup with the parent phase and from there, we can use the residual peaks to extract the k-vector candidate and for a selected k-vector, we can construct GSAS-II project files for each of the subgroup candidate. We will `not` perform the exhaustive refinement for all the generated project files, though. `In the future, we can think about creating a wrapper script to run through all the generated candidate subgroups in a programmable manner.`
+To demonstrate this for this tutorial, we will generate simulated data for the SrTiO${}_3$ (STO) structure in space group $P 4/mmm$) and will select an arbitrarily generated subgroup with a k-vector of (0, 1/2, 0). We will simulate the powder diffraction data for both, with a typical instrument parameter file from the POWGEN diffractometer at SNS, ORNL. We will then use the simulated data to "reverse engineer" this simulation, meaning we can fit the simulated data first to discover the k-vector that allows generation of the additional magnetic peaks that are not fit by the parent structure. With that k-vector and the parent structure, we will use GSAS-II and ISODISTORT to construct GSAS-II project files for each of the subgroup candidates. The exhaustive refinement for all the generated project files will not be performed, here. At some point in the future It is under consideration that in the future, a capability may be added to GSAS-II to systematically fit all the generated subgroup project files. 
 
-Here below is shown the two structures used in this tutorial -- (left) the parent STO structure and (right) the arbitrarily generated subgroup structure.
+Below is shown the two structures used in this tutorial -- (left) the parent STO structure and (right) the arbitrarily generated subgroup structure.
 
-<img src="./imgs/structures.png" alt="order parameter plot" style="width:500px;">
+<img src="./imgs/structures.png" alt="Parent and subgroup structures" style="width:500px;">
 
 ## Data Simulation
 
-For the data simulation with a CIF file, for sure we can use GSAS-II to do it. But here we want to showcase a convenient web-based tool for such a purpose. In fact, the backend calculation engine is still using GSAS-II, it is just that we will be doing this through an easy-accessible web interface. First, download the two structure files we include in the tutorial, `STO_Parent.cif` and `STO_Subgroup.cif`, together with the instrument parameter file we will be using for the simulation `powgen_profile_lwf.instprm`. Then go to the website, [https://addie.ornl.gov/simulatingpowder](https://addie.ornl.gov/simulatingpowder) (or, go to [https://addie.ornl.gov](https://addie.ornl.gov), then `Scattering Tools` => `SimulatePowder`). The interface looks like the figure to the right.
+The data simulation from a CIF file could be performed directly within GSAS-II, but for this tutorial we wish to showcase a convenient web-based tool for such a purpose, that uses GSAS-II as a backend calculation engine. First, from [this tutorial's exercise files](data/index.html) download the two needed structure files, `STO_Parent.cif` and `STO_Subgroup.cif`, together with the instrument parameter file we will be using for the simulation `powgen_profile_lwf.instprm`. Then go to the website, [https://addie.ornl.gov/simulatingpowder](https://addie.ornl.gov/simulatingpowder) (or, go to [https://addie.ornl.gov](https://addie.ornl.gov), then click on `Scattering Tools` and on the next page `SimulatePowder`). The web interface looks like the figure to the right.
 
 ![ADDIE Powder Diff Simulation](imgs/addie_simu.png)
 
-There we can upload the CIF file and the instrument parameter file to use for the simulation and click on the `Submit` button. One can notice that we have a dropdown selection menu there in the interface from which we can select one of the pre-included instruments such as NOMAD and POWGEN at SNS, ORNL and HB-2A (Powder) and HB-2C (WAND^2), HFIR, ORNL. One can also select the scatterer type and put in some optional parameters (follow the link there to see what options we can put in). The resulted here will be like the figure to the right.
+There we can upload the CIF file and the instrument parameter file to use for the simulation and click on the `Submit` button. Supply structure `STO_Subgroup.cif`  and  the instrument parameter file we will be using for the simulation `powgen_profile_lwf.instprm`. The result will be like the figure to the right. The simulation is also displayed in $d$ and $Q$ space units, but we do not need them here. 
 
 ![ADDIE Powder Diff Simulation Result](imgs/addie_simu_result.png)
 
-We can download the simulated powder diffraction data by clicking on the `Datafile Download` button on top of the time-of-flight (TOF) result presented at the very top. Data in $d$ and $Q$ space are also presented but we do not need them here. We can do this for both CIF files provided here and if we do not change the CIF file names (`STO_Parent.cif` and `STO_Subgroup.cif`), we will obtain the following two simulated powder diffraction patterns, `STO_Parent_neutron_powder_calc.txt` and `STO_Subgroup_neutron_powder_calc.txt`, for the parent and subgroup phase, respectively. We will use these two simulated data files for the next part of the tutorial. Before that, if we want to have a quick comparison between the two datasets, we can go to [https://addie.ornl.gov/plotter](https://addie.ornl.gov/plotter), select the `Multiple Files Mode` and upload the two data files for a quick comparison plot. Here to the right is presented a demo for the tool.
+We can download the simulated powder diffraction data by clicking on the `Datafile Download` button on top of the time-of-flight (TOF) result presented at the very top.
+The downloaded data file will be named based on the CIF files name and thus will be `STO_Subgroup_neutron_powder_calc.txt`. 
+
+Press the `Go Back` button and repeat the process, uploading the structure file `STO_Parent.cif` and the same instrument parameter file (`powgen_profile_lwf.instprm`). Download that pattern which will be named `STO_Parent_neutron_powder_calc.txt`.
+
+We can do this for both CIF files provided here and if we do not change the CIF file names (`STO_Parent.cif` and `STO_Subgroup.cif`), we will obtain the following two simulated powder diffraction patterns, `STO_Parent_neutron_powder_calc.txt` and `STO_Subgroup_neutron_powder_calc.txt`,
+
+Note that this web page can also be used without supplying an instrument parameter file. The alternative is to use the dropdown selection menu, where one can select one of the predefined ORNL instruments such as NOMAD and POWGEN at the SNS, and HB-2A (Powder) and HB-2C (WAND^2), HFIR. Other options include selecting the probe type to simulate with x-rays or to modify the computation with optional parameters (follow the link there to see what options are offered). 
+
+Another useful option of this web interface allows plotting the two simulated powder diffraction patterns, `STO_Parent_neutron_powder_calc.txt` and `STO_Subgroup_neutron_powder_calc.txt`, for the parent and subgroup phase, respectively. (Optional) To make a quick comparison between the two datasets, we can go to [https://addie.ornl.gov/plotter](https://addie.ornl.gov/plotter), select the `Multiple Files Mode` and upload the two data files for a quick comparison plot. Here to the right is presented a demo for the tool.
 
 ![ADDIE Data Plotter](imgs/addie_plotter.gif)
 
 ## Refinement of the Subgroup Data with the Parent Phase
 
-Since we are dealing with the simulated data, here we are not going to refine the parent data with the parent phase since that will be trivial and we are expecting a 'perfect' refinement. To start, we load in the subgroup simulated data and refine it with the parent phase, pretending that we don't know the subgroup structure. First, launch the GSAS-II GUI, and then proceed to the menu item `Import` => `Powder Data` => `from Topas xyz/qye or 2th Fit2D chi/qchi file`, followed by browsing files and selecting the simulated data from previous step, namely `STO_Subgroup_neutron_powder_calc.txt`. If `ADDIE` interface was used previously for simulating the data, the downloaded simulated data will be ending with `.txt`. In this case, we have to select `any file (*.*)` from the file type dropdown selection while trying to find the previously saved simulated data. Once the data is selected, we want to click on `Yes` when prompted with the window to confirm the selection. Automatically, this will be followed by GSAS-II letting us to select the instrument parameter file. Here, we want to select exactly the one that was used above for the data simulation, i.e., `powgen_profile_lwf.instprm`. By default, GSAS-II assumes `GSAS iparm file (*.prm, *.inst, *.ins)`. Therefore, here we want to select `GSAS-II iparm file (*.instprm)` from the file type dropdown selection so that we can select the instrument parameter file `powgen_profile_lwf.instprm` to use.
+Since we are dealing with simulated data here, we are not going to refine the parent phase data against the simulated parent phase data since that will produce the trivial result of reproducing the initial structure, but in a real experiment one would do this to obtain an optimal model for the non-magnetic structure. To start, we load in the simulated data using the subgroup and refine against it with the parent phase, as if we were not aware of the subgroup structure. 
+
+First, launch the GSAS-II GUI, and then proceed to the menu item `Import` => `Powder Data` => `from Topas xyz/qye or 2th Fit2D chi/qchi file`, followed by browsing files and selecting the simulated data from previous step, namely `STO_Subgroup_neutron_powder_calc.txt`. If `ADDIE` interface was used previously for simulating the data, the downloaded simulated data file will have file extension `.txt`. So that GSAS-II will find the file in the selection window, we have to select `any file (*.*)` from the file type dropdown selection to find the previously saved simulated data. Once the data is selected, we want to click on `Yes` when prompted with the window to confirm the selection. Automatically, this will be followed by GSAS-II letting us to select the instrument parameter file. Here, we want to select exactly the one that was used above for the data simulation, i.e., `powgen_profile_lwf.instprm`. By default, GSAS-II assumes `GSAS iparm file (*.prm, *.inst, *.ins)`. Therefore, here we want to select `GSAS-II iparm file (*.instprm)` from the file type dropdown selection so that we can select the instrument parameter file `powgen_profile_lwf.instprm` to use.
 
 Next, proceed to the menu item `Import` => `Phase` => `from CIF file` and select the parent structure CIF file, `STO_Parent.cif`. Click `Yes` to confirm the selection when prompted. When asked, we want to give the phase a name -- here I am using `STO_parent`. GSAS-II will then let us select which histogram to attach the phase to -- here we only have one histogram and that is for sure the one we want to select. Just check the box in front of the histogram in the prompted window and click on `OK`. Without any other settings, let's just go ahead with the refinement -- go the menu `Calculate` => `Refine`. If we haven't saved the project yet, we will be asked to first save the project before proceeding and we can give the project a name like `test_subgroup_data_with_parent_structure.gpx` (we don't have to give the extension explicitly). Since we are dealing with the simulated data here, even though we are fitting the data simulated from the subgroup structure with the parent phase, we are still getting a very small Rwp (0.031%). However, if we zoom in the plot, we will see some peaks are not indexed by the parent structure, as seen to the right.
 

MDtutorials/k_vec_tutorial/k_vec_tutorial.md

@@ -1,5 +1,5 @@
 ---
-title: k-vector searching in GSAS-II #1 (all zero vector)
+# Tutorial: k-vector searching in GSAS-II #1 (all-zero vector)
 ---
 <!--- Don't change the HTML version of this file; edit the .md version -->
 

MDtutorials/k_vec_tutorial_non_zero/k_vec_tutorial_non_zero.md

@@ -1,5 +1,5 @@
 ---
-title: k-vector searching in GSAS-II #2 (non-zero k-vector)
+# Tutorial: k-vector searching in GSAS-II #2 (non-zero vector) 
 ---
 <!--- Don't change the HTML version of this file; edit the .md version -->
 

webdocs/index.rst

@@ -112,7 +112,7 @@ There are many options within GSAS-II that allow you to tailor aspects
 of the program to operate differently. These are described
 here. Options are available to change how
 powder diffraction refinement results are plotted or change defaults
-used in different parts of the program, , for example. 
+used in different parts of the program, for example. 
 
 .. toctree::