### Check Installation (Windows)

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/docs_source/installation.md

Verify the installation by listing installed packages and filtering for 'crystalpytools'. This command is for Windows.

```console
conda list | findstr /i crystalpytools
```

--------------------------------

### Check Installation (Linux/macOS)

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/docs_source/installation.md

Verify the installation by listing installed packages and filtering for 'crystalpytools'. This command is for Linux and macOS.

```console
conda list | grep -i 'crystalpytools'
```

--------------------------------

### Loading Quasi-Harmonic Thermodynamics Data (Deprecated)

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/test_oldmethods.ipynb

This example demonstrates loading quasi-harmonic thermodynamics data from a CRYSTAL-QHA output file using the deprecated `from_QHA_file` method. The recommended method is `from_file(source='crystal-QHA')`.

```python
from CRYSTALpytools.thermodynamics import Quasi_harmonic

obj = Quasi_harmonic(filename=None).from_QHA_file('thermodynamics/qha_corundumG.out')
```

--------------------------------

### Initialize and Remove ECHG Block

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/docs_source/crystalpytools.base.propd3.md

Demonstrates how to initialize the ECHG block for charge density calculations and how to remove it if it's no longer needed. The second example shows setting specific parameters for the ECHG block.

```python
obj = Properties_input()
obj.echg() # Initialize ECHG
obj.echg(None) # Remove ECHG
obj.echg(0, 95) # Charge density map, Npoint of MAPNET is 95 (default value 100)
```

--------------------------------

### Read, Modify, and Write Input File

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/docs_source/crystalpytools.base.propd3.md

This example demonstrates reading an existing CRYSTAL input file, modifying specific blocks like ECHG and ECH3, and then writing the changes to a new file. It's useful for incremental updates to input files.

```python
obj = Properties_input('charge2d.d3')
obj.echg(None) # Remove ECHG block
obj.ech3(100) # Define ECH3 block
obj.ech3.range(-10, 10) # Range of Non-periodic direction
obj.to_file('charge3d.d3') # Print it into file
```

--------------------------------

### Get Forces and Gradients

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/output/output.ipynb

Reads and prints forces on the cell, forces on atoms, and the RMS gradient from an optimization output file. Requires specifying an SCF log file to get the last optimization step's forces.

```python
from CRYSTALpytools.crystal_io import Crystal_output

out = Crystal_output('out_mgoOpt.out')
out.get_forces(grad=True, scflog='out_mgoOpt.SCFLOG')

print('Unit: Hartree/Bohr\n')
print("Forces on cell = \n %s \n\n Forces on atoms = \n %s \n\n RMS Gradient = \n %s \n\n" %
      (out.forces_cell[-1], out.forces_atoms[-1], out.opt_rmsgrad[-1]))
```

--------------------------------

### Example Experimental Data for Plotting

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/thermodynamics/qha.ipynb

This snippet provides sample experimental data, likely intended for comparison with calculated thermodynamic properties. It defines a NumPy array of floating-point values.

```python
import matplotlib.pyplot as plt

exp = np.array([111.5836, 111.9421, 112.0463, 113.4580, 114.3871,
                115.0082, 116.0031])

```

--------------------------------

### Instantiate and Modify Input from File

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/input_and_basisset/input_and_basisset.ipynb

Read an existing CRYSTAL input file using the `read_file` classmethod and modify its contents. This example shows how to set a title and specific optimization parameters within the geometry block.

```python
mgo_opt = Crystal_input.read_file('crysinp_mgo.d12')
mgo_opt.geom.title('Generated by CRYSTALpytools')
mgo_opt.geom.optgeom.toldex(0.0012)
mgo_opt.geom.optgeom.toldeg(0.0003)
print(mgo_opt.geom.data)
```

--------------------------------

### Get Basic Convergence Information

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/output/output.ipynb

Extracts basic SCF/OPT convergence information using `get_convergence()`. For more detailed analysis, use `get_scf_convergence()` or `get_opt_convergence()`. This snippet also demonstrates accessing the final energy and optimization energy differences.

```python
from CRYSTALpytools.crystal_io import Crystal_output

out = Crystal_output('out_coOpt.out')
out.get_convergence()
print('Final optimization energy {:.4f} eV'.format(out.final_energy))
print('Optimization energy difference (eV)')
print(out.opt_deltae)
```

--------------------------------

### Handle Repeated ECHG Blocks in Appended Calculations

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/docs_source/crystalpytools.base.propd3.md

This example illustrates how to manage repeated keywords, like ECHG, when using appended calculations. It shows setting up the first ECHG block, then initializing an appended calculation and setting a second ECHG block within it.

