CRYSTALClear is an open source project that provides an easy Python interface with CRYSTAL. The package allows you to quickly extract information from the CRYSTAL output files and to easily generate customizable plots of computed quantities. In particular, the package supports plotting functionalities for:
Band Structures and DOSS
Mechanical Properties
IR and Raman Spectra
bands.png
DAFADNP_comp_04GPa.png
phonon_soft_p21.png
QTAIM
Transport Properties
Density Maps
Screenshot 2025-01-28 at 3.20.22 PM.png
seebeck_calc_carrier.jpg
soc-soc_alpha20_JZ.png
For a more comprehensive review of the package capabilities we refer you to the Documentation Website.
How to Install
Prerequisites:
Python: Ensure you have Python installed on your system.
conda (Optional but Recommended): conda is a powerful package and environment manager that simplifies the process of managing Python dependencies. If you don't have conda, install it from the official Anaconda distribution: https://www.anaconda.com/
Installation Steps:
Create a Dedicated Environment (Recommended):
Creating a separate conda environment for CRYSTALClear helps isolate its dependencies from other projects and avoid potential conflicts.
conda create -n env_name python=3.9 # Replace 3.9 with your desired Python version
Activate the Environment (Reccommended):
conda activate env_name
Install CRYSTALClear using pip:
pip install CRYSTALClear
This command will install the CRYSTALClear library and its dependencies.
Verification:
Check Installation:
After installation, you can verify the installation by importing the library in a Python script or interactive session:
import CRYSTALClear
If the import is successful without any errors, the installation was successful.
Additional Notes:
Dependencies: The CRYSTALClear library might have dependencies on other libraries. pip will automatically install these dependencies during the installation process.
Updating: To update the CRYSTALClear library to the latest version:
pip install --upgrade CRYSTALClear
Troubleshooting:
If you encounter any issues during installation:
Check for any error messages and try to resolve them based on the error descriptions.
Ensure you have an active internet connection.
Try updating pip to the latest version: pip install --upgrade pip
If the issue persists, consider creating a new conda environment and reinstalling the library.
If you the issues persist please feel free to comment here below we will try our best to help you.
How to Use it
In order to use any of the feature available in the package the user need to generate
a CRYSTAL object through the crystal_io module. Three classes are available to the user
for different use cases:
Crystal_output: To extract informations and generate the object required to plot
from any .out file of the CRYSTAL package.
Properties_output: To generate the objects required to plot any of quantities
stored in the .DAT and .f25 files generated by the PROPERTIES module.
External_unit: To generate the objects required to plot any of the quantites stored
in .DAT and .f25 file generated by CRYSTAL.
Once the object is generated the user can generate the desired plot using the functions
in the plot module
Example
# Example Band Structure plot
from CRYSTALClear.crystal_io import Properties_output
import CRYSTALClear.plot as CCplt
import matplotlib.pyplot as plt
data = Properties_output().read_electron_band()
CCplt.plot_electron_band(data, **kwargs) # see the documentation for the available **kwargs
# The plotting function returns a matplotlib object that can be visualized as follows
plt.show()
The plotting function will return one (or a list of) matplotlib object(s) that the user can easily modify as any other plot produced with the library.
For a more comprehensive set of example we refer you to the following jupyter notebook repository.
How to Contribute
Any contribution to the project is more than welcome and greatly appreciated, given the open source nature of the project. If you'd like to do so, please check our guidelines on GitHub
How to Cite
If you use this package in any of your work we kindly ask you to cite the following pubblication:
Camino, Bruno, Huanyu Zhou, Eleonora Ascrizzi, Alberto Boccuni, Filippo Bodo, Alessandro Cossard, Davide Mitoli, Anna Maria Ferrari, Alessandro Erba, and Nicholas M. Harrison, Comput. Phys. Commun. 292, 108853 (2023).
@article{camino2023crystalpytools,
title={CRYSTALpytools: A Python infrastructure for the CRYSTAL code},
author={Camino, Bruno and Zhou, Huanyu and Ascrizzi, Eleonora and Boccuni, Alberto and Bodo, Filippo and Cossard, Alessandro and Mitoli, Davide and Ferrari, Anna Maria and Erba, Alessandro and Harrison, Nicholas M},
journal={Computer Physics Communications},
volume={292},
pages={108853},
year={2023},
publisher={Elsevier}
}
