watertap.tools.parameter_sweep package

Submodules

watertap.tools.parameter_sweep.model_manager module

watertap.tools.parameter_sweep.parameter_sweep module

class watertap.tools.parameter_sweep.parameter_sweep.ParameterSweep(**options)[source]

Bases: _ParameterSweepBase, _ParameterSweepParallelUtils

class watertap.tools.parameter_sweep.parameter_sweep.RecursiveParameterSweep(**options)[source]

Bases: _ParameterSweepBase

watertap.tools.parameter_sweep.parameter_sweep_differential module

class watertap.tools.parameter_sweep.parameter_sweep_differential.DifferentialParameterSweep(**options)[source]

Bases: _ParameterSweepBase, _ParameterSweepParallelUtils

__init__(**options)[source]

watertap.tools.parameter_sweep.parameter_sweep_functions module

watertap.tools.parameter_sweep.parameter_sweep_functions.differential_parameter_sweep(build_model, build_sweep_params, build_differential_sweep_specs, build_outputs=None, csv_results_file_name=None, h5_results_file_name=None, h5_parent_group_name=None, optimize_function=None, optimize_kwargs=None, initialize_function=None, initialize_kwargs=None, initialize_before_sweep=False, probe_function=None, debugging_data_dir=None, interpolate_nan_outputs=False, num_samples=None, num_diff_samples=1, seed=None, guarantee_solves=False)[source]

This function is similar to the parameter_sweep function for exploring the parameter space while guranteeing a required number of solves. 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.

  • differential_sweep_specs – A specification dictionary that contains details for how to construct the parameter sweep dictionary for differential sweep. This is a nested dictionary where the first level denotes the variable names for which the differential sweep needs to be carried out. The second level denotes various options to be used for wach variable. The number of samples for each differential sweep is specified while initializing the DifferentialParameterSweep object wsing the keyword num_diff_samples e.g.

  • highlight:: (..) – {“fs.a”: {“diff_mode”: “sum”, “diff_sample_type”: NormalSample, “std_dev”: 0.01, “pyomo_object”: m.fs.input[“a”]}, “fs.b”: {“diff_mode”: “product”, “diff_sample_type”: UniformSample, “relative_lb”: 0.01, “relative_ub”: 0.01, “pyomo_object”: m.fs.input[“b”]}, “fs.c”: {“diff_mode”: “sum”, “diff_sample_type”: GeomSample, “relative_lb”: 0.01, “relative_ub”: 10.0, “pyomo_object”: m.fs.input[“c”]}}

  • outputs (optional) – 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_name (optional) – The path and file name to write a csv file. The default None does not write a csv file.

  • h5_results_file_name (optional) – The path and file name to write a h5 file. The default None does not write a file. Writing an h5 file will also create a companion text file {h5_results_file_name}.txt which contains the variable names contained within the H5 file.

  • h5_parent_group_name (optional) – Parent h5 groups for the parameter sweep inputs and outputs to be embedded in. The default is None and it accepts a string for the h5 group.

  • 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.

  • probe_function (optional) – A user-defined function that can cheaply check if a current model configuration is solvable without actually reinitializing or solving.

  • 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 grid of values, they need to set the required number of samples. This is the number of base solves that the user desires. The differential sweep will be performed on these base solves.

  • num_diff_samples (optional) – Number of samples for the differential sweep at a given base value.

  • 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