```python
obj = Properties_input()
obj.echg(0) # Set the first ECHG. MAPNET density = 100, default value is used.
obj.echg.coordina([-2.498, 0., 1.696], [-2.498, 0., -1.696], [-1.249, -2.164, -1.696])
obj.echg.rectangu()
obj.echg.margins(3, 3, 3, 3)
obj.append1() # Initialize the first appended calculation
obj.append1.pato(1, 0)
obj.append1.echg(0) # Set the second ECHG. MAPNET density = 100, default value is used.
obj.append1.echg.coordina([-2.498, 0., 1.696], [-2.498, 0., -1.696], [-1.249, -2.164, -1.696])
obj.append1.echg.rectangu()
obj.append1.echg.margins(3, 3, 3, 3)
```

--------------------------------

### Plotting Electronic Structure (Band and DOS)

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/test_oldmethods.ipynb

Combines plotting of band structure and density of states from a single file. Use 'read_electron_band' and 'read_electron_dos' for reading, and 'plot_electron_es' for plotting. This example customizes colors, line styles, and labels for both band and DOS components.

```python
from CRYSTALpytools.crystal_io import Properties_output
from CRYSTALpytools.plot import plot_cry_es

obj1 = Properties_output().read_cry_band('electronic_structure/es_grapheneDV.f25')
obj2 = Properties_output().read_cry_doss('electronic_structure/es_grapheneDV.f25')

fig = plot_cry_es(obj1, obj2, color_bd='brown', fermi='limegreen',
                  color_doss=['blue', 'red', 'green'], energy_range=[-4,6],
                  linestl_doss=['-', '--', 'dotted'], prj=[1,2,3],
                  labels=['prj1', 'prj2', 'prj3'], dos_range=[0, 20],
                  k_labels=['Gamma', 'M', 'K', 'A', 'L', 'H', 'K'])
```

--------------------------------

### Get Optimized Geometry and Write GUI File

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/output/output.ipynb

Retrieves the optimized structure from a 0D molecule optimization and writes a '.gui' file. Use `symmetry='initial'` if symmetry is maintained during optimization, as pymatgen's symmetry analysis is limited to 3D systems. The `write_gui` and `gui_name` arguments control the output file generation.

```python
from CRYSTALpytools.crystal_io import Crystal_output

struc = Crystal_output('out_coOpt.out').get_geometry(
    initial=False, write_gui=True, gui_name='out_coOpt.gui', symmetry='initial')
print(struc)
! cat out_coOpt.gui
```

--------------------------------

### Getting Last Geometry (Deprecated)

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/test_oldmethods.ipynb

This example demonstrates retrieving the last geometry from a CRYSTAL output file using the deprecated `get_last_geom` method. The recommended method is `get_geometry(initial=False)`.

```python
from CRYSTALpytools.crystal_io import Crystal_output

out = Crystal_output('output/out_mgoOpt.out')
out.get_last_geom(write_gui_file=False)
```

--------------------------------

### Initialize and Remove OPTGEOM Block

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/docs_source/crystalpytools.base.crysd12.md

Demonstrates how to initialize the OPTGEOM block by calling the `optgeom` method with no arguments, and how to remove it by calling it with `None`.

```python
obj = Crystal_input()
obj.geom.optgeom() # Initialize OPTGEOM
obj.geom.optgeom(None) # Remove OPTGEOM
```

--------------------------------

### Restarting QHA Calculations from YAML Files

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/thermodynamics/qha.ipynb

Demonstrates how to restart QHA calculations using previously saved YAML files for frequencies, Grüneisen parameters, and equations of state. This allows for recalculating properties without rerunning the entire QHA process.

```python
from CRYSTALpytools.thermodynamics import Quasi_harmonic

freq = Quasi_harmonic.restart('qha_FreqFit.yaml')
print("QHA method: {}".format(freq.method))
print("EOS method: {}".format(freq.eos_method))
print("Frequency polynomial order:")
print(freq.fit_order)

gru = Quasi_harmonic.restart('qha_GruFit.yaml')
print("QHA method: {}".format(gru.method))
print("EOS method: {}".format(gru.eos_method))
print("Gruneisen parameter of mode 4 at Gamma:")
print(gru.gru_fit[0, 3])

eos = Quasi_harmonic.restart('qha_EoSFit.yaml')
print("QHA method: {}".format(eos.method))
print("EOS method: {}".format(eos.eos_method))
print("Gibbs free energy polynomial order:")
print(eos.fit_order)
```

--------------------------------

### Install windows-curses

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/README.md

Installs the 'windows-curses' package, which may be required for Windows users when installing CRYSTALpytools via pip.

```console
pip install windows-curses
```

--------------------------------

### Install CRYSTALpytools via Pip

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/README.md

Installs or upgrades the CRYSTALpytools package from PyPI using pip. This is the standard method for installing Python packages.

```console
pip install --upgrade CRYSTALpytools
```

--------------------------------

### Install CRYSTALpytools via Conda Forge

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/README.md

Installs the CRYSTALpytools package from Conda Forge. This method is an alternative to pip installation and is suitable for conda environments.

```console
conda install CRYSTALpytools -c conda-forge
```

