AppJobXml

From UGP-Wiki

Documentation on appForm file: app_job.xml

Contents 1 Purpose of app_job.xml 2 Overall Syntax 3 Required Tags which do not have a visible keyword 4 Required Tags for which you can specify a visible keyword 5 Required Tags with Special Formatting 6 Optional Tags for which you can specify a visible keyword 7 Multiple Job Types (serial or mpi) 8 Useful Links

[edit] Purpose of app_job.xml

• app_job.xml is one the three required files for any application to be used with appForm.
• app_job.xml defines the form elements that appear on the "Job Parameters" tab. More specifically, the form elements that define the options to be used for job submission to the Grid.

• NOTE: Replace app in the file name with the "Display Name" of the application as it appears in the UGP Application table.

[edit] Overall Syntax

The app_job.xml file should look like this:

  <?xml version="1.0" ?>
  <?xml-stylesheet type="text/xsl" href="rsl.xsl"?>
  <app>
     xml element
     xml element
     xml element
     ...
  </app>

Rules:

• All xml elements must appear inside of the <app> </app> tags. Do not replace <app> with the name of the application but code <app> exactly as it appears here.
• The order of the xml elements inside of <app> does not matter, the order is automatically specified by appForm
• Some xml elements look like this:

  <tag>value</tag>

• Others look like this:

  <tag [visible="true"|"false"]>value</tag>

visible="true"

specifies that the element (Label and value) is to be displayed to the user in the form. The user is not able to modify the value.

visible="false"

specifies that the element will NOT be displayed to the user in the form. However, the information in this tag will still be included in job submission.

visible not coded

specifies that the label for the tag is to be displayed next to a text entry field in the form so that the user can input or modify the value.

[edit] Required Tags which do not have a visible keyword

  <appName>application-name</appName>
      
  <target name="cluster-display-name">%CLUSTERNAME%</target>
      cluster-display-name shows up as:
          Submit to: cluster-display-name
      %CLUSTERNAME% is a variable that is replaced by appForm to reflect 
        the cluster address that is stored in the appForm dastabase

  <description>Description of the App</description>
      shows up as:
          Application Description:

[edit] Required Tags for which you can specify a visible keyword

  <count [visible="false"|"true"]>1</count>
      shows up as:
         Number of Processors:

[edit] Required Tags with Special Formatting

<executable [visible="false"|"true"] [jobType="jobType"]> complete path to the executable</executable>

      shows up as:
         Executable(mpi): path to the executable
      The jobType defined here must be identical to one defined in a <jobType> element 

  <environment [visible="false"|"true"] [jobType="jobType"]> list of environment variables</environment>
      shows up as:
         Environment(mpi): list of environment variables
      The jobType defined here must be identical to one defined in a <jobType> element 

  <jobType [default="true"]>serial</jobType>
      shows up as:
         JobType: (radio button)
      valid values are most likely serial, mpi, multiple or condor.
      add the default tag to the <jobType> you want to be initially selected
      <jobType> does not use a visible attribute, it is always displayed

For more information on these elements, see Multiple Job Types

[edit] Optional Tags for which you can specify a visible keyword

  <jobName>name you give this job</jobName>
      shows up as:
         Job Name:

  <defaultArgument>default arguments</defaultArgument>
      shows up as:
         Default Arguments:

  <argument [visible="false"|"true"]>arguments</argument>
      shows up as:
         Arguments:

  <directory>directory where the executable should be run</directory>
      shows up as:
         Directory:

  <scheduler display="none">SGE</scheduler>
      shows up as:
         Scheduler:

  <stdin [visible="false"|"true"]>/dev/null</stdin>
      shows up as:
         Stdin:
      Use if the executable accepts input through stdin

  <maxTime [visible="false"|"true"]>7200</maxTime>
      shows up as:
         Max Time (in hours):

  <maxWallTime [visible="false"|"true"]>time</maxWallTime>
      shows up as:
         Max Wall Clock Time:

  <maxCpuTime [visible="false"|"true"]>time</maxCpuTime>
      shows up as:
         Max CPU Time:

  <maxMemory [visible="false"|"true"]>memory-in-meg</maxMemory>
      shows up as:
         Max Memory (in MB):

  <queue [visible="false"|"true"]>queue-name</queue>
      shows up as:
         Queue:

  <project [visible="false"|"true"]>project description</project>
      shows up as:
         Project:

  <libraryPath [visible="false"|"true"]>library path</libraryPath>
      shows up as:
         Library Path:

[edit] Multiple Job Types (serial or mpi)

When submitting jobs with different Job Types (e.g. serial or mpi), the grid usually utilizes different executables and environment variables for each Job Type. appForm accomodates this by allowing you to define multiple Job Types and multiple Executable and Environment Variables that are linked to each Job Type. The following elements have additional formatting that facilitate this feature. These three elements are the only ones that may be defined more than once in a job.xml file.

  <executable [visible="false"|"true"] [jobType="jobType"]> complete path to the executable</executable>
      shows up as:
         Executable(mpi): path to the executable
      The jobType defined here must be identical to one defined in a <jobType> element 

  <environment [visible="false"|"true"] [jobType="serial"|"mpi"|"multiple"|"condor"]> list of environment variables</environment>
      shows up as:
         Environment(mpi): list of environment variables
      The jobType defined here must be identical to one defined in a <jobType> element 

  <jobType [default="true"]>serial</jobType>
      shows up as:
         JobType: (radio button)
      valid values are most likely serial, mpi, multiple or condor.
      add the default tag to the <jobType> you want to be initially selected
      <jobType> does not use a visible attribute, it is always displayed

• When using multiple <jobType> elements, each <environment> and <executable> are linked to their Job Type by the jobType attribute
• You may want to define only one <jobType>, and therefore only one <environment> and <executable>. In this case, you would not need to use a jobType attribute.
• Job Types are displayed as a user-selectable radio button. Once the user submits their job, appForm selects the proper executable and environment for the Job Type chosen by the user

An example of a partially implemented file with one possible jobType

  <executable visible="true">/u/local/home/gamess</executable>
  <environment visible="false">NWCHEM_BASIS_LIBRARY /u/local/libraries/ NWCHEM /u/local/</environment>
  <jobType>mpi</jobType>

• since there is only one <environment> and <executable>, the jobType attribute is not needed
• since there is only one <jobType>, the default attribute is not needed
• the above <environment> declares two environment variables, where each term is separated by a single space
• the jobType would be displayed as a radio button with one choice (mpi), which is permanently selected

An example of a partially implemented file with multiple possible jobTypes

  <executable visible="true" jobType="mpi">/u/local/home/gamess_mpi</executable>
  <executable visible="false" jobType="serial">/u/local/home/gamess_serial</executable>
  <environment visible="false" jobType="mpi">NWCHEM_BASIS_LIBRARY /u/mpi/libraries/</environment>
  <environment visible="false" jobType="serial">NWCHEM_BASIS_LIBRARY /u/serial/libraries/</environment>
  <jobType default="true">mpi</jobType>
  <jobType>serial</jobType>

• notice that each of the jobType atrributes match up with the values defined in the <jobType> elements
• <executables> and <environments> independently use their visible attributes. In this example, only the first executable would be displayed
• the jobTypes would be displayed as radio button with two choices (mpi and serial), where mpi is pre-selected

[edit] Useful Links

• appForm Main Page

• Sample app_job.xml file

• Documentation on app_form.xml (Input Generator Tab)

• Documentation on app_form_input.xsl (Translator which creates input file)