:py:mod:`parameter_sweep.functions` =================================== .. py:module:: parameter_sweep.functions Module Contents --------------- Functions ~~~~~~~~~ .. autoapisummary:: parameter_sweep.functions.parameter_sweep parameter_sweep.functions.recursive_parameter_sweep parameter_sweep.functions.differential_parameter_sweep .. py:function:: 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) 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. :param build_model: A function that can be called to build a Pyomo :class:`~pyomo.environ.ConcreteModel`, OR (deprecated) a Pyomo :class:`~pyomo.environ.ConcreteModel` containing a watertap flowsheet. :param 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. :param outputs: 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. :type outputs: optional :param csv_results_file_name: The path and file name to write a csv file. The default `None` does not write a csv file. :type csv_results_file_name: optional :param h5_results_file_name: 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. :type h5_results_file_name: optional :param h5_parent_group_name: 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. :type h5_parent_group_name: optional :param optimize_function: 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. :type optimize_function: optional :param optimize_kwargs: 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. :type optimize_kwargs: optional :param reinitialize_function: 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. :type reinitialize_function: optional :param reinitialize_kwargs: 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. :type reinitialize_kwargs: optional :param reinitialize_before_sweep: 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. :type reinitialize_before_sweep: optional :param probe_function: A user-defined function that can cheaply check if a current model configuration is solvable without actually reinitializing or solving. :type probe_function: optional :param debugging_data_dir: Save results on a per-process basis for parallel debugging purposes. If None no `debugging` data will be saved. :type debugging_data_dir: optional :param interpolate_nan_outputs: 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. :type interpolate_nan_outputs: optional :param num_samples: If the user is using sampling techniques rather than a linear grid of values, they need to set the number of samples :type num_samples: optional :param seed: If the user is using a random sampling technique, this sets the seed :type seed: optional :param number_of_subprocesses: Directive for fanning out subprocesses to perform parallel computation. :type number_of_subprocesses: optional :param build_model_kwargs: A dictionary of kwargs to pass into the build_model function. :type build_model_kwargs: optional :param build_sweep_params_kwargs: A dictionary of kwargs to pass into the build_sweep_params function. :type build_sweep_params_kwargs: optional :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. :rtype: save_data .. py:function:: 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) This function is similar to the :func:`~parameter_sweep.functions.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. :param model: A Pyomo :class:`~pyomo.environ.ConcreteModel` containing a watertap flowsheet, for best results it should be initialized before being passed to this function. :param 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``. :param 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. :param csv_results_file_name: The path and file name to write a csv file. The default `None` does not write a csv file. :type csv_results_file_name: optional :param h5_results_file_name: 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. :type h5_results_file_name: optional :param h5_parent_group_name: 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. :type h5_parent_group_name: optional :param optimize_function: 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. :type optimize_function: optional :param optimize_kwargs: 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. :type optimize_kwargs: optional :param reinitialize_function: 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. :type reinitialize_function: optional :param reinitialize_kwargs: 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. :type reinitialize_kwargs: optional :param reinitialize_before_sweep: 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. :type reinitialize_before_sweep: optional :param probe_function: A user-defined function that can cheaply check if a current model configuration is solvable without actually reinitializing or solving. :type probe_function: optional :param debugging_data_dir: Save results on a per-process basis for parallel debugging purposes. If None no `debugging` data will be saved. :type debugging_data_dir: optional :param interpolate_nan_outputs: 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. :type interpolate_nan_outputs: optional :param num_samples: 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. :type num_samples: optional :param seed: If the user is using a random sampling technique, this sets the seed :type seed: optional :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. :rtype: save_data .. py:function:: 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) This function is similar to the :func:`~parameter_sweep.functions.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. :param model: A Pyomo :class:`~pyomo.environ.ConcreteModel` containing a watertap flowsheet, for best results it should be initialized before being passed to this function. :param 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``. :param 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. :param .. code-block::: {"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"]}} :param 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. :type outputs: optional :param csv_results_file_name: The path and file name to write a csv file. The default `None` does not write a csv file. :type csv_results_file_name: optional :param h5_results_file_name: 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. :type h5_results_file_name: optional :param h5_parent_group_name: 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. :type h5_parent_group_name: optional :param optimize_function: 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. :type optimize_function: optional :param optimize_kwargs: 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. :type optimize_kwargs: optional :param reinitialize_function: 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. :type reinitialize_function: optional :param reinitialize_kwargs: 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. :type reinitialize_kwargs: optional :param reinitialize_before_sweep: 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. :type reinitialize_before_sweep: optional :param probe_function: A user-defined function that can cheaply check if a current model configuration is solvable without actually reinitializing or solving. :type probe_function: optional :param debugging_data_dir: Save results on a per-process basis for parallel debugging purposes. If None no `debugging` data will be saved. :type debugging_data_dir: optional :param interpolate_nan_outputs: 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. :type interpolate_nan_outputs: optional :param num_samples: 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. :type num_samples: optional :param num_diff_samples: Number of samples for the differential sweep at a given base value. :type num_diff_samples: optional :param seed: If the user is using a random sampling technique, this sets the seed :type seed: optional :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. :rtype: save_data