-
Notifications
You must be signed in to change notification settings - Fork 2
Quick Start Guide
Welcome to the Gricli Quick Start Guide. Here you will find a brief overview on how to use Gricli to submit and manage jobs sent to a computing service. This guide is suitable for those with some experience in using command line batch submission systems. If your are new to command lines or batch computing, please see the Beginner's Guide.
If your grid service provider supports Gricli you may use SSH to connect and get started. Please contact your grid service provider for SSH login details. When you have connected, start the Gricli shell:
$ griclish
You will have to select an authentication option as shown below. Your grid service provider should have documentation on which option to choose.
Please select your preferred login method:
[1] Institutions login
[2] MyProxy login
[3] Certificate login
[0] Exit
Once you have logged in, you will see the Gricli prompt:
jobs>
This is where you can type commands to create and manage your jobs. For example to see the help documentation type:
jobs> help
This guide will give you a brief introduction to the commands commonly used but if your would like more information use the help command for more detailed descriptions and examples.
Gricli uses a list of properties called globals to define a job's configuration. To see the list of globals, enter the following command:
jobs> print globals
For more information on globals in general or any specific global use the help command:
jobs> help topic Globals
jobs> help memory
There are some globals which you must set or that must have valid values, they are:
- group: The group to submit under. This will determine the job queues you are authorized to submit to.
- queue: The submission queue. This will determine what hardware and software configuration will be used to execute the job.
- package: The program (or program package) you wish to use.
- jobtype: single, smp or mpi.
- cpus: The number of CPUs your job will require.
- memory: The total memory shared among the CPUs in MB.
- walltime: Maximum duration in minutes that your job will be allowed to run for.
To set the value for each global use the set command. We will go through simple examples showing how to choose and set each of these properties.
To see the list of groups you belong to type:
jobs> print groups
Choose one of the listed groups (in this example we use /my/group) and use the set command:
jobs> set group /my/group
The queue can be set manually or automatically. To let Gricli determine the correct queue type:
jobs> set queue auto
To set the queue manually you will need to see the queues available for your group:
jobs> print queues
Choose the queue (here we use myqueue) and type:
jobs> set queue myqueue
To see the list of available application packages type:
jobs> print packages
If you would like to see the queues that support an application package (here we use myapp) as well as the available versions type:
jobs> print package myapp
To set the package , type:
jobs> set package myapp
By default the application package version is set to any which means Gricli will choose any supported version. If you would like to set the version (here we use myversion) type:
jobs> set version myversion
To see details on the available job types type:
jobs> help jobtype
To set the jobtype (here we use myjobtype) type:
jobs> set jobtype myjobtype
To set the number of CPUs required by your package use the set command e.g:
jobs> set cpus 10
To set the amount of memory used by all the CPUs combined use the memory global. Below we set the amount of memory to 1 GB directly and by using a formatted string.
jobs> set memory 1024
jobs> set memory 1g
To see more examples type:
jobs> help memory
To set number of minutes a job will run for use the walltime global. Here we set the job to run for 1 hour in two different ways:
jobs> set walltime 60
jobs> set walltime 1h
For more examples type:
jobs> help walltime
Once the required globals have been set you may submit a job using the submit command and the command line string to be executed. Here is a simple example of submitting an echo job:
jobs> submit echo Hello World
job name is gricli
Note that quotation marks are not required around the command eg "echo Hello World" or the argument "Hello World ".
If the submission was successful, Gricli will report the submitted job name. To change the job name set the jobname global:
jobs> set jobname sleep_job
jobs> submit sleep 100
job name is sleep_job
If you submit multiple jobs with the same name, Gricli will append a number to make the job name unique with respect to your other active jobs.
jobs> submit sleep 200
job name is sleep_job_1
If your job requires input or output files, you may include them in the submission with the attach command.
jobs> attach file_1 file_2
jobs> submit cat file_1
Note that each job will use the current set of globals. If the next job requires a different set of files, use unset files command and attach the new files:
jobs> unset files
jobs> attach file_3 file_4
You may also give your jobs a description which will help identify them at a later:
jobs> set description "This is my long sleep job"
jobs> submit sleep 1000
job name is sleep_2
If you would like to receive an email when your job has started and / or finished set the following globals:
jobs> set email [email protected]
jobs> set email_on_start false
jobs> set email_on_finish true
You can see a list of current jobs and their status using the print jobs command:
jobs> print jobs
A job can have one of several status values as it moves from submission to completion:
- Ready to submit: The job has been prepared for submission to the queue.
- Unsubmitted: The submission did not succeed.
- Pending: The job has been submitted.
- Active: The job has started.
- Done: The job has finished.
- Failed: There was a problem during execution.
To see the properties of a specific job use the print job command as follows:
jobs> print job myjob
A variation on this command allows you to see a specific job property such as the job walltime:
jobs> print job myjob walltime
To stop a job at any time use the kill job command e.g :
jobs> kill job myjob
If the job was active it will stop executing and change status to 'Done'. Note that once a job has been stopped it cannot be resumed.
Once your job has finished you may download the job directory. You may specify the download location by setting the global dir:
jobs> set dir /some/dir
Now you may download the job using the download job command:
jobs> download job myjob
This command can also take an additional argument to specify the target directory:
jobs> download job myjob /some/dir
The downloaded job directory will contain all input and output files associated with the job. To see the output of a job check the contents of the stdout.txt and stderr.txt files.
When you have finished with a job, use the clean job command to remove temporary job files and other records associated with the job.
jobs> clean job myjob
Note that once a job has been cleaned it cannot be accessed anymore. Downloaded files are not affected by this command. To avoid loosing data always download the job before cleaning it. You may combine these actions into one command:
jobs> downloadclean job myjob
jobs> downloadclean job myjob /some/dir
If you would like to see the contents of any files in a job directory, use the view command.
jobs> view myjob myfile
You may also specify remote file locations with this command. For more information type help view. To view the contents of local files use the exec command:
jobs> exec cat /my/local/file
To automate tasks and create workflows use Gricli scripts. The run command will execute Gricli commands stored in a text file:
jobs> run myscript
Here is a simple script which sets up a job environment and submits a job:
set group mygroup
set queue myqueue
set jobname myjob
submit echo "script submitted"
If the script is specified without a path, the location of the script file must be the same directory like the one in the global variable 'dir'
jobs> print global dir
dir = ~
In this example, the location where gricli will look for myscript is the home directory (~). Alternatively, an absolute path to the script can be specified:
jobs> run ~/Erw_PRO/WT/myscript
To submit multiple jobs in a loop, use a shell script to echo the commands and pipe them to griclish:
#!/bin/bash
#script name: myscript.sh
#set globals:
echo "set group /my/group"
echo "set queue myqueue"
echo "set jobname myjob"
for i in {1..10}
do
#the & makes the command asynchronous
echo "submit sleep 100 &"
done
Now we execute the script and pipe to griclish:
> ./myscript.sh | griclish
If you would like a more complex workflow which involves processing results and resubmitting jobs use the wait job command:
#!/bin/bash
#script name: myscript.sh
#set globals:
echo "set group /my/group"
echo "set queue myqueue"
echo "set dir ~/jobs"
for i in {1..10}
do
echo "set jobname myjob_$i " # give a unique name
echo "unset files" # clear file list from previous job
echo "attach input_$i" # attach files for current job
echo "submit myprogram -f input_$i" # perform computation on the grid
echo "wait job myjob_$i" # wait for the job to finish
echo "downloadclean job myjob_$i" # download results and clean job
./process_results.sh < ~/jobs/myjob_$i/stdout.txt > ~/jobs/input_$(($i+1)) # process results and prepare input for the next job
done