--------------------------------

### Set SCF and Frequency Calculation Parameters

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/docs_source/crystalpytools.base.crysd12.md

Illustrates setting parameters like `toldeg` for `preoptgeom` within `freqcalc`, and `toldee` for the `scf` block. It also shows how to print a keyword without a value using `ppan()`.

```python
obj.geom.freqcalc.preoptgeom() # Initialize PREOPTGEOM
obj.geom.freqcalc.preoptgeom.toldeg(0.0003)
obj.scf.toldee(9) # Set SCF TOLDEE = 9
obj.scf.toldee(None) # Clean the TOLDEE keyword and value
obj.scf.ppan() # Print PPAN keyword, without value
```

--------------------------------

### Visualize CO2 Structure at Origin

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/geometry/visualization.ipynb

Visualize a CO2 structure with the origin at [0, 0, 0]. This example is for developer testing.

```python
from CRYSTALpytools.convert import cry_gui2pmg
from CRYSTALpytools.geometry import CStructure

cstruc = CStructure.from_pmg(cry_gui2pmg('geom_co2.gui'))
# co2 at origin
cstruc.visualize()
```

--------------------------------

### Initialize and Fit QHA Frequencies

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/thermodynamics/qha.ipynb

Initializes the Quasi_harmonic object with temperature and pressure data, loads phonon frequencies from crystal output files, and fits them using the 'thermo_freq' method. Requires at least 5 pressure sampling points for stable fitting.

```python
import numpy as np
from CRYSTALpytools.thermodynamics import Quasi_harmonic

file_list = ['qha_paracetamolGm4.out', 'qha_paracetamolGp4.out',
             'qha_paracetamolGr0.out', 'qha_paracetamolGp8.out']
T = np.array([20, 50, 80, 150, 200, 250, 330], dtype=float)
p = np.linspace(0, 0.15, 6)

qha = Quasi_harmonic(filename='qha_FreqFit.yaml', temperature=T,
                     pressure=p).from_file(*file_list, source='crystal')
qha.thermo_freq(eos_method='birch_murnaghan', poly_order=[2, 3],
                min_method='BFGS')
```

--------------------------------

### Instantiate from Phonon Output Files

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/docs_source/crystalpytools.thermodynamics.md

Instantiate the Quasi_harmonic class from various phonon output files, including CRYSTAL and Phonopy formats. This method supports sorting modes based on overlap tolerance.

```python
qha = Quasi_harmonic()
qha.from_file('phonopy_qpoints.out', source='phonopy', mode_sort_tol=0.4)
```

--------------------------------

### Activate Conda Environment

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/README.md

Activates the previously created conda environment named 'crystal'. Ensure the environment is activated before installing packages.

```console
conda activate crystal
```

--------------------------------

### Get Geometry from Properties Output

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/output/output.ipynb

Retrieves and prints the crystal structure geometry, including lattice parameters and atomic positions, from a properties output file.

```python
from CRYSTALpytools.crystal_io import Properties_output

out = Properties_output('out_mgo.outp')
out.get_geometry()
```

--------------------------------

### Generating Charge Difference Maps with Properties_input

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/input_and_basisset/input_and_basisset.ipynb

Illustrates how to set up and calculate charge difference maps using the `Properties_input` class, including defining coordinates and margins for the charge density calculation. This is useful for analyzing electronic structure differences between calculations.

```python
from CRYSTALpytools.crystal_io import Properties_input

inp = Properties_input()
inp.echg(0, 100)
inp.echg.coordina([-4., -4., 0.], [4, -4, 0.], [4., 4., 0.])
inp.echg.margins(1.5, 1.5, 1.5, 1.5)
inp.echg.rectangu()

inp.append1.pato(0, 0)
inp.append1.echg(0, 100)
inp.append1.echg.coordina([-4., -4., 0.], [4, -4, 0.], [4., 4., 0.])
inp.append1.echg.margins(1.5, 1.5, 1.5, 1.5)
inp.append1.echg.rectangu()

inp.write_file('adv_dCHG.d3')
print(inp.data)
```

--------------------------------

### Visualize CO2 Structure at Body Center

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/geometry/visualization.ipynb

Visualize a CO2 structure centered at [0.5, 0.5, 0.5] in fractional coordinates. This example is for developer testing.

```python
from CRYSTALpytools.convert import cry_gui2pmg
from CRYSTALpytools.geometry import CStructure

cstruc = CStructure.from_pmg(cry_gui2pmg('geom_co2.gui'))
# co2 at body center
cstruc.visualize(display_origin=[0.5, 0.5, 0.5])
```

--------------------------------

### Performing QHA Calculations with thermo_freq() and thermo_eos()

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/thermodynamics/qha.ipynb

This snippet demonstrates how to initialize Quasi_harmonic objects and perform both mode-specific frequency fitting (`thermo_freq()`) and equation of state fitting (`thermo_eos()`). It compares the time consumption of these two methods. Ensure you have the necessary output files and define temperature and pressure arrays.

