Desktop Condor (DTCondor) User Guide

Contents

Introduction

Installation

Starting DTCondor and Logging In

Introduction to Job Templates

Creating and Editing Job Templates

Submitting Jobs

Monitoring Progress

Using DTCondor from off-campus

Walk-though example - submitting multiple MATLAB jobs

Walk-though example - submitting a single MATLAB M-file job

Walk-though example - submitting multiple R jobs

Introduction

Desktop Condor (DTCondor) provides an easy-to-use graphical interface which considerably simplifies the processs of submitting jobs to the Research IT HTCondor pool. By using DTCondor, there is no longer any need to remember obscure UNIX commands or to transfer files to and from the HTCondor server manually. DTCondor is therefore ideal if you are new to HTCondor, dislike the arcane UNIX command line environment, or are an infrequent and fairly light HTCondor user.

The DTCondor graphical interface (DTCondor for short) has been tested extensively (but not exhaustively !) on 32 and 64-bit versions of the Windows 10 operating system that forms the basis of IT Services' Managed Windows Service (MWS). It may work on other versions of Windows but unfortunately there is no support for Macs or for Linux-based systems.

DTCondor works best when used on the University campus network but off-campus use is possible via the Virtual Private Network (VPN). See the section of Using DTCondor from off-campus for details. If you would like to use DTCondor, please contact the HTCondor administrator (Dr Ian C. Smith, i.c.smith@liverpool.ac.uk ) in the first instance, as it will be necessary to set up the server side of things first. You will of course also need an account on the HTCondor service (for details see the HTCondor registration web page).

This document provides an introduction to DTCondor and describes in detail how to use it for running applications based on MATLAB or R. Although it is not especially complicated, there is a lot of information presented here and it may be best to have a quick read through first and then try the walk-through examples before reading the guide again in depth. The examples should help familiarise yourself with DTCondor and can act as a starting point for your own applications. Hopefully the documentation should cover most things but if anything isn't clear or if you have any suggestions for improvements, please contact the HTCondor administrator as this will help to improve the documentation.

Installation

The DTCondor software is bundled into a Microsoft Installer (MSI) package which can be downloaded by clicking on the button below.

Once you have downloaded the package, double-click on the downloaded file (dtcondor_client.msi) and the installer setup wizard will start. You can just repeatedly click the Next button to accept the defaults and DTCondor will install correctly. The installation folder should not be changed, otherwise DTCondor will not work. For 64-bit operating systems, the DTCondor files will be installed in:

C:\Program Files (x86)\ARC\DTCondor

and for the (increasingly rare) 32-bit systems in:

C:\Program Files\ARC\DTCondor

A DTCondor icon (see left) should also appear on your desktop after the installer finishes and can be used to start DTCondor. DTCondor can also be run from the Start menu via:

Start | (All Programs |)  DTCondor | DTCondor 

Note that you must have administrator rights on your computer for DTCondor to install correctly and therefore DTCondor cannot be installed on teaching and learning centre machines.

Starting DTCondor and Logging In

To start DTCondor, either click on the desktop icon or use the Start menu as follows:

Start | ( All Programs | ) DTCondor | DTCondor

After a short while, the DTCondor Login window should appear as shown below.



[NOTE: throughout this guide "condoruser" should appear as your own username when you actually come to use DTCondor].

Your username should already be filled in but if it is this incorrect, enter your correct HTCondor username (this will usually be the same as your MWS/e-mail username), then enter your normal MWS/e-mail password and click the Continue button. If you are unable to login, please contact the HTCondor administrator for help.

After you have successfully logged in, the DTCondor Login window should disappear to be replaced by two other windows, namely the DTCondor Main Menu window and the Monitor window (it may take some time for the latter to appear). We'll ignore the Monitor for now (its purpose will become apparent later on) and just concentrate on the Main Menu shown below:

The Main Menu contains a list of actions which you can perform with DTCondor. Usually either the second or third items are needed i.e. "create or edit a job template" or "submit jobs using an existing template". The "build a stand-alone MATLAB executable" no longer works and if you wish to run MATLAB applications it will be necessary to create a stand-alone executable using the latest version of MATLAB on your own PC/laptop - see the MATLAB applications guide for details.

