## Physics 410: Computational Physics: Software Availability and Usage Hints

This document will be updated throughout the course

### Index

General purpose system and programming software Numerical analysis software (see also Course Resources Page)
• drand48 (Portable random number generation)
• fftpack (Fast Fourier Transforms)
Postscript viewer and plotting software Visualization and related software Scientific word-processing and related software General purpose graphics software and examples Miscellaneous (source code available in ~phys410/util and subdirs).
• democomplex.f: Demonstrates usage of complex arithmetic in Fortran.
• stringfmt.f: Demonstrates Fortran "Internal I/O" (writing to a character string), in the context of generation of filenames with embedded run-time parameters.
• dvappend.f: Appends double precision vector to a file. tdvappend.f: Driver routine for dvappend.
• mg0.f: Driver program for mgv, a multi-grid routine which solves the Poisson equation on 1-d, square 2-d and cubical 3-d domains using Dirichlet boundary conditions only. Source for the libvcyc.a library, including mgv. Makefile for the demo application.

Usage notes:

1. When using mgv the following libraries must be included at link-time:
```   -lvcyc -lp410f -lvutil -lv2util -lv3util
```
2. For 3-D solutions, the following parameter settings are recommended
```   preswp = 3
pstswp = 3
ncycle = 3
```
Student requested software
• If there is some software you would like to see installed on the lnx machines, send me a message.

Maple: One of the two major general-purpose "symbolic manipulation" packages (also general-purpose programming environments), and the one that we will study in this course (the other package is Mathematica).

On the lnx machines type

```lnx1% xmaple
```
for the GUI version, or
```lnx1% maple
```
for a terminal-based (text) session. In the latter instance you should see something like this.
```lnx1 1> maple
|\^/|     Maple 6 (IBM INTEL LINUX)
._|\|   |/|_. Copyright (c) 2000 by Waterloo Maple Inc.
<____ ____>  Waterloo Maple Inc.
|       Type ? for help.
>
```
If there is any sequence of `Maple` commands that you find yourself typing at the beginning of each session (`maple` or `xmaple`) you can put them in a file `.mapleinit` in your home directory, whereafter they will automatically be executed each time you use `Maple`.

Fortran 77: A general purpose programming language which is particularly well-suited to numerical (scientific/engineering) applications. On the lnx machines, we will be using the Portland Group (PG) compiler, pgf77

Typical usage:

```% pgf77 -g mypgm.f mysubs.f -o mypgm
```
See the on-line notes describing the use of Fortran and C in the Unix environment for additional information, as well as the Fortran 77 section of the Course Resources page.

C: Another general purpose programming language which is also widely-used for scientific and engineering applications. On the lnx machines, I recommend you use the PG compiler, pgcc Typical usage:

```% pgcc -g mypgm.c myfcns.c -o mypgm
```
See the on-line notes describing the use of Fortran and C in the Unix environment for additional information.

libp410fa: Utility library for Fortran 77 programs. Available on the lnx machines. Sample driver for utility routines: `p410fsa.f`. See source code and course notes for further information.

Typical usage:

```   % pgf77 pgm.f -L/usr/local/PGI/lib -lp410 -o pgm
```

drand48: See Fortran notes, Lecture 4.

fftpack: A library of Fortran callable routines for performing single and double precision Fast Fourier Transforms (FFTs). Available on the lnx machines. Documentation for the double precision routines is available here.

Sample main program tfft.f and Makefile which uses some of the basic routines.

gv: Available on lnx machines as well as physics. Use for viewing Postscript documents. Largely considered an improved (more user friendly) version of the venerable ghostview.

Typical usage:

```   lnx1% gv somefile.ps
```
Note: Not all Postscript files will have .ps extensions, but many do by convention.

ghostview: Available on all machines. Use for viewing Postscript documents.

Typical usage:

```   lnx1% ghostview somefile.ps
```

gnuplot: X-application available on lnx machines and physics. 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:

```   lnx1% gnuplot
.
.
.
Terminal type set to 'x11'
gnuplot> help
.
.
.
gnuplot> quit
```

sm: Supermongo plotting package. Available on all course machines. 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.

Note: If you are using KDE you should initialize the X11 device with

```   : device x11 -bg black
```
and ignore the error message
```   Unknown default colour #000000, using white
```
Typical usage:
```   lnx1% sm
Hello Matt, please give me a command
: device x11 -bg black
: help
.
.
.
: quit
```

vsxynt: A Fortran- and C-callable routine which was specifically designed for the output and subsequent visualization of data generated in the solution of time-dependent problems in one spatial dimension.

Use of this routine in Fortran is illustrated by the code vswave.f which generates a time-series of waveforms, and, at each time step, outputs the data using vsxynt.

Depending on which library is linked-to, data which is output via vsxynt will be sent to special-purpose files, or sometimes directly to a visualization server such as scivis. I strongly recommend that you use the following libraries when using the vsxynt interface:

```    -lsvs -lrnpl -lsv -lm
```
I further recommend that you communicate these libraries to make using the following setenv command which should be placed in your .cshrc:
```    setenv LIBVS '-lsvs -lrnpl -lsv -lm'
```
If you do this, then Makefiles such as this one will work properly.

Assuming that your executable has linked to the libraries given above, calls to vsxynt will direct data to files with the extension .sdf. Thus, in the vswave.f example, the call

```     call vsxynt('wave',t,x,y,nx)
```
will send data to
```     wave.sdf
```
.sdf files can then be sent to scivis using the sdftosv command, as discussed in more detail below.

Important: Note that .sdf files are not ``human-readable'', so please don't try to edit them or, worse, to print them!

scivis (jser): A package for interactive & collaborative visualization developed at NPAC in Syracuse. Unfortunately, the on-line documentation previously available from the NPAC site no longer exists, so if you have any questions concerning the use of the software, contact the instructor.

PLEASE SEND ME E-MAIL IMMEDIATELY IF YOU HAVE PROBLEMS WITH THIS SOFTWARE.

You can start jser from the command-line:

```   lnx1% jser &
```
Note, that we start jser in the background so that we can continue to type commands at the shell prompt. Also note that jser is an X-application, so even though it is being run on lnx1, the windows should appear on your local screen.

After invocation of jser, the following window should pop up on your screen in a few seconds (but be patient, it may be 15 seconds, or so):

Note that, with the exception of the Exit button---which shuts the server down---you will probably find little use for the various selections on the server panel. Rather, you will primarily interact with the server through additional windows which display data sets which are sent to the server after it is started. For example, assume that we have previously generated an .sdf file using, for example, a Fortran program which calls vsxynt:

```   lnx1% pwd
/usr/people/phys410/fd/new_wave

lnx1% ls
Makefile   gpwave.f   vswave.f

lnx1% make vswave
f77 -g -64 -c vswave.f
f77 -g -64 -L/usr/local/lib vswave.o -lp410f -lsvs -lrnpl -lsv -o vswave

lnx1% vswave
usage: vswave

lnx1% vswave 101

lnx1% ls *.sdf
wave.sdf
```
Then, once we have started the scivis server, we can send the data in this .sdf file to the server using the sdftosv command:
```   lnx1% sdftosv wave
```
In a few seconds you should see a window such as the following pop-up:

Observe that the new window displays one time step (dataset) of the data at a time. Using the pull down menus and/or keyboard accelerators, you can step through the data, zoom-in or or, play (animate) the data, and perform many other functions, many of which are fairly self-explanatory.

Here is a guide to the annotations on the above scivis data window:

Note that the server's main function (in the context of this course) is to provide you with a useful tool to develop and analyze programs which solve time-dependent partial differential equations in one spatial dimension (or time dependent particle motion in 2 dimensions). In particular, you should not expect to use it to produce ``quality'' hardcopy output.

scivis (jser) keyboard-accelerators

