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) 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). Student requested software

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.
 \  MAPLE  /  All rights reserved. Maple is a registered trademark of
 <____ ____>  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:

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.

Additional Information

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

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.

Available documentation: Under construction, in the meantime, start with man inventor.

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.