Compilation, Installation and Execution

GENESIS 1.3 is distributed as executables for the Linux and Windows platform, as well as the source code and can be obtained from the official website

http://pbpl.physics.ucla.edu/genesis

GENESIS 1.3 is originally written in FORTRAN but the limit capability of FORTRAN to handle various input and output formats and a restricted string processing, resulted in a C++ version of the code. The simulated physics of both the C++ and FORTRAN version is the same and the only difference is in the extended set of file formats, supported by C++. The support of the Fortran stops with the release of the current version.

The compilation section is only important for those who are building GENESIS 1.3 from the source code. However the distributed executable might depend on addition libraries not included in the distribution. The section on the installion lists all required libraries and enviroment variables for running GENESIS 1.3

Compilation of the FORTRAN Source Code

After unpacking the '.tar'-archive the directory genesis contains the subdirectory base and extension. The base directory has all the source code, which is needed to run GENESIS 1.3, supporting only the original fileformat for input and output. Additional source files are located n the extension directory. For FORTRAN only two two extensions are supported: the SDDS file format and the parallelized version, using MPI. By default all extensions are disabled.

The source code has three different types of source files, indicated by their extension. Files with the extension '.f' contain all functions, subroutine and local variables, while variables used in more than one subroutine are grouped into common blocks in the files with the extension '.cmn'. The last type of files is the single file 'genesis.def' which defines constants and function prototypes.

The memory requirement of GENESIS 1.3 can be demanding if time-dependen simulation are performed or external distribution are imported and kept in memory. The file 'timerec.cmn' holds the information of the time records of the slippage field. NTMAX is the total record length, if the slippage filed is stored in memory. If simulation encounters the case that this size is too small (GENESIS 1.3 will give an error message) NTMAX has to be increased. Another possible way is to export the slippage field to a file. It is done by setting and NTMAX to unity. The file will be deleted at the end of the run. The default setting has a time-record, which demands 160 MByte of free memory - equivalent to 700 records of a grid with 121 times 121 grid points.

The default settings of GENESIS 1.3 is that the external distribution is read from a file for every slice. Due to the processing of the input file it can be time-consuming. To keep the distribution in memory after the first processing two parameters in 'genesis.def' have to be change. KEEPDIST has to be set to unity while NDMAX defines the maximum number of particles GENESIS 1.3 can hold in memory. Note that 100000 particles correspond to an additional memory demand of 5 MByte.

The FORTRAN follows in general the F77 standard although it is not fully ANSI-F77 compliant. This requires to set specific flags while invoking the compiler. Because compiler option and flags are compiler specific the following list of recommended option just gives a general description. Please refer to the manual of your compiler. The distribution contains a 'Makefile', which works with the Absoft FORTRAN compiler under linux. If might be used as a template for setting up the compiler and linking instruction.

• Optimization should be turned on. In addition if the linker supports a library of optimized mathematical function it should be used
• The compiler should warn or preferable generate an error, if variables are not defined explicitly.
• In general it is a good idea that the compiler issues all warning, but due to the function prototyping in 'genesis.def' the warning of unused variable should be disabled.
• GENESIS 1.3 relies on intrinsic double-precision complex numbers for assignment such as A=DCMPLX(1.d0,0.d0). Most FORTRAN compilers support this by a special VAX or complex option. As an alternative method the DCMPLX(...,...) statements must be replaced by CMPLX(...,... kind=8) statements by hand.
• It is recommended to generate a symbolic table (debugger option)
• Some compilers do not automatically treat variables in DATA blocks as static, but GENESIS relies on it. Either enable this option or, as an alternative, make all local variables static (the size of the executable is increased only by a small amount).
• GENESIS is not written consistently with the same case of all variables through out the source code. A compiler option should fold all variable and function names to lower or upper case letters if the compiler is case-sensitive.

The SDDS extension of GENESIS 1.3 is in the directory extension/SDDS. Compilation requires that the SDDS libraries are installed on the computer. In addition the FORTRAN wrapper of SDDS must be linked to the executable to make GENESIS 1.3 work. Unfortunately FORTRAN compilers do not support compiler instructions as C++ compiler do. As a consequnce the base source code must be edited to enable calls to the SDDS part of the program. Which files and where to edit are described in the README.SDDS file in the root directory of the genesis distribution.

Compilation of the MPI Version of Genesis

• Copy the file mpi.f.multi to mpi.f
• Remove the file mpif.h

Compilation of the C++ Source Code

Installation

The FORTRAN version of GENESIS is a single executable and can be located anywhere. Under Linux it is preferable in the directory '/usr/local/bin'.

Both versions can rely on additional libraries, which have to be installed prior to running GENESIS 1.3. The following lists all possible extensions and links, where further information can be obtained.

SDDS

The Self-Describing Data Set (SDDS) is a file format, where a header defines the properties of the following data section. The SDDS toolkit allows processing and displaying content of SDDS files. The offical link is

http://www.aps.anl.gov/asd/oag/oagPackages.shtml

XML

The eXtensible Markup Language (XML) is a popular file format for platform independent data, mainly in ASCII. XML files can be checked with any XML reader (e.g. Internet Explorer) whether the file does not violates the basic syntax of XML. In addition files can be validated, so that the data has to fulfill user-defined contraints. The standard for XML and is associated formats can be found at

http://www.w3c.org

GENESIS 1.3 is build with the Xerces XML libraries of the Apache distribution. The libraries can be downloaded from the Xerces website

http://xml.apache.org

HDF5

The Hirachial Data Format (HDF5) is a standard for platform independent binary data. It is benefical to GENESIS 1.3 because it also allows parallel computation and data compression. The offical website is

http://hdf.ncsa.uiuc.edu/HDF5/

MPI

The Message-Passing Interface is a standard for portable code for parralel computer architecture.

http://www-unix.mcs.anl.gov/mpi/

Running GENESIS 1.3

GENESIS 1.3 requires at least one argument, which is the name of the main input file. In the C++ version it is a command line argument, while the FORTRAN version promt for the filename. If additional information is needed the program will propt for the missing information. The progress as well as warning and error messages are directed to the standard output channel or redirect to a file if the ILOG parameter is set.

The C++ versions allows addition comand line arguments for more flexability

On UNIX and LINUX platforms GENESIS 1.3 can be easily executed in the background by redirecting the standard input, output and error to files such as

where GENINPUT contains line by line all file name, which are normally be prompted for by GENESIS. Any output and error message will be written to the file GENOUTPUT. If ILOG is set a log-file is created and GENOUTPUT remains empty.