ACES: Advanced Concepts in Electronic Structure

CODE DEVELOPMENT FOR ACES III AND SIAL


As ACES III has become more widely used in recent months, a need is seen to allow other developers to add to the system. In order for this to work smoothly, we need to agree upon a set of conventions for working in cooperation with each other.

CVS: concurrent version system


Source code will be maintained in a CVS repository at UF. Currently, this resides on crunch, and is accessible by setting the CVSROOT environment variable appropriately in a login script. Anyone desiring access to this repository must be approved by Erik Deumens (deumens@qtp.ufl.edu), and will be given privileges to make modifications to this repository. It is currently anticipated that perhaps 5 or 6 developers will be given access.

It is expecetd tha, developers will mostly be creating new SIAL programs, or will modify existing SIAL programs. Also, they may require adding new special instructions, optimizing contractions. etc.

Modifications to the SIP code is expected to be less frequent and often requires more careful orchestration.

Release management


When a new release is made, A CVS tag will be created. We need a naming convention for this tag so that developers may easily refer to it. We suggest a tag of the form Release_iii_jjj_kkk, where iii is the major release number, jjj is the minor release number, and kkk is a bugfix number. For example, our next release would be tagged Release_3_0_0. After several minor changes are made, we might make the next release Release_3.1.0. If a bug is found and corrected, we would use Release_3.1.1.

When a new release is anticipated, an email will be sent to all developers having access to the ACES III repository informing them of the release date. New code to be included in the release must be checked in at least one week before this date, so we can test it on different platforms.

When a developer wants to begin working on development of a new feature, to be included in some future release, he or she must create new branch. We will create the branch using the tag Branch_iii_jjj_kkk_dev, where iii,jjj,kkk are as before, and dev is the developer's login id. For example, if Victor Lotrich starts a new project from Release_3_1_0, we would create a branch called Branch_3_1_0_lotrich. In this way, the branches are tagged to the exact release tag as well as the individual developer. If the new development is done by a team, the user id of the team member who is responsible for managing the CVS will be used.

Development on a branch


Once the branch has been created, it must be checked out by the developer. The command will look like the following:
cvs co -d ACESIII_Branch_3_1_0_lotrich -r Branch_3_1.0_lotrich ACESIII

The -d is used to checkout the code into a branch-specific directory, the -r indicates the branch tag being used.

The developer of a branch is responsible for keeping up-to-date with the developments on the main trunk of ACES III. This is done using the command

cvs update

regularly, but at least before the final round of tests. If new code on teh main trunk are in conflict with the code developed on the bracnh, then the cdeveloper must resove these conflicts. Obviously clear and frequent communicvation with other developers will make this easier.

When a developer has completed his or her work on the branch, and has included merging new developments and new releases from the main trunk, and has completed throrough testing, the final code can be checked in on the branch and tagged.

Once this is done Mark Ponton (ponton@qtp.ufl.edu) should be notified. It will be his responsibility to merge the new branch development into the main trunk. Since the develope already ensured that there are no conflicts between the branch and the main trunk, this process should be simple and straightforward and therefore quick. If a conflict still exists, Mark will notify the developer, and it is his or her responsibility to correct the code, retest it, and check it in again on the branch. This cycle may be repeated until we have a successful merge. When the branch has finally been merged succesfully, we will create a new tag for the merged code, and possibly a new release. From then on the main trunk will contain the new feature that was developed on the branch.

The devlopemnt on a branch may be short, a few weeks, or be as long as several months and may span several releases. Development should not be too long, because then too much effort is needed to stay without conflict with the main trunk. Projects that appear to take too long, should be broken up and intermediate stages should be identified that can be completed and merged into the main trunk.

Automated testing


We will have a new directory added to the ACESIII code tree, called tests. Within the tests directory will be various subdirectories, one for each job flow to be tested. When a developer checks in a new SIAL program, he or she must also add a test job (i. e. ZMAT) for that program, as well as relevant output files, Hessians, etc.

For example, if we add a new program called hess_rhf_mp2_seg.sial, we would also add a sub-directory within ACESIII/tests, called hess_rhf_mp2_seg. Within this sub-directory, we would have a ZMAT containing the test job, an output file, say hess_rhf_mp2_seg.out, and a Hessian file output by the program (FCMINIT). Also, if any changes are required in the file sial_config to run this code, they would have been checked in when the branch code was checked in.

A program is being developed that will scan the directories within ACESIII/tests, and generate scripts to run these tests automatically. The tests must be completed successfully before a developer's branch will be merged into the main trunk of the release.