matcal.dakota.uncertainty_quantification_studies

This module contains MatCal’s interface to Dakota’s uncertainty quantification methods.

Functions

DramBayesianCalibrationStudy(*parameters[, ...])

Runs a Bayesian calibration study for a given parameter collection and set of evaluation sets.

Classes

AdaptiveMetropolisBayesianCalibrationStudy(...)	Runs a Bayesian calibration study for a given parameter collection and set of evaluation sets.
MuqDramBayesianCalibrationStudy(*parameters)
QuesoDramBayesianCalibrationStudy(*parameters)

class matcal.dakota.uncertainty_quantification_studies.DakotaBayesFileBase(*args, **kwargs)

set_number_of_samples(number_of_samples)

Set the number of samples.

Parameters:

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

get_number_of_samples()

Returns the number of samples for the study.

Return type:

int

set_number_of_burnin_samples(value)

Set the total number of burn-in samples for the study.

Parameters:

value (int) – number of burn-in samples to run

get_number_of_burnin_samples()

Returns the number of burn-in samples for the study.

Return type:

int

set_proposal_covariance(*proposal_covariance)

Set the proposal covariance for the parameters. This can be set as the same value for all parameters or as a specific value for each parameter. It can also accept any custom string format that a Dakota input deck can accept.

Parameters:

proposal_covariance (str or float) – the proposal covariance value/values: a single float; a comma separated list or unpacked list of floats of length N, where N is the number of study parameters; a custom string valid for covariance specification in a Dakota input deck.

get_proposal_covariance()

Returns the processed proposal covariance for the study. Returns None if not user specified. :rtype: str or None

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

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_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

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.

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

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

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.

class matcal.dakota.uncertainty_quantification_studies.AdaptiveMetropolisBayesianCalibrationStudy(*parameters)

Runs a Bayesian calibration study for a given parameter collection and set of evaluation sets. The current values for the parameters sent to this study should be from a traditional calibration method that located an objective minimum.

Parameters:

parameters (list(Parameter) or ParameterCollection) – The parameters of interest for the study.

Raises:

StudyTypeError – if parameters is of incorrect type.

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_burnin_samples()

Returns the number of burn-in samples for the study.

Return type:

int

get_number_of_samples()

Returns the number of samples for the study.

Return type:

int

get_proposal_covariance()

Returns the processed proposal covariance for the study. Returns None if not user specified. :rtype: str or 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

launch()

This launches the study. Note that at least one evaluation set must be added with add_evaluation_set().

Returns:

study specific results.

Raises:

StudyError – if no evaluation sets have been added.

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_burnin_samples(value)

Set the total number of burn-in samples for the study.

Parameters:

value (int) – number of burn-in samples to run

set_number_of_samples(number_of_samples)

Set the number of samples.

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_proposal_covariance(*proposal_covariance)

Set the proposal covariance for the parameters. This can be set as the same value for all parameters or as a specific value for each parameter. It can also accept any custom string format that a Dakota input deck can accept.

Parameters:

proposal_covariance (str or float) – the proposal covariance value/values: a single float; a comma separated list or unpacked list of floats of length N, where N is the number of study parameters; a custom string valid for covariance specification in a Dakota input deck.

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

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.

class matcal.dakota.uncertainty_quantification_studies.QuesoDramBayesianCalibrationStudy(*parameters)

Parameters:

parameters (list(Parameter) or ParameterCollection) – The parameters of interest for the study.

Raises:

StudyTypeError – if parameters is of incorrect type.

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_burnin_samples()

Returns the number of burn-in samples for the study.

Return type:

int

get_number_of_samples()

Returns the number of samples for the study.

Return type:

int

get_proposal_covariance()

Returns the processed proposal covariance for the study. Returns None if not user specified. :rtype: str or 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

launch()

This launches the study. Note that at least one evaluation set must be added with add_evaluation_set().

Returns:

study specific results.

Raises:

StudyError – if no evaluation sets have been added.

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_burnin_samples(value)

Set the total number of burn-in samples for the study.

Parameters:

value (int) – number of burn-in samples to run

set_number_of_samples(number_of_samples)

Set the number of samples.

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_proposal_covariance(*proposal_covariance)

Set the proposal covariance for the parameters. This can be set as the same value for all parameters or as a specific value for each parameter. It can also accept any custom string format that a Dakota input deck can accept.

Parameters:

proposal_covariance (str or float) – the proposal covariance value/values: a single float; a comma separated list or unpacked list of floats of length N, where N is the number of study parameters; a custom string valid for covariance specification in a Dakota input deck.

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

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.

class matcal.dakota.uncertainty_quantification_studies.MuqDramBayesianCalibrationStudy(*parameters)

Parameters:

parameters (list(Parameter) or ParameterCollection) – The parameters of interest for the study.

Raises:

StudyTypeError – if parameters is of incorrect type.

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_burnin_samples()

Returns the number of burn-in samples for the study.

Return type:

int

get_number_of_samples()

Returns the number of samples for the study.

Return type:

int

get_proposal_covariance()

Returns the processed proposal covariance for the study. Returns None if not user specified. :rtype: str or 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

launch()

This launches the study. Note that at least one evaluation set must be added with add_evaluation_set().

Returns:

study specific results.

Raises:

StudyError – if no evaluation sets have been added.

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_burnin_samples(value)

Set the total number of burn-in samples for the study.

Parameters:

value (int) – number of burn-in samples to run

set_number_of_samples(number_of_samples)

Set the number of samples.

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_proposal_covariance(*proposal_covariance)

Set the proposal covariance for the parameters. This can be set as the same value for all parameters or as a specific value for each parameter. It can also accept any custom string format that a Dakota input deck can accept.

Parameters:

proposal_covariance (str or float) – the proposal covariance value/values: a single float; a comma separated list or unpacked list of floats of length N, where N is the number of study parameters; a custom string valid for covariance specification in a Dakota input deck.

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

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.

matcal.dakota.uncertainty_quantification_studies.DramBayesianCalibrationStudy(*parameters, library='queso')

Runs a Bayesian calibration study for a given parameter collection and set of evaluation sets. The current values for the parameters sent to this study should be from a traditional calibration method that located an objective minimum.

DRAM stands for Delayed Rejection Adaptive Metropolis. Delayed Rejection means that there is some memory in the method that the sampling of points which may improve the efficiency of the chain. The adaptive part of the name means the calibration will perform adaptive adjustments to their proposal covariance. This puts less weight on the initial guess used to define the proposal covariance. But the better the user submitted values, the more efficient the early chain will be.

There are two library options for using DRAM, QUESO and MUQ. Currently, only QUESO is fully supported with MatCal. MUQ is a newer library and can be run with MatCal, however it is on the user to gather the Dakota output. The Dakota output can be found in the ‘dakota.out’ file. There is work with the Dakota team to add the necessary features to make MUQ fully supported by MatCal.

Parameters:

• parameters (list(Parameter) or ParameterCollection) – The parameters of interest for the study.

• library – Which library to use for the back end Bayesian calculations. Currently there are two options queso and muq. queso is the only fully supported option at the moment. work is underway to fully support muq. muq will run a study, but the user will need to read the ‘dakota.out’ file to get the results of their study, and MatCal will raise an error when the study completes because it can not parse the results correctly.