```python
import numpy as np
from CRYSTALpytools.thermodynamics import Quasi_harmonic
import time

file_list = ['qha_paracetamolGm4.out', 'qha_paracetamolGp4.out',
             'qha_paracetamolGr0.out', 'qha_paracetamolGp8.out']
tempt = np.array([0, 20, 50, 80, 150, 200, 250, 330], dtype=float)
press = np.linspace(0, 0.15, 6)

mode = Quasi_harmonic(filename='qha_FreqFit.yaml').from_file(*file_list, source='crystal', mode_sort_tol=0.4)
eos = Quasi_harmonic(filename='qha_EoSFit.yaml').from_file(*file_list, source='crystal', mode_sort_tol=None)

tbg = time.perf_counter()
# Mode-specific
mode.thermo_freq(temperature=tempt, pressure=press,
                 eos_method='birch_murnaghan',
                 poly_order=3, min_method='BFGS', mutewarning=True)

tmode = time.perf_counter()
# EoS
eos.thermo_eos(temperature=tempt, pressure=press,
               eos_method='birch_murnaghan',
               poly_order=3, mutewarning=True)

teos = time.perf_counter()
print('Time consumption for Mode-Specific fitting: %12.6f s' % (tmode - tbg))
print('Time consumption for EoS fitting: %12.6f s' % (teos - tmode))
```

--------------------------------

### Generate Thumbnail Image

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/elastic_properties/elastic_properties.ipynb

This code block is used solely for generating a thumbnail image for the example gallery. It displays a PNG image using matplotlib.

```python
import matplotlib.pyplot as plt
fig, ax = plt.subplots()
ax.imshow(plt.imread("./elastic_thumbnail.png"))
ax.axis('off')
```

--------------------------------

### Initializing and Running QHA Calculation

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/thermodynamics/qha.ipynb

Initializes a Quasi_harmonic object from a CRYSTAL output file and performs thermodynamic calculations over a range of temperatures and pressures. Requires numpy, matplotlib, and CRYSTALpytools.

```python
import numpy as np
from CRYSTALpytools.thermodynamics import Quasi_harmonic
import matplotlib.pyplot as plt

file = 'qha_corundumG.out'
T = np.linspace(0, 1000, 21)
p = np.linspace(0, 1, 5)

gru = Quasi_harmonic(filename='qha_GruFit.yaml').from_file(file, source='crystal-QHA')
gru.thermo_gruneisen(temperature=T, pressure=p, eos_method='birch_murnaghan',
                     poly_order=3, min_method='BFGS')

fig, ax = plt.subplots(1, 1, figsize=(6, 4))
style = ['v-b', 'v-c', 'v-g', 'v-y', 'v-r']

for v, s, p in zip(gru.volume, style, gru.pressure):
    ax.plot(T, v, s, label='{:.2f} GPa'.format(p))

ax.legend(loc='lower right')
ax.set_xlabel('Temperature (K)')
ax.set_ylabel(r'Volume ($\AA^{3}$)')
```

--------------------------------

### Get Raman Spectra Data

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/spectra/spectra.ipynb

Retrieves Raman spectra data using the get_spectra method from Crystal_output. Prints the frequency unit and the length of the frequency array.

```python
from CRYSTALpytools.crystal_io import Crystal_output

ra = Crystal_output('spec_dryIceRaman.out').get_spectra('spec_dryIceRaman.RAMSPEC')

print('Frequency Unit: {}'.format(ra.unit))
print('Length of frequency: {:d}'.format(len(ra.frequency)))
```

--------------------------------

### Generate Thumbnail Image

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/thermodynamics/qha.ipynb

This code snippet is used solely for generating a thumbnail image for the example gallery. It reads an image file and displays it without axes.

```python
import matplotlib.pyplot as plt
fig, ax = plt.subplots()
ax.imshow(plt.imread("./qha_paracetamolG.png"))
ax.axis('off')
```

--------------------------------

### Fit and Plot Lattice Parameters with lattice_poly()

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/thermodynamics/qha.ipynb

Fits lattice parameters as a polynomial function of volume at constant pressures and plots the results. Requires pre-calculated QHA output files and temperature/pressure arrays.

