CXASAP for high pressure experiments

Before you start

Read the CXASAP - serial data analysis background and basics page.

You will need to install CXASAP, and some other accompanying software on your computer.

See CXASAP Windows Installation Instructions for instructions for installing on Windows.

See https://cx-asap.github.io/USER.html#installation for instructions for installing on Linux.

Step 1. Pipeline-refinement

This pipeline will refine a series of datasets based on a single reference structure, which would likely be your ambient structure or the lowest pressure structure. Although if there is a phase change or significant changes in this structure, you may want to use a reference in the middle of the pressure series. If you don't think refining your datasets based on a single reference structure will be helpful, you can skip to Step 2: pipeline-variable-analysis

Setup datasets

For the reference structure, you will need to:

• Refine it to convergence

• Label the atoms, especially those you are interested in throughout the series

• DO NOT use the solvent mask or SQUEEZE. This will confuse CXASAP because it will look for a fab file. If your structure is porous, just refine it as best you can without SQUEEZE or a solvent mask. If you need to refine it with a solvent mask for publication, you will need to do it manually after you do the parallel refinement. 

• Place the ins, res, hkl and cif files in a folder together. 

For the datasets, you will need a folder for each, which includes its hkl and ins files.

All the dataset folders and your reference dataset should be in the one folder, where you will run CXASAP.

Setup CXASAP

If you are running pipeline-refinement the first thing you want to do is run the help command in CXASAP, which should look like this:

Open

You can check the files required, by running this command:

Then you want to configure CXASAP for this pipeline, by running this command:

This will make a new file called conf.yaml in the cx_asap folder, which is in your CX-ASAP-main folder where you installed the software.

It will also print out a description of each of the fields in the conf.yaml file which you need to fill out:

Open

Open the conf.yaml file and add the details for your datasets. The main fields you need to fill in are the experiment_location and the reference_path. 
Most importantly, the experiment location is the path to the folder containing all your datasets, while the reference path is the path to the .ins or .res file for your reference.

Be aware that if/when you run the --configure command again for any pipeline, it will overwrite this file. So you might want to save a copy in your dataset folder if you think you will want to use it again, like if you are going to use a different reference file. 

Run CXASAP!

Now you should be able to run pipeline-refinement

You should see the output of shelxl running in powershell. 

Wait patiently for it to finish. 

Check the output

You can look at the error_output.txt or refinement_summary.txt files in the folder with all your datasets. This will tell you if there are structures that did not converge, or if other errors occurred. 

If there are multiple structures that have not converged, try increasing the maximum cycles and the refinements in the conf.yaml file, and running pipeline-refinement again. You can also open the .res files for the structures that did not refine to convergence and see if they are looking sensible or have solved/refined to nonsense. If that is the case, you will need to finish off the refinement manually.  But after you do this and have all your cifs ready, providing they stay in the same space group as the reference structure, you can move on to pipeline-variable-analysis. At this step, don’t add any information under _refine_special_details as this will upset the next step.

Step 2. Pipeline-variable-analysis

To extract all the structural information your heart may desire from the cifs you have just made, you want to run pipeline-variable-analysis through cxasap

Collect cifs into a single folder

In order to run the pipeline that will compare the structures based on their cifs, you need to copy all the cifs into the same folder, and give them unique names, probably naming them by their pressure would be the best bet.

Add pressure values to cif

You will need to add a field to each of your cifs with the pressure of the experiment. Keep the units consistent (either GPA or Pa) and only add a number, not the units.

It should look like this:

_diffrn_ambient_pressure 150000

You can add it anywhere in your cif, but best practice would be to add it after _diffrn_ambient_temperature

Configure pipeline-variable-analysis

Go back to your powershell in the CX-ASAP-main folder, where you have the virtual environment activated. 

Configure pipeline-variable-analysis

Open the new conf.yaml file in the cx_asap folder, and edit it with your experiment details. 

The parameters you need to fill out are these:

• ADP_analysis: enter 'true' if you want to extract ADP information, otherwise enter 'false'

• atoms_for_analysis: enter the label of the atoms you are most interested in

• cif_parameters: these are the parameters that will be extracted from the cif - default ones are usually enough - note that any additional ones must be written in exact cif format

• experiment_location: enter the full path to the folder which contains your .cif files

• reference_unit_cell: enter the path to a reference .ins file. This could be your ambient dataset, or first pressure point.

• structural_analysis_bonds: enter 'true' if you want to extract bond information, otherwise enter 'false'

• structural_analysis_angles: enter 'true' if you want to extract angle information, otherwise enter 'false'

• structural_analysis_torsions: enter 'true' if you want to extract torsion information, otherwise enter 'false' - note that cif files will only contain this information if you refined your structures with the 'CONF' command

• varying_cif_parameter: enter the parameter in your .cif files that is changing. Make sure you use proper .cif syntax (for high pressure, it will be _diffrn_ambient_pressure)

You can change the ADP_analysis, structural_analysis_angles, structural_analysis_bonds and structural_analysis_torsions from false to true if you want to extract the information on these parameters. Generally you may as well make them all true. Unless you have isotropic atoms in your reference structure, in which case leave ADP_analysis as false. 

For example the conf.yaml will look something like this:

Now you can run the analysis!

After it has run you should have png files of graphs of bond lengths and angles etc. And the raw data that has been extracted will be in .csv files. These can be opened in excel if you want to select specific data to make graphs. 

The bond lengths, angles and torsions from the atoms which you listed under “atoms_for_analysis” in the conf.yaml will be in the _Important_Bond_Angles, _Important_Bond_Lengths and _Important_Bond_Torsions files in the folder with your cifs. All others will be in subfolders called _Individual_Angle_Data, _Individual_Bond_Length_Data and _Individual_Torsion_Data.

Step 3. Enjoy your data analysis and write lots of papers! 

And don't forget to reference CXASAP https://doi.org/10.1107/S1600576723000298