Unlike most of the other tutorials, this one is aimed towards developers. Being an ABINIT user is not required, though it will help a lot. However some experience in programming is necessary if you want to take maximum benefit from this lesson. In particular, some ease with Fortran 90 / Fortran 95 will be truly welcome. Be familiar with the command line will be a must. We want here to give you an insight into the internals of ABINIT. In other words, you will look at what's under the cap.
The ABINIT package is aimed at being used by different groups of people, without mandatory control by the main contributors of the ABINIT group. In the same way, the ABINIT development project is fundamentally open to the contributions of different persons, not located in one of the major groups of the ABINIT project (see the list of institutions in ~ABINIT/Infos/contributors). De facto, these external contributors are members of the ABINIT group.
People using the code might consider developping their personal subroutines without trying to make them part of the official ABINIT package. However, this has two drawbacks for them: in subsequent versions, their modifications will not be incorporated, so that they might have to check and modify the interface for each new version; moreover, their addition is not tested by other users of the code, so that some nasty bugs might remain unnoticed. Our opinion is that it would also be nicer from them to share the fruits of their coding efforts with other users of the code.
Of course, a collaborative effort has some drawbacks as well. In particular, the collaboration between distant developers should be carefully planned, since orthogonal modifications of the same piece of code by two different people at the same time is very likely to happen, generating "negative progress", i.e. a large waste of time when synchronization is to be done. It is also necessary to use a well-defined coding style, to provide test case files, and to comment the modifications and additions as much as possible, aiming at facilitating the maintenance and the future modifications.
The procedure that is followed was described in the (severely out-of-date) collab file. It is now part of the web site under "How to contribute" in the Developer's corner section.
The main goals of this lesson are to provide you with a useful understanding of the source tree structure and the compile process, as well as sensibilize you to the rules and procedures followed for the development of ABINIT. We have chosen to explain you what to do in case you want to add an input variable to the code and create an associated subroutine. We will now imagine that you have designed a new exchange-correlation functional and that you want to test it with ABINIT. Here are the steps we will follow:
There are two ways of getting the source code of ABINIT:
While the first method is straightforward, the second one requires you to know how to use TLA, Thomas Lord's implementation of GNU Arch. Although using this powerful development tool is far beyond the scope of this lesson, we feel it is worth mentioning it, as it has become the basis for the management of contributions to ABINIT. There is a comprehensive tutorial for GNU Arch on the ABINIT web site, in the Developer's corner section.
Once you have got the tarball, uncompress it by typing:
Then go into the newly-created abinit-4.6.3 directory and have a look at it. To get more familiar with the source tree structure, have a closer look at the ~ABINIT/Infos/dirs_and_files file You can alternatively consult it on the website (see "Developer's docs"). Then answer the following questions:
Q1. If you need off-line documentation, in which directories will you look for?
Q2. Where can be found the external libraries?
Q3. What do the numbers in the names of the "Src_*" subdirectories stand for?
Q4. In the source subdirectories, what do the object_list files contain? In your opinion, what is their purpose?
Q5. What kind of tests are available? How important do you think they are?
Now you can try to compile ABINIT. Information on how to do this is available on the Web site, or in the package : ~ABINIT/Infos/Installation_notes/install.html
The compilation will likely take more than 10 minutes. In the meantime, you can proceed to the next task.
At this point, you have to discover what parts of the code will have to be modified in order to have your contribution correctly integrated. Devise a strategy to establish the list of files you will have to work on. Answering the following questions should give you some hints.
Q6. How would you identify the subroutines involved in the treatment of input variables?
Q7. Where are the routines handling exchange-correlation? Which input variables are they strongly related to?
Q8. What subroutine would you choose to call yours?
Choose randomly a subroutine in one of the "Src_*" subdirectories and have a look at it, putting emphasis on its header. Then read thoroughly the file ~ABINIT/Infos/Notes_for_coding/rules_coding, and see whether the rules have been correctly followed. This is an essential step before you start writing your own subroutine. To actually start, go to the subdirectory you've identified before and just type:
For this lesson, your input variable will be a real number called "lesson". The task devoted to your routine is just to transmit the value of this input variable in a suitable format to the wrtout subroutine.
Q9. Where is wrtout? What is its purpose? How does it work?
Add treatment code for your input variable to the files you have identified previously. Then write your subroutine and add a call to it at a suitable place. Last but not least, recompile abinis.
Since your contribution is integrated into the 4.6 version of ABINIT, all associated tests should go to the ~ABINIT/Test_v4/ directory. Wander a little bit around the Test_* directories, and have a look at their content. Focus particularly on the README and RunTests.cnf files there. Each test is identified by an index, attributed after consulting the ABINIT Project leader. Suppose it was decided that your contribution will be checked by test #200.
Q10. What do you need to do in order to have a new test added ?
Implement your test and execute the RunTests script with suitable parameters.
There are two ways of creating a patch, depending on whether you are using GNU Arch or not. If yes, you just have to register your new files, write a change log and commit your changes. This procedure is highly recommended, as it is very fast and as the project leader will be provided with a lot of flexibility and information to handle your contribution. If no, you have to create a patch along with a full description of your changes and send it by email or ftp.
To get some comfort, the project leader needs a patch both in universal format and where new files are considered empty in the old version.
Q11. Which options will you give to the diff command to produce the patch ?
Q12. How will you proceed exactly to create it ?