```python
import numpy as np
from CRYSTALpytools.thermodynamics import Quasi_harmonic
import matplotlib.pyplot as plt


file_list = ['qha_paracetamolGm4.out', 'qha_paracetamolGp4.out',
             'qha_paracetamolGr0.out', 'qha_paracetamolGp8.out']
T = np.array([0, 20, 50, 80, 150, 200, 250, 330], dtype=float)
p = np.linspace(0, 0.15, 6)

obj = Quasi_harmonic(filename='qha_LattPolyFit.yaml', temperature=T,
                     pressure=p).from_file(*file_list, source='crystal')
obj.thermo_freq(eos_method='birch_murnaghan', poly_order=[2, 3],
                min_method='BFGS')
obj.lattice_poly(poly_order=3)

fig, ax = plt.subplots(2, 2, figsize=(8, 6), sharey=False, layout='tight')

name = ['a', 'b', 'c', 'beta']
color = ['tab:gray', 'tab:purple', 'tab:blue', 'tab:green', 'tab:orange', 'tab:red']
for il in range(obj.latt_params.shape[-1]):
    for ip in range(obj.latt_params.shape[0]):
        # nPressure*nTemperature*nLattice
        fig.axes[il].plot(T, obj.latt_params[ip, :, il], color=color[ip],
                          marker='v', label='{} @ {:.2f}GPa'.format(name[il], p[ip]))
    fig.axes[il].legend(loc='lower right')
    fig.axes[il].set_xlabel('Temperature (K)')
    fig.axes[il].set_ylabel(r'Length ($\AA$)')
fig.axes[-1].set_ylabel(r'Degree ($\circ$)')
```

--------------------------------

### Get Mulliken Charges

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/output/output.ipynb

Retrieves Mulliken charges for converged SCF or OPT calculations. Requires the 'PPAN' keyword in the input. Currently, it only reads charges per atom.

```python
from CRYSTALpytools.crystal_io import Crystal_output

out = Crystal_output('out_gMVsaddleSCF.out').get_mulliken_charges()
print('Charges of atom 1: Total = {:.4f}; Alpha = {:.4f}; Beta = {:.4f}'.format(
    out[0, 0], out[0, 1], out[0, 2]
))
```

--------------------------------

### Instantiate ElectronBand Object

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/electronic_structure/electronic_structure.ipynb

Instantiates an ElectronBand object from band structure files. Requires the band file and the output file.

```python
from CRYSTALpytools.electronics import ElectronBand

mgoband = ElectronBand.from_file('band_mgo.BAND', 'band_mgo.outp')
```

--------------------------------

### Convert CRYSTAL output to pymatgen Structure

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/convert/convert.ipynb

Use cry_out2pmg to convert a CRYSTAL output file to a pymatgen Structure object. Set initial=False to get the optimized geometry.

```python
from CRYSTALpytools.convert import cry_out2pmg

struc = cry_out2pmg('conv_mgoOpt.out',initial=False)
print(struc)
```

--------------------------------

### from_file Method

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/docs_source/crystalpytools.thermodynamics.md

Instantiates the Quasi_harmonic object from output file(s) generated by CRYSTAL or Phonopy. It supports various input formats and allows for sorting phonon modes based on eigenvector overlap.

```APIDOC
## from_file(*filename, source='crystal', mode_sort_tol=0.4, **kwargs)

### Description
Instatiation from output file(s). Files generated by the following methods are supported (also the accepted entries for `source`):

* `'crystal'`: CRYSTAL harmonic phonon outputs (Gamma, dispersion).
* `'crystal-QHA'`: CRYSTAL QHA outputs.
* `'phonopy'`: Phonopy qpoints and mesh files.

### Parameters
* ***filename** (*str*) – Phonon output filename(s). Extendable.
* **source** (*str*) – The program used for the output file.
* **mode_sort_tol** (*float* | *None*) – The threshold of close mode overlaps with eigenvectors if present. If none, do not sort modes and eigenvector is not read.
* ****kwargs** – Optional keywords passed to `Harmonic().from_file()`.
  * **scale** (*float* | *array*)
  * **scale_range** (*array*)
  * **imaginary_tol** (*float*)
  * **q_overlap_tol** (*float*)
  * **q_id** (*array*) – Applied to all HA calculations.
  * **q_coord** (*array*) – Applied to all HA calculations.
  * **struc_yaml** (*list*[*str*]) – *phonopy*. ‘qpoints.yaml’ only.
  * **u_0** (*list*[*float*]) – *phonopy*. Static internal energy in kJ/mol.
  * **irreps_yaml** (*array*[*str*]) – *phonopy*. nCalc*nQpoint array. Read ‘irreps.yaml’ for mode symmetry symbols. The fractional coordinates in the file are used for `q_coord` if not specified. Phonopy ‘irreps.yaml’ only contains symmetry info of a q point. Use a list of filenames for multiple q points.

### Returns
* **self** (*Quasi_harmonic*) – New Attributes listed below
* **ncalc** (*int*) – Number of HA phonon calculations.
* **combined_volume** (*array[float]*) – 1*nCalc volumes. Unit: $\AA^{3}$
* **combined_struc** (*list[CStructure]*) – 1*nCalc HA structures.
* **combined_u0** (*array[float]*) – 1*nCalc static internal energies. Unit: kJ/mol
* **combined_freq** (*array[float]*) – nQpoint*nMode*nCalc frequencies. Unit: THz
* **combined_symm** (*array[str]*) – nQpoint*nMode*nCalc mode symmetry in Mulliken symbol.
* **nqpoint** (*int*) – Number of q points.
* **qpoint** (*array[float]*) – nQpoint*4 array. The first three elements are fractional coordinates, and the last is the weight.
* **nmode** (*int*) – Number of modes.
* **natom** (*int*) – Number of atoms.
```

