[Swift-commit] r5075 - branches/release-0.93/docs/siteguide

[davidk at ci.uchicago.edu]

Author: davidk
Date: 2011-09-06 11:48:56 -0500 (Tue, 06 Sep 2011)
New Revision: 5075

Modified:
   branches/release-0.93/docs/siteguide/pads
Log:
Various updates to pads site guide


Modified: branches/release-0.93/docs/siteguide/pads
===================================================================
--- branches/release-0.93/docs/siteguide/pads	2011-09-06 15:16:00 UTC (rev 5074)
+++ branches/release-0.93/docs/siteguide/pads	2011-09-06 16:48:56 UTC (rev 5075)
@@ -4,8 +4,12 @@
 PADS Quickstart
 ~~~~~~~~~~~~~~~
 This section will walk you through running a simple Swift script
-on PADS.
+on PADS. It will explain how to setup software packages, how
+to create the required Swift configuration files, and finally
+how to run Swift.
 
+Adding Software Packages
+++++++++++++++++++++++++
 In your home directory, edit a file called .soft and add these
 lines (in this order):
 -----
@@ -15,43 +19,71 @@
 @default
 -----
 
-Log out of PADS, and log back in.
+Log out of PADS, and log back in for these changes to take effect.
 
-Next, paste the example below into a file called sites.xml.
+Creating sites.xml
+++++++++++++++++++
+Swift relies on various configuration files to determine how to
+run. This section will provide a working configuration file which
+you can copy and paste to get running quickly. The sites.xml file
+tells Swift how to submit jobs, where working directories are
+located, and various other configuration information. More 
+information on sites.xml can be found in the Swift User's Guide.
 
+The first step is to paste the text below into a file named sites.xml.
+
 -----
 include::../../tests/providers/PADS/coasters/sites.template.xml[]
 -----
 
-Create a directory called swiftwork. Modify _WORK_ in sites.xml
+This file will require just a few customizations. First, create a 
+directory called swiftwork. Modify \_WORK\_ in sites.xml
 to point to this new directory. For example
 -----
 <workdirectory>/home/myhome/swiftwork</workdirectory>
 -----
 
-Next, paste the following example into a file called tc.data
+Creating tc.data
+++++++++++++++++
+The tc.data configuration file gives information about the applications
+that will be called by Swift. More information about the format
+of tc.data can be found in the Swift User's guide.
 
+Paste the following example into a file named tc.data
+
 -----
 include::../../tests/providers/PADS/coasters/tc.template.data[]
 -----
 
-Copy the catsn Swift script and input text file into your current directory
+Copy a Swift Script
++++++++++++++++++++
+
+Within the Swift directory is an examples directory which contains
+several introductory Swift scripts. The example we will use in this
+section is called catsn.swift. Copy this script to the same directory
+that your sites.xml and tc.data files are located.
+
 -----
 $ cp ~/swift-0.93/examples/misc/catsn.swift .
 $ cp ~/swift-0.93/examples/misc/data.txt .
 -----
 TIP: The location of your swift directory may vary depending on how you installed it. Change this to the examples/misc directory of your installation as needed.
 
-And finally, run the script
+Run Swift
++++++++++
+
+Finally, run the script
 -----
 $ swift -sites.file sites.xml -tc.file tc.data catsn.swift
 -----
 
 You should see 10 new text files get created, named catsn*.out. If
-you see these files, then you have succesfully run Swift on PADS!
+you see these files, then you have succesfully run Swift on PADS! 
 
 TIP: Make sure your default project is defined. Read on for more information.
 
+Read on for more detailed information about running Swift on PADS.
+
 Requesting Access
 ~~~~~~~~~~~~~~~~~
 If you do not already have a Computation Institute account, you can request
@@ -90,20 +122,17 @@
 @default
 -----
 
-What You Need To Know Before Running Swift
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Before you can create a Swift configuration file, there are some things
-you will need to know.
-
 Swift Work Directory
 ^^^^^^^^^^^^^^^^^^^^
 The Swift work directory is a directory which Swift uses for processing work.
-This directory needs to be writable. Common options for this are:
+This directory needs to be writable and available to all worker nodes on
+a shared filesystem. 
 
+.Examples
 -----
 /home/username/swiftwork
 /home/username/work
-/tmp
+/autonfs/gpfs-pads/projects/CI-CCR000013/myusername
 -----
 
 Which project(s) are you a member of?
@@ -171,9 +200,11 @@
 include::../../tests/providers/PADS/coasters/sites.template.xml[]
 -----
 
-Before you can use this configuration file, you will need to modify _WORK_ to a directory writable by you, 
-and have your default project defined. Copy this template, replace _WORK_, and then save as sites.xml.
+Before you can use this configuration file, you will need to modify \_WORK\_ to a directory writable by you, 
+and have your default project defined. Copy this template, replace \_WORK\_, and then save as sites.xml.
 
+If you wanted to use a different queue, replace "fast" with the desired queue name.
+
 Manually Editing tc.data
 ~~~~~~~~~~~~~~~~~~~~~~~~
 Below is the tc.data file used by Swift's test suite for running on PADS.
@@ -186,12 +217,15 @@
 
 Catsn.swift
 ~~~~~~~~~~~
-The swift script we will run is called catsn.swift. It simply cats a file and saves the result. This is a nice simple test to ensure jobs are running correctly. Create a file called data.txt which contains some simple input - a "hello world" will do the trick.
+The swift script we will run is called catsn.swift. It simply cats a file and saves the result. This is 
+a nice simple test to ensure jobs are running correctly. Create a file called data.txt which contains 
+some simple input - a "hello world" will do the trick.
 
 -----
 include::../../examples/misc/catsn.swift[]
 -----
 
+
 Running Swift
 ~~~~~~~~~~~~~
 Now that everything is in place, run Swift with the following command: