matcal.dakota.sensitivity_studies

This module contains MatCal’s interface to Dakota’s sensitivity study methods.

Classes

LhsSensitivityStudy(*parameters)

Perform LHS sensitivity studies for a parameter collection.

class matcal.dakota.sensitivity_studies.LhsSensitivityStudy(*parameters)[source]

Perform LHS sensitivity studies for a parameter collection. This can provide parameter Pearson correlations and Sobol indices for a set of evaluation sets over the specified parameter range depending on options. The default behavior is to find the sensitivities at each experimental data point. For large data sets this may require down sampling. To only compare to the overall objective value, use the use_overall_objective method.

Parameters:: parameters (list(Parameter) or ParameterCollection) – The parameters of interest for the study.
Raises:: StudyTypeError – if parameters is of incorrect type.

make_sobol_index_study()[source]: Runs the study so that it will output the Sobol indices.

Warning

Due to our adoption of the Dakota interface, this will run more samples than expected. It will run $N(M+2)$ samples where $N$ is the number of requested user samples and $M$ is the number of study parameters being investigated.

launch()[source]

The Dakota LhsSensitivityStudy returns sensitivity information which varies depending on the options used for the study.

By default the study will run and calculate the Pearson correlations between the parameters and the study objectives. This should give an approximation of linear correlations between the model study parameters and the objectives of concern for the study. These results are output as a dictionary with the keys being the study parameter names and the values being the correlation of those parameters to the objective values of interest.

If the make_sobol_index_study() has been chosen the study will return the Sobol indices for each parameter.

See the Dakota documentation for more information on the output [5].

Returns:: dictionary of parameter correlations to objectives
Return type:: dict(str, float)

add_evaluation_set(model, objectives, data=None, states=None, data_conditioner_class=<class 'matcal.core.data.MaxAbsDataConditioner'>)

Adds an evaluation set to the study. An evaluation set is a set of datasets, objectives and states that are applicable to a model. For each evaluation set, the model will be evaluated for every state in the set. The results from each model state will be compared to each dataset its state. This comparison consists of each objective in the passed objectives.

Parameters:

model (valid model type from the models module) – The model that will generate results for comparison to the data in the set.
objectives (Objective or ObjectiveCollection) – The objectives to quantitatively compare the model results to the data.
data (Data or DataCollection) – The data to be evaluated with this evaluation set. Data is not required when this method is called with a SimulationResultsSynchronizer.
states (State or StateCollection) – A subset of states in the data that are of interest for this study.
data_conditioner_class – the class that will be used as a data conditioner for this evaluation set. See data for valid data conditioners.

Raises:

StudyTypeError – if passed arguments are of the incorrect type.
StudyError – if all the passed states are not in the data.

add_line(line, replace=False)

Add a line to the input file block.

Parameters:

line (InputFileLine) – the line to be added.
replace (bool) – replace existing value if the line is in the block lines when sen to True

add_lines(*lines, replace=False)

Add a set or list of lines to the input file block.

Parameters:

lines (list(InputFileLine)) – the lines to be added.
replace (bool) – replace existing value if the line is in the block lines when sen to True

add_lines_from_dictionary(dictionary, replace=False)

Use a dictionary to add several keyword, value pairs to the block as lines. The keywords will end up being the lines’ leading statements and the values will be the values.

Parameters:

dictionary (dict(str or float or tuple(float, str) or list(float, str))) – the dictionary containing the line information to be added to the block.
replace (bool) – replace lines if already existing in the subblock

add_parameter_preprocessor(parameter_preprocessor)

Add a parameter preprocessor to the study that will operate on the parameters before they are sent to the models. See UserDefinedParameterPreprocessor.

Parameters:: parameter_preprocessor (UserDefinedParameterPreprocessor) – the parameter preprocessor that will modify and update the given model parameters

add_subblock(subblock, replace=False, set_begin_end_to_parent=False)

Add a subblock to the input file block or input file.

Parameters:

subblock (matcal.core.input_file_writer.InputFileBlock) – the subblock to be added. Can be unpopulated.
replace (bool) – the subblock will replace an existing one if found.

add_table(table): Add an InputFileTable to the subblock.

do_not_save_evaluation_cache(): Do not save the entire evaluation cache. This is recommended for studies with large data sets that may fill all available memory.

Warning

This will make restarting fail. Only use this if you will likely not need restarts.

property final_results_filename

Returns the filename for the final results file for the current study.

return: final results filename as an absolute path rtype: str

get_environment_block()

Returns the Dakota input file environement block. Users can modify this input file block directly. See matcal.core.input_file_writer.InputFileBlock.

Return type:: matcal.core.input_file_writer.InputFileBlock

get_input_string(): Returns a string of the entire input file/block.

get_interface_block()

Returns the Dakota input file interface block. Users can modify this input file block directly. See matcal.core.input_file_writer.InputFileBlock.

