Guide for TACC/XSEDE Researchers

To submit jobs as a researcher, you could either use the job submission interface available on this website, or you could submit the jobs after logging in to the Stampede2/Lonestar5 systems at TACC. This user-guide contains information on:

Steps for Submitting Jobs from the Website
Example: Step-by-Step Instructions for Running the OpenSees Application from the Job Submission Page
Steps to Submit Jobs Directly Through Stampede2/Lonestar5
Example: Step-by-Step Instructions for Running the OpenSees Application on BOINC Through Stampede2/Lonestar5
Video Demonstration of the BOINC@TACC Infrastructure

1. Steps for Submitting Jobs from the Website

  1. For submitting jobs through this website, you should first run the registration script from the Stampede2/Lonestar5 systems at least once
    • Login to Stampede2 or Lonestar5 using your TACC portal credentials
    • Create a directory named "boinc" ( mkdir boinc) and switch to this directory ( cd boinc)
    • Copy the registration script by running the following command:
      wget https://raw.githubusercontent.com/ritua2/BOINCatTACC/master/stampede2-backend/register-boinc.sh
    • Add execute permissions on the script:
      chmod +x register-boinc.sh
    • Run the script for registration (register-boinc.sh):
      ./register-boinc.sh
  2. Log in to this website as a Researcher using your TACC portal credentials: https://boinc.tacc.utexas.edu/login_as_a_researcher_form.php
  3. Go to the Job Submission page: https://boinc.tacc.utexas.edu/job_submission.php
  4. For running applications through BOINC@TACC, you will need to select one of the following options:
    • Use the Docker image of an application supported by BOINC@TACC : If you are using the Docker image provided by BOINC@TACC, keep the radio-button for the "List of BOINC@TACC Docker images" selected and select the desired Docker image
    • Use a Docker image of the application supported by you or someone else on Docker Hub : If the Docker image is on Docker Hub but not supported by BOINC@TACC, click the radio button for Docker Hub. Type in the name of the desired Docker image as it appears on Docker Hub (not the URL). Then select the "Check if it exists on Docker hub" button and the BOINC@TACC system will check if the Docker image exists or not.
    • If your code is not containerized yet, you can upload the code and the steps to compile it through the job submission page. A Docker image will be created automatically for you.
  5. Type in the list of commands necessary to run the file. Separate each command with a “semi-colon” or remember to hit enter after each line of command
  6. Select whether the input files will be uploaded as a compressed TAR file (*.tgz) or as a ZIP file (*.zip). Then browse to the desired *.tgz or *.zip file on your computer using the "Browse" button. Then select the file, and click the "Submit the Job" button.
    Congrats, your job is submitted!
  7. If your job got submitted successfully, you will see it listed under the "Job History" page: https://boinc.tacc.utexas.edu/job_history.php
  8. Once your job has finished executing successfully, you will receive an email notification with the subject "BOINC job completed", and your job results will either be attached to the email as a *.tgz file or a link to download the results will also be provided
  9. Note : If your job was submitted successfully, and it ran on the client but there was a run-time error caused due to wrong parameters or wrong commands, you may still get an email with job completed with "success" but there will be no results.

2. Example: Step-by-Step Instructions for Running the OpenSees Application from the Job Submission Page

  1. Make sure you are a registered BOINC@TACC user and have completed the following steps:
    • Login to Stampede2 or Lonestar5 using your TACC portal credentials
    • Create a directory named "boinc" (mkdir boinc) and switch to this directory (cd boinc)
    • Copy the registration script by running the following command:
      wget https://raw.githubusercontent.com/ritua2/BOINCatTACC/master/stampede2-backend/register-boinc.sh
    • Add execute permissions on the script:
      chmod +x register-boinc.sh
    • Run the script for registration (register-boinc.sh):
      ./register-boinc.sh
  2. Create a directory named "data" on your computer and copy the sample input files for running OpenSees in this directory, example:
    mkdir data
    cd data
    curl -O http://opensees.berkeley.edu/wiki/images/a/a1/ElasticFrame.tcl
    curl -O http://opensees.berkeley.edu/wiki/images/3/3d/MomentCurvature.tcl
    cd ..
  3. Create a *.zip or a *.tgz file containing the contents of the data directory, example:
    tar -cvzf data.tgz data
  4. Login to the BOINC@TACC website using your TACC credentials and click on "Job Submission" tab
  5. By default, the radio-button for "List of docker images maintained by BOINC@TACC" will be selected. Keep this as-is, and click on the drop-down list to select "OpenSees"
  6. In the text-box for the list of commands, enter:
    OpenSees < ./data/MomentCurvature.tcl ;
    OpenSees < ./data/ElasticFrame.tcl;
  7. Upload the data.zip or data.tgz file created in step # 3
  8. Click on "Submit the job" button
  9. If your job got submitted successfully, you will see it listed under the "Job History" page: https://boinc.tacc.utexas.edu/job_history.php
  10. Once your job has finished executing successfully, you will receive an email notification with the subject "BOINC job completed", and your job results will either be attached to the email as a *.tgz file or a link to download the results will also be provided

    Note: If your job was submitted successfully, and it ran on the client but there was a run-time error caused due to wrong parameters or wrong commands, you may still get an email with job completed with "success" but there will be no results

3. Steps to Submit Jobs Directly Through Stampede2/Lonestar5

In preparation of submitting jobs from Stampede2/Lonestar5, you will need to do the following:
  • Create a directory named "data" on your computer and copy the sample input files for running OpenSees in this directory
  • You would need to respond to the questions prompted by script, and if your job meets the constraints for running through BOINC@TACC, it will be submitted to the BOINC server, else, a SLURM job script will be generated for you so that you can run the job on Stampede2/Lonestar5.

    Please note: you will not be able to login to Stampede2/Lonestar5 if you do not already have an existing project allocation on TACC resources. Please visit the following website to learn more about the process of requesting allocation on TACC resources: https://portal.tacc.utexas.edu/

4. Example: Step-by-Step Instructions for Running the OpenSees Application on BOINC Through Stampede2/Lonestar5

  • Obtain the necessary files
curl -O https://raw.githubusercontent.com/ritua2/BOINCatTACC/master/stampede2-backend/S2-test-files/MC.tcl
	
  • Run advance-submit.sh :
curl -O https://raw.githubusercontent.com/ritua2/BOINCatTACC/master/stampede2-backend/advance-submit.sh
chmod +x advance-submit.sh
./advance-submit.sh
  • Provide your email when requested

  • Select 1 for allowed options when prompted

  • Select 9 for applications when prompted

  • Continue with the following instructions to run an OpenSees input file

    • Provide the following file:

        MC.tcl
      
    • No directories must be provided (enter to skip)

    • Provide the following command:

        OpenSees < MC.tcl
      

5. Video Demonstration of the BOINC@TACC Infrastructure