--------------------------------

### Get Geometry from SCF Calculation

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/output/output.ipynb

Extracts the crystal structure from a CRYSTAL SCF output file. Returns a `geometry.CStructure` object, which inherits from `pymatgen.core.structure.Structure`. Ensure the `Crystal_output` class is imported.

```python
from CRYSTALpytools.crystal_io import Crystal_output

struc = Crystal_output('out_mgoSCF.out').get_geometry()
print(struc)
```

--------------------------------

### Instantiate and Load QHA Data

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/docs_source/crystalpytools.thermodynamics.md

Instantiate the Quasi_harmonic class and load data from a QHA output file. This is useful for resuming calculations or analyzing existing QHA results.

```python
qha = Quasi_harmonic()
qha.from_QHA_file('qha_phonon.out')
```

--------------------------------

### Convert CRYSTAL output to pymatgen Molecule

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/convert/convert.ipynb

Use cry_out2pmg with molecule=True to convert a CRYSTAL output file to a pymatgen Molecule object. Set initial=False to get the optimized geometry.

```python
from CRYSTALpytools.convert import cry_out2pmg

struc = cry_out2pmg('conv_coOpt.out',initial=False, molecule=True)
print(struc)
```

--------------------------------

### Use Existing File as Template for Input Generation

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/input_and_basisset/input_and_basisset.ipynb

Initialize a `Crystal_input` object using an existing CRYSTAL input file as a template. This allows for modification, deletion, or addition of keywords and blocks based on the template.

```python
mgo_opt = Crystal_input('crysinp_mgo.d12')
mgo_opt.geom.optgeom()
print(mgo_opt.geom.data)
```

--------------------------------

### Load Harmonic data from Phonopy YAML file

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/thermodynamics/harmonic.ipynb

Load harmonic data from a Phonopy YAML file. Specify 'phonopy' as the source. For 'qpoints.yaml', a separate structure file must be provided.

```python
from CRYSTALpytools.thermodynamics import Harmonic

obj = Harmonic(filename=None, autocalc=False).from_file('ha_Fe2O3mesh.yaml', source='phonopy')

print('Number of q / k points: {:d}'.format(obj.nqpoint))
print('Number of modes at Gamma: {:d}'.format(obj.nmode))
print('The first non-translational mode frequnecy at Gamma: {:.4f} THz'.format(
    obj.frequency[0, 3]))
```

--------------------------------

### Get Shear Modulus Between Directions

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/elastic_properties/elastic_properties.ipynb

Calculate the shear modulus between two specified crystallographic directions using the `get_pair` method of a `Tensor3D` object. `use_cartesian=False` is used for crystallographic directions.

```python
print(t3d.get_pair('shear', [1, 0, 0], [0, 0, 1], use_cartesian=False))
```

--------------------------------

### Create CRYSTAL Input Object with Keywords

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/input_and_basisset/input_and_basisset.ipynb

Instantiate a `Crystal_input` object and set various CRYSTAL keywords programmatically. This method is useful for building input files from scratch by specifying each parameter individually.

```python
from CRYSTALpytools.crystal_io import Crystal_input

mgo_input = Crystal_input()
mgo_input.geom.title('MGO BULK - GEOMETRY TEST')
mgo_input.geom.crystal(225, # Space group
                      [4.217], # Minimal set of lattice parameters
                      [[12, 0., 0., 0.], # Atomic labels and coordinates
                       [8, 0.5, 0.5, 0.5]]
                      )
mgo_input.basisset.basisset('POB-DZVP')
mgo_input.scf.dft.xcfunc('B3LYP')
mgo_input.scf.dft.xxlgrid()
mgo_input.scf.tolinteg(7, 7, 7, 7, 14)
mgo_input.scf.shrink(12, 24)
mgo_input.scf.maxcycle(70)
mgo_input.scf.fmixing(70)
mgo_input.scf.diis()

print(mgo_input.data)
```

--------------------------------

### Visualize Hematite Structure (Trigonal)

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/geometry/visualization.ipynb

Visualize a hematite structure with specific atom-bond ratio and scale, using default display settings for trigonal representation. This example is for developer testing.

```python
from CRYSTALpytools.convert import cry_gui2pmg
from CRYSTALpytools.geometry import CStructure

cstruc = CStructure.from_pmg(cry_gui2pmg('geom_hematite.gui'))
# trigonal
cstruc.visualize(atom_bond_ratio='small', scale=1.0)
```

--------------------------------

### Instantiate and Plot ElectronBandDOS

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/electronic_structure/electronic_structure.ipynb

