DOEDriver

DOEDriver facilitates performing a design of experiments (DOE) with your OpenMDAO model. It will run your model multiple times with different values for the design variables depending on the selected input generator. A number of generators are available, each with its own parameters that can be specified when it is instantiated:

Note

FullFactorialGenerator, PlackettBurmanGenerator, BoxBehnkenGenerator and LatinHypercubeGenerator are provided via the pyDOE2 package, which is an updated version of pyDOE. See the original pyDOE page for information on those algorithms.

The generator instance may be supplied as an argument to the DOEDriver or as an option.

DOEDriver Options

Option

Default

Acceptable Values

Acceptable Types

Description

debug_print

[]

N/A

[‘list’]

List of what type of Driver variables to print at each iteration. Valid items in list are ‘desvars’, ‘ln_cons’, ‘nl_cons’, ‘objs’, ‘totals’

generator

DOEGenerator

N/A

[‘DOEGenerator’]

The case generator. If default, no cases are generated.

procs_per_model

1

N/A

[‘int’]

Number of processors to give each model under MPI.

run_parallel

False

[True, False]

[‘bool’]

Set to True to execute cases in parallel.

DOEDriver Constructor

The call signature for the DOEDriver constructor is:

DOEDriver.__init__(generator=None, **kwargs)[source]

Construct A DOEDriver.

Parameters
generatorDOEGenerator, list or None

The case generator or a list of DOE cases.

**kwargsdict of keyword arguments

Keyword arguments that will be mapped into the Driver options.

Simple Example

UniformGenerator implements the simplest method and will generate a requested number of samples randomly selected from a uniform distribution across the valid range for each design variable. This example demonstrates its use with a model built on the Paraboloid Component. An SqliteRecorder is used to capture the cases that were generated. We can see that that the model was evaluated at random values of x and y between -10 and 10, per the lower and upper bounds of those design variables.

import openmdao.api as om
from openmdao.test_suite.components.paraboloid import Paraboloid

prob = om.Problem()
model = prob.model

model.add_subsystem('comp', Paraboloid(), promotes=['*'])

model.add_design_var('x', lower=-10, upper=10)
model.add_design_var('y', lower=-10, upper=10)
model.add_objective('f_xy')

prob.driver = om.DOEDriver(om.UniformGenerator(num_samples=5))
prob.driver.add_recorder(om.SqliteRecorder("cases.sql"))

prob.setup()

prob.set_val('x', 0.0)
prob.set_val('y', 0.0)

prob.run_driver()
prob.cleanup()

cr = om.CaseReader("cases.sql")
cases = cr.list_cases('driver')

print(len(cases))
driver
    rank0:DOEDriver_Uniform|0
driver
    rank0:DOEDriver_Uniform|1
driver
    rank0:DOEDriver_Uniform|2
driver
    rank0:DOEDriver_Uniform|3
driver
    rank0:DOEDriver_Uniform|4
5
values = []
for case in cases:
    outputs = cr.get_case(case).outputs
    values.append((outputs['x'], outputs['y'], outputs['f_xy']))

print("\n".join(["x: %5.2f, y: %5.2f, f_xy: %6.2f" % xyf for xyf in values]))
x: -3.83, y:  8.84, f_xy: 174.74
x:  7.77, y:  7.21, f_xy: 201.25
x:  3.06, y: -3.11, f_xy: -11.74
x:  0.98, y:  6.30, f_xy: 113.43
x: -8.03, y:  6.02, f_xy: 170.70

Running a DOE in Parallel

In a parallel processing environment, it is possible for DOEDriver to run cases concurrently. This is done by setting the run_parallel option to True as shown in the following example and running your script using MPI.

Here we are using the FullFactorialGenerator with 3 levels to generate inputs for our Paraboloid model. With two inputs, \(3^2=9\) cases have been generated. In this case we are running on two processors and have specified options['run_parallel']=True to run cases on all available processors. The cases have therefore been split with 5 cases run on the first processor and 4 cases on the second.

Note that, when running in parallel, the SqliteRecorder will generate a separate case file for each processor on which cases are recorded. The case files will have a suffix indicating the recording rank and a message will be displayed indicating the file name, as seen in the example.

import openmdao.api as om
from openmdao.test_suite.components.paraboloid import Paraboloid

from mpi4py import MPI

prob = om.Problem()

prob.model.add_subsystem('comp', Paraboloid(), promotes=['x', 'y', 'f_xy'])
prob.model.add_design_var('x', lower=0.0, upper=1.0)
prob.model.add_design_var('y', lower=0.0, upper=1.0)
prob.model.add_objective('f_xy')

