Introduction and Installation Guide

[fbodo]

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

QTAIM	Transport Properties	Density Maps

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:

1. 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

2. Activate the Environment (Reccommended):

conda activate env_name

3. 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:

1. Crystal_output: To extract informations and generate the object required to plot
   from any .out file of the CRYSTAL package.
2. Properties_output: To generate the objects required to plot any of quantities
   stored in the .DAT and .f25 files generated by the PROPERTIES module.
3. 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}
}