Return type:: matcal.core.input_file_writer.InputFileBlock

get_line(line_name)

Returns a line with the passed line name.

Parameters:: line_name (str) – the name of the line desired.
Return type:: InputFileLine

get_line_value(key, index=1)

Return the value from the line values at a specified index. By default it returns the second value, which is the value after the line keyword.

Parameters:

key (str) – the name of the line. Usually the keyword.
index (int) – an optional parameter to set a different index for the returned value from the line

get_method_block()

Returns the Dakota input file method block. Users can modify this input file block directly. See matcal.core.input_file_writer.InputFileBlock.

Return type:: matcal.core.input_file_writer.InputFileBlock

get_method_type_block()

Returns the Dakota input file method type block. Users can modify this input file block directly. See matcal.core.input_file_writer.InputFileBlock.

Return type:: matcal.core.input_file_writer.InputFileBlock

get_number_of_samples()

Returns the number of samples for the study.

Return type:: int, None

get_read_restart_filename(): Returns the restart filename that Dakota will read for restarting. :rtype: str

get_response_block()

Returns the Dakota input file response block. Users can modify this input file block directly. See matcal.core.input_file_writer.InputFileBlock.

Return type:: matcal.core.input_file_writer.InputFileBlock

get_seed()

Returns the seed for the random samples if specified by the user. Otherwise returns None.

Return type:: int, None

get_string(): Verifies all required lines and input are added and then generates and returns the input block/file string.

get_subblock(key)

Get a subblock by name from the block.

Parameters:: key (str) – the name of the desired subblock.

get_subblock_by_type(block_type)

This will return the subblock of a given type. It will return the first one found if there are multiple subblocks of the same type. If the block_type is not found as a subblock, the function returns None.

Parameters:: block_type (str) – the type of the subblock to be returned. This is the input file type, not a Python type.
Return type:: InputFileBlock

get_subblocks_by_type(block_type)

This will return all subblocks of a given type.: If the block_type is not found as a subblock, the function returns None.

Parameters:: block_type (str) – the type of the subblock to be returned. This is the input file type, not a Python type.
Return type:: list(InputFileBlock)

get_table(name)

Returns a table for a given table name if it is in the input file/block.

Parameters:: name (str) – name of the desired table.

get_variables_block()

Returns the Dakota input file variables block. Users can modify this input file block directly. See matcal.core.input_file_writer.InputFileBlock.

Return type:: matcal.core.input_file_writer.InputFileBlock

get_write_restart_filename(): Returns the restart filename that Dakota will write for restarting. :rtype: str

property lines

Returns a list of all block lines.

Return type:: list(InputFileLine)

property name

Returns the subblock name.

Return type:: str

plot_progress(): Calling this method will cause matcal to generate automatic plots after each batch of parameter evaluations. These plots are made using the standard plotter and will show things such as objective value evolution.

print_title(): This method returns if the block will print the title.

remove_subblock(subblock)

Remove and return the passed subblock or subblock name.

Parameters:: subblock (str or matcal.core.input_file_writer.InputFileBlock) – the subblock to be removed from the input file block.

remove_subblocks_by_type(block_type)

This will remove all subblocks of a given type. If the block_type is not found as a subblock, none are removed.

Parameters:: block_type (str) – the type of the subblocks to be removed. This is the input file type, not a Python type.

reset_lines(): Clears out the lines in the input block.

restart(restart_filename='dakota.rst', matcal_results_filename='in_progress_results.joblib')

Allows the Dakota study to be restarted from a restart file.

Parameters:

restart_filename (str) – The Dakota restart filename to be used. This should be the filename relative to where the input file is and take into account any directory changes that the input file may have.
matcal_results_filename (str) – The MatCal results file to be used. This should be the filename relative to where the input file is and take into account any directory changes that the input file may have.

property results: Return access to the study’s results. Will return None, if study has not been run.

run_in_serial()

Tell MatCal to run evaluations in serial. This is only recommended if the study is serial, like a MCMC Bayes Study, and the model evaluations are fast, like a python model.

Running in serial avoids the overhead of reloading large data sets that are necessary in async studies.

set_cleanup_mode(new_pruner: DirectoryPrunerBase): Changes the pruner to the object passed as an argument

set_core_limit(core_limit, override_max_limit=False)

Sets the total number of cores that the study may use.

Parameters:

core_limit (int) – The max number of cores that the study can use at any time.
override_max_limit – Override the default max cores that can be specified for a given study. The current limit of 500 is recommended by the MatCal team but might not be best for all cases.

Raises:

StudyTypeError – if the passed value is not an int.

set_method_type_block_line(keyword, *values, suppress_symbol=False)

Add a new input file line to or change the value of an existing lie in the method type block. This can be used to add method specific options to the method type block. By default this will add a line with the following format keyword = value_1 value_2 … value_n to the method type block.

Parameters:

