Questions? Feedback? powered by Olark live chat software
Resources Home

Run a Design of Experiments (DOE) Job

The DOE job type allows you to run your simulation code multiple times for a range of input parameters. This tutorial demonstrates how to use this feature with a simple example.


Please contact us if you're having trouble.


Import Job Setup Get Job Results

About this simulation

This example uses the OpenFOAM simpleFOAM solver. This is a steady-state solver for incompressible turbulent flow. It can be used to find a reasonable initial condition for a transient analysis. This 2D example of steady state flow around an airfoil is based on the example from the OpenFOAM v2.4.0 tutorials.

The compressed archive airFoil2D_DOE.tar.gz contains the original example's input files, with the exception of airFoil2D_DOE/0/U, the file which defines the freestream velocity. This DOE will run the simulation for a variety of input conditions using a template file to vary the magnitude of the freestream velocity vector and create a different version of the file airFoil2D_DOE/0/U for each run in the simulation.

DOE Job: Input Files

The first stage in this process is to change the Job Type to DOE and upload the file airFoil2D_DOE.tar.gz. The screenshot below, with modified fields highlighted in red, shows how your Input Files setup page should look on completion of this step.


DOE Job: Parallel Settings

The Parallel Settings stage is where the parameter space for your DOE is defined. For this example, two variables, Xvelocity and Yvelocity are specified. Click on the Use a run definition file (CSV) radio button and use the Choose File button to upload the file freestreamValue.csv. The image below shows how your Parallel Settings setup page should look on completion of this step.


The file freestreamValue.csv defines three simulations and consists of:


These values represent the X and Y components of the freestream velocity for values of the angle of attack, commonly known as alpha, from -1 to 13 degrees, in increments of 0.5 degrees. The magnitude of the freestream velocity is held constant, and is the same as that defined in the airFoil2D tutorial included with OpenFOAM v2.4.0. Using the Rescale DOE functionality, we can characterize the performance of the airfoil under a range of angles of attack in a single job.

For simulation codes requiring fixed width input, or input in a specific notation, using the comma separated variable (CSV) file input option will ensure each value is substituted into your populated input file in exactly the form required. Additional flexibility with input data can be achieved by using formatting statements in your template files to specify the exact strings that will be substituted into your template file.

Alternatively, you can specify the variables directly on the Rescale platform by selecting Specify your variables here. Here you can either select Cross Product (shown below) or Monte Carlo. Selecting Cross Product allows you to create multiple variables in a specified domain (with a specified increment). The platform then automatically performs runs for every combination of the variables.


Selecting Monte Carlo you can specify variables to sampled from a variety of probability distributions. The platform again automatically performs runs for every combination of the variables. For this tutorial, however, we will continue with the specified definition file as discussed prior.

DOE Job: Templates

Template files for DOE jobs are simulation input files in which the values of parameters have been replaced with string references to those parameters. These string references are substituted with the actual parameter values at runtime. The populated template file can be given a modified file name to be passed to the analysis executable.


For this example, use the Choose File button to upload the file, Utemplate and edit the processed file name to be airFoil2D_DOE/0/U as shown above. The X and Y components of velocity specified in the original file U were:

uniform (25.68290046 -4.068847993 0);

In Utemplate, these values have been replaced with the reference strings:

uniform (${Xvelocity} ${Yvelocity} 0);

For each run, a unique input file named airFoil2D_DOE/0/U is created from the template and values substituted for the parameters Xvelocity and Yvelocity.

DOE Job: Software Settings


The next stage of the setup process is Software Settings. Access this by clicking on the Analysis icon. Type "OpenFOAM" in the search field, shown highlighted in red above, and select the OpenFOAM icon.

Enter the Command:


The Rescale platform automatically extracts the file Allrun with other runtime files contained in the compressed archive airFoil2D_DOE.tar.gz prior to beginning the simulation.

The screenshot below, with modified fields highlighted in red, shows how your Software Settings setup page should look on completion of this step. Ensure that you have selected OpenFOAM version 2.4.0


DOE Job: Hardware Settings


When the Job Type is DOE, the hardware settings allow you to decide how many simultaneous runs of your analysis will take place. For software that can take advantage of multiple cores, e.g. MPI codes, you can increase the value of Cores / slot to dedicate more cores to each DOE task.

In this case, we can select Number of Task Slots of 1, Number of Cores / Slot of 1, and Core Type as Nickel.

If you selected 3 task slots instead of 1, simultaneous runs of three of the tasks defined in the CSV file would take place, reducing the overall completion time for the job.

DOE Job: Review


Save the job and move to the Review section. The job is now ready to be run by clicking on the blue button labeled Submit.


When running a DOE Job Type with Task Slots greater than 1, the Status page will allow users to monitor their runtime files for multiple cases running concurrently using Rescale's Live Tailing feature. In this case, since Task Slots equals one, only one run is active at a time.

In the screenshot below, run 2 of the DOE is executing. The log file shared/airFoil2D_DOE/log.simpleFoam has been selected and its contents are shown in the live tailing window.


When all of the runs have completed the Status page should look like the one shown below.




The Results page allows you to examine the duration of each run defined in the job, download a zip archive consisting of run files for every case (when complete), download a zip archive consisting of run files for an individual case, or inspect an individual run more closely. The Results page for Run 2 is highlighted below. Note that if you click on Download before the Status page shows Cluster stopped in the Job Log section, then you may download a zip file containing data for only some of the runs.


Template Variable Formatting

The Rescale "Design of Experiments" (DOE) job type allows you to specify your runs and variables by means of these options:

  • Use a Run Definition File (CSV): each row is a case - also known as a run or Child Run
  • Specify your variables here: variable ranges are specified in your browser

Each of these options provides flexibility in how the variables you specify get transformed for use as input to each run of the DOE. This is done by means of template variable formatting.

Template files contain references to the variables that get substituted, at run- time, with values applicable to each Child Run. The basic placeholder for a variable, such as "x", in a template file looks like this:


If you use this syntax and specify your variables in a CSV file, then we will replace the placeholder with the value from your CSV without any modification. This is useful if the simulation code you are using has fixed-width text input files. This can be also useful if you would like to include non-numeric data in a file specific to that case. For example, you might include a description of each case as a comment in an input file, which may be more meaningful than the identifier we automatically assign to that case. So if your CSV looks like this:

description, v, z
case 1a, 2.2, 3.4
case 1b, 2.3, 3.4
case 2a, 3.1, 3.2

And your input file template looks like this:

# ${description}
vel: ${v}
z: ${z}

Then the processed template for the first case would look like this:

# case 1a
vel: 2.2
z: 3.4

You may prefer to have a specific consistent number format in the file, regardless of how the variable was specified in the CSV or how you specified it in the browser. For this situation, you can supply an additional format instruction, using a "0" or "#" for a digit, where trailing zeros are absent if the "#" symbol is used. Here are some examples:

x ${x?string("0")} ${x?string("0.0")} ${x?string("0.00##")}
0.9 1 0.9 0.90
1.49 1 1.5 1.49
-55.123 -55 -55.1 -55.123
9810 9810 9810.0 9810.00

Notice that when the format string has fewer digits to the right of the decimal place than the value, then the value will be rounded accordingly. Scientific notation can be used as shown below:

x ${x?string("0E0")} ${x?string("000E00")} ${x?string("0.0##E0")}
0.9 9E-1 90E-02 9.0E-1
1.49 1E0 15E-01 1.49E0
-55.123 -6E1 -55E00 -5.512E1
9810 1E4 98E02 9.81E3
Last Updated: Apr 24, 2017 05:56PM PDT

Powered by
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
Invalid characters found