Planguage Documentation and Usage



Planguage Documentation and Usage


Online Instructions

Building, Testing, and Installing
User Guide: Making and Running an Application
An Example Application with Files
Planaguage Programmers' Field Guide

Manuals

PC Users' Guide
The Pfortran Reference Manual
Pfortran Users' Guide

Building, Testing and Installing

To obtain the distribution got the distribution download on the Planguage home page. The distribution with source code is freely available, only requiring some information and agreement to a end-user license.

Unpack the tar file contatining the distribution at a place where you will build the distribution, let's say, /usr/local/src. This will create a directory tree rooted at plang. This location, for example, /usr/local/src/plang, will be used to define the environment variable PLANG_TOP below.

After building the installation you may want to make a tailored install tree containing executables, libraries, and examples; the install will not contain the translator source code. The install described below will be rooted at PLANG_ITOP, for example /usr/local/apps/plang.

The build is currently supported on the following platforms: Linux PCs, SGI Onyx, SP2, and T3E. Here are the steps for building the distribution:

  1. shell> cd plang
  2. Check the environment variable definitions in the file plangrc (sample plangrc).
    PLANG_TOP The root directory of the Planguage distribution tree.
    PLANG_ITOP
    The root directory of the installation tree.
    PLANG_PLATFORM

    Determines what platform compiling on.
    Choose one from: linux ipsc paragon sgi32 sgi64 solaris sunos sp2 t3e.
    PLANG_NETINT

    Determines what network interface to build for.
    Choose one from: mpi nx pvm shmem isim.
    PLANG_SYSTEMS

    Determines what Planguage systems to build. Choose one or more from: all all+doc isim pfc pcc pflib pclib pftests pctests.
    PLANG_MPROC

    The maximum number of processes for running tests. Each test is run from 2 to PLANG_MPROCs in increments of 1.
    PLANG_MPIRUN

    The location qualified name of mpirun on your system if applicable. This matters only for running tests which use mpirun.
    PLANG_MPIBARRIER

    0: use Planguage synchronization in runtime library;
    1: use MPI synchronization in runtime library.
  3. shell> source plangrc
  4. shell> gmake config
  5. shell> gmake build
  6. shell> gmake runtests
    More details about the tests are given below.
  7. shell> gmake install

Testing Details

The command gmake runtests will cause tests to execute from 2 to PLANG_MPROCS process configurations in increments of 1. (The tests are run from the perl script plang/BIN/runtests.pl.) All tests should pass; a failed test is cause for investigation. The test script runtests.pl output to stderr is condensed pass or fail information. The test program and runtests.pl output goes to the following files in plang/tmp:
test.out: program stdout for one run, one process configuration only.
test.log: all runtests.pl script output for one runtests invocation.
test.llog: history of all test program and runtests.pl script output.
All STDERR goes to tty. In addition to gmake runtests, one can also gmake runpftests and gmake runpctests.

T3E NOTE
For the T3E, it is necessary to execute the three lines:

source /opt/modules/modules/init/csh
module load PrgEnv
module load mpt

User Guide

In this section we describe

  1. the installation,
  2. how to make an application,
  3. how to run an application, and
  4. how to time an application.

1. The Planguage Installation

The installation is designed for getting the beginner started building an application consists of copying a makefile, editing one line, and typing make. The supplied makefile for user applications bases its paths on the variable, $PLANGROOT, the root of the Planguage installation. The installation at $PLANGROOT consists of:

translators:
bin/pfc
bin/pcc
parallel simulator:
bin/isim
application libraries:
lib/libpcmpi.a - PC mpi
lib/libpfmpi.a - Pfortran mpi
lib/libisim.a - simulator
lib/libpfnx_i.a - Pfortran simulator
lib/libpcnx_i.a - PC simulator
makefile include files:
include/makefile.h
include/system.h
example source code:
examples/src
example makefile:
examples/makefile
example binaries:
example/bin
documentation at doc
The example binaries are compiled for execution by mpi. One can copy the example source code into a working directory, and using the makefile there, compile one's own versions either for an mpi environment or for the parallel simulator. (Pfortran and PC have previously targeted numerous other network interfaces, however, we are focusing here on principal NPACI ones.)

2. Making an application

  1. Copy the Planguage makefile to your working directory
    cp $PLANGROOT/examples/src/makefile mywork
  2. Edit the OBJ makefile macro to be your set of objects.
  3. Edit the NETINT makefile macro to your preference.
  4. Typing gmake produces the executable "mybuild".
Note that the makefile includes two files from the Planguage installation:
$PLANGROOT/include/system.h (sample for SP2)
$PLANGROOT/include/makefile.h
In general one should include these files from the Planguage installation on your system. Make variables can be modified immediately below the include in the user makefile (illustrated in makefile for PFFLAGS). However, one might can include these files from another directory, possibly to tailor for a special purpose.

3. Running an Application

Running a parallel application is highly application specific: one will likely be mpi or the simulator at the moment. The following examples are examples to get one started - numerous variations are possible. These examples suppose four processes.
  1. MPI on Linux, using mpirun:
    mpirun -np 4 build
  2. MPI on SP2, using POE
    poe build -procs 4 -rmpool 1
  3. MPI on the T3E, using mpirun:
    First execute:
    source /opt/modules/modules/init/csh
    module load PrgEnv
    module load mpt
    Now run the program
    mpirun -np 4 build
  4. isim simulator on all machines
    The parallel simulator, isim, is available in the PLANGROOT/bin directory as isim. The simulator emulates a hypercube (powers of 2 processes only) using Unix processes. Here is a sample session; check the simulator online help for more details.
    shell> isim
    sim> getcube -t4
    sim> ld mybuild
    sim> start
    sim> quit

THE ISIM SIMULATOR DOES NOT FUNCTION ON THE T3E.



4. Timing an Application

The Pfortran runtime library provides the subroutine
pclock(seconds)
to return an elapsed time on the calling processor in seconds using the mpich function
MPI_Wtime.

The implementation is

SUBROUTINE pclock(secs)
IMPLICIT NONE
#ifndef T3E
double precision secs, mpi_wtime
#else
real secs, mpi_wtime
#endif
secs = mpi_wtime()
RETURN
END
to be used as
real start, stop, total
...
call pclock(start)
... compute something
call pclock(stop)
total = stop - start

An Example Application with Files

This example builds the Pfortran program mybuild and uses the installation with translators and make include files described above. To use the example, copy into a directory the two files:
makefile
pfsort.PF.
Edit the first line of the makefile defining PLANGROOT to the installation point on your machine. The makefile will work together with the installation to link with the proper libraries for the platform the Planguage distribution is installed on. To build the executable mybuild from the Pfortran source pfsort.PF, enter
shell> gmake
To execute the program, please refer to Running an Application for platform specific information.

There are numerous examples in the example directory of the installation.

Good luck!


email to Planguage support


last updated February 5, 2001 by TClark