[ previous ] [ contents ] [ next ]

Download and installation

System requirements

As ar-HRT-1 is written using the arfg meta language, it is necessary that you are able to run arfg on your system. Furthermore, the program is most comfortably used if your system allows for symbolic links; otherwise, you will have to make do with copying files, which can be tedious if you plan to extend the program. Anything but support for long file names with any number of dots in the file name will require extensive work-arounds. There should be no difficulty in using ar-HRT-1 on any Unix-like system; otherwise, your mileage may vary.

Software requirements

As ar-HRT-1 is written in arfg, and the arfg program is needed for the construction of the Fortran 90 code to be compiled and run, any application of ar-HRT-1 is tied to a proper installation of arfg; the corresponding installation instructions are to be found at http://purl.oclc.org/NET/arfg/current/install.html.

Numerical constants are evaluated during code construction, which brings about notational convenience and allows for initialization code involving arbitrary mathematical functions. To this end, the budding computer algebra system yacas is called and must therefore be installed and on your load path; installation instructions are to be found on the yacas-site.

Obviously, you will also need some Fortran 90 compiler in order to be able to compile the source built by arfg; the only non-standard feature ar-HRT-1 relies on is support for IEEE arithmetic and the special values +Inf, -Inf, and NaN for signed overflow and numerically undefined values [34]. Note, however, that not every compiler that claims to be standards-compliant holds up to that promise; in particular, as of version 6.0 Intel's popular ifc is bug-ridden with respect to overloading and import of module routines, in addition to standards-violating default settings (at the very least, you must use command-line parameter -nbs). ar-HRT-1 has successfully been used with compilers by NAG and Lahey. Be sure to run the test programs included in basics.arfg and files.arfg with any unknown compiler.

It is convenient to use the Makefile provided; in this case, you will also need a working version of make. The GNU implementation of make is known to work well.

The most natural way of checking whether or not an additional application of arfg is needed is to consider a suitable hash (e. g., md5) of the file contents; indeed, for the Makefile to work, md5sum must be installed. GNU's package textutils has a working implementation.


Download and save any of the following files:

Installation of ar-HRT-1

To install, create and enter the sub-directory where ar-HRT-1 will reside; expand and extract the files from the archive you downloaded, preserving directory structure and file permissions.

In version 5.20030128a, you should end up with the following files and subdirectories:

-rw-r--r--    18k  COPYING
-rw-r--r--    303  README
drwxr-xr-x   1.0k  doc/
-rw-r--r--   7.6k  doc/about.html
-rw-r--r--    13k  doc/history.html
-rw-r--r--   7.3k  doc/index.html
-rw-r--r--    18k  doc/install.html
-rw-r--r--   4.5k  doc/mp_ansatz.html
-rw-r--r--   4.0k  doc/mp_basics.html
-rw-r--r--   3.4k  doc/mp_files.html
-rw-r--r--   3.0k  doc/mp_hrt.html
-rw-r--r--   3.2k  doc/mp_nodes.html
-rw-r--r--   3.9k  doc/mp_potential.html
-rw-r--r--   3.5k  doc/mp_reference.html
-rw-r--r--   2.8k  doc/mp_solver.html
-rw-r--r--   3.3k  doc/mps.html
-rw-r--r--   7.2k  doc/references.html
-rw-r--r--    29k  doc/usage.html
-rw-r--r--   8.0k  doc/utils.html
drwxr-xr-x   1.0k  iso.arfg/
drwxr-xr-x   1.0k  iso.arfg/.ansatz.arfg/
-rw-r--r--    59k  iso.arfg/.ansatz.arfg/20010313-ar
-rw-r--r--    90k  iso.arfg/.ansatz.arfg/20010420-ar
-rw-r--r--    59k  iso.arfg/.ansatz.arfg/20010504-ar
-rw-r--r--    89k  iso.arfg/.ansatz.arfg/20010720-ar
-rw-r--r--    58k  iso.arfg/.ansatz.arfg/20020824-ar
drwxr-xr-x   1.0k  iso.arfg/.f90/
drwxr-xr-x   1.0k  iso.arfg/.f90/.opt/
drwxr-xr-x   1.0k  iso.arfg/.f90/.trash/
drwxr-xr-x   1.0k  iso.arfg/.potential.arfg/
-rw-r--r--    18k  iso.arfg/.potential.arfg/20000817-ar.square-well
-rw-r--r--    29k  iso.arfg/.potential.arfg/20010312-ar.hard-core-yukawa
-rw-r--r--    28k  iso.arfg/.potential.arfg/20010426-ar.steps
-rw-r--r--   227k  iso.arfg/.potential.arfg/20020228-ar.hard-core-girifalco
-rw-r--r--    34k  iso.arfg/.potential.arfg/20020317-ar.hard-core-multi-yukawa
drwxr-xr-x   1.0k  iso.arfg/.reference.arfg/
-rw-r--r--    31k  iso.arfg/.reference.arfg/20000824-ar.HS-GH
-rw-r--r--    13k  iso.arfg/.reference.arfg/20010221-ar.HS-PY
drwxr-xr-x   1.0k  iso.arfg/.solver.arfg/
-rw-r--r--    73k  iso.arfg/.solver.arfg/20000712-ar
-rw-r--r--    78k  iso.arfg/.solver.arfg/20010302-ar
-rw-r--r--    22k  iso.arfg/hrt.arfg
-rw-r--r--    44k  iso.arfg/nodes.arfg
drwxr-xr-x   1.0k  share.arfg/
-rw-r--r--   1.3k  share.arfg/.arfg-post
-rw-r--r--    12k  share.arfg/.arfg-pre
-rwxr-xr-x   4.6k  share.arfg/.arfg-rewrite
-rw-r--r--    793  share.arfg/.boilerplate
-rw-r--r--    556  share.arfg/.m
drwxr-xr-x   1.0k  share.arfg/.m4/
-rw-r--r--   4.1k  share.arfg/.m4/auxvars.m4
-rw-r--r--   5.1k  share.arfg/.m4/cache.m4
-rw-r--r--   9.8k  share.arfg/.m4/capabilities.m4
-rw-r--r--   1.9k  share.arfg/.m4/checkrange.m4
-rw-r--r--   2.9k  share.arfg/.m4/lists.m4
-rw-r--r--   2.0k  share.arfg/.m4/math.m4
-rw-r--r--   1.1k  share.arfg/.m4/pointers.m4
-rw-r--r--   2.9k  share.arfg/.m4/save.m4
-rw-r--r--   2.9k  share.arfg/.m4/type.m4
-rw-r--r--   1.5k  share.arfg/Makefile
-rw-r--r--    27k  share.arfg/basics.arfg
-rw-r--r--    60k  share.arfg/files.arfg
drwxr-xr-x   1.0k  util.arfg/
drwxr-xr-x   1.0k  util.arfg/.f90/
drwxr-xr-x   1.0k  util.arfg/.f90/.opt/
-rw-r--r--    220  util.arfg/.hooks
-rwxr-xr-x    17k  util.arfg/ar-Phase
-rwxr-xr-x    713  util.arfg/hrt.phase-mma
-rw-r--r--    16k  util.arfg/iso2ascii.arfg