prob.driver = om.DOEDriver(om.FullFactorialGenerator(levels=3))
prob.driver.options['run_parallel'] = True
prob.driver.options['procs_per_model'] = 1

prob.driver.add_recorder(om.SqliteRecorder("cases.sql"))

prob.setup()
prob.run_driver()
(rank 0) Note: SqliteRecorder is running on multiple processors. Cases from rank 0 are being written to cases.sql_0.
(rank 1) Note: SqliteRecorder is running on multiple processors. Cases from rank 1 are being written to cases.sql_1.
prob.cleanup()

print(MPI.COMM_WORLD.size)
(rank 0) 2
(rank 1) 2
# check recorded cases from each case file
rank = MPI.COMM_WORLD.rank
filename = "cases.sql_%d" % rank
print(filename)
(rank 0) cases.sql_0
(rank 1) cases.sql_1
cr = om.CaseReader(filename)
cases = cr.list_cases('driver')
print(len(cases))
(rank 0) driver
    rank0:DOEDriver_FullFactorial|0
driver
    rank0:DOEDriver_FullFactorial|1
driver
    rank0:DOEDriver_FullFactorial|2
driver
    rank0:DOEDriver_FullFactorial|3
driver
    rank0:DOEDriver_FullFactorial|4
5
(rank 1) driver
    rank1:DOEDriver_FullFactorial|0
driver
    rank1:DOEDriver_FullFactorial|1
driver
    rank1:DOEDriver_FullFactorial|2
driver
    rank1:DOEDriver_FullFactorial|3
4
values = []
for case in cases:
    outputs = cr.get_case(case).outputs
    values.append((outputs['x'], outputs['y'], outputs['f_xy']))

print("\n"+"\n".join(["x: %5.2f, y: %5.2f, f_xy: %6.2f" % xyf for xyf in values]))
(rank 0) x:  0.00, y:  0.00, f_xy:  22.00
x:  1.00, y:  0.00, f_xy:  17.00
x:  0.50, y:  0.50, f_xy:  23.75
x:  0.00, y:  1.00, f_xy:  31.00
x:  1.00, y:  1.00, f_xy:  27.00
(rank 1) x:  0.50, y:  0.00, f_xy:  19.25
x:  0.00, y:  0.50, f_xy:  26.25
x:  1.00, y:  0.50, f_xy:  21.75
x:  0.50, y:  1.00, f_xy:  28.75

Running a DOE in Parallel with a Parallel Model

If the model that is being subjected to the DOE is also parallel, then the total number of processors should reflect the model size as well as the desired concurrency.

To illustrate this, we will demonstrate performing a DOE on a model based on the ParallelGroup example:

class FanInGrouped(om.Group):
    """
    Topology where two components in a Group feed a single component
    outside of that Group.
    """

    def __init__(self):
        super().__init__()

        self.set_input_defaults('x1', 1.0)
        self.set_input_defaults('x2', 1.0)

        self.sub = self.add_subsystem('sub', om.ParallelGroup(),
                                      promotes_inputs=['x1', 'x2'])
        self.sub.add_subsystem('c1', om.ExecComp(['y=-2.0*x']),
                               promotes_inputs=[('x', 'x1')])
        self.sub.add_subsystem('c2', om.ExecComp(['y=5.0*x']),
                               promotes_inputs=[('x', 'x2')])

        self.add_subsystem('c3', om.ExecComp(['y=3.0*x1+7.0*x2']))

        self.connect("sub.c1.y", "c3.x1")
        self.connect("sub.c2.y", "c3.x2")

In this case, the model itself requires two processors, so in order to run cases concurrently we need to allocate at least four processors in total. We can allocate as many processors as we have available, however the number of processors must be a multiple of the number of processors per model, which is 2 here. Regardless of how many processors we allocate, we need to tell the DOEDriver that the model needs 2 processors, which is done by specifying options['procs_per_model']=2. From this, the driver figures out how many models it can run in parallel, which in this case is also 2.

The SqliteRecorder will record cases on the first two processors, which serve as the “root” processors for the parallel cases.

import openmdao.api as om
from openmdao.test_suite.groups.parallel_groups import FanInGrouped

from mpi4py import MPI

prob = om.Problem(FanInGrouped())

prob.model.add_design_var('x1', lower=0.0, upper=1.0)
prob.model.add_design_var('x2', lower=0.0, upper=1.0)
prob.model.add_objective('c3.y')

prob.driver = om.DOEDriver(om.FullFactorialGenerator(levels=3))
prob.driver.add_recorder(om.SqliteRecorder("cases.sql"))