Instantiates an ElectronBandDOS object from a 'fort.25' file and plots the band structure with specified labels and energy range. Assumes the 'es_grapheneDV.f25' file exists.

```python
from CRYSTALpytools.electronics import ElectronBandDOS

es = ElectronBandDOS.from_file('es_grapheneDV.f25')
fig = es.plot(k_label=[r'$\\\Gamma$', "M'", 'K', r'$\\\Gamma$', 'M', "K'", r'$\\\Gamma$'],
              energy_range=[-3, 3], dos_prj=[-1], dos_label='Total')
```

--------------------------------

### Phonon.from_file

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/docs_source/crystalpytools.phonons.md

Instantiates a Phonon object from a file. It supports various sources including CRYSTAL harmonic phonon outputs, CRYSTAL QHA outputs, and Phonopy band, qpoints, and mesh files. Optional parameters allow for specifying q-points by ID or coordinates.

```APIDOC
## Phonon.from_file

### Description
Instantiation from a file. Files generated by the following methods are supported (also the accepted entries for `source`):
* `'crystal'`: CRYSTAL harmonic phonon outputs (Gamma, dispersion and band).
* `'crystal-QHA'`: CRYSTAL QHA outputs.
* `'phonopy'`: Phonopy band, qpoints and mesh files.

NOTE: In rare cases, the user might want to collect data of a few specific q points. `q_id` and `q_coord` can be set but not simultaneously. If set, `q_id` takes priority and `q_coord` is ignored.

### Method
classmethod

### Parameters
#### Path Parameters
* **filename** (*str*) – Name of the output file.
* **source** (*str*) – The program used for the output file. (Default: 'crystal')
* **q_id** (*array*) – Index (from 0) of q points to be read. 1*nqpoint. (Default: None)
* **q_coord** (*array*) – Fractional coordinates of q points to read. nqpoint*3 list. (Default: None)
* **\*\*kwargs** – Other keywords passed to corresponding I/O functions. See below.
  * **qha_index** (*int*) – *crystal-QHA*. The index of calculation to read (from 0).
  * **struc_yaml** (*str*) – *phonopy*. ‘qpoints.yaml’ only.
  * **u_0** (*float*) – *phonopy*. Static internal energy in eV.
  * **irreps_yaml** (*array* *[**str* *]*) – *phonopy*. Read ‘irreps.yaml’ for mode symmetry symbols. The fractional coordinates in the file are used for `q_coord` if not specified. Phonopy ‘irreps.yaml’ only contains symmetry info of a q point. Use a list of filenames for multiple q points.

### Returns
#### Success Response
* **self** (*Phonon*) – An instance of the Phonon class with attributes matching the inputs.

```

--------------------------------

### Visualize Hematite Structure (Hexagonal)

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/geometry/visualization.ipynb

Visualize a hematite structure with specific atom-bond ratio and scale, using a custom display matrix for hexagonal representation. This example is for developer testing.

```python
from CRYSTALpytools.convert import cry_gui2pmg
from CRYSTALpytools.geometry import CStructure

cstruc = CStructure.from_pmg(cry_gui2pmg('geom_hematite.gui'))
# hexagonal
cstruc.visualize(atom_bond_ratio='small', scale=1.0,
                 display_matrix=[[1, -1, 0], [0, 1, -1], [1, 1, 1]])
```

--------------------------------

### Loading Multiple Quasi-Harmonic Thermodynamics Data (Deprecated)

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/test_oldmethods.ipynb

This snippet shows how to load quasi-harmonic thermodynamics data from multiple CRYSTAL output files using the deprecated `from_HA_files` method. The recommended method is `from_file(source='crystal')`.

```python
from CRYSTALpytools.thermodynamics import Quasi_harmonic

files = ['thermodynamics/qha_paracetamolGm4.out',
         'thermodynamics/qha_paracetamolGr0.out',
         'thermodynamics/qha_paracetamolGp4.out',
         'thermodynamics/qha_paracetamolGp8.out']

obj = Quasi_harmonic(filename=None).from_HA_files(*files)
```

--------------------------------

### SCFBASE.get_SCF_blocks

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/docs_source/crystalpytools.base.output.md

Identifies and extracts the start and end points of all SCF (Self-Consistent Field) convergence blocks within the output data. This is useful for analyzing the convergence behavior of SCF calculations.

```APIDOC
## SCFBASE.get_SCF_blocks

### Description
Get SCF convergence block from output file.

### Method
`classmethod`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **data** (*DataFrame*) – Pandas DataFrame of the output.

### Returns
* **nSCF** (*int*) – Number of SCF blocks
* **SCFrange** (*array[int, int]*) – The beginning and ending points of every SCF block.
```

--------------------------------

### Get SCF History with ONELOG

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/output/output.ipynb

Retrieves optimization convergence data and includes SCF energy history when the 'ONELOG' keyword is enabled. Accesses SCF energies for a specific optimization step.