As can be seen from the above list, in order to avoid overwriting existing customization information the files .compile-time-parameters and .hooks are not part of the package, nor are the options files. The source code building process, however, expects to find these files, so you should make sure they exist:

touch iso.arfg/.compile-time-parameters
touch iso.arfg/.hooks
touch share.arfg/.local
touch util.arfg/.compile-time-parameters

Furthermore, you need to set up a number of (preferably: symbolic) links from the source code directories iso.arfg and util.arfg to share.arfg in order to allow for consistency between the main program and the accompanying utilities; in case your system does not allow symbolic links you should instead copy the files, but bear in mind that it is of utmost importance to keep these files synchronized between directories at any time.

ln -sf ../share.arfg/.arfg-post    iso.arfg/
ln -sf ../share.arfg/.arfg-pre     iso.arfg/
ln -sf ../share.arfg/.arfg-rewrite iso.arfg/
ln -sf ../share.arfg/.boilerplate  iso.arfg/
ln -sf ../share.arfg/.local        iso.arfg/
ln -sf ../share.arfg/.m            iso.arfg/
ln -sf ../share.arfg/.m4           iso.arfg/
ln -sf ../share.arfg/Makefile      iso.arfg/
ln -sf ../share.arfg/basics.arfg   iso.arfg/
ln -sf ../share.arfg/files.arfg    iso.arfg/
ln -sf ../share.arfg/.arfg-post    util.arfg/
ln -sf ../share.arfg/.arfg-pre     util.arfg/
ln -sf ../share.arfg/.arfg-rewrite util.arfg/
ln -sf ../share.arfg/.boilerplate  util.arfg/
ln -sf ../share.arfg/.local        util.arfg/
ln -sf ../share.arfg/.m            util.arfg/
ln -sf ../share.arfg/.m4           util.arfg/
ln -sf ../share.arfg/Makefile      util.arfg/
ln -sf ../share.arfg/basics.arfg   util.arfg/
ln -sf ../share.arfg/files.arfg    util.arfg/

Customization in .local

As part of the definitions read during processing of .arfg-pre, the file .local is read; it is intended to hold site-specific information that is not likely to change from one application of ar-HRT-1 to the next, definitions of hooks that you want to be applied in every invocation of the program in particular. Several useful or even mandatory settings are listed below; note that items relevant only for buggy compilers are marked by «[BUG]» in the following headings:

Calls to Fortran 90 compiler

You also have to provide some Perl code for building the call to the Fortran 90 compiler; this function is called with the list of the names of the Fortran source files, ordered according to their dependencies. The result of this Perl sub will be written to a file and is assumed to be an executable script for calling the compiler. An example, checking for a flag compile__with_debugging indicating which compiler flags should be used and putting a symbolic link to the compiled executable in the current working directory is as follows:

