GSIM for Developers At work.

Introduction:

Hello gsim developers. Welcome to the gsim project. The following sort of sums what gsim looks like for the novice:

A Dilbert Cartoon.

So it is pretty clear we can use a lot of your help, and I would like to encourage everybody to document your code.

In all fairness, the gsim code is comming along, and the documentation is improving (slowly but steadily.) More developers are joining, but there are still projects available. Check the main gsim page and the project descriptions and don't hesitate to email me for suggestions.

Getting Started:

If you are completely new, read and follow the instructions for gsim users. This will get you going at the basic level and show you how to set up the CLAS environment and check out the relevant code.

Once you have a copy of the code you are ready to start making your modifications. There are two things you may wish to do:

  1. Modify the guser routines to add your own personal histograms etc.
  2. Modify the main code and distribute the changes to all gsim users.

Modifying the GUSER routines.

Most users will probably only want to modify the guser*.F routines to add their own histograms, ntuples and other diagnostics.To do this, check out a copy of the guser*.F routines from the gsim subdirectory, and copy them to the gsim_int (or gsim_bat) directory, then edit them and remake the gsim_int executable. Starting in your own copy of the "packages" subdirectory execute something like the following commands. (If you don't have a packages directory yet, create one with: cd ~ ; mkdir packages)

cvs checkout gsim_int
ls $CLAS_PACK/gsim/guser_* | sed -e 's$/$ $g' | \
gawk '{printf "%s/%s\n",$7,$8}' | xargs cvs checkout
mv gsim/guser*.F gsim_int
cd gsim_int
foreach i (guser*.F)
sed -e 's/Default/Personal/' < i > tmp.tmp && mv tmp.tmp i
end
make exe

The first command checks out gsim_int the next one checks out all the guser*.F routines, (if you don't need all of them you can substitute the following command instead: cvs checkout gsim/gsuser_book.F etc.)
After you change directory to gsim_int, the "foreach" loop edits each file using "sed" to change "Default" to "Personal". This can also be done in your favorite editor. I do recommend that you change the write statement in each of the guser*.F routines, so that you can verify that your own copy of these routines gets called.
The last command builds a copy of gsim_int with your own routines linked in.

I very highly recommend that you DO NOT BUILD KINEMATICS GENERATORS inside your user routines. The general and far superior method is to write a standalone code that generates a BOS file. See "event generators" for more.

Modifying the main libgsim.a routines.

Occasionally you may want to modify some routines for "what if" scenarios and modifications that you don't intend to distribute to all users. In that case the method mentioned above should work just fine.

If you want to modify one of the main subroutines in the gsim library (subroutines other than guser*.F) for distribution to all gsim users, please check first with the "projects list" to make sure somebody else is not already working on the same problem. If there is a name assigned to the project you are interested in, contact that person to get a status report and see if you can join their effort. If nobody is assigned to the project, or if the project does not exist yet, send me an email and I'll add it to the list.

Once you are on the project you probably want to start with checking out all the gsim code:

cvs checkout gsim gsim_int gsim_bat

and become somewhat familiar with the way the routines work. Next you can go ahead and make your changes. Please comment all modifications and additions to the code ! It can get very difficult to remember later what a particular piece of code does.

If you have been working on a set of routines for some time (more than a couple of days), you may wish to make occasional updates of all the sources, to verify that nobody else has made changes that affect your work. The cvs command "cvs -n -q update" will give you a brief report of all the files that have changed in the repository, and all files you changed locally, without making changes to your local files. The command "cvs update" will make the modifications to the local files, including files you have also changed. Now it is important to have a little understanding of how this works. This is explained in the cvs manual, but I'll repeat some here. For each file that cvs changes it will write a line to the screen informing you of what it did. Here's a list of the important codes:
 

U <file> The file was brought up to date. You had not made modifications. No action needed.
A <file> The file was added to your directory.
R <file>  The file was removed from your directory, it is no longer needed.
M <file> You had modified this file. If the file in the repository was also modified, cvs was able to merge the two modifications. No action is needed ( but you may wish to verify cvs)
C <file> The modifications you made are in conflict with modifications made to the repository. You must edit the file in your directory to make sure that the conflict can be resolved. If this happened, the file will have some directives in it as to where the conflict occurred. Look for <<<<< and >>>>>.
? <file> This file only exists in your directory and not in the repository.
It is obviously important to resolve all conflicts as soon as possible.

When you are done with your modifications, first verify that they work. You probably want to run several different tests. Second, verify that the code compiles and runs on all TJNAF platforms. There have been several occasions in which an innocent looking modification did not compile on one of the platforms. The platforms currently (after 2000) used are Linux, now our main platform on the Farms, and SunOS (note that  HP and AIX are dropped). Third, run "cvs update" to make sure there are no conflicts. When there are conflicts, cvs should not allow you to check the code in, but it is good to update first anyway.

Finally you are ready to commit your changes. You do this with the cvs commit command. Please make sure that you only commit the files you modified from the gsim directory and not any additional files (such as last.kumac or *.o) also, never commit the guser*.F files.

At this point you're done. Please send me an email, and I will update the status on the project.