Table of Contents:

1. Introduction
2. Installation
   • 2.1 Software:
   • 2.2 Setting up NPIB:
3. Set up "public_html" for JWave and NPIB"
   • 3.1 Download and setup NPIB and JWave directories:
   • 3.2 NPIB setup: execute legacy code locally and remotely:
     • 3.2.1 Set up legacy code to execute on "local_" (Web-server) computer:
     • 3.2.2 Set up legacy code to execute on "remote_" site computers:
4. "How-to" NPIB-form tutorials:
   • 4.1 How-to-create NPIB-forms:
   • 4.2 How-to-use NPIB-forms:
5. Frequently asked questions:
6. Known bugs:

3.1 Download and set up NPIB and JWave directories

3.1.1 Download the STARTUP_public_html.tar file
           Downloaded this file from http://www.jwave.vt.edu/npib/STARTUP_public_html/
           and put the STARTUP_public_html.tar in the user's home directory.

3.1.2 Extract the contents of the STARTUP_public_html.tar file

% tar xvf STARTUP_public_html.tar

!!!! CAUTION !!!! unpacking this tar file will over-write an existing public_html directory in the user's home directory.

3.1.3 Modify template files to execute NPIB and JWave applications

           Go into the newly created public_html directory

% cd public_html

Notice that there are three directories: crcd/, jwave/, and npib/.

In the crcd/ directory there is a bin/ directory where the user must archive all compiled PV-Wave/JWave *.cpr files. This new directory must be added to the JWave manager path by the server system administrator. The crcd/ directory also contains the lectures/, assignments/, and modules/ set up by the user.

In the jwave/ directory there is a classes/ directory. In this directory there are three JWave *.jar files that were created by the JWave manager. To avoid copying these three *.jar files everytime JWave is reconfigured, the README file in this directory show how to make symbolic links to these files.

In the npib/ directory there are three directories: 1) PUT_contents_IN_home-bin/, 2) local_APP/, 3) remote_APP/, and two files: 1) form.jar, 2) npib.commands. The form.jar file is the same form.jar file located in the codebase file directory "server"/npib. The npib.commands file contains one line for each application, which can be set up to execute either as a local_APP or as a remote_APP application.

CONTENTS of npib.commands: ------------------------------------ 

local_APP local /export/home/USER_NAME/public_html/npib/local_APP/local_APP.sh
remote_APP remote /export/home/USER_NAME/public_html/npib/remote_APP/remote_APP.npib

Setting up local_APP or remote_APP applications is described in sections 3.2.1 and 3.2.2 respectively.

           The PUT_contents_IN_home-bin/ directory contains a script file named "form"
           which links the user to the form.jar file. Using this script file the user does not
           have to define the PATH and CLASSPATH to the form.jar file.

CONTENTS of form: ---------------------------------------------

#!/bin/sh
java -cp /usr/local/java2/lib:$HOME/public_html/npib/form.jar:. \
form.FormLoader $ 

CONTENTS of npib.commands: ------------------------------------ 

local_APP local /export/home/USER_NAME/public_html/npib/local_APP/local_APP.sh
remote_APP remote /export/home/USER_NAME/public_html/npib/remote_APP/remote_APP.npib

3.2.1 Setting up legacy code on "local_" (Web-server) computer.

The local_APP directory contains a single shell script file, local_APP.sh (see below), and a local_APP_.d directory that contains all files for execution on the local (Web-server) computer.

The local_APP.sh file first transfers the contents of the local_APP_.d directory into a "Web-accessible working directory", which is indicated in the script file as a period, ".", at the end of the first and second line of this script file.