```python
from CRYSTALpytools.crystal_io import Crystal_output

out = Crystal_output('out_mgoOptONELOG.out').get_opt_convergence(scf_history=True)
print('SCF energy history of OPT step 2 (eV)')
print(out.scf_energy[1])
```

--------------------------------

### Read and Plot Electron Density (Deprecated)

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/test_oldmethods.ipynb

Shows how to read and plot electron density using deprecated functions. The output includes warnings about the deprecated function and potential file not found issues.

```python
from CRYSTALpytools.crystal_io import Properties_output
from CRYSTALpytools.plot import plot_dens_ECHG, plot_spin_ECHG

obj = Properties_output().read_cry_ECHG('charge_density/dens_grapheneMV.f25')
fig = plot_dens_ECHG(obj)
```

--------------------------------

### Quasi_harmonic Class

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/docs_source/crystalpytools.thermodynamics.md

Initializes the Quasi_harmonic object to generate and rearrange harmonic phonons, store QHA phonon information, and obtain thermodynamic properties. It can be initialized with temperature, pressure, and filename, or by loading data from existing files.

```APIDOC
## class Quasi_harmonic(temperature=[], pressure=[], filename=None, use_old=False)

### Description
Generate and rearrange harmonic phonons, store the fitted, volume-dependent QHA phonon information and obtain the QHA thermodynamic properties.

### Parameters
* **temperature** (*array* | *float*) – Should be given in ascending order, or will be sorted. Unit: K
* **pressure** (*array* | *float*) – Should be given in ascending order, or will be sorted. Unit: GPa
* **filename** (*str*) – Name of the output file in YAML format for restarting calculation.
* **use_old** (*bool*) – Use the deprecated text fomat output, which cannot be used for restarting calculation.

Temperatures and pressures can also be defined by `self.thermodynamics`, whose entries always cover the entries here.

### Usage Example
```python
qha = Quasi_harmonic()
qha.from_QHA_file('qha_phonon.out')
qha.thermo_freq(eos_method='birch_murnaghan', temperature=[0, 100, 200, 300], pressure=[0., 0.5, 1.])
```
```

--------------------------------

### Get SCF Convergence History

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/output/output.ipynb

Retrieves the SCF convergence history, including energies and energy differences. Useful for visualizing the convergence process of a CRYSTAL calculation. Requires matplotlib for plotting.

```python
from CRYSTALpytools.crystal_io import Crystal_output
import matplotlib.pyplot as plt

out = Crystal_output('out_mgoSCF.out').get_scf_convergence()

print('SCF convergence status = {}'.format(out.scf_status))
print('SCF number of cycles = {:d}'.format(out.scf_cycles))
print('Final energy = {:.6f} eV'.format(out.final_energy))

fig, ax = plt.subplots(1, 1, figsize=[6, 3])
x = [i for i in range(out.scf_cycles)]
ax.plot(x, out.scf_energy, 'b-', label='SCF energy')
ax.set_xlabel('Number of SCF Cycles')
ax.set_ylabel('Total Energy (eV)')
ax.legend()
ax2 = ax.twinx()
ax2.plot(x, out.scf_deltae, 'r-', label=r'$\\Delta$E')
ax2.set_ylabel('Energy Differenece (eV)')
ax2.legend()
```

--------------------------------

### Instantiate Elastic Tensors from Files

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/elastic_properties/elastic_properties.ipynb

Create `Tensor3D` and `Tensor2D` objects using wrapper functions or class methods, specifying effective thickness for 2D tensors. This is an alternative to using `Crystal_output` for direct elastic tensor analysis.

```python
from CRYSTALpytools.elastics import *

t3d = tensor_from_file('elastic3D_ZIF8_P0.out', conventional_lattice=True)
t2d = Tensor2D.from_file('elastic2D_graphene.out', thickness=10.2)

print('3D tensor: ', type(t3d))
print('2D tensor: ', type(t2d))
```

--------------------------------

### Get Phonon Band Data from Crystal Output

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/phonons/phonons.ipynb

Extracts phonon band structure data from a CRYSTAL output file using Crystal_output.get_phonon_band(). Returns a PhononBand object for further analysis and plotting.

```python
from CRYSTALpytools.crystal_io import Crystal_output

out = Crystal_output('phono_Gstrain0Band.out')
band = out.get_phonon_band()
print('Number of bands: {:d}'.format(band.n_bands))
print('Number of k points: {:d}'.format(band.n_kpoints))
```

--------------------------------

### Get Averaged Poisson Ratio

Source: https://github.com/crystal-code-tools/crystalpytools/blob/main/examples/elastic_properties/elastic_properties.ipynb

Retrieve the averaged Poisson ratio perpendicular to a specified crystallographic direction using the `get_1D` method of a `Tensor3D` object. `use_cartesian=False` is used for crystallographic directions.

```python
print(t3d.get_1D('poisson avg', [1, 0, 0], use_cartesian=False))
```