About The Project

YAIV is a collection of tools for plotting results of condensed matter ab initio codes such as Quantum Espresso, VASP, Wannier90, Wannier Tools... Although it can be used from the command line, the main intention of YAIV is to be used within JupyterLab, thereby allowing users to centralize the data analysis of a whole project into a single file. The goal is to provide both (1) fast and easy plotting defaults to glance over results, while (2) being flexible and powerful enough to generate publication-ready figures.

(back to top)

Why?

A single file to rule them all...

Most of the tools contained on YAIV are nothing more than glorified python scripts I needed during my PhD. Although python libraries for ab initio data analysis already exist, I found many of them being disigned to work within the command line (often required to be run from a certain directory). YAIV is aimed at providing useful ab initio analysis functionalities to those people willing to use a single JupyterLab file to organize their projects.

YAIV also intends to provide enough flexibility and modularity for most scenarios. To this end, useful tools are also provided in order to scrape data from the output of a variety of codes. Then, users can either further process the raw data or plot it in any desired way.

(back to top)

Installation

Create an isolated python enviroment

In case you want to create your own python enviroment and have it available in JupyterLab.

    python -m venv yaiv_env                             #Create yor new enviroment
    source yaiv_env/bin/activate                        #Load the enviroment
    pip install ipykernel                               #In order to create a Jupyter Kernel for this enviroment
    python -m ipykernel install --user --name=YAIV      #Install your new kernel with your desired name
    jupyter kernelspec list                             #Check that the new installed kernel appears

Now your new installed Kernel should be available in JupyterLab. You can select Kernel clicking at the top-right corner of JupyterLab.

Installing YAIV

You can either install from pip as:

   pip install yaiv

Or cloning the git repository:

   git clone https://github.com/mgamigo/YAIV.git
   cd YAIV
   pip install .

(back to top)

Current tools

All the functions are properly documented (remember that in JupyterLab all the documentation can be conviniently accesed with the shift + tab shortcut).

I. Grep module

Provides text-scraping utilities for extracting (grepping) structural and spectral information from first-principles calculation outputs. It supports common DFT packages such as Quantum ESPRESSO and VASP.

from yaiv.grep import kpointsEnergies
spectrum = kpointsEnergies("OUTCAR")
spectrum.eigenvalues.shape
-----
(100, 32)

II. Utils module

Provides general-purpose utility functions that are used across various classes and methods in the codebase. They are also intended to be reusable by the user for custom workflows, especially when combined with the data extraction tools.

III. Spectrum module

This module defines core classes for representing and plotting the eigenvalue spectrum of periodic operators, such as electronic bands or phonon frequencies, across a set of k-points. It also supports reciprocal lattice handling and coordinate transformations.

from yaiv.spectrum import electronBands
bands = electronBands("data/qe/Si.bands.pwo")
bands.eigenvalues.shape
---
(100, 32)
---
bands.plot()
---
(Basic Figure)

IV. Plot module

Provides plotting utilities for visualizing eigenvalue spectra from periodic systems. It supports electronic and vibrational spectra obtained from common ab initio codes such as Quantum ESPRESSO and VASP.

from yaiv.spectrum import electronBands
from yaiv import plot
bands = electronBands("OUTCAR")
plot.bands(bands)
---
(Decorated Figure)

V. Cell module

Defines core functions and a container class for crystal structures used in symmetry analysis, format conversion, and structural manipulation.

It provides a Cell class that wraps an ASE Atoms object along with its spglib-compatible representation. The Cell object allows for easy integration with spglib and includes utility methods to extract and report symmetry information, Wyckoff positions, and symmetry operations in symbolic form.

from yaiv.cell import Cell
cell = Cell.from_file("data/POSCAR")
cell.get_sym_info()
SpaceGroup = Fd-3m (227)
Equivalent positions: ...
Symmetry operations: ..

---
cell.get_wyckoff_positions()
cell.wyckoff.labels
['a', 'b']
cell.wyckoff.symbols
['Si', 'Si']

VI. Phonon module

Provides tools to handle vibrational properties of crystals from first-principles calculations. It includes data structures and utilities to:

• Read .dyn* files generated by ph.x.
• Diagonalize phonon Hamiltonians to extract frequencies and modes.
• Compute commensurate supercells for charge density wave (CDW) distortions.
• Build distorted atomic configurations based on soft phonon modes.
• Creation Born-Oppenheimer energy surfaces.

from yaiv.phonon import CDW
cdw = CDW.from_file(q_cryst=[[0,0,0],[1/2, 0.0, 0.0]], results_ph_path="ph_output/")
distorted = cdw.distort_crystal(amplitudes=[1,1/5], modes=[0,0])
---
(returns Cell object of the distorted crystal)

Built With

(back to top)