Lausanne 2017Version 4 out and rockingYambo-pyFLASH-IT

Main menu

HomeNewsPeopleDownloadRun the codeInput fileTutorials
Overview GW Lifetimes SiH4 Fantastic dimensions Hydrogen chain Electron Phonon KERR effect Surface spectroscopy GaSb Parallel Developing Yambo
DocumentationPublicationsEventsContactsRobots Forum

The Wikipedia Page of Yambo Yambo@Wiki

Fortran cafe The Fortran Cafe'

Bethe-Salpeter wine The Bethe-Salpeter-Equation (BSE) wine

A street entitled to Yambo in Rome
A bar entitled to Yambo in Rome
A bar entitled to Yambo in Rome Yambo road, bar & restaurant

Developing Yambo: calculation of the momentum distribution
by Myrta Grüning, Davide Sangalli and Claudio Attaccalite
Last revised: April 2015 - work with Yambo GPL 4.0.0


This tutorial guides you through the implementation of a new functionality in YAMBO. Though it considers the specific problem of computing the momentum distribution the procedure you will follow is general. This example is necessarily simple to fit in the tutorial. For such a simple calculation in "real life" one would likely opt for easier solutions than the one here proposed. However, rather than learning how to code the calculation of the momentum distribution, through this exercise you will learn about the general YAMBO structure, the underlying coding-philosophy and the key subroutines and variables and you will be well-equipped to start your own project if you wish.

Together with this tutorial we are also setting up specific subversion branches inside the GPL repository (still experimental) for users who would like to add new features to the yambo code. Thus, in case you are interested, please contact the yambo team yambo@yambo-code.org and we will be glad to set up a specific branch for your needs.

Calculation of momentum distribution

The task is to implement in YAMBO the calculation of the momentum distribution in independent particle approximation. The momentum distribution is defined as:

and it is related to the Compton profile [1] measured in the inelastic-ray scattering experiments:

Within the independent-particle approximation where n(p) the three-dimensional momentum distribution density is given by:

where the sum is on the occupied states only. This equation is based on the impulse approximation, and it is assumed to be valid when the energy transferred in the scattering process is much larger than the binding energy of the electronic states involved. In YAMBO all single-particle orbitals are expanded in plane waves. The previous formula then reduces to:

The latter expression is the one that you will implement in YAMBO. Later we will look at this expression more closely.

Befor starting (Warning: CECAM school students skip this part)

To be able to work, you need to perform the following steps:
  1. Create the working directory: In your home directory create the directory DEV_YAMBO (or any name you like).
  2. Get the source: Enter the DEV_YAMBO folder and download there the Yambo source code from the svn repository. Configure and compile the code. This directory will be referred in the following as the yambo (root) directory.
  3. Get the test SAVE folder: Create the directory TEST under DEV_YAMBO. Download the zip file with the SAVE directory. Unzip it and move the /YAMBO_TUTORIALS/Solid_Si/YAMBO/8x8x8/SAVE into the DEV_YAMBO/TEST directory.
  4. Get the extra source code: The fortran subroutine that actually performs the calculation is provided with this tutorial. Download the file Mdistr_driver.F, create the folder mom_distr under the yambo-4.0.0-rev71/src/ directory and move the source file Mdistr_driver.F under the new folder yambo-4.0.0-rev71/src/mom_distr .

Getting started

As well, before starting it is important to understand what is a "runlevel"?
"runlevel" is a particularly important notion in developing YAMBO. YAMBO operates through a series of functionally distinct runlevels. Each runlevel carries out a specific physical task. The main runlevels are activated via the command-line interface (or in case of dependencies by other runlevels). For example "yambo -x" activates the calculation of the Hartree-Fock self-energy. In practice it creates an input file that contains the name of the runlevel (HF_and_locXC) and all the relevant input variables. By invoking YAMBO then the code executes just the HF self-energy runlevel. Runlevels terminate with the creation of one or more databases containing the results of the calculations (for example the HF self-energy runlevel creates the db.HF_and_locXC in the SAVE directory). As well during the run a runlevel output specific log and report files, and depending on the runlevel, human-readable output files that tabulates results for e.g. plotting.

Overview of the main implementation steps

Before going into details, let's take a bird's-eye view on the implementation. Make sure you get the picture before starting the actual implementation.

First, you will create a dedicated runlevel for the momentum distribution. From what you learned here above on runlevels this implies to add a new option to the command-line interface and a new logical variable (a flag) to yambo which value is "true" ("on") when the runlevel is activated. You also want this logical variable to appear in the input generated by the command line. As you will see for this you just need to add few lines of code basically re-using the existing structure. JUMP to the first part.

Second, you need to create the input variables and add them to the generated input file so that the user can change their values. YAMBO makes a quite extensive and systematic use of fortran modules. A module is "a program unit that packages declarations and subroutines and can be easily imported into other program units". At this step you will create a module that contains the declarations of the input variables for the runlevel. Then you will "import" the module into the subroutine that 'write' the input file. In this step you see as well how to add a file to the list of files to be compiled by the "make yambo". JUMP to the second part.

Then you are ready to actually "insert" the Mdistr_driver.F subroutine into YAMBO. In this step you will take a close look of the extra source code. You will then add a call to the subroutine into the YAMBO main driver. JUMP to the third part.

Finally, you will take care of the runtime messaging (log, report) and output of the results.JUMP to the last part.

START the tutorial...


  1. Compton scattering and electron momentum determination
    J Cooper, Rep. Prog. Phys. 48 415 (1985)
  2. Compton Profiles of Li in the GW Approximation
    Yasunori Kubo J. Phys. Soc. Jpn. 65 (1996) pp. 16-18
  3. Calculation of valence electron momentum densities using the projector augmented-wave method
    I. Makkonena, M. Hakalab and M.J. Puska, J.Phys. and Chem. of Solids, 66, 2005, Pages 1128-1135
  4. On correlation effects in electron spectroscopies and the GW approximation
    Lars Hedin , J. Phys.: Condens. Matter 11 R489 (1999)