Before you start
Read the CXASAP 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.
Running CXASAP
CXASAP runs via a terminal, where you will input instructions about the module or pipeline you want to run.
After it is installed, if you open a terminal, activate the virtual environment and run this command:
cxasap
Read the output in the terminal and it will guide you how to run the code.
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-cif
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:
You can check the files required, by running this command:
cxasap pipeline-refinement --files
Then you want to configure CXASAP for this pipeline, by running this command:
cxasap pipeline-refinement --configure
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 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
cxasap pipeline-refinement --run |
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-cif