{ "cells": [ { "cell_type": "markdown", "id": "5c275cb1-7a6f-4ba5-9b68-233d12ed1d99", "metadata": {}, "source": [ "Post-processing\n", "===" ] }, { "cell_type": "markdown", "id": "f40c40ab-fe76-479a-b96f-ffa631f26a4c", "metadata": {}, "source": [ "Usually with the auto-reduced data (see for here more) or the manually reduced data (see here for more), one can already perform the total scattering data analysis, using, e.g., the unit-cell baesd approach. Tools available for such analysis can be found here. The symmetry constraint on the structural model for such unit-cell based approaches guarantees a limited parameter space, as compared to the degree of freedom of the data. In such a situation, one can safely treat the scale as one of the refinable parameters. However, this is not that much the case for the supercell based approach for total scattering data analysis, such as the reverse Monte Carlo (RMC) modeling. With the supercell approach, symmetry constraint will be completely removed after expanding the crystallographic unit cell to a supercell. The model has large number of degrees of freedom and will be driven completely by the data. Although some constraint could be added based on geometrical, physical, or chemical considerations, still the degree of freedom is too large as compared to the total number of data points involved in the modeling, and therefore it is unavoidable one may have the concerns about overfitting. Treating the RMC modeling in a statistical manner, by constructing an ensemble of RMC modeling trials, is a commonly used approach. On the data side, it requires one to treat the data more rigorously, especially concerning the data scaling -- it is always the best practice to try to make sure the data is on an absolute scale, which means the scale of the data and the model is directly comparable without the need for an extra scale factor. This section will cover the post-reduction treatment of the total scattering data and here ***we will be assuming the using of RMCProfile package for the total scattering data modeling***. For details about how to get RMCProfile to work, refer to the link here and here." ] }, { "cell_type": "markdown", "id": "436d2e0e-0ad4-4256-bc25-fbd7378ccf5f", "metadata": {}, "source": [ "## Data Format Checking\n", "\n", "1. Reciprocal space\n", "\n", " In RMCProfile, we follow the convention of defining symbols for various functions as presented in section-2 of Ref. {cite}`dkeents`. It is always strongly recommended that before feeding the data into RMCProfile, we should check the format of the data to see whether it is consistent with what we specify in the input for RMCProfile. For example, in our RMCProfile control file we specify our data format to be \"F(Q)\", that means we are referring our data to be the same format as defined by Eqn. (14) in Ref. [1]. It is noteworthy that in the community, people use the same symbol \"F(Q)\" to represent another format of the reciprocal space data, which is something like $Q[S(Q)-1]$, where S(Q) is the normalized total scattering structure factor as quoted in Eqn. (19-21) in Ref. {cite}`dkeents`. To tell which version of the data that the symbol \"F(Q)\" is representing, we can plot the data and inspect the low-Q region – if it is following our RMCProfile definition, the low-Q level should be somewhat sitting on a flat level (though, in practice it may not be purely flat due to low-Q noise). If it is following the $Q[S(Q)-1]$ definition, the low-Q level should then be sitting on an obvious slope due to the multiplicative $Q$ term in the definition.\n", "\n", "2. Real space\n", "\n", " Similarly in real space, we also need to pay attention to the representation of the same symbol used in the community for different definitions. Again, in RMCProfile, we follow the definition as given in section-2 in Ref. {cite}`dkeents`. For example, when we say our data is in \"G(r)\" format, we mean Eqn. (10) in Ref. {cite}`dkeents`. The asymptotic behavior at low-$r$ and high-$r$ region is accordingly presented in Eqn. (15) in Ref. {cite}`dkeents`. Sometimes, with the same symbol \"G(r)\", one may mean the definition as in Eqn. (43) in Ref. {cite}`dkeents`, e.g., in `pdffit` community. The way to tell which version we mean by \"G(r)\" is similar as above -- we plot the data and inspect the low-$r$ region. If we see our data is sitting on an obvious slope, that means we have the definition as in the `pdffit` community. Otherwise, if the level in the low-$r$ region is somewhat flat, we are following the RMCProfile definition. After all, we need to do the necessary homework to check the data before throwing it into RMCProfile. The fitting engine will take what we tell it as granted and do whatever it can do to fit the data. So, if we tell it something wrong, it can never do it right." ] }, { "cell_type": "markdown", "id": "0e014960-e51d-4f50-9c02-2710d49947be", "metadata": {}, "source": [ "## Rebin\n", "\n", "Following the definition of discrete Fourier transform (see Wikipedia, for example), we require the data to be transformed to be sitting on an equally-spaced grid. If our original data is not in such format, we could use the tool `rebin` that is bundled in the RMCProfile package to rebin the data to be equally-space. Usage of this tool is straightforward -- just input the starting and ending points together with the interval following the order as prompted on terminal, it should do the job properly." ] }, { "cell_type": "markdown", "id": "7f750e2e-6da7-4773-ba7f-dfc91bfd3e6e", "metadata": {}, "source": [ "## Scaling\n", "\n", "To rescale the total scattering data (with the aim of bringing the data to an absolute scale), we can use the `stog_new` tool bundled in RMCProfile package. Here we have a template input for this tool.\n", "\n", "> N.B. Comments here are for instruction purpose only -- in pratice when running `stog_new`, comments are not allowed.\n", "\n", "```\n", "1 # Number of files\n", "input_binned_data.dat # Input file name\n", "0.4 30.0 # Qmin Qmax\n", "0 1 # yoffset yscale, so that output_y = data/yscale + yoffset\n", "0 # Qoffset, normally we can leave it as 0\n", "scale.sq # scaled S(Q)\n", "scale.gr # scaled G(r)\n", "50 # rmax\n", "5000 # Number of points in r-space\n", "N # windows function? (which makes the peaks more smooth, less noise, less ripples)\n", "0.0764 # number density (angstrom^-3)\n", "0 # yoffset, normally we can keep it as 0\n", "N # Try again, normally keep it as 'N'\n", "Y # Fourier Filter?\n", "1.0 # rcutoff for Fourier filter, meaning data in real-space below the\n", " # cutoff will be filtered out. The corresponding components will also be\n", " # removed in Q-space\n", "scale_ft.sq # Fourier filtered S(Q)\n", "scale_ft.gr # Fourier filtered G(r)\n", "0.08 # Faber-Ziman coefficient, for X-ray, if the data has been normalized, we can\n", " # put 1 here\n", "scale_ft_rmc.fq # F(Q) used by RMC\n", "scale_ft_rmc.gr # G(r) used by RMC\n", "scale_ft_rmc.dr # D(r) used by RMC\n", "5 1.0 3.0 # cutoff, rmin of 1st peak, rmax of 1st peak. The purpose is to remove ripples\n", " # in the low-r region and those between the first and second peak.\n", "```\n", "\n", "Using the template provided above, we can fill in information specific to our data and sample, remove all blank lines and comments, and then run the program from the RMCProfile terminal window like,\n", "\n", "```bash\n", "stog_new < get_stog_input.txt\n", "```\n", "\n", "where `get_stog_input.txt` is our saved stog iput file.\n", "\n", "Things to keep in mind are,\n", "\n", "1. In line-4 of the input file, we specify the offset and scale for our data which would then rescale our data according to the formula presented in the comments. The end product we are pursuing here is the normalized total scattering structure factor, which, simply put, should go to $1$ in the high-$Q$ region.\n", "\n", "2. However, here may come the question that we have two parameters to control the level at high-$Q$. In practice, we can have infinite number of combinations of offset and scale to achieve the same high-$Q$ level. How do we move forward with this? First option is to refer to the low-$r$ behavior in the data output from the Fourier filter step -- `scale_ft.gr` in the example presented above. If the data is scaled properly, we are expecting the Level-1 and Level-2 (see picture down below) to be on the same level.\n", "\n", " \"drawing\"\n", " \n", "3. Quite often, even going through the step above still won’t bring our data to an absolute scale, in which case the only way left is probably to go through the painful trail-and-error process. That means we may want to play around with different scales of the data and see its effect on the fitting. In most cases, if the data scaling is not proper, not refining scale in RMCProfile has little chance to fit the data well.\n", "\n", "4. Alternative option one is to fit scale and offset in RMCProfile, especially for X-ray data.\n", "\n", "5. Alternative option two is to fit the scale in, e.g., PDFgui first and use the scale obtained there to rescale our data.\n", "\n", "Apart from the `stog_new` tool in the RMCProfile package, one can also use the `pystog` python module (which was developed following the same underlying principle as `stog_new`) for post-processing the total scattering data. The post-processing tab in ADDIE is using `pystog` as the backend engine for the data scaling and Fourier transform (see here for more information). One can refer to the link here for the instruction about installing and using `pystog`. The package was developed in a modular manner so we could build our own Python wrapper script to call those available `pystog` modules. Also, a command-line interface (CLI) `pystog_cli` was developed to take in an input JSON file and the running logic is pretty much similar to the `stog_new` program, as detailed above. A typical input JSON file for `pystog_cli` is presented here,\n", "\n", "```json\n", "{\n", " \"Files\": [\n", " {\n", " \"Filename\": \"DATA_FILE_NAME.sq\",\n", " \"ReciprocalFunction\": \"S(Q)\",\n", " \"Qmin\": 0.5,\n", " \"Qmax\": 40.0,\n", " \"Y\": {\n", " \"Offset\": 0.0,\n", " \"Scale\": 1.0\n", " },\n", " \"X\": {\n", " \"Offset\": 0.0\n", " }\n", " }\n", " ],\n", " \"RealSpaceFunction\": \"g(r)\",\n", " \"NumberDensity\": 0.049948,\n", " \"Rmax\": 50.0,\n", " \"Rpoints\": 5000,\n", " \"FourierFilter\": {\n", " \"Cutoff\": 1.5\n", " },\n", " \"^2\": 0.17215,\n", " \"LorchFlag\": false,\n", " \"RippleParams\": [\n", " 0.0,\n", " 0.0,\n", " 0.0\n", " ],\n", " \"Outputs\": {\n", " \"StemName\": \"OUTPUT_STEM_NAME\"\n", " }\n", "}\n", "```\n", "\n", "Most of the parameters involved in the JSON file are in one-to-one mapping relation with those parameters for the `stog_new` program. There is only one extra parameter in the JSON file -- the `RealSpaceFunction` parameter which contols the format of the real space function to be used for the intermediate processing (i.e., the Fourier filter). Usually the default option `g(r)` should be working but if needed, one can change it to, e.g., `G(r)`." ] }, { "cell_type": "markdown", "id": "c67721bf-3437-49f9-8f89-46f2d669fb90", "metadata": {}, "source": [ "## Demonstration\n", "\n", "> A demo dataset for Si standard sample is included here -- one can download the dataset by clicking this link.\n", "\n", "### Step-by-step instructions using `RMCProfile`\n", "\n", "0. In this demo, I will be using the RMCProfile package and the two programs coming with the package -- `rebin` and `stog_new` for post-processing the demo data for the Si standard sample.\n", "\n", "1. First, download the demo data (see the link just above) to your local area.\n", "\n", "2. Unzip the downloaded package to somewhere, e.g., in my case, under `d:\\Temp_Local` so that we can see the following files and sub-directories under it,\n", "\n", " ```\n", " exp.json\n", " GSAS\n", " Logs\n", " SofQ\n", " SofQ_merged\n", " StoG\n", " Topas\n", " ```\n", "\n", "3. Download the RMCProfile package if you haven't already got it, following the link, https://rmcprofile.ornl.gov/download\n", "\n", "4. Launch the RMCProfile terminal -- the actual way of launching will depend on your operating system. Detailed instructions for each platform can be found here, https://rmcprofile.ornl.gov/how-to-launch-rmcprofile-program\n", "\n", " > N.B. In the demo video below, I am using the Windows version of the RMCProfile package.\n", "\n", "5. Change to the working directory from the RMCProfile terminal (e.g., `cd d:\\Temp_Local\\SofQ_merged` in my case, and on Windows, we may need to type `d:` from command line to change to the right disk), where you are going to see the following files (run `dir` on Windows, or `ls -al` on Linux/Unix),\n", "\n", " ```\n", " get_stog_data.txt\n", " NOM_Si_640d_bank1.dat\n", " NOM_Si_640d_bank2.dat\n", " NOM_Si_640d_bank3.dat\n", " NOM_Si_640d_bank4.dat\n", " NOM_Si_640d_bank5.dat\n", " NOM_Si_640d_bank6.dat\n", " NOM_Si_640d_merged.sq\n", " Si_merge.json\n", " ```\n", "\n", "6. Rebin the data by running `rebin` from the RMCProfile terminal and feeding in the input file name when asked -- in this case, `NOM_Si_640d_merged.sq`. Then enter `0.5 0.01 40.0` when asked for next-step parameters, followed by inputting the output file name `NOM_Si_640d_merged_rebin.sq` when asked.\n", "\n", "7. Run `stog_new < get_stog_data.txt` from the RMCProfile terminal to process the rebinned data, and after running it, the directory should contain the following files,\n", "\n", " ```\n", " ft.dat\n", " get_stog_data.txt\n", " NOM_Si_640d_bank1.dat\n", " NOM_Si_640d_bank2.dat\n", " NOM_Si_640d_bank3.dat\n", " NOM_Si_640d_bank4.dat\n", " NOM_Si_640d_bank5.dat\n", " NOM_Si_640d_bank6.dat\n", " NOM_Si_640d_merged.sq\n", " NOM_Si_640d_merged_rebin.sq\n", " Si_640d_scaled.gr\n", " Si_640d_scaled.sq\n", " Si_640d_scaled_ft.gr\n", " Si_640d_scaled_ft.sq\n", " Si_640d_scaled_ft_rmc.dr\n", " Si_640d_scaled_ft_rmc.gr\n", " Si_640d_scaled_ft_rmc.sq\n", " ```\n", "\n", "The `Si_640d_scaled.sq` and `Si_640d_scaled.gr` file is the scaled normalized $S(Q)$ data and its Fourier transform, respectively. The `Si_640d_scaled_ft.sq` and `Si_640d_scaled_ft.gr` is the same dataset but with Fourier filter applied. The `Si_640d_scaled_ft_rmc.sq`, `Si_640d_scaled_ft_rmc.gr` and `Si_640d_scaled_ft_rmc.dr` are files in RMCProfile `F(Q)`, `G(r)` and `D(r)` format, respectively.\n", "\n", "### Demo video using `RMCProfile`" ] }, { "cell_type": "code", "execution_count": 6, "id": "d54e82f5-7264-48e8-beed-908ac43c251a", "metadata": { "execution": { "iopub.execute_input": "2023-06-01T02:47:20.726134Z", "iopub.status.busy": "2023-06-01T02:47:20.725835Z", "iopub.status.idle": "2023-06-01T02:47:20.884429Z", "shell.execute_reply": "2023-06-01T02:47:20.883806Z", "shell.execute_reply.started": "2023-06-01T02:47:20.726113Z" }, "tags": [] }, "outputs": [ { "data": { "image/jpeg": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wCEABALDBoYFhwaGRoeHRwfIigmIyIiIicqKiUnMC0zMi8tLzI1PVBCNThLOi0vRWFFS1NWW1xbMkFlbWRYbFBZW1cBERISGRYZLRsbMFdCNT1XV1dXV1dXV1dXV1dXV1dXV1dXV1dXV1dXV1dXV1dXV1dXV1dXV1dXV1dXV11XV1dXV//AABEIAWgB4AMBIgACEQEDEQH/xAAbAAEAAwEBAQEAAAAAAAAAAAAAAQIDBAUGB//EAEUQAAEDAgIFCQQIBAYCAwEAAAEAAhEDIRIxBBNBUWEFFCIycYGRodFSU5KxBhUjQmLB4fAWJDNyF0NUY4KiB/E0c9JE/8QAGQEBAQEBAQEAAAAAAAAAAAAAAAECAwQF/8QAJREBAAICAQQCAgMBAAAAAAAAAAERAhIhAxMxUUFhFCIEQoEy/9oADAMBAAIRAxEAPwD8/REQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERAREQEREBERARdlTk17QCXNk/d6U/KFmdDdvb5+iuspcOdF0jQ3b2+fonMnRm3z9E1kuHMi9A8kVInFT+I+ixOguE9Jtu30V1kuHKi6OZu3jzU8xfEyOOdvJTWS4cyLrfye8R0mmRNjlwPG3mq8yfw8/RKktzIunmTt7fP0XVo/IdWo3E1zI4l3olSk5RHl5iL0vqWoHBpfTDiSAJN47lr/AA7W9qn4u9EqUnqYx8vIRev/AA9W9qn4u9FH8PVvap+LvRNZTu4e3kovW/h6t7VPxd6J/D1b2qfi70TWTu4e3kovW/h6t7VPxd6J/D1b2qfi70TWTu4e3kovW/h6t7VPxd6J/D1b2qfi70TWTu4e3kovW/h6t7VPxd6J/D1b2qfi70TWTu4e3kovX/h6t7VPxd6J/Dtb2qfi70TWTu4e3kIvX/h6t7VPxd6KP4ere1T8Xeiayd3D28lF638PVvap+LvRP4ere1T8Xeiayd3D28lF1jk2oQSIIGZvAnfay0byRVIxCI33tPctdvL06U4EXf8A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0c1LtCLarqTnNlsXBt47lzUOUX06hqMADt4Lrb9ql3KTi8vLWlzsyS+/mkZc8+HT9dftpWoBrZDg4bxkurTeRa2jik6phw1XYWlrpuM9i4KmnlwgsZH/AD//AErVOU6j8OLpYTLcT6joPAFys5R8I9L6pbPXd5LynCCRxXT9eVfZZ4O9VwGsSSbLGE5f2dM5w/q1RY608E1p4Le0OTdFjrTwTWngm0DZFjrTwTWngm0I2UESFlrTwTWngm0D7n/EWt/pqfxu9E/xFrf6an8bvRfDa08E1p4KcK+4/wARa3+mp/G70T/EWt/pqfxu9F8NrTwTWngnA+5/xGrf6an8bvRD/wCRa3+mp/G70Xw2tKa0pwvD7n/Eat/pqfxu9FV//kOq4EHRqcER13L4jWFNYU4Xh9kPp28WGjMiZ/qPz3qaX02qOqNjRm43OgHWvzJ3ZZ8F8ZrCrU67muDm2c0gg7iLhODh98eXtIkt5qJa4gxVrGCNhPn3HctKX0n0qzm6I02jrVjbsjgvjHfSLTDM1iZnY3bM7PxO8VP8SaZ7878m753cSnDl+/0+ro/Tyu/LR6IvF3u9FFT6fV2iTo9IiYtUdnAO7ivhaekvb1SR2EhHaQ45knbcnPL8gnDXN/T71n06rubi5vRAib1Hei00T6Z6TWqik3RqOMiR9o6OrizjcvgG6XUAgOIG4Eq+j8pVqRcaby0uGEnaRuV/VnLapr/H21L6d6S97WDRKeJ7gwdN3WJiPFXf9NtKaKhOiU4puwOOsNnTEcb7l+fiqQZGe9Tr3Xvnnc37d6n6uj79/wBNtKaXg6HTBYAXfaGwIn5K7fphppcGjQmFxbjADyejvX58NIcCSCZIgmTcbkGkPFwSLRYnLd2Jwk/T9CofS/TahpBugtitOrLnOa10CTc22IfphpuAv5lTwirqj9pfWbo/PJfnzNLqNjC9wjKHER2XsoOkPMySZMm5ud53lOFfoJ+mWlgVCdEpg0yQ4GoZsJ+RWlL6X6c8vazQqZLGaxw1mTePHhmvzznlSHDG6HdYYj0u291VukPEw4iRBgkSNx3hOLR+gN+m+lnBGiU/tBLftDcflsWQ+n2knLRKdzh65z3L4UaS8EEOILerBNuzcq652/5qcEfb72n9PdKeCW6IwgZ9M2VaX/kOq6ZoUWwJu91+GS+DFUrWnptRohpAHYFeF4fbVf8AyJVaSBQpO4h7vRWd/wCQK4IB0elckdd2zPYvh62m1KghxB7gPkqCu6QTeN8lOBkiIsoIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiAiIgIiICIiD/9k=\n", "text/html": [ "\n", " \n", " " ], "text/plain": [ "" ] }, "execution_count": 6, "metadata": {}, "output_type": "execute_result" } ], "source": [ "from IPython.display import YouTubeVideo\n", "YouTubeVideo('lN8csTJ3XDY', width=720, height=500)" ] }, { "cell_type": "markdown", "id": "16dc8084-43d7-4af2-97d2-5e44418b877d", "metadata": {}, "source": [ "### Dealing with noisy data\n", "\n", "In practice, it is unavoidable that we would have noise in our data and sometimes the noise level might be on a significant level. Fourier transforming such noisy dataset needs some special care. On one hand, we might want to reduce the maximum $Q$ to diminish the contribution of noise from the high-$Q$ region. On the other hand, since the finite $Q$ range would have broadening effect in real-space due to the truncation in $Q$-space. The smaller maximum $Q$ being used, the more significant the broadening effect would be. Both of the two aspects could help smoothing out the data in real-space. However, the other side of the coin is that such a broadening effect could potentially smooth out the real features at the same time. As such, it may be necessary to try different maximum $Q$ values to obtain different datasets and see the effect upon the data analysis result. In the demo below, we will be present a practical way to deal with the noisy data, *but it should be kept in mind that there is really not a golden rule for deciding the most suitable maximum $Q$ value to be used, and in practice, back-and-forth efforts might be needed*.\n", "\n", "1. Download the demo data, by clicking on the link here.\n", "\n", "2. Copy over the `get_stog_data.txt` file from the step-5 in the section just above to the same location where the downloaded data is sitting and change to that directory from RMCProfile terminal. For example, on my Windows machine, I downloaded the data to `d:\\Downloads\\`, in which case I would execute,\n", "\n", " ```\n", " cd d:\\Downloads\\\n", " d:\n", " ```\n", "\n", " from my RMCProfile terminal window.\n", "\n", "3. The downloaded data should have already been binned properly so the first step of rebinning in the previous instruction could be skipped. Open the `get_stog_data.txt` file in a text editor and change the file name in the second line of the file to `NOM_Si_640d_merged_noisy.sq` in accordance with the data file just downloaded. Also, change the `Qmax` value in the third line of the file to `35.0` and meanwhile change all the output file names to be specific to the `Qmax` value being used. The changed file should be looking like this,\n", "\n", " ```\n", " 1\n", " NOM_Si_640d_merged_noisy.sq\n", " 0.5 35.0\n", " 0.0 1.0\n", " 0\n", " Si_640d_scaled_qmax35p0.sq\n", " Si_640d_scaled_qmax35p0.gr\n", " 50\n", " 5000\n", " N\n", " 0.049948\n", " 0\n", " N\n", " y\n", " 1.5\n", " Si_640d_scaled_ft_qmax35p0.sq\n", " Si_640d_scaled_ft_qmax35p0.gr\n", " 0.17215\n", " Si_640d_scaled_ft_rmc_qmax35p0.sq\n", " Si_640d_scaled_ft_rmc_qmax35p0.gr\n", " Si_640d_scaled_ft_rmc_qmax35p0.dr\n", " 0.0 0.0 0.0\n", " ```\n", " \n", " and save the changed file to `get_stog_data_qmax35p0.txt`\n", "\n", "4. Change the `Qmax` to several other different values (e.g., 32.5, 30.0 and 25.0), by repeating the step-3. Then execute all the saved stog input file to obtain a series of processed datasets, and then compare the outcome. For example, plot `Si_640d_scaled_ft_rmc_qmax35p0.gr` together with all the other similar files corresponding to other `Qmax` values outcome to see the effect of changing `Qmax`. Usually, the features that change significantly with the changing of `Qmax` are with higher chance being Fourier ripples. Also, we may need to pay attention to those features that do not change that much until reducing the `Qmax` to a certain value, and that can give us some hint about the lower limit of the `Qmax` value.\n", "\n", "5. In some rare cases (not in this demo one), changing `Qmax` alone may not eliminate the noise in data. Then one might need to smooth out the real-space pattern by introducing a Lorch modification function in $Q$-space, as originally proposed by Lorch -- see the reference here. To do this, use the following `stog` input file,\n", "\n", " ```\n", " 1\n", " NOM_Si_640d_merged_noisy.sq\n", " 0.5 35.0\n", " 0.0 1.0\n", " 0\n", " Si_640d_scaled_qmax35p0.sq\n", " Si_640d_scaled_qmax35p0.gr\n", " 50\n", " 5000\n", " Y\n", " 0.049948\n", " 0\n", " N\n", " y\n", " 1.5\n", " Si_640d_scaled_ft_qmax35p0.sq\n", " Si_640d_scaled_ft_qmax35p0.gr\n", " Si_640d_scaled_ft_qmax35p0_lorched.gr\n", " 0.17215\n", " Si_640d_scaled_ft_rmc_qmax35p0_lorched.sq\n", " Si_640d_scaled_ft_rmc_qmax35p0_lorched.gr\n", " Si_640d_scaled_ft_rmc_qmax35p0_lorched.dr\n", " 0.0 0.0 0.0\n", " ```\n", " \n", " where the major change is happening in line-10 (from `N` to `Y`, indicating a Lorch function is to be applied.)." ] }, { "cell_type": "markdown", "id": "43ff9b9a-4827-4359-9b71-5f2a25f36bc5", "metadata": {}, "source": [ "### Step-by-step instructions using `pystog`\n", "\n", "Here, we will be performing similar task as in previous demonstration, i.e., rebin & rescale data, and Fourier transform. The tool being used here is `pystog` (see the github repo for the resource codes and documentation). Beyond the tasks we have been walking through in previous steps, we will be using the power of the `pystog` engine to perform tasks like converting in between different data formats needed by different software.\n", "\n", "Here, we will be using Google Colab notebook which is a dedicated environment for this demo. It covers the installation of necessary software package and actual codes for performing the data processing tasks. So, for this demo, you can visit the link here and log in with your Google account to be able to run the notebook.\n", "\n", "Beyond this demo, `pystog` can be installed on your local machine. For the installation, we strongly recommend installing `conda`, for which one can refer to this link. Once `conda` is installed,\n", "\n", "1. Create a `conda` environment named, e.g., `pystog`, by running `conda create -n pystog python=3.7`\n", "\n", "2. Then activate the environment, `conda activate pystog`\n", "\n", "3. Install `pystog` either `pip` by running `pip install pystog`, or via `conda` by running `conda install -c neutrons pystog`\n", "\n", "4. From the terminal, change to the demo data directory. Following the example as presented above, in my case, the command is `cd d:\\Temp_Local\\SofQ_merged`, followed by running `d:` to make sure we are in the `d:` drive.\n", "\n", "5. Put the following contents into a Python script file and name it as, e.g., `proc_pystog.py`,\n", "\n", " ```python\n", " import numpy as np\n", " from matplotlib import pyplot as plt\n", " \n", " # Load in data\n", " q, sq = np.loadtxt(\"./NOM_Si_640d_merged.sq\", unpack=True, skiprows=2)\n", " \n", " # Rebin data\n", " from pystog import Pre_Proc\n", " rebin = Pre_Proc.rebin\n", " q_rebin, sq_rebin = rebin(q, sq, 0.5, 0.01, 40.0)\n", " with open(\"NOM_Si_640d_merged_rebin_pystog.sq\", \"w\") as f:\n", " for i, q_val in enumerate(q_rebin):\n", " f.write(\"{0:10.3F}{1:15.6F}\\n\".format(q_val, sq_rebin[i]))\n", " \n", " # plot data\n", " plt.plot(q, sq, 'o-', label=\"original data\")\n", " plt.plot(q_rebin, sq_rebin, 'v-', label=\"rebinned data\")\n", " plt.legend()\n", " plt.xlim([1.9, 2.1])\n", " plt.ylim([-1, 22])\n", " plt.show()\n", " \n", " # Convert the normalized S(Q) to F(Q)\n", " from pystog import Converter\n", " converter = Converter()\n", " fq, _ = converter.S_to_F(q_rebin, sq_rebin)\n", " \n", " # plot data\n", " plt.plot(q_rebin, fq)\n", " plt.show()\n", " \n", " # Convert the normalized S(Q) to FK(Q)\n", " kwargs = {'^2': 0.17215}\n", " fkq, _ = converter.S_to_FK(q_rebin, sq_rebin, **kwargs)\n", " \n", " # plot data\n", " plt.plot(q_rebin, fkq)\n", " plt.show()\n", " \n", " # Transform into real-space G(r)\n", " from pystog import Transformer\n", " transformer = Transformer()\n", " r = np.linspace(0., 50., 5000)\n", " r, gr, _ = transformer.S_to_G(q_rebin, sq_rebin, r)\n", " \n", " # plot data\n", " plt.plot(r, gr)\n", " plt.show()\n", " \n", " # Convert G(r) to GK(r)\n", " kwargs = {'rho': 0.049948, '^2': 0.17215}\n", " gkr, _ = converter.G_to_GK(r, gr, **kwargs)\n", " \n", " # plot data\n", " plt.plot(r, gkr)\n", " plt.show()\n", " ```\n", " \n", "6. Next, we will be performing the comprehensive `stog` processing as we have seen in previous demo, but this time using the `pystog` engine. First, create a directory under the current working directory, with the name, e.g., `pystog_proc` and change to that directory from command line, by running `cd pystog_proc`. Then, download the JSON input file, by clicking on the link here and move it to the created `pystog_proc` directory. Then from the command line, execute,\n", "\n", " ```\n", " pystog_cli --json si_pystog_demo.json\n", " ```\n", " \n", " to run the `pystog` processing, and all files generated will be put in the current working directory, which is `pystog_proc`." ] }, { "cell_type": "markdown", "id": "908eea5b-fcf8-4835-8959-5abcc6b166ba", "metadata": {}, "source": [ "### Step-by-step instructions using `ADDIE`\n", "\n", "1. As above, grab the demo data for Si standard sample and unzip to somewhere in your local area, e.g., `/SNS/users/y8z/Temp/` in my demo case. Here we will be using the `ADDIE` software deployed on the analysis cluster. So, you should log in analysis using your UCAMS credential, using either a web browser or ThinLinc (the domain name is https://analysis.sns.gov). Then launch a terminal and type in `addie --dev` to start `ADDIE`.\n", "\n", " \"drawing\"\n", "\n", " > N.B. Since we need to log in analysis and use `ADDIE` from there, we need to download the demo data from within analysis. Sometimes, launching the browser from within the analysis can take a long time, in which case one can use the following command from the terminal,\n", " \n", " > `wget --no-check-certificate https://powder.ornl.gov/files/si_demo_data.zip`\n", "\n", "2. In `ADDIE`, change the output directory to where the downloaded data is unzipped to, e.g., `/SNS/users/y8z/Temp/`.\n", "\n", " \"drawing\"\n", "\n", "3. Click on the `Post Processing` tab in the `ADDIE` interface,\n", "\n", " \"drawing\"\n", "\n", "4. Click on the `Load` button and browse to the `NOM_Si_640d.nxs` file under the `SofQ` directory of the downloaded package,\n", "\n", " \"drawing\"\n", "\n", "5. Once the data is loaded in, click on the `Extract` button to extract the workspace, and the extracted data will be populated in the `Raw Data` tree under `File List`, where one can right click to plot the data,\n", "\n", " \"drawing\"\n", "\n", "6. Then load in the merge configuration file, followed by clicking on the `Merge` button to merge the bank-by-bank data,\n", "\n", " \"drawing\"\n", "\n", " > N.B. The merge configuration file is a JSON file containing the range to be used for each bank, together with the offset and scale parameters for each bank. One can open the JSON file with any preferred text editor to inspect and change the contents.\n", " \n", "7. Finally, load in the `pystog` configuration file, followed by clicking on the `StoG` button to perform the `pytstog` processing,\n", "\n", " \"drawing\"" ] }, { "cell_type": "code", "execution_count": null, "id": "a657ae9e-2135-453c-9976-23209c2a3947", "metadata": {}, "outputs": [], "source": [] } ], "metadata": { "kernelspec": { "display_name": "Python (default)", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.7.13" }, "widgets": { "application/vnd.jupyter.widget-state+json": { "state": {}, "version_major": 2, "version_minor": 0 } } }, "nbformat": 4, "nbformat_minor": 5 }