Introduction to Job Templates

HTCondor provides a very powerful resource for speeding up processing but it will of course need to be told precisely what it is you are trying to achieve. This is where job templates come in - they tell HTCondor exactly what it is you want HTCondor to do in a very concise way. A moments pause for thought should convince you that this is essentially the minimum information that is required:

• what application needs to be run (in other words, what is the executable file or script) ?
• how many times does the application need to be run (i.e. how many jobs are required) ?
• what input data needs to be processed (alternatively, what are the input files) ?

The last point can be sub-divided into:

• what input data is the same for every job (this will be held in the "common input files") ?
• what input data is different for each job (this will be held in the "indexed input files") ?

In a Monte Carlo or other stochastic analysis application, for example, the indexed input files may contain different random number generator seeds. In a pharmaceutical field trial, the indexed input files might contain data from different patients.

There is one other optional piece of information to supply:

• what output data should the application produce (i.e. what will the output files be) ?

This turns out to be very useful in catching errors and so it's a good idea to always provide it if possible.

In the past, all of the above information would need to be supplied to HTCondor by typing it into a text file. This was both cumbersome and error-prone and therefore DTCondor allows users to enter the information via a graphical interface. [If you have used the HTCondor service previously, then it's worth pointing out that job templates are essentially the same as simplified submit description files but are hidden and do not (and should not) need to be edited "by hand"].

After a job template has been created, it is straightforward to submit large numbers of jobs and make small changes to the analyses/simulations as needed. Going back to the earlier examples; in the Monte Carlo case, a different model could be used just by changing the underlying code and running it again with the same random number seeds (for MATLAB, the executable would also need to rebuilt). This would provide a direct comparison between the two sets of results. In the pharmaceutical example, a new set of field trial data could be processed just by replacing the input files.

Creating and Editing Job Templates

To create a new job template, first open the Job Template Editor by selecting the Main Menu option called "create or edit a job template". The following window should appear:



The Job Type box is used to select which kind of application is to be run. The "MATLAB M-file" option allows you to run a single job based on one or more M-files (rather than a stand-alone executable) and is useful for testing. The "Generic MWS job" option is provided for backwards compatibility and is not really aimed at new users (if you do need to run applications that are not based on MATLAB or R, please contact the HTCondor Administrator for advice on how to proceed). The "MATLAB stand-alone executable" option, as it suggests, can be used to run MATLAB applications using executables built earler using DTCondor. Finally the "R script" option can be used for jobs employing one or more R scripts.

Having selected the job type, the next step is to specify the executable or script that is to be run as follows:

MATLAB M-file jobs:

Type the name of the main M-file in the "Executable, M-file or R script" text box.

Stand-alone MATLAB applications:

Enter the name of the executable that was built previously (see the MATLAB applications guide for details).

R applications:

Enter the name of the main R script (i.e. the script that calls any other R scripts) - this will usually have a .R extension.

Generic Applications:

The executable can be either a DOS batch (.bat) file or a binary executable (.exe file). In each case, only the name of the file is needed - not the complete path to it.

The next step is to fill in the details of the input and output files in the text boxes below the executable option. Filenames can be entered one per line and (if there are several of them) multiple filenames can be entered in the same box separated by one or more spaces. There is no need to put in the actual path to the file - just the filename itself. The actual files to be used will be selected when you come to submit the jobs.

The "Common input files" boxes can be used to specify which files are the same for all of the jobs and may only be needed for a few applications. Common input files can be useful if (for example) you have look-up data which is needed by all of the jobs and which is the same for each. In the case of R applications, all of the other R scripts apart the main one are counted as common input files and need to be given here. For a "MATLAB M-file" job, enter the names of the "Other M-files" in the "Common input files" text boxes as these are counted as input files.

The "Indexed input files" lie at the the heart of HTCondor's operation and determine which input files are to be used by each job. They perform the same role with both R and MATLAB applications but we'll start with a MATLAB example. To make this clearer, imagine that we wish to run just ten MATLAB-based jobs and that each reads its input from the file input.mat. Here only one indexed input filename would need to be given: input.mat. The actual files would be numbered (or indexed) as below:

input0.mat
input1.mat
input2.mat
    .
    .
    .
input9.mat

(note that the indices start at 0 not 1). There is no need to specify the actual index value in the text box or in the underlying MATLAB code as all of the index manipulation will be done for you behind the scenes.

Say each job which reads input.mat does some processing and writes the results to output.mat. In this case, the indexed output files would just be specified as output.mat and the actual output files produced would be:

output0.mat
output1.mat
output2.mat
    .
    .
    . 
output9.mat

Again there is no need to worry about the index value either in the template or in your code - everything will be taken care of automatically in the background. Indexed output files are optional but their use is recommended.

There is nothing special about the filenames used here. Equally we might have an R application that reads data from say field_data.dat and writes the results to results.dat. Here the indexed input files would be just field_data.dat and the indexed output files would be just results.dat whilst the actual files would be as below:

  input file         corresponding output file

field_data0.dat            results0.dat
field_data1.dat            results1.dat
field_data2.dat            results2.dat
      .                        .
      .                        .
      .                        .
field_data9.dat            results9.dat

The reason that specifying the output files is so important is that it allows HTCondor to flag an error if any of the files are missing after the jobs have run. Put another way, HTCondor can only determine if something has gone wrong if it knows what outputs are expected. For the very simple examples given below, it is quite easy to spot if things have gone wrong but when submitting very large batches of jobs (we've seen 40,000 jobs in a few cases) it can be tedious to say the least to have to sift through all of the output files to confirm that they are all in fact there.

The "Total number of jobs" option should be fairly self explanatory and determines the amount of times the executable will be run by HTCondor with different input data. The number of jobs must tally with the actual number of indexed input files used.

When all of the information has been entered, the template can be saved by clicking on the Save Template button. You can save the template under any name you like however filenames that include spaces should be avoided and it is safest to stick to just letters and numbers with underscores or hyphens to make things more readable. The default file extension for DeskTop Condor templates is .dtc (.mws for generic MWS job templates) and to avoid confusion it is best to keep to this. The default folder for template files is:

C:\Users\condoruser\Desktop\DTCondor\templates

and by saving templates there, they will be easier to locate in future; however you can select any folder you wish.

Once a template has been saved it can then be used to submit (potentially very large) batches of Condor jobs easily. You can also make small changes to the template to run different sets of analyses or simulations. To edit a template, open the Job Template Editor window and click on the Load button. By default, the following folder will open:

C:\Users\condoruser\Desktop\DTCondor\templates

and all files with a .dtc extension will be shown (for generic MWS jobs, switch the filter to .mws to see the relevant templates). You can select one of these and the information contained in it will be displayed in the editor window. You can also load templates from another location by navigating to them. After all of the changes have been made, click on the Save Template button to save the file. The template can be saved under a different filename if you want to keep the old template.

Once you have finished using the Job Template Editor, click the Close button to go back to the Main Menu.

Submitting jobs

If a job template has been created, a batch of Condor jobs can then be submitted by selecting the "submit jobs using an existing template" option in the Main Menu. The following Job Submission window should then appear:-

The first step in submitting jobs is to load a job template file. To do this, click the Browse button to the left of the Job Template File text box. You can then browse to the required template file, select it, and click the Open button to load the template. The default folder for template files is:

C:\Users\condoruser\Desktop\DTCondor\templates

but you can browse to other folders if the required template has been saved in a different location. Also, by default, only standard template files (those with a .dtc extension) are shown. If you are using a generic job template file, then the file filter will need to be changed to *.mws in order to see those files.

After a job template has been loaded some additional information should appear in the window; namely the executable or script file, the common input file(s) (if any), the indexed input files and the indexed output files (if any). An example is shown below where the various files have been circled.



The total number of jobs will also be shown in green near the bottom of the window.

Before submitting the jobs, you will first need to select the actual executable or script to be run. To do this, browse to the file by clicking the Browse button under either Executable file, R Script or M-file (depending on the job type), then select the file and click Open (you can also type the full path to it directly into the text box).

If all of the input files have been placed in the default folders, then all that is needed now to submit the jobs is to click on the Submit Jobs button. The default folder for common input files is:

C:\Users\condoruser\Desktop\DTCondor\common_input

and for the indexed input files is:

C:\Users\condoruser\Desktop\DTCondor\indexed_input

If the files are located elsewhere, either change the folder displayed in the text boxes or (much easier) browse to the folders using the Browse button (if there are no common input files then the folder is irrelevant so don't worry about it).

Once the correct folders have been selected, you can submit the jobs by clicking the Submit Jobs button. DTCondor will do a quick check to see that all of the files needed are in fact present before submitting the jobs to the server and will issue an error message if any are missing. It will then bundle the files into a ZIP format file and upload it to the HTCondor server for submission. To check that the jobs have actually been submitted properly (and to see how they are progressing) we need to move to the previously sidelined DTCondor Monitor window which is the subject of the next section. For now, you can close the DTCondor Job Submission window to get back to the Main Menu.

Monitoring Progress

You can check how your HTCondor jobs are progressing using the DTCondor Monitor window. This will open once you have successfully logged-in as shown below.



The information is not refreshed continuously (to avoid overloading the server) but by clicking on the Update Messages button, the latest information will be retrieved from the server and displayed.

If this is the first time you have used DTCondor or if the server has been recently restarted you should get this message:

---

The DTCondor server is running and is ready to accept jobs.

---

It's worth trying this now just to check everything is working.

Immediately after submitting some jobs you should see the following message:

---

All of the jobs have now been submitted and none have completed so far.
You can track their progress via the HTCondor website at this address:

               http:\\condor.liv.ac.uk
               http:\\condor.liv.ac.uk\usage\current_use.php

---

A similar message should appear if you have just submitted a job which will build a MATLAB stand-alone executable viz:

---

A matlab_build job has been submitted to the pool

You can track its progress via the HTCondor website at this address:

               http:\\condor.liv.ac.uk
               http:\\condor.liv.ac.uk\usage\current_use.php 

---

Once jobs start to run and begin to finish, DTCondor will indicate how many have completed so far, for example:

---

2 of 10 jobs have completed so far
You can track their progress via the HTCondor website at this address:

               http:\\condor.liv.ac.uk
               http:\\condor.liv.ac.uk\usage\current_use.php

---

You can leave the DTCondor Monitor running on your PC and check periodically how jobs are progressing or use the information provided on the HTCondor website. The address for this is:

http://condor.liv.ac.uk

and detailed information is available by following the "Current Use" link, namely:

http://condor.liv.ac.uk/usage/current_use.php

(To see your own jobs, enter your username in the text box and click on the Submit button). DTCondor can also be closed on the PC and started again later without affecting any of the jobs.

As well as giving more in-depth information than DTCondor, the website has the advantage that it can be used anywhere (including off-campus) without the need for DTCondor to be installed. It is therefore ideal for checking quickly how your jobs are faring whilst away from the office.

Once all of the jobs have completed, you should receive this message.

---

All of the jobs have now completed.

You can now retrieve the output from 

/condor_data/DTCondor/condoruser/output/

To submit a new job, upload the files to the server in:

/condor_data/DTCondor/condoruser/

---

The output files can then be downloaded by clicking the Download Output button. By default, the output files will be saved to this folder:

c:\users\condoruser\downloads

If you would like to save them to a different folder just use the Browse button to select the desired folder or type the full pathname into the text box. The output files will be compressed into a ZIP file which can be extracted later (right-click on the file in Windows Explorer and select Extract All...).

You can also download the partial results at any time whilst jobs are running by clicking the Download Output button. This can be useful as a check that everything is working correctly. In this case, all of the output files will be downloaded including any log files etc.

If for any reason you wish to terminate all of the jobs at any stage, click on the Remove Jobs Button. You should then see this message after clicking the Update Messages button:

---

Removing HTCondor jobs - this may take a while.

---

If the HTCondor server is busy, it may take some time for all jobs to be removed but eventually by clicking the Update Messages button, you should get this message:

---

All jobs have been removed.

You can now retrieve the output (if any) from 

/condor_data/DTCondor/condoruser/output/

To submit a new job, upload the files to the server in:

/condor_data/DTCondor/condoruser/output/

---

If the jobs refuse to terminate, please contact the HTCondor administrator.

You can safely remove jobs at any time without destroying the results obtained so far which can always be downloaded using the Download Output button. In fact the output files from a given batch of jobs will remain on the server until a new batch of jobs is submitted.

Using DTCondor from off-campus

It is possible to submit jobs and retrieve their output files from off-campus using DTCondor however, because direct access to the HTCondor server is blocked to the outside world, it will first be necessary to establish a connection using the Virtual Private Network. You can find details of how to do this on the IT Services page on Virtual Private Network (VPN). If you have difficulties using DTCondor it still possible to use the command line interface and retrieve files using secure FTP. Details on this can be found on the remote access to HTCondor web page. Note that submitting HTCondor jobs and retrieving the results can require the transfer of large amounts of data so a fast reliable connection will be needed.

Walk-through example - submitting multiple MATLAB jobs

This example shows how to submit multiple MATLAB jobs using a stand-alone executable built earlier. Again the application is exactly the same as that described in the web page on MATLAB Applications and the executable just reads two input matrices, multiplies them together and writes the results to an output file.

The input files will have the form input<index>.mat and the corresponding output files output<index>.mat. Note that the index does not need to be specified either in the MATLAB code or any of the templates as all of the index manipulation is done for you in the background. Similarly, there is nothing special about the filenames chosen and any filename of the form <basename>.<extension> will suffice. However, spaces should not be used and it is best to stick to letters and numbers (and possibly hyphens or underscores used to make things more readable).

The steps are as follows:

1. To begin with, all of the required files will need to be put in place. For this simple example we will just submit 10 jobs and the input files will be:

   input0.mat
   input1.mat
   input2.mat
       .
       .
       .
   input9.mat
   

   Some sample input files have been bundled into a ZIP file and can be dowloaded using this link input.zip (right-click on the link and select Save Link As...). Once the ZIP file has been downloaded, right-click on it in Windows Explorer and select Extract All... To make things easier later, extract the files to this folder:

   C:\Users\condoruser\Desktop\DTCondor\indexed_input
   

   For the job template file, we'll use one prepared earlier which you can download from this link multiple.dtc. To simplify things it's easiest to save this to the default template folder i.e.:

   C:\Users\condoruser\Desktop\DTCondor\templates
   

   Only one other file is needed - the stand-alone executable product.exe. This should have already been built earlier and if you have not already done so, copy this to the default executable folder i.e.

   C:\Users\condoruser\Desktop\DTCondor\executable
   



2. If you haven't already started DTCondor, start it now using:

   Start | (All Programs |)  DTCondor | DTCondor 
   

   and login using your ordinary MWS username and password.


3. The next step is optional but nonetheless useful. To check that the job template is correct, select the "create or edit a job template" option in the Main Menu to open the Job Template Editor, then load the job template file (multiple.dtc). The information in the template file should be displayed as shown below:
   
   
   
   If any changes were needed, for example the number of jobs or input files, then this would be the place to make them. You can try this now by changing some of information and you should see that a message warning you that the template has not been saved appears at the bottom of the window. To make the changes permanent, you could then click the Save Template button to save them to a file. In this case, no changes are needed so just click Close to get back to the Main Menu.
   
   
4. The next step is to actually submit the jobs using the previously downloaded template file. To do this, select the "submit jobs using an existing job template" option in the Main Menu and click the Continue button. The Job Submission window should now open allowing you to load the job template file. Click the Browse button under the Job template file: text and select the previously downloaded template file (multiple.dtc). You should see that the information from the template (i.e. the executable and indexed input files) is now displayed in the window as shown below:
   
   
   
   
5. Once a template file has been loaded, the next step is to identify the actual files to be used with the jobs. Firstly, you will need to select the stand-alone executable. To do so click the Browse button under the Executable file text and select the previously built executable (product.exe). There are no common input files for this example so skip over that option to the Indexed input files folder option. If you have previously saved the input files (product0.mat ... product9.mat) to the default location i.e.

   C:\Users\condoruser\Desktop\DTCondor\indexed_input
   

   then there is no need to change anything but if they were saved to a different folder, this should now be selected by browsing to it using the Browse button below the Indexed input files folder: text.



6. The next step is to submit the jobs by clicking the Submit Jobs button. Progress information will be displayed at the bottom of the window and eventually, after the jobs have been successfully submitted, the appearance of the window should change to:
   
   
   
   Since the Job Submission window is no longer needed, it can be closed by clicking the Close button to return to Main Menu.
   
   
7. For the next few steps we need to turn our attention to monitoring the submitted jobs - so ensure that you can access the Job Monitor window (this should have appeared after you logged in with DTCondor). Progress information will be displayed in this window but it is not updated continuously. Instead the latest status messages are retrieved from the server by clicking the Update Messages button. If you are quick, then you may catch the jobs before any have started to run and the window will appear as below when the Update Messages button is clicked:
   
   
   
   By repeatedly clicking Update Messages, you should see that the jobs eventually start to run and, after a while, complete. For example here five of the ten jobs have completed.
   
   
   
   You can shut down DTCondor at anytime and start it again later without it affecting any of the submitted jobs. It is also possible to get detailed information on how your jobs are progressing by visiting to the HTCondor website (condor.liv.ac.uk) which is accessible from anywhere (even outside of the University network).



8. The length of time taken for all of the jobs to complete will depend how busy the HTCondor pool is and how many machines are available but generally it should be no longer than 10-20 minutes and eventually this information will be displayed:
   
   
   
   
9. The HTCondor server will automatically detect when all of the jobs have completed and will then bundle all of the output files into a ZIP file for ease of downloading. The ZIP file can be retrieved by clicking the Download Output button and will be saved to the default output folder which is:

   c:\users\condoruser\downloads
   

   If you wish to save the output to a different folder, then select it first by clicking the Browse button before the Download Output button. After the ZIP file has been successfully downloaded, the window should appear as follows:
   
   
   
   The individual output files can be extracted by right-clicking on the ZIP file (here output.mat.zip) in Windows Explorer and selecting Extract All....

Walk-through example - submitting a single MATLAB M-file job

This example shows how to submit a single MATLAB job using one or more M-files rather than a previously built stand-alone executable Again the application is exactly the same as that described in the web page on MATLAB Applications and the executable just reads two input matrices, multiplies them together and writes the results to an output file. There is one important change needed to the previous M-file code, namely the addition of a quit command. This is absolutely essential as without it the MATLAB interpreter will wait for ever for more commands and the job will never finish. The MATLAB code will now look like:

function product 

        load input.mat;
        C=A*B;
        save( 'output.mat', 'C' ); 
	quit;
end

The input files will still have to be indexed in form input<index>.mat (and the corresponding output files output<index>.mat) even though for this example there is only one input file input0.mat. Note that the index does not need to be specified either in the MATLAB code or any of the templates as all of the index manipulation is done for you in the background. Similarly, there is nothing special about the filenames chosen and any filename of the form <basename>.<extension> will suffice. However, spaces should not be used and it is best to stick to letters and numbers (and possibly hyphens or underscores used to make things more readable).

The steps are as follows:

1. To begin with, all of the required files will need to be put in place. For this simple example we are only going to submit a single job and the sole input file is input0.mat. You can download that from this link: input0.mat (right-click on the link and select Save Link As...). To make things easier later, save the file to this folder:

   C:\Users\condoruser\Desktop\DTCondor\indexed_input
   

   For the job template file, we'll use one prepared earlier which you can download from this link m_file.dtc. To simplify things it's easiest to save this to the default template folder i.e.:

   C:\Users\condoruser\Desktop\DTCondor\templates
   



2. If you haven't already started DTCondor, start it now using:

   Start | (All Programs |)  DTCondor | DTCondor 
   

   and login using your ordinary MWS username and password.


3. The next step is optional but nonetheless useful. To check that the job template is correct, select the "create or edit a job template" option in the Main Menu to open the Job Template Editor, then load the job template file (m_file.dtc). The information in the template file should be displayed as shown below:
   
   
   
   If any changes were needed, for example the input file, then this would be the place to make them. You can try this now by changing some of information and you should see that a message warning you that the template has not been saved appears at the bottom of the window. To make the changes permanent you could then click the Save Template button to save them to a file. In this case, no changes are needed so just click Close to get back to the Main Menu.
   
   
4. The next step is to actually submit the job using the previously downloaded template file. To do this, select the "submit jobs using an existing job template" option in the Main Menu and click the Continue button. The Job Submission window should now open allowing you to load the job template file. Click the Browse button under the Job template file: text and select the previously downloaded template file (m_file.dtc). You should see that the information from the template (i.e. the executable and indexed input files) is now displayed in the window as shown below:
   
   
   
   
5. Once a template file has been loaded, the next step is to identify the actual files to be used with the jobs. Firstly, you will need to select the main M-file. To do so click the Browse button under the M-file text and select the previously downloaded M-file (product.m). There are no common input files for this example so skip over that option to the Indexed input files folder option. If you have previously saved the input file (input0.mat) to the default location i.e.

   C:\Users\condoruser\Desktop\DTCondor\indexed_input
   

   then there is no need to change anything but it was saved to a different folder, this should now be selected by browsing to it using the Browse button below the Indexed input files folder: text.



6. The next step is to submit the job by clicking the Submit Jobs button. Progress information will be displayed at the bottom of the window and eventually, after the job has been successfully submitted, the appearance of the window should change to:
   
   
   
   Since the Job Submission window is no longer needed, it can be closed by clicking the Close button to return to Main Menu.
   
   
7. For the next few steps we need to turn our attention to monitoring the submitted job - so ensure that you can access the Job Monitor window (this should have appeared after you logged in with DTCondor). Progress information will be displayed in this window but it is not updated continuously. Instead the latest status messages are retrieved from the server by clicking the Update Messages button. If you are quick, then you may catch the job before is has started to run and the window will appear as below when the Update Messages button is clicked:
   
   
   
   By repeatedly clicking Update Messages, you should see that the job eventually starts to run and, after a while, complete.

   You can shut down DTCondor at anytime and start it again later without it affecting any of the submitted jobs. It is also possible to get detailed information on how your jobs are progressing by visiting to the HTCondor website (condor.liv.ac.uk) which is accessible from anywhere (even outside of the University network).




8. The length of time taken for the job to complete will depend how busy the Condor pool is and how many machines are available but generally it should be no longer than 10-20 minutes and eventually this information will be displayed:
   
   
   
   
9. The HTCondor server will automatically detect when all of the jobs have completed and will then bundle all of the output files into a ZIP file for ease of downloading. The ZIP file can be retrieved by clicking the Download Output button and will be saved to the default output folder which is:

   c:\users\condoruser\downloads
   

   If you wish to save the output to a different folder, then select it first by clicking the Browse button before the Download Output button. After the ZIP file has been successfully downloaded, the window should appear as follows:
   
   
   
   The individual output file can be extracted by right-clicking on the ZIP file (here output.mat.zip) in Windows Explorer and selecting Extract All....

Walk-through example - submitting multiple R jobs

This example shows how to submit R jobs using DTCondor. Although only a single R script file is employed here, the extension to applications that require multiple R scripts is straightforward. The application is exactly the same as that described in the web page on R Applications and it calculates a frequency distribution for a very large number of observations stored as R data files. The input files will have the form observations<index>.dat and the corresponding output files results<index>.mat. Note that the index does not need to be specified either in the R code or any of the templates as all of the index manipulation is done for you in the background. Similarly, there is nothing special about the filenames chosen and any filename of the form <basename>.<extension> will suffice. However, spaces should not be used and it is best to stick to letters and numbers (and possibly hyphens or underscores used to make things more readable).

The steps are as follows:

1. To begin with, all of the required files will need to be put in place. For this simple example we will just submit 10 jobs and the input files will be:

   observations0.mat
   observations1.mat
   observations2.mat
       .
       .
       .
   observations9.mat
   

   Some sample input files have been bundled into a ZIP file and can be dowloaded using this link observations.zip (right-click on the link and select Save Link As...). Once the ZIP file has been downloaded, right-click on it in Windows Explorer and select Extract All... To make things easier later, extract the files to this folder:

   C:\Users\condoruser\Desktop\DTCondor\indexed_input
   

   For the job template file, we'll use one prepared earlier which you can download from this link run_analysis.dtc. To simplify things, it's easiest to save this to the default template folder i.e.:

   C:\Users\condoruser\Desktop\DTCondor\templates
   

   Only one other file is needed - the R script which you can download from this link analyse.R. To make life easier later it best to download this to the default executable folder namely:

   C:\Users\condoruser\Desktop\DTCondor\executable
   



2. If you haven't already started DTCondor, start it now using:

   Start | (All Programs |)  DTCondor | DTCondor 
   

   and login using your ordinary MWS username and password.


3. The next step is optional but nonetheless useful. To check that the job template is correct, select the "create or edit a job template" option in the Main Menu to open the Job Template Editor, then load the job template file (run_analysis.dtc). The information in the template file should be displayed as shown below:
   
   
   
   If any changes were needed, for example the number of jobs or input files, then this would be the place to make them. You can try this now by changing some of information and you should see that a message warning you that the template has not been saved appears at the bottom of the window. To make the changes permanent you could then click the Save Template button to save them to a file. In this case, no changes are needed so just click Close to get back to the Main Menu.
   
   
4. The next step is to actually submit the jobs using the previously downloaded template file. To do this, select the "submit jobs using an existing job template" option in the Main Menu and click the Continue button. The Job Submission window should now open allowing you to load the job template file. Click the Browse button under the Job template file: text and select the previously downloaded template file (run_analysis.dtc). You should see that the information from the template (i.e. the executable and indexed input files) is now displayed in the window as shown below:
   
   
   
   
5. Once a template file has been loaded, the next step is to identify the actual files to be used with the jobs. Firstly, you will need to select the main R script. To do this click the Browse button under the R script text and select (analyse.R). There are no common input files for this example so skip over that option to the Indexed input files folder option. If you have previously saved the input files (observations0.dat ... observations9.dat) to the default location i.e.

   C:\Users\condoruser\Desktop\DTCondor\indexed_input
   

   then there is no need to change anything but if they were saved to a different folder, this should now be selected by browsing to it using the Browse button below the Indexed input files folder: text.



6. The next step is to submit the jobs by clicking the Submit Jobs button. Progress information will be displayed at the bottom of the window and eventually, after the jobs have been successfully submitted, the appearance of the window should change to:
   
   
   
   Since the Job Submission window is no longer needed, it can be closed by clicking the Close button to return to Main Menu.
   
   
7. For the next few steps we need to turn our attention to monitoring the submitted jobs - so ensure that you can access the Job Monitor window (this should have appeared after you logged in with DTCondor). Progress information will be displayed in this window but it is not updated continuously. Instead the latest status messages are retrieved from the server by clicking the Update Messages button. If you are quick, then you may catch the job before it has started to run and the window will appear as below when the Update Messages button is clicked:
   
   
   
   By repeatedly clicking Update Messages, you should see that the jobs eventually start to run and, after a while, complete. For example here five of the ten jobs have completed.
   
   
   
   You can shut down DTCondor at anytime and start it again later without it affecting any of the submitted jobs. It is also possible to get detailed information on how your jobs are progressing by visiting to the HTCondor website (condor.liv.ac.uk) which is accessible from anywhere (even outside of the University network).



8. The length of time taken for all of the jobs to complete will depend how busy the HTCondor pool is and how many machines are available but generally it should be no longer than 10-20 minutes and eventually this information will be displayed:
   
   
   
   
9. The HTCondor server will automatically detect when all of the jobs have completed and will then bundle all of the output files into a ZIP file for ease of downloading. The ZIP file can be retrieved by clicking the Download Output button and will be saved to the default output folder which is:

   C:\Users\condoruser\downloads
   

   If you wish to save the output to a different folder, then select it first by clicking the Browse button before the Download Output button. After the ZIP file has been successfully downloaded, the window should appear as follows:
   
   
   
   The individual output files can be extracted by right-clicking on the ZIP file (here results.dat.zip) in Windows Explorer and selecting Extract All....