Starting a new project with SZIN -- a rough guide -- by Balint Joo. Nov. 14, 2001 Adding to the szin library: =========================== a) Go to the szin/lib directory b) Make a new directory for your project specific stuff eg szin/lib/bjproj c) In this directory you can make several subdirectories if you like, such as szin/lib/bjproj/actions szin/lib/bjproj/misc d) Add all of these directories to the VPATH variable in the Makefile.cfg file in szin/lib (I prefer just scrolling to the end, and appending to the VPATH for now and adding the lines -- for the purposes of this example: VPATH += $(TOPDIR)/lib/bjproj VPATH += $(TOPDIR)/lib/bjproj/actions VPATH += $(TOPDIR)/lib/bjproj/misc ) e) populate your project subdirectories with .m files ones that are fermion specific should have their names end with _w.m, _s.m, or _g.m for Wilson, Staggered or Pure gauge specificity respectively. Fermion independent routines can just end in .m. For the purpose of this example consider a wilson specific file bjwilson_w.m in bjproj/misc and hello.m in bjproj/actions. Each of these files contain a single routine. For example: bjproj/actions/hello.m: include(types.mh) SUBROUTINE(hello) { START_CODE; FPRINTF(stdout, "Hello\n"); END_CODE; } and bjproj/misc/bjwilson_w.m include(types.mh) SUBROUTINE(BjWils, u) LATTICE_COMPLEX_COLOUR_COLOUR_CB_DIRECTION(u); { START_CODE; FPRINTF(stdout, "Totally ignoring input u field\n"); END_CODE; } Now to get these to be compiled into the relevant libraries, edi szin/lib/Makefile and add them to the SUPPORT_FILES variable, before the architecture dependent file list definitions (start at scalar_FILES := ...) in my case I added the line: SUPPORT_FILES += hello.m bjwilson_w.m (Note that I just added them as if they were in the szin/lib directory -- the same place as the makefile. The VPATH takes care of the fact that they are not) f) Finally, last but not least: You have to add prototypes for your subroutines to the prototypes.h file in szin/macros/prototypes.h For 'hello' it is easy, just add the line PROTOTYPE(`hello') to the end of the file. (NOTE THE DIFFERENT QUOTES at the start and end of the string hello -- the quoting is used by M4.) For a subroutine with arguments, we must describe the argument list in the prototype. This prototype business is a silly artifact of C, and its lack of support for passing by reference instead of value or pointer. There are three kinds of prototype: DESC - descriptor: anything that is an object and required an ALLOCATE. E.g., lattice objects, integer arrays, etc. REF - reference: simple primitives (INTEGER(a), REAL(b), etc.) passing by reference as in C++ parlance. Etc., if the variable is updated then the variable is returned modified. VAL - value: only the value is passed and any mods within the routine are ignored (as in C). Those of type DESC -- which are really descriptions of a data, say with a macro. This includes types like LATTICE_COMPLEX_COLOUR_SPIN_COLOUR_SPIN_CB but also array types of otherwise primitive types like INTEGER. Descriptors are used by anything that ALLOCATE's memory and is just a way of saying something is passed by reference. A REF says a simple type (no memory allocation) like INTEGER are passed by reference instead of by value, hence they can be changed in the subroutine. The other type of argument is that passed by value. In a prototype this would be denoted with the label VAL. There is no support for passing by VAL a huge lattice object (described by a descriptor). This would involve a huge memory copy. So our second function would be declared in the prototypes.h file as: PROTOTYPE(`BjWils',`DESC') Let us now recap the important steps in adding new routines to the libraries: i) Add the path to the files to the VPATH variable in szin/lib/Makefile.cfg ii) Add the files to the SUPPORT_FILES variable in szin/lib/Makefile (presuming they are not type, machine or architecture dependant -- they need to be added to other Makefile variables -- see reference). iii) Add prototypes for the functions to the szin/macros/prototypes.h file Now if you go back to szin/lib and type gmake MACHINE_TYPE= FERMION_TYPE= all (you can also do gmake MACHINE_TYPE= FERMION_TYPE= clean followed by gmake MACHINE_TYPE= FERMION_TYPE= all to do a rebuild. There is also even a 'veryclean' target. You should find your files being built and added to the _szin.a or _szin_.a libraries. You can now refer to these routines in your main_programes. Adding new main programs ======================== Now that we can extend the library we should think of a way of adding new main programs. This is most easily done. We go to the szin/mainprogs directory. By default there are two directories here: main/ and tests/ You can place your main program in either main or in tests. The programs in tests tend to begin with t_ (signifying that they are tests) The programs in main tend to not have any special prefix. We can put our main programs in either of these directories or if we prefer not to pollute our szin distribution needlessly, we can always make our own directory in mainprogs/ If we make our own directory we should copy the makefile from mainprogs/main to this new directory. The makefile will not need to be altered as it simply includes szin/Makefile. and szin/mainprogs/Makefile. We must however add the name of our new main program to the MAIN_FILES environment variable in szin/mainprogs/Makefile. Suppose I wanted to put a test main program in szin/mainprogs/bjlearn I would create the directory, and put a test code there, let's call it szin/mainprogs/bjlearn/hello.m: include(types.mh) PROGRAM(hello_world) { START_CODE; PRINTF("Hello World\n"); END_CODE; } I must also then copy szin/mainprogs/main/Makefile to szin/mainprogs/bjlearn This is just a template: Its contents are: # $Id: Makefile,v 1.2 2001/06/15 19:03:36 edwards Exp $ # # Makefile for creating the library # # Usage: # gmake MACHINE_TYPE= FERMION_TYPE= # _purgaug_ include ../../Makefile.$(MACHINE_TYPE) include ../Makefile And finally I have to add the line with the name of my program to the szin/mainprogs/Makfile (the second included in the template above). Because this Makefile is included directly into the one in bjlearn/ -- we don't need to specify the bjlearn directory. We can pretend the file is local... So the line I add is MAIN_FILES := $(MAIN_FILES) hello.m (or possibly I could do it with MAIN_FILES += hello.m as with the VPATH earlier -- note its *NOT* MAIN_FILES += bjlarn/hello.m ) At this point I can go into szin/mainprogs/bjlearn and gmake MACHINE_TYPE=linux FERMION_TYPE=g linux_hello_g to build my new main program. Miscellaneous Notes: -------------------- Environment Variables --------------------- If you get fed up with typing MACHINE_TYPE= FERMION_TYPE= you can always define these as environment variables. For example, suppose I know for a fact that on the edinburgh linux machines I will only work with wilson fermions for the next few months. I can then add export MACHINE_TYPE=linux export FERMION_TYPE=w to my UNIX startup files for bash (or I can just type them into a bash shell.) I then can do all the building with just: gmake all; gmake clean; and so forth File Variables in the szin/lib/Makefile: ---------------------------------------- There is a whole bunch of Makefile variables used to collect lists of files in szin/lib/Makefile These are SPECIAL_FILES -- to do with byte ordering, namelist reading and parsing. A general user shouldn't mess with these. These are strict C files that don't go through M4. They are mostly low level support routines. TYPES_MACROS -- these are to do with defining macros for types. If you define new types you should add them here. SUPPORT_FILES -- Almost all physics related files come here. This is constructed in three parts although strictly it doesn't need to be. First the fermion independent types are added here. Then in the next two sections, the Wilson and staggered specific filenames (*_w.m and *_s.m) are added on here. I personally created a fourth section of SUPPORT_FILES where I have my own files. But if I were extending SZIN for everyone, I could add the files just to the previous three sections as relevant. Then there are ARCHITECTURE specific files, there are two macros for each architecture: _FILES and _TYPES_MACROS where is one of scalar, vector, dsp, smp, tsmp (threaded SMP) parsmp (parallel smp) , partsmp (parallel threaded smp), and cm. _FILES is built out of $(SUPPORT_FILES) and various other architecture files eg to read configurations and so on. _TYPES_MACROS is built out of $(TYPES_MACROS) with architecture dependent extra include files Finally the machine dependent files are built up: There are three Makefiles for each machine type: _FILES -- Constructed from the _FILES for the relevant architecture for the machine with machine specific extra files _SPECIAL_FILES -- Made up from the SPECIAL_FILES and some machien specific extras and _TYPES_MACROS -- constructed from _TYPES_MACROS with more machine specifics. (mach can be bsun, vsun, dspsun, mitsmp, gmitsmp, ultra, jlabsmp, qnxsmp, kxtsmp, wnxtsmp, Jlabsmp, fibm, ibm, cibm, qibm, eibm, Sibmpsmp, Ibmsmp, hp, osf, posf, ro, axtsmp, inxtsmp, linux, znxsmp, ynxsmp) Finally the _FILES and _SPECIAL_FILES get split into two groups: GENERIC_FILES, and FERMION_FILES. It is from these in the end that the _szin.a and the fermion specific _szin_.a libraries are built. The files that are fermion specific are filtered based on their names (extentions _w.m etc) using a PERL script. ------------------------------------------------------------------- Dr Balint Joo Post Doctoral Research Fellow Department of Physics Department of Physics and Astronomy Columbia University University of Edinburgh 538 W120th St, New York Mayfield Road, Edinburgh EH9 3JZ NY 10027, USA Scotland UK Tel: +1-(212)-854-3946 +44 (0)131-650 6481 Fax: +1-(212)-932-3169 email: bj@phys.columbia.edu bj@ph.ed.ac.uk WWW : http://www.pa.uky.edu/~bj -------------------------------------------------------------------