Important Note: Due to a bug in the scivis software, you must first RESIZE any window that scivis creates in order for the following keyboard accelerators to work. All accelerators are Ctrl-key based; for example, C-a means depress the ctrl key and then the a key (without releasing the ctrl key).

Keystroke Mnemonic Function
C-q Quit Closes window
C-a Animate Starts animation
C-s Stop Stops animation
C-n Next Displays next dataset
C-p Previous Displays previous dataset
C-g Goto Goto specific dataset

sdftosv: Sends data in .sdf files to the Scivis server (also known as jser). Here is the full usage for the command

```   % sdftosv
sdftosv version: 1.0
Copyright (c) 1997 by Robert L. Marsa
sends .sdf files to the scivis visualization server
Usage:
sdftosv [ -i ivec ]
[ -n oname ]
[ -s ]
input_file [ input_file [ ... ] ]

-i ivec  -- use ivec (0 based) for output control
-n oname -- name all data sets oname
-s       -- send data sets one at a time
useful for large or nonuniform data
input_file is an .sdf file
```
Beware that there is a command sdftovs which sends an .sdf file to a different server---if you get an error message such as
```  assign_Server: Could not communicate with sgi1
assign_Server: Ensure that server is running on sgi1 and/or
assign_Server: check/reset value of environment variable VSHOST.
```
you have typed sdftovs instead of sdftosv.

A typical invocation will be:

```   % ls
wave.sdf

% sdftosv wave
```
Note that you do not have to specify the .sdf extension explicitly, but you can if you so wish.

If we wanted to send only every second time step of wave.sdf to the server we could use
```   % sdftosv -i '0-*/2' wave
```
In this example, the construct
```   0-*/2
```
is an example of an index-vector (or ivec), which is just a shorthand for a regular sequence of integers:
```   min-max/step  ===>  min, min + step, min + 2 step, ... min + n step
```
where n is the largest integer such that
```   min + n step <= max
```
Index 0 refers to the first time level of data stored in the file, and an asterisk (*) can be used in place of min and/or max to denote "first time-level" or "last time-level" respectively. When using * in an index-vector specfication, such as in the above example, be sure to enclose the index-vector in single quotes to keep the shell from interpreting * in its own special way.

IMPORTANT NOTE: The utilities sdftosv and jv1 need to know on which machine jser is running. Often this will be the same machine from which you are sending data, but it need not be so. Thus the utilities require that the environment variable JSERHOST be set to the name of the host which is running jser. On the lnx machines, JSERHOST will be automatically set at shell start-up to the name of the local host, so normally, you won't have to worry about setting it explicitly. However, if you want to send data from some other machine, say physics.ubc.ca, to jser running on lnx1, for example, then on physics you will need to issue:

```   physics% setenv JSERHOST lnx1
```
before you transmit the data.

sdfinfo: Program which dumps summary information about an .sdf to standard output.

Typical usage:

```   % sdfinfo wave.sdf

Data set 1
name=<wave>
version=1
time=0
rank=1
shape=(10)
bbox=(0,1)
csize=10
dsize=10
cnames=(r)
tag=<NULL>
|data|=0.329628, min(data)=1.38879e-11, max(data)=0.734444
Data set 2
name=<wave>
version=1
time=0.111111
rank=1
shape=(10)
bbox=(0,1)
csize=10
dsize=10
cnames=(r)
.
.
.
```
Key to output:
• name: Data set name.
• version: SDF version number.
• time: Data set time.
• rank: Data set rank.
• shape: Data set dimensions.
• bbox: Data set bounding box (xmin xmax ymin ymax ...)
• csize: Size of coordinates (number of doubles).
• dsize: Size of data (number of doubles)
• cnames: Coordinate names.
• tag: Optional additional character information associated with data set.
• |data|: l2-norm of data set (RMS value).
• min(data): Minimum of data set.
• max(data): Maximum of data set.

jv1: Filter which reads two columns of numbers ((x,y) pairs) from standard input and then sends the data to scivis (jser).

Typical usage:

