Parameter Sweep Tool

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 (Vars, Expressions, 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 must specify a path, results_file, which is a CSV summary of the parameter sweep. Each column specifies a fixed parameter or the associated output, and each row is a single run with the specified parameters and resulting outputs.

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.

mpirun -n 2 python parameter_sweep_script.py

For advanced users, the parameter sweep tool can optionally take a MPI communicator as an argument.

Function Documentation

class watertap.tools.parameter_sweep.FixedSample(pyomo_object, *args, **kwargs)[source]
class watertap.tools.parameter_sweep.LatinHypercubeSample(pyomo_object, *args, **kwargs)[source]
class watertap.tools.parameter_sweep.LinearSample(pyomo_object, *args, **kwargs)[source]
class watertap.tools.parameter_sweep.NormalSample(pyomo_object, *args, **kwargs)[source]
class watertap.tools.parameter_sweep.RandomSample(pyomo_object, *args, **kwargs)[source]
class watertap.tools.parameter_sweep.SamplingType(value)[source]

An enumeration.

class watertap.tools.parameter_sweep.UniformSample(pyomo_object, *args, **kwargs)[source]
watertap.tools.parameter_sweep.parameter_sweep(model, sweep_params, outputs=None, csv_results_file=None, h5_results_file=None, optimize_function=<function _default_optimize>, optimize_kwargs=None, reinitialize_function=None, reinitialize_kwargs=None, reinitialize_before_sweep=False, mpi_comm=None, debugging_data_dir=None, interpolate_nan_outputs=False, num_samples=None, seed=None)[source]

This function offers a general way to perform repeated optimizations of a model for the purposes of exploring a parameter space while monitoring multiple outputs. If provided, writes single CSV file to results_file with all inputs and resulting outputs.

Parameters

  • model – A Pyomo ConcreteModel containing a watertap flowsheet, for best results it should be initialized before being passed to this function.

  • sweep_params – A dictionary containing the values to vary with the format sweep_params['Short/Pretty-print Name'] = (model.fs.variable_or_param[index], lower_limit, upper_limit, num_samples). A uniform number of samples num_samples will be take between the lower_limit and upper_limit.

  • outputs – An optional dictionary containing “short names” as keys and and Pyomo objects on model whose values to report as values. E.g., outputs['Short/Pretty-print Name'] = model.fs.variable_or_expression_to_report. If not provided, i.e., outputs = None, the default behavior is to save all model variables, parameters, and expressions which provides very thorough results at the cost of large file sizes.

  • csv_results_file (optional) – The path and file name where the results are to be saved; subdirectories will be created as needed.

  • h5_results_file (optional) – The file name without the extension where the results are to be saved; The path is identified from the arguments of csv_results_file. This filename is used when creating the H5 file and the companion text file which contains the variable names contained within the H5 file.

  • optimize_function (optional) – A user-defined function to perform the optimization of flowsheet model and loads the results back into model. The first argument of this function is model. The default uses the default IDAES solver, raising an exception if the termination condition is not optimal.

  • optimize_kwargs (optional) – Dictionary of kwargs to pass into every call to optimize_function. The first arg will always be model, e.g., optimize_function(model, **optimize_kwargs). The default uses no kwargs.

  • reinitialize_function (optional) – A user-defined function to perform the re-initialize the flowsheet model if the first call to optimize_function fails for any reason. After reinitialize_function, the parameter sweep tool will immediately call optimize_function again.

  • reinitialize_kwargs (optional) – Dictionary or kwargs to pass into every call to reinitialize_function. The first arg will always be model, e.g., reinitialize_function(model, **reinitialize_kwargs). The default uses no kwargs.

  • reinitialize_before_sweep (optional) – Boolean option to reinitialize the flow sheet model before every parameter sweep realization. The default is False. Note the parameter sweep model will try to reinitialize the solve regardless of the option if the run fails.

  • mpi_comm (optional) – User-provided MPI communicator for parallel parameter sweeps. If None COMM_WORLD will be used. The default is sufficient for most users.

  • debugging_data_dir (optional) – Save results on a per-process basis for parallel debugging purposes. If None no debugging data will be saved.

  • interpolate_nan_outputs (optional) – When the parameter sweep has finished, interior values of np.nan will be replaced with a value obtained via a linear interpolation of their surrounding valid neighbors. If true, a second output file with the extension “_clean” will be saved alongside the raw (un-interpolated) values.

  • num_samples (optional) – If the user is using sampling techniques rather than a linear grid of values, they need to set the number of samples

  • seed (optional) – If the user is using a random sampling technique, this sets the seed

Returns

A list were the first N columns are the values of the parameters passed

by sweep_params and the remaining columns are the values of the simulation identified by the outputs argument.

Return type

save_data