EnFuzion 8.0 User Manual
Prev	Chapter 2. Tutorial	Next

Creating The Sample Parametric Study

This section describes the sample parametric study that is included with the EnFuzion distribution package. The sample study illustrates key concepts of EnFuzion operation.

The section starts with an introduction to parametric studies. It continues with a detailed description of the sample parametric study and how the sample parametric study can be created using EnFuzion tools.

Introduction to Parametric Studies

Parametric studies execute one application many times with different sets of input parameters. EnFuzion simplifies parametric studies by automating time consuming, manual steps and provides the results faster by utilizing distributed computing power.

A parametric study consists of the following:

parameters. These describe sets of input values. Each set of input values specifies values for one application execution, which is referred to as a job.
tasks. These contain commands, describing how the application is to be executed. In general, a parametric study contains several types of tasks:
- root initialization. This task is performed on the EnFuzion root computer. Usually, it prepares input files for the study and performs any other initialization steps. This task is often omitted.
- node initialization. This task is performed on each EnFuzion node, before any of the user applications are executed. The task usually copies to the node common files that are used by all jobs. If required, it can also install the user application on the node.
- main task. This task is required and is the most important task. It corresponds to one job, which calculates results for one set of input values. The task usually copies job specific files to the node, sets up input parameter values for the job, executes the user application on the node and copies the results back to the EnFuzion root.
- root completion. This task is performed on the EnFuzion root computer. It collects the results from all jobs and prepares a summary report. This task is often omitted.

Description of the Sample Parametric Study

The sample parametric study illustrates key principles of EnFuzion use (see Figure 2-1). It is included with each EnFuzion distribution package and is installed in the test subdirectory of the main EnFuzion directory. The study can be easily modified for specific applications. The sample parametric study is called sample.pln and is located in the test EnFuzion subdirectory. The rest of the section describes the contents of sample.pln in detail.

Figure 2-1. Sample Parametric Study - Plan File sample.pln

#
#   This is a sample EnFuzion plan. It contains most
#   commonly used plan constructs and features.
#

#---------------------------------------------------------------------
#   parameter section, specifying input values for parameters
#---------------------------------------------------------------------

#   an example of a range of values
#
parameter xrange label "X-Range" integer range from 1 to 5 step 1;
parameter yrange label "Y-Range" integer range from 1 to 5 step 1;

#   an example of a parameter with one selected value
#
parameter oneof label "OneOf" integer select oneof 1 2 3 4 5 default 1;

#   an example of a parameter with many selected values
#
parameter anyof label "AnyOf" integer select anyof 6 7 8 9 10 default 6;

#----------------------------------------------------------------------
#   task section, specifying tasks to be executed
#----------------------------------------------------------------------

#   the nodestart task initializes the node
#   it is performed once on each node
#
task nodestart
    # copy common files to the node
    copy input.txt node:.
    copy template.txt node:.
endtask

#   the main task executes a job
#   it is executed for all specified parameter values
#
task main

    # get job name, node host name, the operating system and user parameters
    node:execute echo This is job: $ENFJOBNAME, \
        executing on host $ENFHOSTNAME >output.txt
    node:execute echo The node runs the $ENFOS operating system >>output.txt

    # user parameters are provided on a command line
    node:execute echo Parameter values are: \
        OneOf $oneof, AnyOf $anyof >>output.txt
    node:execute echo Parameter values are: XRange $xrange, \
        YRange $yrange >>output.txt

    # in the template file, substitute parameters with values
    # user parameters are provided in a text file	
    node:substitute template.txt values.txt

    # a user command is normally executed here, something like:
    # (uncomment the line below and insert real values for your application)
    #node:execute <user_command> <inputs> <outputs>

    # wait a few seconds to simulate a command execution
    node:sleep 3

    # copy the result files back to the root host
    copy node:input.txt $ENFJOBNAME/common.txt
    copy node:output.txt $ENFJOBNAME/.
    copy node:values.txt $ENFJOBNAME/.
endtask

The sample study demonstrates the following EnFuzion principles:

range parameters. The values for these parameters are specified by a starting value, an ending value and a step.
select parameters. The values for these parameters are selected from a range of provided values.
common input files. These are files that are common to all jobs and are copied only once to each node.
file based parameter values. These parameters are provided to user applications in an input file.
command line parameter values. These parameters are provided to user applications on the command line.
executing user application. User applications are executed from a command line. Input values are provided on the command line or in an input file.
result files. These are files that contain valuable results and are stored after the study has completed.

The sample study performs the following steps:

Takes input files input.txt and template.txt. This demonstrates how to copy to nodes common input files for all jobs. The files are copied to each node only once for all jobs, not separately for each job.
Creates output file output.txt, which contains job specific values. This demonstrates how parameter values can be used as command line options.
Takes the input file template.txt and replaces its contents with job specific values. It produces the output file values.txt. This demonstrates how parameter values can be used in input files, instead of on the command line.
Copies output files from the node to the root system. The following files are copied:
- input.txt, which is renamed to common.txt.
- output.txt
- values.txt
Files are copied to a job specific directory on the EnFuzion root system, so that results from different jobs do not interfere with each other. This demonstrates how to copy result files from the node to the EnFuzion root system. After a job has completed, all job specific files on the node are deleted, so it is important to save the result files.

The following sections describe sample.pln in detail.

Description of Parameters

The sample study defines four parameters: xrange, yrange, oneof and anyof.

xrange and yrange are range parameters. They are defined by the start value, the end value and the step of the range. Their description in the plan file is shown in Figure 2-2.

Figure 2-2. Sample Parametric Study - Range Parameters

#   an example of a range of values
#
parameter xrange label "X-Range" integer range from 1 to 5 step 1;
parameter yrange label "Y-Range" integer range from 1 to 5 step 1;

The oneof parameter is a select parameter. It offers a set of choices, and the user can select only one value. Its description in the plan file is shown in Figure 2-3.

Figure 2-3. Sample Parametric Study - Oneof Select Parameter

#   an example of a parameter with one selected value
#
parameter oneof label "OneOf" integer select oneof 1 2 3 4 5 default 1;

The anyof parameter is a select parameter. It offers a set of choices, and the user can select any combination. Its description in the plan file is shown in Figure 2-4.

Figure 2-4. Sample Parametric Study - Anyof Select Parameter

#   an example of a parameter with many selected values
#
parameter anyof label "AnyOf" integer select anyof 6 7 8 9 10 default 6;

These descriptions of parameters in plan files define only possible parameter values. Specific input values still need to defined. This is done by the Generator, which performs the following steps:

Reads a plan file.
Obtains input parameter values from the user.
Generates jobs, where each job is assigned one combination of input values.
Writes out a run file, which can be submitted for execution.

Description of Tasks

The sample study uses only the node initialization task and the main task. The root initialization and root completion tasks are not used.

The node initialization task is described in the task nodestart. It performs the following steps:

The common input files are copied to each node during the node initialization. These commands are shown in Figure 2-5.
Figure 2-5. Sample Parametric Study - Common Input Files
```
task nodestart
    # copy common files to the node
    copy input.txt node:.
    copy template.txt node:.
endtask
```

The main task is described in the task main. It performs the following steps:

The file based parameter values are used to provide input values in files. This command is shown in Figure 2-6.
Figure 2-6. Sample Parametric Study - File Based Parameter Values
```
    # in the template file, substitute parameters with values
    # user parameters are provided in a text file	
    node:substitute template.txt values.txt
```
The substitute command takes a template file and replaces parameter placeholders with their input values for each job. The template file template.txt is shown in Figure 2-7, and the resulting values.txt file for a job is shown in Figure 2-8.
Figure 2-7. Sample Parametric Study - Template File
```
This is job: $ENFJOBNAME.
Parameter values are:
	XRange		$xrange
	YRange		$yrange
	OneOf		$oneof
	AnyOf		$anyof
```
Figure 2-8. Sample Parametric Study - Resulting File
```
This is job: 005.
Parameter values are:
	XRange		5
	YRange		1
	OneOf		1
	AnyOf		6
```

The command line parameters are used in the task as command line values. These commands are shown in Figure 2-9. They contain user defined parameters: oneof, anyof, xrange and yrange, as well as system defined parameters ENFJOBNAME, ENFHOSTNAME, and ENFOS. These parameters are replaced with their input values before the commands are executed, so that they are provided as command arguments.

Figure 2-9. Sample Parametric Study - Command Line Parameter Values

    # get job name, node host name, the operating system and user parameters
    node:execute echo This is job: $ENFJOBNAME, \
        executing on host $ENFHOSTNAME >output.txt
    node:execute echo The node runs the $ENFOS operating system >>output.txt

    # user parameters are provided on a command line
    node:execute echo Parameter values are: \
        OneOf $oneof, AnyOf $anyof >>output.txt
    node:execute echo Parameter values are: XRange $xrange, \
        YRange $yrange >>output.txt

