EUROPEAN ORGANIZATION FOR NUCLEAR RESEARCH

MAD-X Module Writer's Guide

Introduction

All I/O (except for debug or error messages) is performed by CONTROL. The modules receive their input data via calls (Fortran), or take them from structures (C); the module outputs are stored in tables or variables via calls (Fortran) or directly in structures (C).

For each new module to be added, FS will provide a complete development environment consisting of:

• Makefile
• A separate mad-X version with a call to the new module
• Access to the input commands steering the module

In the following, the different cases are handled separately.

C part

The C language is already pretty safe by nature. However, one can still produce bad code! Therefore, use the compile flags "-Wall -pedantic" (can be done via "make -f Makefile_develop" either for madx or madxp) and please fix all warnings that the compiler detects. The last checking campaign revealed hundreds of warnings! To allow for better code maintainability we have recently to introduce a general indentation by 2 characters per level level with all curly brackets on an extra line. The curly brackets are aligned with the operators. FS has semi-automatic tools to do this indentation.
• Memory allocation: Never use the plain malloc or calloc C functions!. Instead use the wrappers mymalloc and mycalloc . The syntax of how to call these functions can be found in madxu.c.

  Fortran

  Fortran normally mixes well with C (at least under Unix) provided a few basic rules are respected. They concern mainly the transfer of arguments to and from C.

  Normally the module will already exist in MAD-8.In this case, follow these steps:

  • Extract all routines belonging to the module from MAD-8 (possibly with the help of FS)
  • Find out which routines if any have already been transmitted to mad-X
  • Remove all common statements
  • Transfer variables that exist only inside the module either via calls (as arguments), or via a common block with a name reminding of the module. This common block has to be identical in all routines where it appears.
  • Make a list of all variables that the module needs from outside
  • Give the list to FS so he can provide them
  • Make a list of the output data provided by the module (reminder: the module should only print error messages, and transfer all result data to tables or variables); Discuss the details of the output storage with FS
  • Attach the modified module to mad-X and test it
  • Provide module documentation (based on MAD-8 documentation)
  • Provide test jobs that test the module abilities as far as reasonable
  If it is a new module, the above rules are modified accordingly. However, new modules should be written in C whenever possible.

  Strict Checking

  Before committing to CVS (see next section) it is mandatory to perform a strict check of all your examples. To this end create an executable with Makefile_develop:
  • For madx perform: "make -f Makefile_develop"
  • For madxp perform: "make -f Makefile_develop madxp"
  Check compiler output for warnings and get rid of them. Then run your examples with these executables until MAD-X finishes the job successfully. There will be a crash if variables have not been initialized before usage and in case of out-of-bound usage of arrays.

  CVS

  MAD-X is kept under CVS (Concurrent Version System). The CVS version number should be >=1.11.2.

  Here are the CVS basics for MAD-X:

  • For CERN users: First step is to include the following lines into your .tcshrc file in your HOME directory (users of other SHELLs adapt accordingly):

    setenv CVSROOT :kserver:isscvs.cern.ch:/local/reps/madx

    setenv CVSEDITOR emacs

    (second command for emacs users) use "source .tcshrc" to activate the MAD-X CVS repository.
  • Go to your directory of choice, probably the one where you develop your module.
  • type cvs checkout madX this will create a new directory named madX with the newest files from the CVS repository. Change directory to madX.
  • Make your changes.
  • VERY IMPORTANT BEFORE PROCEEDING!!!
    • Before you commit your changes check with cvs log your_file if anybody has worked on that file in the meantime.
    • Also, before a commit please check with cvs -n update -A your_file if this is truly what you want to commit or if there are conflicts. Explanation: -n is a global CVS option that give information without actually changing any files, the auxiliary -A flag removes sticky tags about which you do not really want to know about!
    • With make produce an executable madx and check that all your examples run properly!
  • type cvs commit your_file for each file you have changed.
  • In the rare case that there is a conflict with another module writer that has edited the same file, you have to contact him to sort out possible problems. It is one of the advantage of the CVS system to detect these conflicts.
  • Optional: Go back to directory above and type cvs release madX this insures that you really have committed all changed files before getting rid of the madX directory.
  • Optional: If you want to know about the history of a file type cvs log -S your_file (you have to be in the madX directory). Explanation: The -S flags avoids excessive printout.
  If you want to learn more about CVS please consult the manual which is accessible at: /afs/cern.ch/eng/sl/MAD-X/dev/cvs_manual.ps

  Comments from readers are most welcome. They may be sent to the following Internet addresses:

  
     Frank.Schmidt@cern.ch
  

  ---

  ---