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 firstname.lastname@example.org and we will be glad to set up a specific branch for your needs.
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.
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.