```   % jv1 < data_file
```
or
```   % jv1 name < data_file
```
where data_file is a two column file containing the data to plot. In the first instance, the data will be visualized in a jser window named Standard input, in the second the jser window will be labelled name.

libbbhutil.a: Fortran- and C-callable output utility routines written for the Binary Black Holes Grand Challenge Project. Available on lnx 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 calledor 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. On the lnx1 machines, 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.

IRIS Explorer: A powerful scientific visualization system available on the lnx machines. You need to be logged into a console to use the software.

Complete on-line documentation for the system is available via IRIS Explorer Center and Postscript versions of the User's Guide with graphics and without graphics.

latex and tex: Available on all course machines. 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
```
You can easily include Encapsulated Postscript files in a TeX/LaTeX document, using the epsf package. Here is a sample tex source file, here is the figure file which is included, and here is the final postscript file.

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
' TeX output 1997.01.22:1442' -> document.ps
. [1]

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

Open GL: A widely used software interface to graphics hardware, consisting of about 120 commands which are used to specify the objects and operations needed to produce interactive 2- and 3-dimensional applications.

This software is available on the lnx machines.

Available PS documentation:

GLUT: OpenGL Utility Toolkit Programming Interface. Facilitates construction of OpenGL programs which manipulate windows, handle user-initiated events etc.

Available PS documentation:

See pp2d below for sample application including a Makefile which can be modified for use on the lnx machines.

Note that the Makefile requires the following environment variables to be set as documented HERE.

```CC
CCFLAGS
CCCFLAGS
CCLFLAGS
LIBGL
```
On the lnx machines, these variables should be set properly by default, for all users.

Open Inventor: An object-oriented toolkit (written in C++) that simplifies and abstracts the task of writing graphics programming into a set of easy to use objects.

This software is available on the lnx machines.

Part of the Open Inventor environment is ivview, a fast interactive 3D viewer of Inventor files. The source code for this application, ivview.C and ivviewMenus.h may be of interest to those of you interested in using Open Inventor for graphics programming. Makefile for ivview. Sample Inventor File (ASCII format) engine.iv.

Note that the Makefile requires the followinng environment variables to be set as documented HERE.

```CXX
CXXFLAGS
CXXCFLAGS
CXXLFLAGS
LIBINVENTOR
```
On the lnx machines, these variables should be set properly by default, for all users.

pp2d: OpenGL/GLUT Graphics program for animating two dimensional particle motion. Available on the lnx machines.

Sample usage

```   % 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, pp2d.h and Makefile, may be of interest to those of you interested in using OpenGL for graphics programming.

Sample 6-body input file input6. Use

```   % pp2d < input6
```
to view.

XForms: A software package consisting of

1. A C-callable library, libforms.a
2. A GUI, fdesign
which, together, facilitate the construction of other X- and OpenGL-based GUIs.

This software is available on the lnx machines.

Available PS documentation:

See xfpp3d below for sample application including a Makefile which can be modified for use on the lnx machines.

pp3d: OpenGL/GLUT Graphics program for animating three dimensional particle motion. Available on the lnx machines.

Sample usage

```   % nbody 2.0 0.01 < nbody_input | pp3d
% nbody 2.0 0.01 < nbody_input | pp3d -m
```
Help is available via
```   % pp3d -h
```
Again, the source code, pp3d.c, pp3d.h and Makefile may be of interest to those of you interested in using OpenGL for graphics programming.

Sample 20-body input file input20. Use

```   % pp3d < input20
```
to view.

Warning: This application is still under development. Report any problems to Matt immediately.

xfpp3d: Version of pp3d which incorporates a GUI created using the XForms package.

Must be used via the console on the lnx machines.

Sample usage

```   % nbody 2.0 0.01 < nbody_input | xfpp3d
```

xfpp3d expects input in precisely the same format as pp3d does.

The source code, xfpp3d_main.c, and Makefile may be of interest to those of you interested in using OpenGL and XForms for graphics programming.

Warning: This application is still under development. Report any problems to Matt immediately.