Parameter Sweep
Overview
The parameter sweep tool systematically fixes variables or modifies
mutable parameters on a flowsheet (or Pyomo ConcreteModel), optimizes
the flowsheet, and reports user-specified results.
The parameter sweep tool can be operated in one of two ways: sweeping a
fixed set of parameters, or allowing for random samples from a distribution.
While different fixed or random sampling types can be combined, in a single
parameter sweep the user must use either all fixed or all random sampling types.
(This implementation detail may be relaxed in future releases.)
For the “fixed” sampling type, LinearSample, the parameter sweep tool will evaluate the
cross product of all the specified parameters, whereas with the “random” sampling
types UniformSample and NormalSample the parameter sweep tool will evaluate
a fixed number of samples specified in num_samples. With either sampling type,
the values of the Pyomo objects (Var s, NamedExpression s, etc.), that the user specifies
in outputs.
For each item the user wants to change, they specify a sweep_params dictionary.
The keys are “short” names, and the values are one of the included Sample objects.
In all cases the Sample objects are instantiated with the Pyomo object to be changed,
with additional arguements depending on the sampling type. For example, for the fixed
LinearSample the user would also specify a lower limit, an upper limit, and the number
of elements to be sampled for this parameter between the lower limit and upper limit.
Each item should be sampled at least twice to capture the upper and lower
limit. The random UniformSample requires a lower limit and upper limit, and the
NormalSample requires a mean and standard deviation.
In addition to the parameters to sweep and the values to track for output,
the user must provide an optimize_function, which takes the model as an
attribute calls an optimization routine to solve it for the updated parameters.
Should the call to optimize_function fail, and a reinitialize_function is not
specified, the outputs will be reported as NaN for that parameter set.
The user can optionally specify a reinitialize_function in case any piece
of the optimize_function fails – after the call to reinitialize_function
the model should be in a state ready to optimize again. If the reinitialize_function
or the second call to the optimize_function fail for any reason, the outputs will
be reported as NaN for that parameter set.
The parameter sweep tool maintains the state of the flowsheet / Pyomo model between
calls to optimize_function to take advantage of initializations provided by
earlier solutions. If this behavior is undesirable, the user should re-initialize
their flowsheet as part of their optimize_function.
Finally, the user can specify a csv_results_file_name and/or an h5_results_file_name,
which will write the outputs to disk in a CSV and/or H5 format, respectively.
In the CSV results
file, each column specifies a fixed parameter or the associated output, and each row
is a single run with the specified parameters and resulting outputs. The H5 file
contains the parameter sweep inputs and the outputs stored in a dictionary-like format.
Additionally, when an H5 file is written, a companion text file is created with the name
h5_results_file_name + ".txt". This text file contains the metadata of the H5 results
file.
Parallel Usage
The parameter sweep tool can optionally utilize mpi4py to split the parameter
sweep over multiple processors. If mpi4py is installed in the user’s conda environment,
a script utilizing the parameter sweep tool can be run in parallel, in this example
using two threads.
mpiexec -n 2 python parameter_sweep_script.py
For advanced users, the parameter sweep tool can optionally take a MPI communicator as an argument.