Practical Supercomputing Toolkit
================================

This document is part of the Practical Supercomputing Toolkit (PST),
written (2001) by Joe Werne, Michael J. Gourlay, Chris Bizon, Chris
Meyer and others.

The Practical Supercomputing Toolkit is a collection of utilities that
simplify using supercomputer facilities.

The Tools for Unified SuperComputing (TUSC) component of PST provide a
unified scheme for using archive file systems and job queues.  The PST
"archive" and "qprep" commands provide these capabilities.  At this stage,
PST primarily provides the TUSC component.




Installing PST
--------------

To install the toolkit:

0. Requirements

    (a) PST requires Perl.  Make sure Perl works correctly on the target
        system, and encourage the supercomputer center on which you will
        run to maintain the latest version of Perl.

    (b) To be useful, PST also requires local configuration modules for
        each site on which it runs.  This currently entails two modules,
        one for "archive" and another for "qprep".  Either these modules
        already exist for your system or someone (you, your system
        administrator) must write those local configuration modules.
        Read further for more information.


1. Download the latest PST distribution file to your system.
   The PST web site contain the official PST distribution
   files.  The URL for the site is https://pstoolkit.nwra.com/.

   The distribution file names have the pattern "PST-{version}.tar.gz".
   where the notation "{version}" indicates a version number, not the
   literal string "{version}".  For example, a distribution file could
   be named "PST-2_0_0.tar.gz" where "{version}" is "2_0_0".


2. Unpack the "install" script from the archive by issuing this command:

     gunzip < PST-{version}.tar.gz | tar xf - PST-{version}/MD/bin/install


3. Install PST at your site by issuing this command:

     PST-{version}/MD/bin/install PST-{version}.tar.gz

   Read and follow instructions in messages that the install script
   prints to your terminal.


4. Set up local configuration Perl modules for your site.

   Local configuration Perl modules reside in the "TUSC/other_sites"
   subdirectory.  Look there to see whether any exist for your site.
   If not, then it is likely that one or more of the existing modules
   will work with your site with relatively minor modifications.
   See the "Porting" section of this document, below.

   After you find or write modules for your site, place them into the
   "TUSC" subdirectory with appropriate names:

    (a) The configuration module for archive is named "local.pm".
        The routines in that module perform elementary operations to
        access an archive file system (a.k.a. a mass storage system).

    (b) The configuration module for qprep is named "localQprep.pm".
        The routines in that module specify how to translate directives
        from the format of PSTQ to the format of the local job queue
        system.  This involves filling in a translation table and writing
        auxiliary routines to handle special cases that the translation
        table can not handle.



5. Visit the PST website (https://pstoolkit.nwra.com/) for more information.

    (a) On-line documentation can be found at the website via the
        "Documentation" link.

    (b) Report problems via the "Bug Report" page on the PSToolkit
        website.




Porting PST to another site
---------------------------

Each supercomputing site must specify the contents of a number of
subroutine which perform the site-specific operations.

Browse through the files in the "TUSC/other_sites" subdirectory to
learn details about how they work.  The PST distribution includes
"test" local configuration Perl modules that set up a fake archive
system, and translate directives to a fake queue system.  Those modules
demonstrate how to write local configuration modules so if you are just
starting, try looking at those modules first.

If you create or modify configuration modules for your site, please
submit them to the PST development team so they can incorporate your
modules in the official distribution.




Testing modifications to PST's archive command
----------------------------------------------

If you have created or modified the local.pm local configuration file,
the utility TestArchive.pm can help you make sure your modifications 
work.  This program is located in the distribution in 
TUSC/bin/TestArchive.pl, and it is designed to be run from that 
directory.  Read the comment statements in TestArchive.pl to learn how
to use it and what it tests.




PST Components
--------------

MD  : Management and Documentation tools
SET : Source Editing Tools
TUSC: Tools for Unified SuperComputing
sums: checksums for PST files