INSTALLING BALLROOM =================== Please refer to the file README for other general information. 1. Installing on a Unix platform -------------------------------- There are two or three ballroom executable files to install: ballroom_gl.x This is the GL version, only for those systems which support GL (SGI, and IBM RS6000 if GL has been installed). Typically this needs to be run at the console, or on a remote SGI connected to a SGI. ballroom_vogl.x This is the X-Windows version, using the VOGL GL emulation library from the University of Melbourne. This can be run from any X capable display. ballroom_nog.x This is the "no-graphics" version, only capable of producing PostScript file. This can be run from any dumb terminal. as well as the shell script 'ballroom' and the help file 'ballroom.help'. If you already have the executables, go to section 1.2. 1.1 Compiling on a Unix platform Go in the main ballroom directory and type 'make' to obtain a list of supported systems. If your system is among the supported ones, type make This should construct all the executables needed for your system (two or three, depending whether ballroom_gl.x is produced or not). If your system is not among the supported ones, edit the Makefile and try to make it working for your system following the guidelines there. If you succeed, please send me the expanded Makefile. The currently supported Unix platforms are aix for a IBM RS/6000 running AIX (*) aixgl for a IBM RS/6000 running AIX, and GL installed (*) axp for a DEC AXP (Alpha) running OSF/1 ultrix for a DEC MIPS running Ultrix (untested) hpux for a HP 9000 Series 700 running HP-UX 9 sgi for a Silicon Graphics running Irix 4 or 5 sun for a Sun running Solaris 2 (untested) (*) On AIX systems, check where the X11 include directory is located. If it is not in /usr/include or another location in the compiler's include search path, please specify its location in this way (example, assuming you have /usr/local/include/X11): make "INCX11=-I/usr/local/include" aix The above can apply to all systems, really. The defaults for the maximum size of systems is nm=100000 particles in file and na=200000 particles in image (the latter is larger since image boxes can be stacked using periodic boundary conditions). These limits can be altered by typing, for example, make "CPPSIZE=-Dnm=500000 -Dna=500000" After the executables have been produced successfully, you may wish to type make clean to remove all the intermediate material, saving disk space. 1.2 Installing the files on a Unix platform 1.2.1 System-wide installation. You need of course to have system privileges. Move all the executable files (those ending with .x) and copy the shell script 'ballroom' into a directory belonging to the system-wide path. This is typically /usr/local/bin . Then copy 'ballroom.help' into that same directory or, at your choice, in any one of the ../lib , ../doc or ../man directories relative to it. That is, if the executables went into /usr/local/bin, then /usr/local/bin, /usr/local/lib, /usr/local/doc and /usr/local/man are all valid locations for 'ballroom.help'. 1.2.2 Personal installation. You must have one of your directories in your path. This is typically $HOME/bin , but you can choose what you want. Move all the executable files (those ending with .x) there, and also copy the shell script 'ballroom'. Moreover, copy there 'ballroom.help' or, if you prefer, put it into a directory ../lib, ../doc or ../man relative to the binaries directory as described above for the system-wide installation. 1.2.3 Special needs. If the above choices do not satisfy you, edit the 'ballroom' script to your taste. 1.3 Testing on a Unix platform Go into directory 'Demo' and type: demo You should see a demonstration running. Make sure your hardware is reasonably fast, and do not run it across slow network connections. 2. Installing on a VMS platform using GKS ----------------------------------------- You still need a Unix machine to produce the a source file 'ballroom.for' (including everything) which is then transferred to the target for compilation and linking. These two latter steps are left to you. To produce the source file on a Unix machine, type make vms Use CPPSIZE to increase the maximum size of systems that can be processed. For instance, make "CPPSIZE=-Dnm=500000 -Dna=500000" vms The C preprocessor is used to produce the VMS/GKS Fortran code by calling '/lib/cpp -P', which is the standard location and option. On some systems, however, the C preprocessor is not able to process correctly Fortran code (for example, it may drop '//' and following characters on a line). These system often provides a modified preprocessor to process Fortran files. For instance, on DEC OSF/1 systems it is called '/lib/fpp'. In this case you would use make "CPP=/lib/fpp -P" vms Transfer the files 'ballroom.for', 'ballroom.help' and 'ballroom.com' to the VMS system. Compile ballroom.for, and then link it with GKS (which must be installed on your system!). Move the .EXE file and the .HELP file in some suitable place, and then edit the .COM file to adapt it to your environment (setting device and directory names, etc). VMS/GKS may become unsupported in the future, since I have the impression that nobody uses it (if you use it let me know). Last time I ran there was several releases and years ago, so there might be problems lying around. 3. Installing on a IBM mainframe running VM or MVS and with GDDM installed -------------------------------------------------------------------------- You still need a Unix machine to produce the a source file 'ballroom.fortran' (including everything) which is then transferred to the target for compilation. This latter step is left to you. To produce the source file on a Unix machine, type make gddm Use CPPSIZE to increase the maximum size of systems that can be processed. For instance, make "CPPSIZE=-Dnm=500000 -Dna=500000" gddm The C preprocessor is used to produce the GDDM Fortran code by calling '/lib/cpp -P', which is the standard location and option. On some systems, however, the C preprocessor is not able to process correctly Fortran code (for example, it may drop '//' and following characters on a line). These system often provides a modified preprocessor to process Fortran files. For instance, on DEC OSF/1 systems it is called '/lib/fpp'. In this case you would use make "CPP=/lib/fpp -P" gddm Transfer the files 'ballroom.fortran', 'ballroom.help' and 'ballroom.exec' to the IBM mainframe. The latter is a REXX script which may or may not be useful on MVS. The following refers to a VM installation, for MVS you are really on your own as I have no clue. Compile BALLROOM FORTRAN using VS Fortran, producing BALLROOM TEXT. Make sure that the GDDM libraries are accessible at run time. If they are not, you may have to add a suitable GLOBAL TXTLIB command to your PROFILE EXEC. Try ballroom fn ft fm where fn ft fm is your data file. You may wish to edit BALLROOM EXEC to adapt it to your environment. IBM/GDDM may become unsupported in the future, since I have the impression that nobody uses it (if you use it let me know). Last time I ran there was several releases and years ago, so there might be problems lying around. Have fun! Comments to furio@sissa.it