MCTDH: Developer guidelines

• The GIT Repository
• Altering the Program
• Debugging the Program

Back to Main Menu

Guidelines for Developers

Using the Git Repository

Check out the Gitlab repository to a directory quantics.

• git clone https://gitlab.com/quantics/quantics.git quantics

Work on the code must be done on a branch rather than the master copy. To see existing branches

• git branch -a

To working on an existing branch, move to that branch

• git checkout branch

If you wish to create a new branch called newbranch

• git branch newbranch
• git checkout newbranch

Now make code changes. To see what has been done,

• git status

shows the files that have been changed and are ready to add (staged to commit) to the repository. To commit the changes to your local repository,

• git add .
• git commit -a

or to add a single file called routine

• git add routine
• git commit

You will be asked to give a log message on committing changes. Please make this descriptive enough for others to know what has been done. To save your branch on the gitlab site, you need to push it.

• git push branch

if it is a new branch you first have to set a tracking link to the remote repository

• git push --set-upstream origin branch

Periodically, you should pull down the lastest repositiry and merge changes that have been made on the master branch into your branch. This prevents your code becoming out-of-date and makes it easier to bring it back into the master development.

• git pull
• git merge master

Git will report clashes that have occured, i.e. where two people have changed the same piece of code. This will need to be examined and sorted using an editor, after which the merged code can be committed to the repository. Once the development is finished and the code tested, merge with the latest master, push it back to gitlab and set up a merge request. This is done by following the menu Repository -> Branches and clicking on merge request next to the branch name.

Altering the Program

When developing the package further, the following rules should be obeyed.

1. Make additions so as to change the existing code as little as possible. When changing the program, always keep in mind that others also need to use and understand your new code. This means for instance:
   • Split larger problems into smaller ones and write an individual subroutine for each.
   • Try to be as general as possible.
   • Use self-explanatory variable and routine names.
   • Comments in the code are welcome. The Doxygen mark-up language can be used to allow comments to be extracted and documented.
2. Test the new code with the Automatic Program Test. Add any new test cases that are necessary for your new options. If changes had to be made that set the Automatic Program Test out of order (e.g. a new output format), immediately update the test files. Check your code on different platforms.
3. If everything works correctly, update your code and documentation with the latest repository version, as it might have changed during your work. Finally, commit your code and documentation to the repository, including a version log which describes the main changes.

Debugging the Program

In order to debug the code set the option -d of the compile shell script when compiling the program. By this, the compiler produces additional symbol table information for full symbolic debugging instead of optimising the code. Note that a "d" is added to the name of the executable, e.g. quanticsd. A debugger (e.g dbx or gdb) can then aid you in detecting a bug. It may also be helpful to compile and run your code on another platform, since different compilers often perform different checks of the code and produce differently rigorous compiler and run-time warning messages.

Known bugs that have not been fixed yet are compiled in the To Be Done documentation.

Version and Release Numbers.

The Quantics project version number is stored in the module Versions.F90. This number has the form V.r, where V is the version number and r the release number. Thus 12.01 denotes the first release of version 12. This number relates to the original Heidelberg MCTDH package and for the Quantics package the version given is V.r - 11 so that 12.01 equates to version 1 release 1.

If the project is changed in such a way that it should be differentiated from previous revisions, then the revision number should be incremented by 1. Such changes are the removal of bugs, minor changes in file formats, major re-writing of code etc. A more major change may then lead to a change in the release, or even version, number.

This information is written, e.g., to the log file and can be used to help narrow down problems if they arise after revisions.