watertap.tools.parameter_sweep.parameter_sweep_functions.parameter_sweep(build_model, build_sweep_params, build_outputs=None, csv_results_file_name=None, h5_results_file_name=None, h5_parent_group_name=None, optimize_function=None, optimize_kwargs=None, reinitialize_function=None, reinitialize_kwargs=None, reinitialize_before_sweep=False, probe_function=None, debugging_data_dir=None, interpolate_nan_outputs=False, num_samples=None, seed=None, number_of_subprocesses=None, build_model_kwargs=None, build_sweep_params_kwargs=None, build_outputs_kwargs=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:

  • build_model – A function that can be called to build a Pyomo ConcreteModel, OR (deprecated) a Pyomo ConcreteModel containing a watertap flowsheet.

  • build_sweep_params – A function that can be called to build 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. OR (deprecated) the dictionary itself rather than a function for creating it.

  • outputs (optional) – An optional function to produce a 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. OR (deprecated) the dictionary itself rather than a function for creating it. If neither is 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_name (optional) – The path and file name to write a csv file. The default None does not write a csv file.

  • h5_results_file_name (optional) – The path and file name to write a h5 file. The default None does not write a file. Writing an h5 file will also create a companion text file {h5_results_file_name}.txt which contains the variable names contained within the H5 file.

  • h5_parent_group_name (optional) – Parent h5 groups for the parameter sweep inputs and outputs to be embedded in. The default is None and it accepts a string for the h5 group.

  • 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.

  • probe_function (optional) – A user-defined function that can cheaply check if a current model configuration is solvable without actually reinitializing or solving.

  • 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

  • number_of_subprocesses (optional) – Directive for fanning out subprocesses to perform parallel computation.

  • build_model_kwargs (optional) – A dictionary of kwargs to pass into the build_model function.

  • build_sweep_params_kwargs (optional) – A dictionary of kwargs to pass into the build_sweep_params function.

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

watertap.tools.parameter_sweep.parameter_sweep_functions.recursive_parameter_sweep(build_model, build_sweep_params, build_outputs=None, csv_results_file_name=None, h5_results_file_name=None, h5_parent_group_name=None, optimize_function=None, optimize_kwargs=None, reinitialize_function=None, reinitialize_kwargs=None, reinitialize_before_sweep=False, probe_function=None, debugging_data_dir=None, interpolate_nan_outputs=False, num_samples=None, seed=None, number_of_subprocesses=None)[source]

This function is similar to the parameter_sweep function for exploring the parameter space while guranteeing a required number of solves. 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_name (optional) – The path and file name to write a csv file. The default None does not write a csv file.

  • h5_results_file_name (optional) – The path and file name to write a h5 file. The default None does not write a file. Writing an h5 file will also create a companion text file {h5_results_file_name}.txt which contains the variable names contained within the H5 file.

  • h5_parent_group_name (optional) – Parent h5 groups for the parameter sweep inputs and outputs to be embedded in. The default is None and it accepts a string for the h5 group.

  • 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.

  • probe_function (optional) – A user-defined function that can cheaply check if a current model configuration is solvable without actually reinitializing or solving.

  • 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 required number of samples. This is the guaranteed number of solves that the user requires.

  • 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

watertap.tools.parameter_sweep.parameter_sweep_reader module

watertap.tools.parameter_sweep.parameter_sweep_reader.get_sweep_params_from_yaml(m, yaml_filename)[source]

Creates a dictionary of swept model parameters specified via yaml file

This function creates a dictionary of the items to vary during a parameter sweep where the variable name, model attribute, and sweeping domain are specified in a YAML file. The YAML file should have the following format:

A_comp:
    type: NormalSample
    param: fs.RO.A_comp
    mean: 4.0e-12
    std: 0.5e-12

where the top-level keyword can be any short, easily understood identifier for the parameter. type must be one of LinearSample, UniformSample, NormalSample, or LatinHypercubeSample. param must be a valid dot-sperated string path to the object attribute (in this case, an RO attribute on the flowsheet m) that you wish to vary. The remaining arguments are dependent on the sample type selected. For NormalSample information about the mean and standard deviation is required. Consult the parameter_sweep help for more information on the different sample classes.

Parameters:

  • m (pyomo model) – The flowsheet containing the model to deploy with the parameter sweep tool.

  • yaml_filename (str) – The path to the yaml file.

Returns:

A dictionary containing different instances of parameter sweep samples

Return type:

sweep_params (dict)

watertap.tools.parameter_sweep.parameter_sweep_reader.set_defaults_from_yaml(m, yaml_filename, verbose=False)[source]

Sets default model values using values stored in a yaml file

This function reads a yaml file with the structure:

fs.path.to.attribute_1: 0.123
fs.path.to.attribute_2: 1.234
...

and uses the (key, default_value) pairs to set default values for the attributes in model m.

Parameters:

  • m (pyomo model) – The flowsheet containing the model to set default values for

  • yaml_filename (str) – The path to the yaml file.

Returns:

N/A

watertap.tools.parameter_sweep.parameter_sweep_writer module

watertap.tools.parameter_sweep.paramter_sweep_parallel_utils module

watertap.tools.parameter_sweep.paramter_sweep_parallel_utils.do_build(param_sweep_instance)[source]

Used to pass into the parallel manager to build the parameters necessary for the sweep function. Defined at the top level so it’s picklable.

watertap.tools.parameter_sweep.paramter_sweep_parallel_utils.do_execute(local_combo_array, param_sweep_instance, model, sweep_params, outputs)[source]

Used to pass into the parallel manager in order to execute the sweep for a set of local values. Defined at the top level so it’s picklable.

watertap.tools.parameter_sweep.paramter_sweep_parallel_utils.return_none(model, outputkeys=None)[source]

Used so that build_outputs=None is a valid usage of the parameter sweep tool without requiring the user to wrap it in a function.

watertap.tools.parameter_sweep.sampling_types module

class watertap.tools.parameter_sweep.sampling_types.FixedSample(pyomo_object, *args, **kwargs)[source]

Bases: _Sample

class watertap.tools.parameter_sweep.sampling_types.GeomSample(pyomo_object, *args, **kwargs)[source]

Bases: FixedSample

class watertap.tools.parameter_sweep.sampling_types.LatinHypercubeSample(pyomo_object, *args, **kwargs)[source]

Bases: _Sample

class watertap.tools.parameter_sweep.sampling_types.LinearSample(pyomo_object, *args, **kwargs)[source]

Bases: FixedSample

class watertap.tools.parameter_sweep.sampling_types.NormalSample(pyomo_object, *args, **kwargs)[source]

Bases: RandomSample

class watertap.tools.parameter_sweep.sampling_types.PredeterminedFixedSample(pyomo_object, *args, **kwargs)[source]

Bases: FixedSample

Similar to other fixed sampling types except the setup function arguments. In this case a user needs to specify a numpy array (or a list) of predetermined values. For example:

sample_obj = PredeterminedFixedSample(np.array([1,2,3,4]))

class watertap.tools.parameter_sweep.sampling_types.PredeterminedRandomSample(pyomo_object, *args, **kwargs)[source]

Bases: RandomSample

Similar to other fixed sampling types except the setup function arguments. In this case a user needs to specify a numpy array (or a list) of predetermined values. For example:

sample_obj = PredeterminedRandomSample(np.array([1,2,3,4]))

class watertap.tools.parameter_sweep.sampling_types.RandomSample(pyomo_object, *args, **kwargs)[source]

Bases: _Sample

class watertap.tools.parameter_sweep.sampling_types.ReverseGeomSample(pyomo_object, *args, **kwargs)[source]

Bases: FixedSample

class watertap.tools.parameter_sweep.sampling_types.SamplingType(value)[source]

Bases: Enum

An enumeration.

class watertap.tools.parameter_sweep.sampling_types.SetMode(value)[source]

Bases: Enum

An enumeration.

class watertap.tools.parameter_sweep.sampling_types.UniformSample(pyomo_object, *args, **kwargs)[source]

Bases: RandomSample

Module contents