keyword (str) – the keyword for the method type option being added.
values (str or float) – optional unpacked list of values that are associated with the keyword.
suppress_symbol (bool) – optionally remove the “=” symbol from the line.

set_name(name)

Set the block name.

Parameters:: name (str) – the new block name.

set_number_of_samples(number_of_samples)

Set the number of samples for the sensitivity study.

Parameters:: number_of_samples (int) – number of samples desired for the study

set_output_verbosity(output_verbosity='silent')

Change the Dakota output verbosity. By default, we set it to “silent”. Other options are available. See Dakota’s documentation for more information.

Parameters:: output_verbosity (str) – The output verbosity level

set_parameters(*parameters)

Parameters:: parameters (Parameter or ParameterCollection) – The parameters of interest for the study.
Raises:: StudyTypeError – if the parameters are of incorrect type.

set_print_name(print_name=True, print_title=False)

Controls whether to print the name of the subblock. By default, it prints the name and not the title.

Parameters:: print_name (bool) – print the name if True or do not if False.

set_print_title(print_title=True)

Controls how to print the title of the subblock. By default, it prints the name and not the title. If the title is printed, it is printed before the name.

Parameters:: print_title (bool) – print the title with the name or as the name

set_random_seed(seed): See set_seed().

set_read_restart_filename(filename)

Change the filename for the restart file read by Dakota. By default, Dakota always attempts to read a restart file with the name “dakota.rst”.

Parameters:: filename (str) – The restart filename to be used.

set_restart_filename(filename)

Change the filename for the restart file written by Dakota. By default, Dakota always outputs a restart file with the name “dakota.rst”.

Parameters:: filename (str) – The restart filename to be used.

set_results_storage_options(data: bool = True, qois: bool = True, residuals: bool = True, objectives: bool = True, weighted_conditioned: bool = False, results_save_frequency: int = 1)

Set which history information to save and return with the study results. You can also down sample which evaluations to save using results_save_frequency. This is particularly useful if you wish to not store finite difference evaluations for gradient based studies. The total objective is always stored.

Parameters:

data (bool) – Store the raw data for each simulation and the raw experimental data for each objective for each desired evaluation.
qois (bool) – Store the QoIs for each objective for each desired evaluation. This includes both experiment and simulation QoIs
residuals (bool) – Store the residuals for each objective for each desired evaluation.
objectives (bool) – Store the objective by state and evaluation set for each desired evaluation.
weighted_conditioned (bool) – Store the weighted and conditioned values for each desired evaluation. This will save the weighted and conditioned, residuals, simulation qois and experiment qois.
results_save_frequency (int) – Set how the results save interval. For studies where finite difference derivatives are used, an interval of $n+1$ will exclude finite difference results from the saved results history.

set_seed(seed)

Set the seed for study.

Parameters:: seed (int) – seed to be used for the study

set_symbol_for_lines(symbol)

Set the symbol for all lines in the block. Does not apply to subblocks.

Parameters:: symbol (None or str) – symbol to be used for all block lines. If none, the symbol will be suppressed.

set_use_threads(always_use_threads=False)

By default, MatCal assumes that the model being run is CPU intensive. As a result, it runs each model in a subprocess which can result in some additional overhead. If running studies cheaper python models, it may be beneficial to use threading instead of a subprocess. Using this method will run the study with threading if only one model can be evaluated at a time. You can optionally run with threads even with concurrent model evaluations with the “always_use_threads” option; however, this can be less reliable. For large memory calibrations, we always recommend using subprocess.

Finally, any external executable is always run using subprocess, but threading can be use to manage that job and return its results.

Parameters:: always_use_threads (bool) – if true, MatCal will use threads over subprocess for concurrent modeling jobs. Defaults to False.

set_working_directory(working_directory, remove_existing=False)

By default, MatCal runs in the current working directory. This method allows the user to specify a subdirectory in the current directory for the study to be run in. This method will create only the last directory in the path. So if the desired subdirectory is under a multiple folders from the current directory MatCal will error if the head of the path does not exist. See os.path.split() for a definition of the path “head”.

Parameters:

working_directory (str) – The desired working directory for the current study. MatCal will only create the last folder if the path is a nested path.
remove_existing – If True, then the directory will be removed if pre-existing at study launch.

property subblocks

Returns a list of all block subblocks.

Return type:: list(InputFileBlock)

suppress_symbols_for_lines(): Suppress the symbol for all lines in the block. Does not apply to subblocks.

property tables

Returns a list of all block tables.

Return type:: list(InputFileTable)

property title

Returns the subblock title.

Return type:: str

use_overall_objective(): Use the overall objective value as the target of the sensitivity study. If this method is not called, the sensitivities will be calculated for each experimental data point.

write(f)

Write the subblock to a file handle object.

Parameters:: f (TextIOWrapper) – the file object that line will be written to.

write_input_to_file(filename)

Writes the input file/block to the given filename.

Parameters:: filename (str) – the filename to write the input file to.