First steps in Yambopy

The yambopy project aims to develop python tools to:

• Read and edit yambo and quantum espresso input files
• Easily perform pre- and post-processing of the simulation data for these two codes - including hard-to-get, database-encoded data beyond standard outputs
• Provide easy visualization and plotting options
• Set up simple automatization workflows (e.g., convergence tests)

Setup

First of all, make sure that you have a suitable python environment (crated for example with conda or venv) with python >=3.10.

If you are not used with python environments, here two simple commands that you can use

python -m venv MYPATH/yamboenv/

(you can replace `MYPATH` with any path you prefer, e.g. `~/`)

source MYPATH/yamboenv/bin/activate

(for bash users, you can add to your .bashrt the line `. MYPATH/yamboenv/bin/activate`)

Then, you may install yambopy in one of the following ways.

Quick installation from PyPI repository

• In order to quickly install the officially released version type:

pip install yambopy

Installation from tarball

• In case you don't want to download from the pip repository and prefer to install a version of yambopy locally, you may download the appropriate tarball from the yambopy github page. Extract the tarball, enter the yambopy folder and type pip install .

Installation of latest patch

• In case you want the latest version of the code including new updates and patches that might not be present in the official version, then you can clone the yambopy git repository (a basic knowledge of git may be helpful):

git clone https://github.com/yambo-code/yambopy.git
cd yambopy
pip install .

Installation for developers

• If you want to install YamboPy in developing mode (to modify or add new functions) you have to download the code from github repository then go in the YamboPy folder and install with the command:

pip install -e .

Important: if you want your changes to be included into a new patch/version of Yambopy, you need to first create your own personal fork of the git repository, make the changes there, and then create a pull request for the original repository.

Dependencies

• In principle, pip should take care of the required python dependencies. They are numpy, scipy, matplotlib, netCDF4, h5py, lxml, PyYAML, monty, scikit-learn, tqdm, spglib, spgrep, pykdtree, and numba. In case some dependency-related problem arises, you can install each of them separately beforehand with:

pip install dependency-name

• If you experience errors related to NetCDF4 or hdf5, these are usually due to incompatibilities between the python modules the library in your environment. In this case, you can force the python installation to match the system library. For example, if you have an hdf5 problem and you are using conda, you could try:

conda install --force-reinstall h5py hdf5

Tutorials

Now yambopy is ready to use! Just go to the tutorials folder and follow the docs!

cd tutorial/

On this wiki, we provide steps for the following tutorials:

1. Data postprocessing:

• Database and plotting tutorial for quantum espresso: qepy (Get the databases: databases_qepy, 46.5MB)
• Database and plotting tutorial for yambo: yambopy (Get the databases: databases_yambopy, 129MB)

2. Manage QE and Yambo runs: [WARNING: these tutorials are currently under maintenance due to updates to the scheduler class]

• GW tutorial. Convergence and approximations (BN)
• Bethe-Salpeter equation tutorial. Optical absorption (BN)

3. Advanced topics:

• Exciton-phonon coupling and luminescence
• Phonon-assisted luminescence by finite atomic displacements

How to cite

If yambopy helped you with your data analysis, workflow management of figure preparation, you can consider citing us.

The way to do so in BibTeX format is the following:

@misc{yambopy, 
     author = {Paleari, Fulvio and Molina-Sánchez, Alejandro and Nalabothula, Muralidhar and Reho, Riccardo and Bonacci, Miki and Castelo, José M. and Cervantes-Villanueva, Jorge and Pionteck, Mike and Silvetti, Martino and Attaccalite, Claudio and Pereira Coutada Miranda, Henrique},
     title = {Yambopy},
     month = mar,
     year = 2025,
     publisher = {Zenodo},
     version = {0.4.0}, 
     doi = {10.5281/zenodo.15012962},
     url = {[https://doi.org/10.5281/zenodo.15012962]}, }