MCTDH: Developer guidelines

• Altering the Program
• Debugging the Program

Back to Main Menu

Guidelines for Developers

Altering the Program

To develop the program further, the following rules should be obeyed.

1. Check out the latest code version from the PRCS archive to your own directory, or merge your personal version with the latest one. Update the PRCS keywords by using prcs rekey for each project.
2. 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 wellcome.
3. Describe your changes in the corresponding documentation files that have been checked out to your local directory. It is good (and efficient!) practice to document changes "on the fly", i.e. parallel to the programmings. Major changes should be reported also in the Changes of the Code documentation.
4. 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.
5. If everything works correctly, again merge your code and documentation with the latest version, as it might have changed during your work. Then check in code and documentation to the PRCS archive. Enter an expressive version log.

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 MCTDH program project version number is listed in the include file versions.inc. This number has the form V.rxxx, where V is the version number, r the release, and xxx the revision number. Thus 8.1001 denotes the first revision of version 8 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.