# the FanInGrouped model uses 2 processes, so we can run
# two instances of the model at a time, each using 2 of our 4 procs
prob.driver.options['run_parallel'] = True
prob.driver.options['procs_per_model'] = procs_per_model = 2

prob.setup()
prob.run_driver()
prob.cleanup()

# a separate case file will be written by rank 0 of each parallel model
# (the top two global ranks)
rank = prob.comm.rank

num_models = prob.comm.size // procs_per_model

if rank < num_models:
    filename = "cases.sql_%d" % rank

    cr = om.CaseReader(filename)
    cases = cr.list_cases('driver')

    values = []
    for case in cases:
        outputs = cr.get_case(case).outputs
        values.append((outputs['x1'], outputs['x2'], outputs['c3.y']))

    print("\n"+"\n".join(["x1: %5.2f, x2: %5.2f, c3.y: %6.2f" % (x1, x2, y) for x1, x2, y in values]))
Note: SqliteRecorder is running on multiple processors. Cases from rank 0 are being written to cases.sql_0.
driver
    rank0:DOEDriver_FullFactorial|0
driver
    rank0:DOEDriver_FullFactorial|1
driver
    rank0:DOEDriver_FullFactorial|2
driver
    rank0:DOEDriver_FullFactorial|3
driver
    rank0:DOEDriver_FullFactorial|4

x1:  0.00, x2:  0.00, c3.y:   0.00
x1:  1.00, x2:  0.00, c3.y:  -6.00
x1:  0.50, x2:  0.50, c3.y:  14.50
x1:  0.00, x2:  1.00, c3.y:  35.00
x1:  1.00, x2:  1.00, c3.y:  29.00

Note: SqliteRecorder is running on multiple processors. Cases from rank 1 are being written to cases.sql_1.
driver
    rank1:DOEDriver_FullFactorial|0
driver
    rank1:DOEDriver_FullFactorial|1
driver
    rank1:DOEDriver_FullFactorial|2
driver
    rank1:DOEDriver_FullFactorial|3

x1:  0.50, x2:  0.00, c3.y:  -3.00
x1:  0.00, x2:  0.50, c3.y:  17.50
x1:  1.00, x2:  0.50, c3.y:  11.50
x1:  0.50, x2:  1.00, c3.y:  32.00


Using Prepared Cases

If you have a previously generated set of cases that you want to run using DOEDriver, there are a couple of ways to do that. The first is to provide those inputs via an external file in the CSV (comma separated values) format. The file should be organized with one column per design variable, with the first row containing the names of the design variables. The following example demonstrates how to use such a file to run a DOE using the CSVGenerator:

import openmdao.api as om
from openmdao.test_suite.components.paraboloid import Paraboloid

prob = om.Problem()
model = prob.model

model.add_subsystem('comp', Paraboloid(), promotes=['x', 'y', 'f_xy'])

model.add_design_var('x', lower=0.0, upper=1.0)
model.add_design_var('y', lower=0.0, upper=1.0)
model.add_objective('f_xy')

prob.setup()

prob.set_val('x', 0.0)
prob.set_val('y', 0.0)

# this file contains design variable inputs in CSV format
with open('cases.csv', 'r') as f:
    print(f.read())
x ,   y
0.0,  0.0
0.5,  0.0
1.0,  0.0
0.0,  0.5
0.5,  0.5
1.0,  0.5
0.0,  1.0
0.5,  1.0
1.0,  1.0
# run problem with DOEDriver using the CSV file
prob.driver = om.DOEDriver(om.CSVGenerator('cases.csv'))
prob.driver.add_recorder(om.SqliteRecorder("cases.sql"))

prob.run_driver()
prob.cleanup()

cr = om.CaseReader("cases.sql")
cases = cr.list_cases('driver')

values = []
for case in cases:
    outputs = cr.get_case(case).outputs
    values.append((outputs['x'], outputs['y'], outputs['f_xy']))

print("\n".join(["x: %5.2f, y: %5.2f, f_xy: %6.2f" % xyf for xyf in values]))
driver
    rank0:DOEDriver_CSV|0
driver
    rank0:DOEDriver_CSV|1
driver
    rank0:DOEDriver_CSV|2
driver
    rank0:DOEDriver_CSV|3
driver
    rank0:DOEDriver_CSV|4
driver
    rank0:DOEDriver_CSV|5
driver
    rank0:DOEDriver_CSV|6
driver
    rank0:DOEDriver_CSV|7
driver
    rank0:DOEDriver_CSV|8