The executing user application shows how to run a program that normally performs core job computation. These commands are shown in Figure 2-10. The sample study does not execute any real program, since these are application specific, but it includes a comment and a sleep statement for illustration. These can be replaced with a real application command.
Figure 2-10. Sample Parametric Study - Executing User Application
```
    # a user command is normally executed here, something like:
    # (uncomment the line below and insert real values for your application)
    #node:execute <user_command> <inputs> <outputs>

    # wait a few seconds to simulate a command execution
    node:sleep 3
```
The result files are copied from the node to the EnFuzion root system. These commands are shown in Figure 2-11. All files on the node are deleted after the job has completed, so it is important to copy all result files to the EnFuzion root system. Each job stores its result files to its own directory by specifying $ENFJOBNAME as the file subdirectory.
Figure 2-11. Sample Parametric Study - Results Files
```
    # copy the result files back to the root host
    copy node:input.txt $ENFJOBNAME/common.txt
    copy node:output.txt $ENFJOBNAME/.
    copy node:values.txt $ENFJOBNAME/.
```

Creating the Sample Plan File

This section provides a step by step instructions on how to create the sample plan file sample.pln with the Preparator. The Preparator is a tool that helps to create plan files and is included in EnFuzion by default. Plan files are text files and they can also be created with standard text editors.

On Windows NT/2000/XP, the Preparator can be started by clicking on the program, which is located in directory C:\enfuzion\bin by default. On Linux/Unix, the Preparator can be started from a command line as:

    enfpreparator

The Preparator includes a wizard, which provides a simple method for building plans. After the Preparator has started, it displays the opening wizard window as shown in Figure 2-12.

Figure 2-12. Wizard - Introduction Window

Press the Next button to continue to the next window.

The Parameter Description window is used to define a new parameter. Enter 'xrange' in the Name field and 'X-Range' in the Label field. This defines the parameter name as xrange, and its label for the application specific interface as X-Range. Select the Integer, Range button to specify the parameter as an integer range. These steps should produce the window in Figure 2-13.

Figure 2-13. Wizard - Parameter Description

Press the Set Value button to open another window for selecting parameter values. Enter '1' in the From field, '5' in the To field, and '1' in the Step field. The resulting window is shown in Figure 2-14.

Figure 2-14. Wizard - Parameter Values

Press the Apply button to define the parameter. The parameter definition text will be shown in the background window. A window to define a new parameter will be displayed as shown in Figure 2-15. Repeat the steps above to define the remaining three parameters. After all the parameters are defined, press the Next button.

Figure 2-15. Wizard - Select Parameter

Press the Next button to skip the Preprocessing window.

The wizard opens a new window to specify input files that are common to all jobs in the parametric study. Type 'input.txt' in the Input File field to produce the window shown in Figure 2-16.

Figure 2-16. Wizard - Common Input Files

Press the Apply to define the input.txt file as a common input file. Repeat the step for the template.txt file. At this stage, both input.txt and template.txt are defined as common input files in the nodestart task. Press the Next button to advance to the next window.

The Substitution Files window is used to define files with parameters that must be replaced with job specific input values. Enter 'template.txt' in the Source file on node field and 'values.txt' in the Destination file field. The resulting window is shown in Figure 2-17.

Figure 2-17. Wizard - File Based Parameters

Press the Next button to continue with the next window.

The User Command window is used to specify user commands that are executed for each job. Enter 'This is job: $ENFJOBNAME, executing on host $ENFHOSTNAME output.txt' in the User command field. This produces the window shown in Figure 2-18.

Figure 2-18. Wizard - User Commands

Press the Apply button to define the command. Repeat this step for the remaining commands. Press the Next button to go to the next window.

The Output Files window is used to define result files that are copied back to the EnFuzion root, before the job has completed. Enter 'input.txt' in the Source file on node field. Enter '$ENFJOBNAME/common.txt' in the Destination file on root field. This produces Figure 2-19.

Figure 2-19. Wizard - Result Files

Press the Apply button to define the result file. Repeat this step for the remaining two files. Press the Next button to go to the next window.

Press the Next button to skip the Post processing window. Press the OK button to complete the wizard. At this stage, the window contains the plan file in a text form as shown in Figure 2-20.

Figure 2-20. Wizard - Final Plan

Press File, Save to save the plan file.

This completes the plan creation process. You should have a complete plan file on the disk.

Creating the Sample Run File

The plan file is used by the Generator to create an application specific graphical user interface (shown in Figure 2-21). This interface is used to define input values and to produce a run file. The run file is then submitted to the Dispatcher for execution.

Figure 2-21. Sample Parametric Study - Application Specific User Interface

On Windows NT/2000/XP systems, the Generator is started simply by clicking on the sample.pln in the EnFuzion test directory. On Linux/Unix systems, the Generator is started with the following command, which must be executed in the $HOME/enfuzion/test directory:

    enfgenerator sample.pln

To produce a run file, select values for all the parameters from the application specific graphical user interface, and press File, Save Run to save the run file. The run file is executed by the Dispatcher as described in the Section called Execution of a Sample Parametric Study and the Section called Execution of a Sample Parametric Study.

Prev	Home	Next
Quick EnFuzion Setup Instructions for Linux/Unix	Up	Creating Your Own Parametric Study