m4_checkrange(`compile__with_debugging', `yes',`no')
m4_ifelse(compile__with_debugging, `yes',
  `m4_define(`__CompilerOptions__', ` -C=all -g90 -g -gline --static ')',
  `m4_define(`__CompilerOptions__', ` -C=none -O --static ')')
sub compile_f90 {
  my $prog = $_[1] || "ar-HRT-1";
  system "touch .f90/$prog ;
          ln -sf .f90/$prog $prog ;
          rm .f90/$prog ";
  return "#!/bin/sh
  [ -f $prog ] && rm $prog
  f90 __CompilerOptions__ -gc -fieee -o $prog $_[0] 2>&1

Do not forget to adapt the compiler flags to reflect your needs; in particular, it is of utmost importance that IEEE arithmetic is supported so that overflows or undefined values do not lead to program termination. - Also, you may wish to customize the setting for the program's name, but beware that some of the scripts that come with the program assume ar-HRT-1 as a default.

Options files

At run time, the executable program by default first reads the master options file to find the location of the three options files holding information on the current run. By default, the master options file is in ~/.ar-hrt-1.rc, but you can set this variable to some other, more convenient value:

m4_define(`m4_MasterOptionsFile', `./.master.opts')

Refer to your compiler's documentation in order to find out how to specify absolute or relative paths.

Alternatively, you may want to use the hooks mechanism to make ar-HRT-1 bypass the master options file and to always look for the remaining options files in one and the same place; e. g., you could put into your .local something along the lines of:

m4_define(`hook hrt:pre-defn-masterOptionsFile',
  `! .local: no masterOptionsFile
m4_define(`hook hrt:post-defn-masterOptionsFile', `<<ARFGCOMMENTS..')
m4_define(`hook hrt:pre-read-masterOptionsFile',
`! .local: no masterOptionsFile
m4_define(`hook hrt:post-read-masterOptionsFile',
  `<<ARFGCOMMENTS..! .local: explicit file names in current directory:
   runOptionsFile =      ".run.opts"
   systemOptionsFile =   ".sys.opts"
   isothermOptionsFile = ".iso.opts"')

The above will cause ar-HRT-1 to always look for the file .run.opts in the current working directory for the run-specific options; in the file .sys.opts in the current working directory for the system-specific options; and in the file .iso.opts in the current working directory for the isotherm-specific options. Note that this is precisely the set-up expected by ar-Phase.

Setting editing modes or the beginning of constructed files

Several of the files produced are intended to be modified by the user; use hooks in order to set editing modes or to add some leading information to them. The following, e.g., sets the emacs m4 editing mode for the file hooks template file .f90/.opt/hooks-template.m4:

m4_define(`hook hrt:auto-startfile-mode:.opt/hooks-template.m4',
          `m4`'_dnl -*-m4-*-')

[BUG] Initialization of IEEE values

If your compiler won't let you compile code with initialization statements for the IEEE values of signed overflow and numerically undefined values, use the following work-around:

m4_define(`_IEEE754_Constant_Init__pInf_NaN_mInf_', `
  $1 = huge_`'KIND_real
  $1 = $1 * $1
  $2 = $1 / $1
  $3 = -$1

Alternatively, check your system's documentation for a way of specifying acceptable initialization statements and use hooks to implement them in main part «basics».

[BUG] Initialize I/O

At least one buggy Fortran 90 compiler segfaults if the I/O system is not initialized before the call to the function returning a pointer to a list of parsed options; to circumvent this problem, the following hook (causing the output of an empty string) has been found to work:

m4_define(`hook hrt:Main-Program-Start', `! hook defined in .local
write(*, fmt="(A)", advance="no") ""'
m4_defn(`hook hrt:Main-Program-Start')

[BUG] Prompt garbage collection

At least one buggy Fortran 90 compiler does garbage collection only on leaving a subroutine while always re-allocating memory for each and every array operation. Consequently, the slowly convergent core condition integrals can not be evaluated in general on machines with limited memory. To prompt timely garbage collection use the following hook definitions, transforming the corresponding integrations' inner loop body to an internal subroutine:

m4_define(`hook ansatz:_Module_Ansatz_:auto-pre-end:Prepare1stStep',
m4_defn(`hook ansatz:_Module_Ansatz_:auto-pre-end:Prepare1stStep')
  subroutine MatrixIntegrLoopBody_NAGF90
  end subroutine MatrixIntegrLoopBody_NAGF90
m4_define(`hook ansatz:init-matrix:start-integration-loop-body',
  call MatrixIntegrLoopBody_NAGF90
m4_define(`hook ansatz:init-matrix:end-integration-loop-body',

Note that this is bound to give a non-negligible performance penalty, so use this hook only if absolutely necessary.

Compile utilities

As a last step, in order to be able to read the isotherm data calculated by ar-HRT-1 you will have to compile the utilities that come with it. Due to the data format employed it is vital that you use the same compiler as for your main programs.

[ previous ] [ contents ] [ next ]

Copyright © 2002-2003 by Albert REINER. All rights reserved.

URL: http://purl.oclc.org/NET/ar-hrt-1/current/install.html

URL: http://purl.oclc.org/NET/ar-hrt-1/5.20030128a/install.html

2003-01-28 16:38:29