|1. ||What does this command do?||[go]|
|2. ||What is the difference between legion_run and legion_run_multi?||[go]|
|3. ||What are the prerequisites?||[go]|
|4. ||What are the required parameters?||[go]|
|5. ||Can I choose the remote host?||[go]|
|6. ||My program expects input files -- how do I get them to the remote host?||[go]|
|7. ||My program will produce output files -- how do I get them back?||[go]|
|8. ||What is an options file and how do I use it?||[go]|
|9. ||Can I control the output?||[go]|
|10. ||Can I set a time limit?||[go]|
|11. ||Can I control stdin, stdout, and stderr?||[go]|
|12. ||I want (or don't want) my program to run on a queue system||[go]|
|13. ||How does the debug option work?||[go]|
|14. ||Some hints to make life easier||[go]|
What does this command do?
- The legion_run command starts one instance of a program on a remote host. You can ask that the job be started on a specific architecture or a specific host, if you wish. If necessary, you can tell Legion to copy input files to and output files from the remote host. The command is fully documented here.
What is the difference between legion_run and legion_run_multi?
- Both of these commands are used to run programs on remote Legion hosts. But where legion_run executes only a single copy of a program on a single host, legion_run_multi executes multiple copies on multiple remote hosts.
What are the prerequisites?
- You must have previously registered the program with Legion, with either legion_register_program or legion_register_runnable (see chapter 8 in the Basic User Manual). If there are any required input files, they must be visible in your local file space or context space.
What are the required parameters?
- You must include the program's Legion class path (created when you registered the program in Legion). If there are any required command-line arguments, you must include them as well. This may require repeating information already provided in Legion flags: e.g., if you have specified an input file with Legion flags you may need to specify it again for your program's parameters.
Can I choose the remote host?
- There are two ways to control which host runs your program: you can use the -h flag to name a specific host or -a to name a specific architecture. If more than one acceptable host is available, Legion will choose one.
The -n flag specifies how many of the remote host's nodes should be allocated for running your program. This is useful if your program is a native parallel job.
My program expects input files -- how do I get them to the remote host?
- You must make sure that these files are visible from either context space or local file space and you must use either -in or -IN to tell Legion to copy the contents of your input files to the remote host. The copied files will be placed in the local directory of the remote host and given the same file name. Once the program is finished, the copied files are deleted. You can also use an option file.
My program will produce output files -- how do I get them back?
- Use either -out or -OUT to tell Legion to look for these files after the program has finished and to copy them back to your local file space or context space. If the program crashes midway through, any existing output files will be available. You can also use an option file.
What is an option file and how do I use it?
- An option file is a local text file that contains instructions for input/output files, architecture, timing, nodes, and tty. If your program requires extensive instructions, this is a useful way to avoid typing everything in at the command line. You can include one or more of the legion_run options except the program class name and arbitrary command-line arguments. Use spaces, tabs, or blank lines to separate your parameters. E.g.:
To use an options file, use the -f flag.
Can I control the output?
- The -w flag tells Legion to direct the program's output to the set tty object (i.e., any output will appear in your current window).
The -v flag, just as in Unix, causes the command to run in verbose mode (i.e., the program reports progress whenever possible). We strongly suggest that you always use this flag, especially if the program takes more than a few seconds to run.
Can I set a time limit?
- If the remote host enforces time limits for outside jobs, the -t flag specifies how many minutes the program needs to run. This may prove especially useful if you are running on queue systems. If a Legion job goes on a queue host, Legion's default run time limit is one hour.
Can I control stdin, stdout, and stderr?
- Yes. You can use -stdin, -stdout, and -stderr to specify a local file to use for standard input, output, and error.
I want (or don't want) my program to run on a queue system
- By default, Legion will choose a remote host, depending what flags you have used. If you need to restrict the possibilities to queueing systems (a.k.a. batch queue hosts) you need to set the program class's desired_host_property to 'queue' with the legion_update_attributes command:
Or, if you want to be sure that the program does not run on a queueing system, you can set the property to 'interactive':
$ legion_update_attributes -c <program class path> \
$ legion_update_attributes -c <program class path> \
Be aware the Legion has a default time limit of one hour for jobs on queueing systems. You may need to use the -t flag to adjust this setting.
How does the debug option work?
- The -debug flag will give you tons of debugging information about legion_run (i.e., about the Legion objects that are working to remotely start your program), but not about your program or its input and output files.
You can redirect this output to a file by resetting stdout.
Some hints to make life easier
- Be careful not to run the program on the wrong architecture.
- Don't specify conflicting architectures with -a and -h.
- Doublecheck your input and output filenames.
- Don't use the -a flag more than once: you will get an error.
- Be sure to include any necessary command-line parameters for the program. For example, you may need to specify input files twice; once in Legion's -IN flag and then again in the program's command-line arguments.
- A program can fail for multiple reasons, including internal bugs: try to be sure that your program is bugfree before you run it.
- We suggest that you always use -v, especially if the program will be running for more than a few seconds.