TITLE: Calculation of MOF pore size distributions using PoreBlazer 4.0
AUTHORS: Jonas Sundberg

[DESCRIPTION]
This is a brief step-by-step protocol for how to calculate and plot the pore-size distribution (PSD) of a metal-organic framework. The protocol uses the nice PoreBlazer software made by Sarkisov et. al., for in-depth information read their paper:
'Materials Informatics with PoreBlazer v4.0 and the CSD MOF Database'
Chem. Mater.2020, 32, 23, 9849–9867
 https://doi.org/10.1021/acs.chemmater.0c03575

Disclaimer
Our protocols are primarily for internal use by students, but shared openly as we believe they might be of broader interest. But remember, this is just how we do it. Not necessarily the best, or smartest, way (but hopefully somewhat correct). Code snippets are not meant to be definite, but used as learning tools and starting points to create your own scripts. If you have comments, please e-mail us freely and direct. :)

[BEFORE_START]
The protocol assumes that you have the following software packages installed and ready:
Mercury/Cambridge Structural Database software suite
PoreBlazer Windows binary
Aten Molecular modelling package
Jupyter Notebooks/JupyterLab with functional Python environment

JupyterLab with Python and Matplotlib are used for plotting the resulting data. For the less computer savvy, easiest way is to download Anaconda, and use conda to install the required packages. 

Working folders
Create an appropriately (structure refcode, name or similar) named sub-folder under the directory where the 'poreblazer.exe' executable is located. This is where you should store and save all files. 

[STEPS]
SECTION: Preparation of input files
1. Crystallographic clean-up using Mercury
If your material has co-crystallized solvent molecule(s) it is important to remove before measuring the pore-size distribution. In this protocol we will work with HKUST-1 (CSD-refcode: FIQCEN) as an example. The crystal structure of HKUST-1 contains one co-crystallized water molecule per unit cell. Furthermore, each copper paddlewheel is coordinatively saturated by two water molecules. 

Open the CIF-file (Ctrl+O) or use the 'Structure Navigator' (right pane in default settings) to locate entry FIQCEN.
You will now see the asymmetric unit of the structure. 
Select the free and bound water molecules (see figure below).
Select 'Edit>Edit Structure'
Click 'Remove> Selected Atoms'
Export the desolvated structure as cif by 'File>Save As'; name the file 'FIQCEN_desolv.cif''.


    
  
 

SECTION: Preparation of input files
2. Use Aten to convert the CIF file to an PoreBlazer-compatible xyz input file. 
 

Start Aten and open the resulting CIF file by clicking the 'Open' icon.
Browse to your data directory, choose 'Crystallographic Information File (CIF)' from the 'Filter' dropdown menu,  select your file and click 'Open'.
Confirm that the structure is fully desolvated.
Click 'Save As', ensure that 'Determine format of saved file by name' is selected, enter 'FIQCEN_desolv.xyz' as filename and click 'Save'.

  
  
 

3. Create a PoreBlazer input files:
In your working directory, create and save a 'input.dat' file in Notepad (or other text editor). 
The first line should contain the xyz filename, e.g. 'FIQCEN_desolv.xyz'
The second and third line contains unit cell dimensions (cell lengths and angles). 
To obtain these, go back to Mercury. With your structure loaded, select 'Structure Information' from the More Info' drop down menu (bottom pane).
The unit cell dimensions are provided under the 'Structure' tab. 
Enter the cell lengths (tab separated) on the second line.
Enter the cell angles (tab separated) on the third line.
In addition to the 'input.dat' file, the PoreBlazer requires force field data. Default values are provided by PoreBlazer and should typically not be modified. Either copy the 'defaults.dat' and 'UFF.dat' files from the source distribution or use the values provided below. 


  

input.dat

 


run.bat
 

defaults.dat
 


UFF.atoms
 

SECTION: Simulation and plotting/presentation of results
4. Execute PoreBlazer:
Start the Windows command prompt by pressing Windows+R and entering 'cmd' followed by clicking 'Ok'.
Change directory to enter the working folder containing the input files.
Execute 'run.bat', wait a few seconds and voila!

  
The software should generate the following files:
'results.txt';
'summary.dat'; Contains a brief summary of the results, including pore-limiting and largest cavity diameter, total and network accessible surface area. 
'Total_psd.txt' + 'Total_psd_cumulative.txt'; Total pore-size distribution and
'Network-accessible_psd.txt' + 'Network-accessible_psd_cumulative.txt'; network accessible pore-size distribution

An archive containing both input and output files as described in this protocol is attached below.  A more detailed description of the output can be found at https://github.com/SarkisovGitHub/PoreBlazer 

 
  

SECTION: Simulation and plotting/presentation of results
5. Plotting of single PSD data

 


Start JupyterLab by initiating an 'Anaconda prompt' and entering the command 'jupyter lab'
Use the left-pane browser to locate your working directory containing the output from PoreBlazer.
Create new launcher by clicking the '+' symbol and choose a Python 3 Notebook.
Rename the 'untitled.ipynb' to 'DATE-REFCODE_PSD_Plots.ipynb', e.g. '220927-FIQCEN_PSD_Plots.ipynb'
Add the following code snippets to cells of the notebook (example notebook is attached below).
Press Ctrl+Enter to execute each cell in order.

Import the required packages
 

Define and load data
 

Plotting of network accessible pore size distribution
 

Plotting of total accessible pore size distribution

 

 

 
   


  

SECTION: Simulation and plotting/presentation of results
6. Plotting of multiple PSD series as overlay

Create a working directory for storage of all PSD data, e.g. 'PSDs'
Make a copy of each single PSD datafile and rename it to REFCODE_NA_PSD.txt' (or 'REFCODE_tot_PSD.txt' if plotting total PSD). Note: 
Move all uniquely named data files into the working directory.
Create a new Python 3 notebook in Jupyter Lab as described previously.
Add the following code snippets to cells, and execute (example notebook is attached below).

Import required packages
 


 


Multi-data import and overlay plotting
 

   



SECTION: Simulation and plotting/presentation of results
7. Bonus: Summary clean-up and Excel export
This is just a short code-snippet to reformat the multiple 'summary.dat' output file into a slightly more user friendly edition. :)

Create a secondary working subfolder called 'Summaries'
Make a copy of each 'summary.dat' named 'REFCODE_summary.dat' and copy into the 'Summaries' subfolder.
In the parent directory, create a new Jupyter Notebook and add the following code to a cell: