ADD1. PDF Introduction - Basic Refinements

Introduction

Here we aim to introduce you to all of the basic TOPAS and PDF functions that you will use in most, if not all, refinements that you will conduct. You will have to setup your own machine following the instructions here.

Macros

TOPAS utilises a simple system of built-in keywords (such as pdf_data, space_group, r_wp) and defined macros (such as dQ_damping, beq_spherical, Damp, and pdf_for_pairs). The user is able to define their own macros, and the #include statement is the method by which macros are utilised without them needing to be defined within the current input file.

By default, TOPAS comes with a selection of macros which are held within the file topas.inc in the main TOPAS directory. By default, this file is consulted when you run a refinement; so if you request the macro Out_Ycalc it is found within topas.inc and implemented.

VS Code PDF Menu

After installation of the TOPAS Editor extension within VS Code, the Commands menu on the left hand side of VS Code will be available. Commands provides you with a helpful way of accessing various macros defined within the .inc files. You will see the Commands icon on the very left side, click this button to toggle whether the menu appears.

We typically make our TOPAS input files using these menus, although of course you can just type the commands straight into the editor window if you know them! Clicking on an item will insert the relevant lines wherever the cursor is. The location of keywords and macro calls can be important - make sure you have your cursor in the correct position before selecting your desired options.

Here is an image of the menu expanded down a couple of levels. We're going to build our first PDF refinement using these menus now, looking at a nanosolution of CeO₂ in a solvent.

Basic PDF Refinement

Start by running TOPAS if it isn't already running, by clicking Run TOPAS at the top of the Commands menu.
Click TOPAS_for_PDF > 1. PDF data > Select PDF Data File to browse for the file we are going to refine a model against; in this case you the pop up window to find the file "XPDF_CeO2_nanoSolution.xy" in the tutorial directory. Select this file and a new .inp file will be created in a new file in VS Code. You should have something like this…
…where r_wp etc are various R-factors (you can check the TOPAS Technical Reference for definitions of these); iters is the maximum number of iterations that the refinement will perform, and chi2_convergence_criteria stops the refinement when the chi2 is reducing by less than this value. Comments in the file (like the first line) are denoted by strings 'starting with a single quote; xdd declares a new data file to be refined against, pdf_data says that it's PDF data, and weighting 1 says that every point should be equally weighted in the residual equation (again, check the TOPAS Technical Reference for more on this).
We also need to apply some xdd level convolutions such as an instrument convolution, so from select 2. Instrumental Parameters > dQ damping and replace #dQ with a start with a value of 0.05. Throughout this tutorial, text starting # (like #dQ) denotes a number which needs to be entered.
Now we need to insert our starting model for the refinement. click 3. Phase Information > 3b Add new phase from CIF > Read a .CIF file and locate the file ceo2.cif in the tutorial directory.
1. The name is read from the metadata in the cif file. Feel free to change this.
2. We want to refine the lattice parameters, but maintain the cubic symmetry of the phase that has been imported from the cif. TOPAS will allow you to break the metric symmetry by refining a, b, c, al, be, ga lattice parameters even if this is not in keeping with the space group, so we need to tell TOPAS which lattice parameters to refine. Highlight the part of the .inp file where the lattice parameters are defined, and then click 3. Phase Information > 3b Add new phase from CIF > ii. constrain lattice parameters > convert to cubic .
  Highlight the lattice parameters before clicking “convert to cupic”
  An @ is added to the line defining the a lattice parameter, and the =Get(a); command is used to declare that b and c are always equal to a, maintaining the cubic metric symmetry.
As with most materials we'll encounter, this sample also includes some local correlated motion. Delete the beq 0.#### parts at the end of the two site lines (which would be fine for a Rietveld refinement), and replace with 3. Phase Information >beq peak shape functions > beq spherical with rmin and rlo cutoffs. We need to allow these beq macros to refine some variables independently, so change your site lines to be like below. We'll do a whole tutorial on beq peaks shapes later, so don't worry too much about it now.
This phase is actually a nanoparticle, so we need to define a real-space shape function to reflect this. Again, we'll do more tutorials on this later, but for the moment just double click 3. Phase Information > sample shape functions > spherical damping and start with a radius of 50 Å (replace #radius with 50). Here we choose to set the beq_spherical radius and the spherical_damping radius to be equal, so replace the @ with the word beqradius, since this is what we called it within the beq_rcut_rlo_spherical macros above.
Save the file (which by default will have a name related to the file we started with) and send it to TOPAS by pressing the “Send INP to TOPAS” command. Now go to TOPAS and run the refinement by pressing the “Play” button…
…, but do not update the input file when prompted. Always assume that in these tutorials, we don't want you to update the input file unless we explicitly say otherwise! Super quick, wasn’t it? You may want to do it again by pressing the “Step” button…
… a few times first to do single iterations of the refinement. When you are happy that the refinement is progressing sensibly after a few steps, you can press “Play” to run the refinement to completion.
The fit should be ok with an r_wp of ~23.7
There's some signal at low-r that is not accounted for by the model however, and since we know that this is a nanosolution we should try and take the solvent into account. Handily, we collected the PDF of just the solvent and we can add this in to TOPAS and fit that as well. Click miscellaneous macros > background from file and replace #filename.xy with the name of the solvent file, XPDF_Solvent.xy. This is a macro which imports a file as a dataset to include in the fit (in this case XPDF_Solvent.xy) and refines a scale factor for this "background" data (which starts at a scale of 1 in this case).
Refine this model in TOPAS. It's made the fit better, but now we can't tell the difference between what signal comes from the CeO2 and which is the solvent component. Lets add a little more information about the solvent so we can ask TOPAS to show them separately. Back to VS Code, and we'll add a section of code which we can turn on and off easily should we wish to. Copy the below lines into your .inp file (make sure to only include one pdf_bkg_file line in your .inp).
#define proper_solvent_scaling #ifdef proper_solvent_scaling dummy_str phase_name "Solvent" Cubic(4.9276) space_group "Fm3m" site O x 0 y 0 z 0 occ O 1 site H x 0.25 y 0.25 z 0.25 occ H 1 Phase_Density_g_on_cm3( 1.00010) scale = fit_obj_scale; user_y solvent XPDF_Solvent.xy fit_obj = fit_obj_scale solvent; prm fit_obj_scale 1 fit_obj_phase 2 #else pdf_bkg_file(XPDF_Solvent.xy,@,1) #endif
The #define proper_solvent_scaling line makes a definition that the #ifdef command depends on. If proper_solvent_scaling is defined, then the section of code in the #ifdef section is included in the refinement, otherwise it is not. Try running the refinement with and without the proper_solvent_scaling definition, either by changing the name on the #define line, or commenting it out entirely. Why is this better than just commenting out the section of code? The rest of the commands in this block are an attempt to try and get a meaningful scale factor from the refinement, don't worry too much about them at this point.
With the definition included, run the refinement in TOPAS and this time click Yes when the refinement finishes to replace the .inp file with the output of the refinement. Highlight the phases in the top right of the fit window to show the contributions from the nanoparticle and the solvent. Return to VS Code and see how the file has changed. Refined values will now appear in red and have a ` character after them. These are the numerical results of your refinement. This refinement is now complete. Look through the .inp file and see what information you can recognize.