Physics 387N - Spring 1998

Physics 387N: Relativity Theory II: Software Availability and Usage Hints

This document will be updated throughout the course

Index

Software Notes for Project 3
- Using generic RNPL Makefiles
- Sample RNPL codes
  - 1d Wave equation (Crank-Nicholson, implicit dissipation)
  - Einstein/Massless-Klein-Gordon model
- Binary search scripts
- Data for n=1 Bartnik-McKinnon solution
- New RNPL features (under construction)
Software Notes for Project 2
ser/vs
IRIS/NAG Explorer
libbhutil.a
pp2d
GLUT
libp329f.a
ghostview
gnuplot
sm (Supermongo)
latex and tex
xdvi
dvips

Software Notes for Project 3:
- Important!! If you have any problems with the software described below, contact the instructor (471-1541) or the system administrator Steve Liebling (471-4700) immediately. Other members of the Center for Relativity may also be able to help, depending on the nature of the problem.
- Using generic RNPL Makefiles: One slightly inconvenient feature of RNPL as it currently installs, is that the Makefile for a given RNPL application tends to vary from machine to machine. This is not a problem if you stick to developing and computing on one machine, but I intend to provide you with access to some of the local Crays, and will encourage you to use them for your "production runs". I thus suggest that you begin to use the following mechanism which will allow you to use a single Makefile on a variety of machines and architecutures, and effectively create completely portable RNPL applications. To use this generic Makefile facility, ensure that the following six environment variables are set prior to making an application:
```
RNPL_RNPL
RNPL_RNPL_FLAGS   (only needed on Crays)
RNPL_F77
RNPL_F77LOAD
RNPL_F77PP
RNPL_FLIBS
```
  The natural place to set these is in your (and your group's) ~/.cshrc files. Note that in your ~/.cshrc on the SGIs you may want to detect whether you are on a 64-bit or 32-bit machine. This can be done with the following csh construct:
```
if( `uname` == IRIX64 ) then
   setenv RNPL_F77 "f77  -64 -O3   -YI,/usr/local/include"
                 .
                 .
                 .
else
   setenv RNPL_F77 "f77 -n32 -O -YI,/usr/localn32/include"
                 .
                 .
                 .
endif
```
  Current valid settings of the above environment variables for various local machines are listed
  here.
  
  You can install a new generic Makefile using the new command as follows:
```
% new Makefile.rnpl.f77.generic
% mv Makefile.rnpl.f77.generic Makefile
```
- 1d Wave equation (Crank-Nicholson, implicit dissipation):
  - RNPL source file: w1dcn_rnpl
  - Generic Makefile: Makefile
  - Sample parameter file: id0
- Einstein/Massless-Klein-Gordon model:
  
  APRIL 2002 NOTE: The following example source code differs from that actually used in the course.
  The previous code used a 3-level explicit scheme in contrast to the current Crank-Nicholson time-stepping.
  - RNPL source file: emkgcn_rnpl
  - Include file containing hand-coded f77 source for update of a, lapse and mass quantities: calc_al.inc
    - RNPL-generated update file (includes above source): updates.f
  - Include file containing hand-coded f77 source for initialization of a, lapse and mass quantities: init_al.inc
    - RNPL-generated initialization file (includes above source): initializers.f
  - Generic Makefile: Makefile
  - Sample parameter file: id0
- Binary search scripts:The following scripts are available to expedite binary searches (bisection searches) at the command-line level:
  - bsnew
```
usage: bsnew lo hi
```
    Intializes the search interval limits to lo and hi and echoes the limits to stdout.
  - bscurr
```
usage: bscurr
```
    Echoes the current search value--(lo + hi) / 2--to stdout
  - bslo
```
usage: bslo
```
    Replaces the low end of the search interval with the current search value and echoes the search limits
  - bshi
```
usage: bshi
```
    Replaces the high end of the search interval with the current search value and echoes the search limits
  - bsfrac
```
usage: bsfrac
```
    Echoes the fractional size of the search interval--(hi - lo) / hi--to stdout.
  - bsdone
```
usage: bsdone [tol]
```
    Exits with a return code of 0 (success) if `bsfrac` < tol, or 1 (failure) otherwise.
    tol defaults to 1.0e-14.
  Sample usage
```
% bsnew 0.0 1.0
0.0
1.0

% bscurr
5.000000000000000e-01

% bslo
5.000000000000000e-01
1.0

% bslo
7.500000000000000e-01
1.0

% bslo
8.750000000000000e-01
1.0

% bshi
8.750000000000000e-01
9.375000000000000e-01

% bshi
8.750000000000000e-01
9.062500000000000e-01

# Pass the current search value to another command
% Setpar rnpl_file search_parameter `bscurr`

% bsfrac
3.508771929824561e-02
```
- Data for n=1 Bartnik-McKinnon solution:
  - W(r): wstatic.sdf
  - -W(r): mwstatic.sdf
Software Notes for Project 2:
- RNPL: A high level language designed for the rapid prototyping of finite-difference codes for time dependent problems on uniform meshes. Although HTML versions of both a Reference Manual and User's Guide are available, they are somewhat out of date and I suggest that you use Chapters 8 and 9 of Robert Marsa's PhD dissertation as your chief reference for the language.
  
  Note that RNPL generates complete f77 or C programs; the output language is controlled by the -l command-line switch. Again, I recommend that you have RNPL generate f77 code, although you can use the C option if you so prefer. When constructing a new RNPL example you can create a template Makefile using a script called new. If you simply type
```
   % new
```
  with no arguments, you will get a listing of available template files. Among these will be
```
   Makefile.rnpl.f77.32   Makefile.rnpl.c.32
```
  Typing
```
   % new Makefile.rnpl.f77.32
```
  or
```
   % new Makefile.rnpl.c.32
```
  will copy a template Makefile for a f77 or C application to the current working directory. You will then have to rename the file; for example
```
   % mv Makefile.rnpl.f77.32 Makefile
```
  and then follow the instructions in the Makefile for tailoring to your specfic application.
  
  I also maintain a Web page of RNPL examples which also may be of use. I am in the process of updating the examples, so, in the short term, be wary of copying source, Makefiles etc. from the example page.
- vsxynt: See the ser/vs overview for information on the use of this routine in f77 and C programs, but read the following information carefully as well since the overview does not detail all of the available output options.
  
  There are several distinct libraries which implement the vsxynt routine and which differ in exactly what type of I/O occurs when the routine is invoked. For the most part, you will probably want to use libsvs.a.
  - libsvs.a (link to using -lsvs )
    - File option: Linking to this library will cause vsxynt, by default, to direct data to .sdf files which can then be sent to ser/vs via
```
   % sdftovs sdf_file [ sdf_file ... ]
```
      or to scivis via
```
   % sdftosv sdf_file [ sdf_file ... ]
```
      Typing either command without arguments will result in a usage message. Note that the .sdf file format is binary and machine-independent; further details concerning the full .sdf interface may be found here
    - Direct-to-server option: If the environment variable BBHSV is set to any value, and the environment variable BBHHOST is set to the name of a machine of which the scivis server is running---e.g.
```
   % setenv BBHSV on
   % setenv BBHHOST einstein.ph.utexas.edu
```
      then output generated via vsxynt goes directly to scivis, so that you interactively watch the output from your calculations. To revert to .sdf file output, be sure to unset both environment variables.
```
   % unsetenv BBHSV
   % unsetenv BBHHOST
```
  - libvs.a (link to using -lvs )
    Linking to this library will cause vsxynt to send data directly to the ser/vs server, which should be running on your console. You also need to set the environment variable VSHOST to the name of the machine on which ser/vs is running (again, this will normally be the machine you are sitting in front of)---e.g.
```
   % setenv VSHOST einstein.ph.utexas.edu
```
    Your group accounts' .cshrc files will generally set VSHOST to the proper value, so normally you shouldn't have to worry about explicitly setting it.
  - libfvs.a (link to using -lfvs )
    Linking to this library will cause vsxynt to send data to .segdat files which are binary, but not machine independent. segdat files can subsequently be sent to ser/vs using the seg2vs command which has usage
```
   % seg2vs segdat_file [ segdat_file ... ]
```
    Again, the VSHOST environment variable in the invoking shell must point to the machine on which the server is running.
- f77 character manipulation & vsxynt: All output via vsxynt is ``call by name'' (the first argument to the routine). When output goes directly to a graphics server, the name transmitted by vsxynt is exactly the name provided as the first argument to the routine, including any punctuation, embedded spaces (blanks) and special characters. When output is directed to a file, the name is stripped of any non-alphanumeric-underscore characters including spaces. Trailing spaces are always stripped.
  
  It is frequently convenient to use a name which encodes some run-time parameter, such as a discretization level. For integer parameters, this is easy to accomplish in f77 using a routine itoc which is available in libp329f.a (link to using -lp329f). Here is a typical usage
```
   character*2     itoc
               .
               .
               .
   level = i4arg(1,i4_never)
               .
               .
               .
   call vsxynt('u'//itoc(level),t,x,u,nx)
               .
               .
               .
```
  itoc is implemented as
```
   character*(*)    itoc
```
  so that the (mandatory!) declaration of itoc in the invoking routine can, in general, be character*N, where N is the maximum anticipated number of digits in the integer(s) to be converted.
- ser/vs: See below for a synopsis and here for an overview.
  
  Steve Liebling has also provided some additional documentation .
  
  As described in the overview, be particularly careful about terminating the server---NEVER kill it by double-clicking on the ``lightning bar''---use the kill window sub-menu while in the main control window (the one named vs).
  
  Data at a single instant of time can be piped from a ser/vs window to standard output using the vsget command, which has usage
```
   % usage: vsget window_name index
```
  Two-column ascii data (x, y pairs separated by whitespace only) can be piped to the server using the v1 and vn commands:
```
   % v1 [ window_name ]
```
  where window_name defaults to Standard input, or
```
   % vn window_name [ time ]
```
  Note that although ser/vs has no intrinsic facilities for hard-copy output, it implements an interface to sm (Supermongo) accessible via the sm selection on the pull-down menu. In addition, .mpeg movies of the data in any window can be created via the mpeg pulldown menu---I recommend that you make movies using a ``quarter-size window'' such as this one. If you only have a single (full size) window open in the server, clone the window (either from the control sub-menu, or by typing SHIFT-C in the window) to get two windows of reduced size. Finally, note that the mpeg generation facility, creates .rgb images which can be converted into .gifs for use in .gif sequence animations.
- scivis: A package for interactive & collaborative visualization developed at NPAC in Syracuse. See the Scivis home page and the User's Guide for available documentation on the package.
  You should be able to use scivis on the SGI machines simply by typing
```
% jser
```
  If you want to send data from another machine to the server, make sure that on the remote machine (where the data is coming from), the environment variable JSERHOST is set to the machine where scivis is running. Also note that scivis is an X-based application so that you can run it on one machine and have the graphics displayed on another (i.e. the machine you are sitting in front of) via the DISPLAY environment variable.
  Note: Due to a bug in SGI's implementation of Java, you must resize any window that scivis creates in order for the keyboard accelerators to work---i.e. so that CTRL-a starts animation, CTRL-s stops it etc.
- ad: An f77 program which illustrates the Berger & Oliger adaptive-mesh refinement algorithm for the spherically-symmetric wave equation in flat spacetime. The PS documentation contains discussions of differencing techinques that you should find useful for the second problem. Further information concerning ad can be found via the BBH Grand Challenge AMR page.
ser (aka vs): SGI specific graphics utility for analyzing time series of 1 dimensional data. Brief overview of usage. Warning: This software is research-quality, not commercial quality, and there is essentially no documentation other than the source code. However, despite its many quirks, ser is a very powerful tool for analyzing the output of finite-difference codes in one spatial dimension and time. Any of the Center for Relativity graduate students or postdocs who are working with me will be happy to give you a quick tutorial, as will I.
IRIS Explorer: A powerful scientific visualization system available on the Center SGI machines, including einstein. You need to be logged into einstein via the graphics console to use the software. Complete documentation for the system is available via the Online Books selection of the pull-down Help menu which should appear in the "Toolchest" located in the upper right corner of the screen when you login. To use, simply type
```
      % explorer
```
Here are links to the IRIS Explorer Center and Postscript versions of the User's Guide with graphics and without graphics.

libbbhutil.a: Fortran- and C-callable output utility routines written for the Binary Black Holes Grand Challenge Project. Available on SGIs and HPCF Cray machines. Postscript ``man-style'' documentation for the C routines is available here. Fortran routines have the same names (gft_out_bbox etc.) and can be either called, or invoked as integer functions. For output of 2- and 3-D arrays on uniform finite-difference meshes, the routines

      gft_out_bbox

should suffice. Here is a usage example:

      integer      nx,        ny
      parameter  ( nx = 65,   ny = 33 )

      real*8       gfcn(nx,ny)
      real*8       xmin,      xmax,     ymin,     ymax, 
     &             time

      integer      shape(2),  rank
      real*8       bbox(4)
               .
               .
               .
c------------------------------------------------------
c     'bbox' defines 'bounding box' of coords.
c     associated with the data:
c
c     bbox := ( xmin, xmax, ymin, ymax )
c------------------------------------------------------
      bbox(1) = xmin
      bbox(2) = xmax
      bbox(3) = ymin
      bbox(4) = ymax

      rank = 2
      shape(1) = nx
      shape(2) = ny
 
      do it = 1 , nt
              .
              .
              .
c------------------------------------------------------
c     The first (string) arg. to 'gft_out_bbox'
c     is stripped of non alphanumeric/underscore 
c     characters (including punctuation) if necessary,
c     and then used as the 'stem' for a filename of 
c     the form 'stem.sdf'.  All calls to 'gft_out_bbox'
c     with the same string result in output to the 
c     same file.
c------------------------------------------------------
         time = it * 1.0d0
         call gft_out_bbox('gfcn',time,shape,rank,
     &                      bbox,gfcn)
      end do
              .
              .
              .

The gft_ routines use a machine-independent binary format; thus data output using gft_out_bbox on a Cray, for example, can be processed on an SGI. On the SGIs, 2- and 3-D data is best visualized using IRIS Explorer. A locally developed module, called ReadSDF_GFT0, is available for Explorer input of data written using the gft_ routines. Here's an image of an Explorer map which uses this module.

pp2d: OpenGL/X Graphics program for animating two dimensional particle motion. May be of use for Homework 3. Currently available only on Center for Relativity SGI machines, but should display on any workstation running X (and X-terms).
Typical usage (second form is for monochrome displays):
```
   % nbody 2.0 0.01 < nbody_input | pp2d 
   % nbody 2.0 0.01 < nbody_input | pp2d -m
```
Help is available via
```
   % pp2d -h
```
The source code, pp2d.c and pp2d.h, may be of interest to those of you interested in using OpenGL for graphics programming. Makefile for pp2d.
GLUT: OpenGL Utility Toolkit Programming Interface. Facilitates construction of OpenGL programs which manipulate windows, handle user-initiated events etc. Available PS documentation: Overview and Specification/Programmer's Guide.
Typical usage (not all Mesa and X libraries will be required for all applications):
```
   % cc -n32 -I/usr/local/include pp2d.c -L/usr/localn32/lib -lglut \
         -lMesaaux -lMesatk -lMesaGLU -lMesaGL -lXmu -lXi -lXext -lX11 \
         -lm -o pp2d
```
libp329fa: Utility library for Fortran 77 programs. Available on SGIs and Crays. Sample driver for utility routines: p329fsa.f. See source code and course notes for further information.
Typical usage:
```
   % f77 pgm.f -L/usr/localn32/lib -lp329 -o pgm
```
ghostview: Available on SGIs and Linux machines. Use for viewing Postscript documents. This is an X-application. As with any X-application, if you are running ghostview on a remote machine, be sure to set your DISPLAY environment variable so that your local display is used.
Typical usage (assuming a remote login to einstein from one the Physics Linux machines):
```
   einstein% set DISPLAY linux1.ph.utexas.edu:0
   einstein% ghostview somefile.ps
```
Note: Not all Postscript files will have .ps extensions, but many do by convention.
gnuplot: X-application available on SGIs and Linux machines. Use for generating X-Y (2D) and some surface plots. Has extensive on-line documentation: type help at the gnuplot prompt for help.
Typical usage:
```
   einstein% gnuplot
             .
             .
             .
   Terminal type set to 'x11'
   gnuplot> help
             .
             .
             .
   gnuplot> quit
```
sm: Supermongo plotting package. Available on SGIs. An alternative to gnuplot which is somewhat quirkier but generally produces more professional-looking (i.e. publication-quality) plots. See on-line postscript documentation and on-line help (type help at the the sm command prompt) for further details. Supermongo runs as an X-application provided the device is set to x11. Ignore the "Can't find entry for iris-ansi-net ..." message at start-up.
Typical usage:
```
   einstein% sm
   Can't find entry for iris-ansi-net in /usr/local/lib/sm/termcap
   Hello Matt, please give me a command
   : device x11
   : help
             .
             .
             .
   : quit
```

latex and tex: Available on SGIs. Scientific typesetting software. Converts .tex source files to .dvi files which can then be previewed using xdvi, or converted to postscript using dvips.
Typical usage:

   % ls 
   document.tex

   % latex document.tex
   This is TeX, Version 3.14159 (C version 6.1)
   (document.tex
   LaTeX2e <1996/06/01>
   Hyphenation patterns for english, german, loaded.
             .
             .
             .
   No file document.aux.
   [1] (document.aux) )
   Output written on document.dvi (1 page, 696 bytes).
   Transcript written on document.log.

   % ls
   document.aux   document.dvi   document.log   document.tex

xdvi: X-application for previewing .dvi files (output from Latex-ing or tex-ing of .tex files). You don't have to explicitly specify the .dvi extension.
Typical usage:
```
   % ls
   document.aux   document.dvi   document.log   document.tex

   % xdvi document
```

dvips: Utility for converting .dvi files to postscript.
Typical usage:

   % ls
   document.aux   document.dvi   document.log   document.tex

   % dvips document
   Got a new papersize
   This is dvips 5.58 Copyright 1986, 1994 Radical Eye Software
   ' TeX output 1997.01.22:1442' -> document.ps
   . [1] 

   % ls 
   document.aux   document.dvi   document.log   document.ps    document.tex