add particle_rugosity

Author: ramayo223

scripts/particle_rugosity/ReadMe.md

@@ -0,0 +1,85 @@
+# Particle Rugosity
+
+## Summary
+Simulates the particle shape of the given crystal structure using BFDH mophology 
+prediction, then calculates the particle rugosity by determining the rugosity 
+of the facets and calculating the weighted average (by facet area).
+
+### Relevance
+Rugosity is considered to be a factor in nucleation, with rougher crystal surfaces 
+having higher energies and being generally less stable. This property has been used
+in rationalizing the relative stability or probability of forming one polymorph 
+(or putative crystal structure from Crystal Structure Prediction, CSP) over another.
+
+Using a protocol similar to that reported by [Cruz-Cabeza and colleagues](https://doi.org/10.1002/anie.202006939) this script
+takes a crystal structure or refcode as an argument and will use the CCDC BFDH 
+morphology module to simulate the predicted particle shape. The facet hkl planes are
+then obtained and the rugosity of these planes is calculated using the [CCDC rugosity function](https://downloads.ccdc.cam.ac.uk/documentation/API/descriptive_docs/particle.html) (including a scan of 
+different off-sets from the origin to identify the minimum rugosity of that crystal 
+plane). Finally, the total particle rugosity is calculated by weighted average 
+according to the facet surface areas.
+
+## Requirements
+
+- Tested with CSD Python API version 3.7.9 on Linux and Windows
+- ccdc.particle
+- ccdc.morphology
+
+## Licensing Requirements
+
+- CSD-Core
+
+## Instructions on Running
+### Linux command line
+- load the CSD Python API Miniconda environment
+- call Python to read the script, add the crystal structure refcode or filename (local file)
+~~~
+$ python particle_rugosity.py AABHTZ
+The crystal structure AABHTZ has been loaded
+Calculating particle rugosity ...
+AABHTZ particle rugosity:  1.5073781143188552
+~~~
+OR
+~~~
+$ python particle_rugosity.py AABHTZ.cif
+~~~
+- results are printed and can be redirected to be saved in an output file
+~~~
+$ python particle_rugosity.py AABHTZ > AABHTZ_rugosity.out
+~~~
+
+### Windows CSD Python API
+- move the particle\_rugostiy.py file to the CCDC\Python\_API\_(year)\ folder 
+- to determine where this is on your computer, start the CSD Python API and enter the following commands
+~~~
+>>> import os
+>>> wd = os.getcwd()
+>>> print(wd)
+C:\Program Files\CCDC\Python_API_2022\
+~~~
+the last line is the folder location where you need to move the particle\_rugostiy.py file
+- now the script can be run in the CSD Python API to calculate the rugosity of any CSD entry using:
+~~~
+>>> import sys
+>>> import subprocess
+>>> subprocess.call([sys.executable, 'particle_rugosity.py', 'AABHTZ'])
+The crystal structure AABHTZ has been loaded
+Calculating particle rugosity ...
+AABHTZ particle rugosity:  1.5073781143188552
+~~~
+OR
+- if you want to run your own crystal structures, make a folder (eg. rugosity_calc) in Python_API_(year), and add your
+ crystal structure file to that folder
+- modify the argument to include the file path
+~~~
+>>> subprocess.call([sys.executable, 'particle_rugosity.py', 'rugosity_calc/AABHTZ.cif'])
+The crystal structure rugosity_calc/AABHTZ.cif has been loaded
+Calculating particle rugosity ...
+AABHTZ particle rugosity:  1.5073781143188552
+~~~
+
+## Author
+
+_R. Alex Mayo_ 2023
+
+> For feedback or to report any issues please contact [support@ccdc.cam.ac.uk](mailto:support@ccdc.cam.ac.uk)

scripts/particle_rugosity/particle_rugosity.py

@@ -0,0 +1,68 @@
+# script for calculating the particle rugosity for a given crystal structure (.cif in local working directory, or refcode of a CSD entry)
+# requires a CCDC license, and loading of the CSD-python miniconda environment if run from Linux command line
+
+# import ccdc modules
+import ccdc
+from ccdc.io import CrystalReader
+from ccdc import particle
+from ccdc.particle import Surface
+from ccdc import morphology
+from ccdc.morphology import BFDHMorphology
+
+def particle_rugosity(crystal):
+# load structure, either (1) crystal structure file in working directory, or 
+# (2) CSD refcode
+    head, sep, tail = crystal.partition('.')
+    if sep == '.':
+    # agrument is crystal structure file 
+        xname = crystal
+        xtal1 = CrystalReader(xname)
+        xtal = xtal1[0]
+        xtal1.close
+    else:
+    # agrument is a CSD refcode 
+        xname = crystal
+        xtal = CrystalReader('CSD').crystal(xname)
+
+    print(f"The crystal structure {crystal} has been loaded")
+    print("Calculating particle rugosity ...")
+# run BFDH morphology to determine predicted particle surface area = hkl planes, and d-spacing of the planes
+    morphology = BFDHMorphology(xtal)
+    facets = morphology.facets
+    f = facets[0]
+    all_hkl = [f.miller_indices.hkl for f in facets]
+    all_mi = [f.miller_indices for f in facets]
+    facets_relA = [morphology.relative_area(mi) for mi in all_mi]
+    all_d_hkl = [f.miller_indices.d_spacing for f in facets]
+    num_face = len(all_d_hkl)
+# generate surfaces and record rugosity, weigh by particle surface area
+    w_part_rug = []
+    for i in range(num_face):
+        hkl = all_hkl[i]
+        rug_list = []
+        # check rugosity of crystal plane at 0, 0.25, 0.5, and 0.75 offset from origin 
+        for split in range(1,5):
+            os = all_d_hkl[i] / split
+            surface = Surface(xtal, hkl, offset=os)
+            rug_list.append(surface.descriptors.rugosity)
+
+        # only take the minimum rugosity value (from all offset calculations) for each hkl
+        rug = min(rug_list)
+        w_surf_rug = rug * facets_relA[i]
+        w_part_rug.append(w_surf_rug)
+
+# sum weighted rugosity values and print total particle rugosity
+    tot_rug = sum(w_part_rug)
+    print(f'{crystal} particle rugosity: ',tot_rug)
+
+# ================================
+# argument parser
+import argparse
+parser = argparse.ArgumentParser()
+parser.add_argument("input_x")
+args = parser.parse_args()
+crystal = args.input_x
+
+# run code
+particle_rugosity(crystal)
+