x:  0.00, y:  0.00, f_xy:  22.00
x:  0.50, y:  0.00, f_xy:  19.25
x:  1.00, y:  0.00, f_xy:  17.00
x:  0.00, y:  0.50, f_xy:  26.25
x:  0.50, y:  0.50, f_xy:  23.75
x:  1.00, y:  0.50, f_xy:  21.75
x:  0.00, y:  1.00, f_xy:  31.00
x:  0.50, y:  1.00, f_xy:  28.75
x:  1.00, y:  1.00, f_xy:  27.00

The second method is to provide the data directly as a list of cases, where each case is a collection of name/value pairs for the design variables. You might use this method if you want to generate the cases programmatically via another algorithm or if the data is available in some format other than a CSV file and you can reformat it into this simple list structure. The DOEGenerator you would use in this case is the ListGenerator, but if you pass a list directly to the DOEDriver it will construct the ListGenerator for you. In the following example, a set of cases has been pre-generated and saved in JSON (JavaScript Object Notation) format. The data is decoded and provided to the DOEDriver as a list:

import openmdao.api as om
from openmdao.test_suite.components.paraboloid import Paraboloid

import json

prob = om.Problem()
model = prob.model

model.add_subsystem('comp', Paraboloid(), promotes=['x', 'y', 'f_xy'])

model.add_design_var('x', lower=0.0, upper=1.0)
model.add_design_var('y', lower=0.0, upper=1.0)
model.add_objective('f_xy')

prob.setup()

prob.set_val('x', 0.0)
prob.set_val('y', 0.0)

# load design variable inputs from JSON file and decode into list
with open('cases.json', 'r') as f:
    json_data = f.read()

print(json_data)
[[["x", [0.0]], ["y", [0.0]]],
 [["x", [0.5]], ["y", [0.0]]],
 [["x", [1.0]], ["y", [0.0]]],
 [["x", [0.0]], ["y", [0.5]]],
 [["x", [0.5]], ["y", [0.5]]],
 [["x", [1.0]], ["y", [0.5]]],
 [["x", [0.0]], ["y", [1.0]]],
 [["x", [0.5]], ["y", [1.0]]],
 [["x", [1.0]], ["y", [1.0]]]]
case_list = json.loads(json_data)

print(case_list)
[[['x', [0.0]], ['y', [0.0]]], [['x', [0.5]], ['y', [0.0]]], [['x', [1.0]], ['y', [0.0]]], [['x', [0.0]], ['y', [0.5]]], [['x', [0.5]], ['y', [0.5]]], [['x', [1.0]], ['y', [0.5]]], [['x', [0.0]], ['y', [1.0]]], [['x', [0.5]], ['y', [1.0]]], [['x', [1.0]], ['y', [1.0]]]]
# create DOEDriver using provided list of cases
prob.driver = om.DOEDriver(case_list)

# a ListGenerator was created
print(type(prob.driver.options['generator']))
<class 'openmdao.drivers.doe_generators.ListGenerator'>
prob.driver.add_recorder(om.SqliteRecorder("cases.sql"))

prob.run_driver()
prob.cleanup()

cr = om.CaseReader("cases.sql")
cases = cr.list_cases('driver')

values = []
for case in cases:
    outputs = cr.get_case(case).outputs
    values.append((outputs['x'], outputs['y'], outputs['f_xy']))

print("\n".join(["x: %5.2f, y: %5.2f, f_xy: %6.2f" % xyf for xyf in values]))
driver
    rank0:DOEDriver_List|0
driver
    rank0:DOEDriver_List|1
driver
    rank0:DOEDriver_List|2
driver
    rank0:DOEDriver_List|3
driver
    rank0:DOEDriver_List|4
driver
    rank0:DOEDriver_List|5
driver
    rank0:DOEDriver_List|6
driver
    rank0:DOEDriver_List|7
driver
    rank0:DOEDriver_List|8
x:  0.00, y:  0.00, f_xy:  22.00
x:  0.50, y:  0.00, f_xy:  19.25
x:  1.00, y:  0.00, f_xy:  17.00
x:  0.00, y:  0.50, f_xy:  26.25
x:  0.50, y:  0.50, f_xy:  23.75
x:  1.00, y:  0.50, f_xy:  21.75
x:  0.00, y:  1.00, f_xy:  31.00
x:  0.50, y:  1.00, f_xy:  28.75
x:  1.00, y:  1.00, f_xy:  27.00

Warning

When using pre-generated cases via CSVGenerator or ListGenerator, there is no enforcement of the declared bounds on a design variable as with the algorithmic generators.

Tags

Driver, DOE