ExecutionEnvironment
From unicore
Execution Environments are used for running UNICORE applications in different execution modes, load software stacks before the execution of the actual application etc.
Contents |
Server Side: IDB configuration
Overwiew
- Name: A human readable name for identifying the execution environment, e.g. debug or parallel.
- Description: A piece of text describing what the execution environment does.
- Executable name: Full path to an executable that implements the logic of the execution environment.
- Arguments: List of command line arguments for the executable. Each argument has a name and an incarnated value, the latter telling UNICORE 6 how to pass the argument to the executable. In addition, arguments may be annotated with metadata:
- Type: Type of the argument value, can be any of the following: int (integer number), double (a real number with double precision), string (textual value), or choice (nominal choice between fixed alternatives).
- Description: A piece of text that is displayed to the end-user for explaining what an argument does.
- Valid value range: A character string that allows for validating user input for the argument. For numerical arguments, intervals can be given (using either integer or real values), and nominal values can be defined by a comma-separated list. In the current implementation, string values are not validated, but in the future, regular expressions will be used for this task.
- Options: Somewhat similar to arguments but options can only be enabled or disabled instead of taking a value. Options have metadata, too, but they only contain a description (since options always have Boolean type).
- Precommands: List of shell commands that should be run before the actual executable of the environment; these commands can be enabled and disabled by the user, so precommands and options are very much alike (though the incarnation is different).
- Postcommands: Analogous to precommands but should be executed to perform postprocessing after the main application run.
Example IDB entry: OpenMPI
<jsdl-u:ExecutionEnvironment>
<jsdl-u:Name>Parallel Execution</jsdl-u:Name>
<jsdl-u:Description>Run an OpenMPI application</jsdl-u:Description>
<jsdl-u:ExecutableName>/vsgc/software/openmpi/bin/mpiexec</jsdl-u:ExecutableName>
<jsdl-u:Argument>
<jsdl-u:Name>Number of Processes</jsdl-u:Name>
<jsdl-u:IncarnatedValue>-np</jsdl-u:IncarnatedValue>
<jsdl-u:ArgumentMetadata>
<jsdl-u:Description>The number of processes</jsdl-u:Description>
<jsdl-u:Type>int</jsdl-u:Type>
<jsdl-u:ValidValue>[1,20]</jsdl-u:ValidValue>
</jsdl-u:ArgumentMetadata>
</jsdl-u:Argument>
<jsdl-u:Argument>
<jsdl-u:Name>Export Environment Variable</jsdl-u:Name>
<jsdl-u:IncarnatedValue>-x</jsdl-u:IncarnatedValue>
<jsdl-u:ArgumentMetadata>
<jsdl-u:Description>Export an environment variable (e.g., "foo=bar" exports the environment variable name "foo" and sets its value to "bar" in the started processes)</jsdl-u:Description>
<jsdl-u:Type>string</jsdl-u:Type>
</jsdl-u:ArgumentMetadata>
</jsdl-u:Argument>
<jsdl-u:Option>
<jsdl-u:Name>Verbose</jsdl-u:Name>
<jsdl-u:IncarnatedValue>-v</jsdl-u:IncarnatedValue>
<jsdl-u:OptionMetadata>
<jsdl-u:Description>Be verbose</jsdl-u:Description>
</jsdl-u:OptionMetadata>
</jsdl-u:Option>
<jsdl-u:PreCommand>
<jsdl-u:Name>Print time before execution</jsdl-u:Name>
<jsdl-u:IncarnatedValue>date</jsdl-u:IncarnatedValue>
<jsdl-u:OptionMetadata>
<jsdl-u:Description>Prints the current time to standard out right before execution starts.</jsdl-u:Description>
</jsdl-u:OptionMetadata>
</jsdl-u:PreCommand>
<jsdl-u:PostCommand>
<jsdl-u:Name>Print time after execution</jsdl-u:Name>
<jsdl-u:IncarnatedValue>date</jsdl-u:IncarnatedValue>
<jsdl-u:OptionMetadata>
<jsdl-u:Description>Prints the current time to standard out right after execution ends.</jsdl-u:Description>
</jsdl-u:OptionMetadata>
</jsdl-u:PostCommand>
</jsdl-u:ExecutionEnvironment>
Note that you will have to add the jsdl-u namespace:
<idb:IDB xmlns:idb="http://www.fz-juelich.de/unicore/xnjs/idb" xmlns:jsdl-u="http://www.unicore.eu/unicore/jsdl-extensions">
- The ExecutableName element points to the mpiexec command which is used to initialize a parallel job through the underlying batch system (TORQUE7 has been installed at this UNICORE 6 site). After calling this command, multiple processes are spawned on allocated cluster nodes, each of which executing the main application. These processes can use MPI for inter-process communication.
- Two arguments for the mpiexec command are defined:
- The Number of Processes argument is used to specify how many parallel processes should be spawned. The mpiexec command expects this argument to be given in the form -np numproc where numproc is an integer number. This can be deduced from the text content of the IncarnatedValue element. The Number of Processes argument is further described by an ArgumentMetadata element which provides a text description for the semantics of the argument, declares the argument type (int stands for "integer number") and sets a valid value range for this argument ([1,20]). These metadata are later used by the UNICORE Rich Client for building an appropriate user interface and validating user input.
- The second argument takes character string values and allows for setting additional environment variables for the parallel processes.
- The Option element defines an option named Verbose that puts OpenMPI in verbose execution mode if selected.
- The precommand defines a shell command that is run on the login node before mpiexec is started; analogously, the postcommand is run after mpiexec has finished. In the example, these commands simply print the current time to standard out.
Rich Client
OpenMPI example job
This section assumes that your IDB is configured according to the example above.
Create a single job using the Generic Gridbean v. 2.0. Choose Custom Executable as application and set the path to the executable. In the following steps, we'll set up the job to compile a simple Hello World program in the working directory, thus we use hello_world here. Alternatively you can also use a pre-compiled executable, in which case some of the steps described below will get a little easier.
Save the following file as hello_world.c on your local computer and define a file import:
#include <stdio.h>
#include <unistd.h>
#include "mpi.h"
int main (argc, argv)
int argc;
char *argv[];
{
int rank, size;
char hostname [1024];
hostname[1023] = '\0';
MPI_Init (&argc, &argv); /* starts MPI */
MPI_Comm_rank (MPI_COMM_WORLD, &rank); /* get current process id */
MPI_Comm_size (MPI_COMM_WORLD, &size); /* get number of processes */
gethostname(hostname, 1023);
printf( "Hello world from host %s process %d of %d\n", hostname , rank, size );
MPI_Finalize();
return 0;
}
In the resources panel, activate Execution Environment and edit its parameters:
You might also want to increase the number of nodes and CPUs to have real parallel execution. :-)
In the Execution Environment dialog, choose Parallel Execution from the dropdown box. Activate and choose the number of processes. If the mpi shared libraries on the target system are not in a standard path, you might want to set the variable LD_LIBRARY_PATH accordingly. As precommand, enter the command needed to compile the c source code.
Now the job definition is complete. If you submit this job, the output should look like this:
Hello world from host zam025c04 process 3 of 10 Hello world from host zam025c03 process 0 of 10 Hello world from host zam025c04 process 6 of 10 Hello world from host zam025c04 process 2 of 10 Hello world from host zam025c04 process 7 of 10 Hello world from host zam025c03 process 8 of 10 Hello world from host zam025c03 process 4 of 10 Hello world from host zam025c03 process 1 of 10 Hello world from host zam025c03 process 9 of 10 Hello world from host zam025c03 process 5 of 10
Command Line Client
OpenMPI example job
This section assumes that your IDB is configured according to the example above. You can use the C source file from the Rich Client example.
If you have already a pre-compiled executable on the target system, you can submit it via the following UCC file:
{
Executable: "/home/rbreu/mympi/hello_world",
# allocate 2 nodes with 2 CPUs each:
Resources:{
CPUsPerNode: 2,
Nodes: 2,
},
Execution environment: {
Name: "Parallel Execution",
Arguments: {
Number of Processes: 10,
},
},
}
Submit it as usual using ucc run.
To compile a source file on the target system before submitting to the batch system, analogous to the Rich Client example, use the following UCC file:
{
Executable: "./hello_world",
Imports:[
{From: "hello_world.c", To: "hello_world.c" },
],
# allocate 2 nodes with 2 CPUs each:
Resources:{
Nodes: 2,
CPUsPerNode: 2,
},
# set environment variable to find the shared openmpi libraries:
Environment: ["LD_LIBRARY_PATH=/vsgc/software/openmpi/lib"],
Execution environment: {
Name: Parallel Execution,
Arguments: {
Number of Processes: 10,
},
# compile program beforehand:
User precommand: "/vsgc/software/openmpi/bin/mpicc hello_world.c -o hello_world",
},
}
With the Hello World example file from the Rich Client section, you should get in both cases an output file which looks similar to this:
Hello world from host zam025c04 process 7 of 10 Hello world from host zam025c03 process 1 of 10 Hello world from host zam025c04 process 6 of 10 Hello world from host zam025c03 process 0 of 10 Hello world from host zam025c04 process 3 of 10 Hello world from host zam025c04 process 2 of 10 Hello world from host zam025c03 process 8 of 10 Hello world from host zam025c03 process 9 of 10 Hello world from host zam025c03 process 4 of 10 Hello world from host zam025c03 process 5 of 10