CONTENTS of local_APP.sh: -------------------------------------
#!/bin/csh
#-------------------- local_APP.sh  -------------------
cp /export/home/USER-NAME/public_html/npib/local_APP/local_APP_.d/* .
cd .
./APP.x
source /usr/local/vni/wave/bin/wvsetup
#echo env: > temp
#/bin/env >> temp 
#echo ' ' >> temp
#echo set: >> temp
#set >> temp
wave create_prop1 > & prop1_foobar
rm prop1_foobar 
rm *.x
rm *.byt
rm *legend.jpg
exit 0

The script file moves into the "Web-accessible working directory" ("cd .") where it then sets up paths and executes the legacy simulation code. After execution of the legacy code the local_APP.sh script also creates images and/or animations of simulation results.

NPIB automatically creates a "Web-accessible working directory" which NPIB labels as outroot / <researcher_output-directory_name> / local_APP / "unique-date-time". The local_APP.sh script file simply refers to this directory as a period, ".". All executions take place in this directroy and can be periodically viewed by the researcher who created the local_APP. Because this outroot directory is web accessible it can also be observed by others ("research collaborators or students"). This feature is particularly useful if the researcher/collaborators/students need to view preliminary legacy simulation results of a batch job that could take several days to execute. If observation of preliminary results suggests errors, the orginiating researcher can "kill" the PID-number associated with the job that was submitted. Inside the archived directory "unique-date-time" the researcher/collaborators/students can make modifications and corrections and resubmit the job using the npib.html file archived within the "Web-accessible working directory".

The syntax for creating a local_APP requires:

1. insert "local" in the ~user-name/public_html/npib/npib.commands file described in section 3.1.3.
   This file sets up directories where files are to be executed locally.
2. the same local_APP directory name must appear consistently in four places:
   • two places on each line in the user's npib.commands file
     where the local_APP directory name is used.
   • one place in a line of local_APP.sh that copies files from local_APP_.d to "."
   • one place in "." => outroot/<researcher_output-direcotry-name>/local_APP/"unique-date-time"

Although a password setup is required when creating the npib.html file which uses the form editor, all local jobs can be executed without password access.

3.2.2 Setting up legacy code to run on "remote_" site computers

The remote_APP/ directory contains two NPIB files: 1) remote_copyAPP.sh and 2) remote_APP.npib, and one directory remote_APP_.d that contains all files for execution.

The remote_copyAPP.sh copies the contents of the remote_APP_.d directory into a "Web-accessible working directory" denoted in the shell script as a period "." at the end of the line. NPIB automatically creates a "Web-accessible working directory" outroot / <researcher_output-directory_name> / remote_APP / "unique-date-time" where all executions take place and can be periodically viewed by the researcher who created the remote_APP but also by the others ("researcher collaborators/students").

CONTENTS of remote_copyAPP.sh: -----------------------------------

#!/bin/sh
cp /export/home/USER_NAME/public_html/npib/remote_APP/remote_APP_.d/* .

The NPIB file, remote_APP.npib, contains the sequence of commands to distribute the execution of this application on the local ("lrun") and remote ("srun") computers.

CONTENTS of remote_APP.npib: -------------------------------------

lrun /export/home/USER_NAME/public_html/npib/remote_APP/remote_copyAPP.sh
sput $APP_remote
srun $APP_remote ./remoteAPP.sh
sget $APP_remote 
lrun ./localAPP.sh

Commands in the remote_APP.npib file need more explanation, where $APP_remote is defined in the NPIB Edit - Passwords "Working Window" and used here like an environmental variable with information about the remote computer.

lrun - run this command or shell script localy

sput - ssh put files in a directory (date-time) on the remote computer.

srun - ssh run on the remoteAPP.sh script in this directory.

sget or sgetd - ssh get or ssh get then delete files from this directory.

The remote_APP_.d directory contains all files for execution on remote computer. NOTE: executable files stored in the remote_APP_.d directory must be compiled on the remote computer, unless the user wants to include an extra compile command in the remoteAPP.sh script which is located in the remote_APP_.d directory. The two *.sh script files: remoteAPP.sh and localAPP.sh are shell script files that control the sequence of commands executed on the remote and local computers respectively:

#!/bin/csh
#------------------ remoteAPP.sh --------------------
APP.x
exit 0

#!/bin/csh
#-------------------- localAPP.sh  -------------------
source /usr/local/vni/wave/bin/wvsetup
#echo env: > temp
#/bin/env >> temp 
#echo ' ' >> temp
#echo set: >> temp
#set >> temp
wave create_prop1 > & prop1_foobar
rm prop1_foobar 
rm *.x
rm *.byt
rm *legend.jpg
exit 0

The other files in the remote_APP_.d directory are templates with helpful hints which can be used to avoid various pitfalls and other problems we encountered in creating PV-Wave modules.

The syntax for creating a remote_APP requires:

1. insert "remote" in the ~user-name/public_html/npib/npib.commands file described in section 3.1.3.
   This file sets up directories where files are to be executed locally and remotely.
2. the same remote_APP directory name must appear consistently in four places:
   • two places on each line in the user's npib.commands file
     where the remote_APP directory name is used.
   • one place in a line of the remote_copyAPP.sh that copies files from remote_APP_.d to "."
   • one place in "." => outroot/<researcher_output-direcotry-name>/remote_APP/"unique-date-time"