matcal.dakota.local_calibration_studies

This module contains MatCal’s interface to Dakota’s local calibration methods.

Classes

`CobylaCalibrationStudy`(*parameters)	The Cobyla algorithm is a local optimization method that exhibits some robustness to noisy objective functions.
`GradientCalibrationStudy`(*parameters)	The Gradient Calibration algorithm is a local optimization method that requires the objective function be smooth and convex.
`MeshAdaptiveSearchCalibrationStudy`(*parameters)	The Mesh Adaptive Search algorithm is a local optimization method that exhibits some robustness to noisy objective functions.
`ParallelDirectSearchCalibrationStudy`(*parameters)	The Parallel Direct Search algorithm is a local optimization method that exhibits some robustness to noisy objective functions.
`PatternSearchCalibrationStudy`(*parameters)	The Pattern Search algorithm is a local optimization method that exhibits some robustness to noisy objective functions.
`SolisWetsCalibrationStudy`(*parameters)	The Solis Wets algorithm is a local optimization method that exhibits some robustness to noisy objective functions.

class matcal.dakota.local_calibration_studies.GradientCalibrationStudy(*parameters)[source]

The Gradient Calibration algorithm is a local optimization method that requires the objective function be smooth and convex. This method can quickly find a nearby minimum if the objective function is smooth. It is useful if you are calibrating to a single model with only a couple states and you know a decent initial guess for the parameters. This is the MatCal implementation of the NL2SOL method from Dakota.

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_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_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()

Dakota calibration studies return calibration information which include the best fit parameter set, the objective or residuals for that parameter set and the evaluation ID for the parameter set.

This information is stored in a dictionary with the keys “parameters”, “objectives”, and “evaluation IDs”.

The value for results[“parameters”] is a dictionary of parameter values and names for the best parameter set.

The value for results[“objectives”] is a list of objectives for the best evaluation from the study where the objectives are floats.

The value for results[“evaluation IDs”] is an integer corresponding to the evaluation number for the best parameter set.

If the study returns multiple best parameter sets, such as with a MultiObjectiveGACalibrationStudy, the study will return a list of each of the above, where the indices of the lists match the best parameter results together.

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_convergence_tolerance(value)

Sets the convergence tolerance for the calibration algorithm. See the Dakota manual for specifics. A value greater than 0.0 and less than 1.0 is expected.

Parameters:: value (float) – The desired convergence tolerance

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_max_function_evaluations(value)

Sets the maximum function evaluation the calibration algorithm can run.

Parameters:: value (int) – The desired maximum iterations

set_max_iterations(max_iterations)

Sets the maximum iterations the calibration can complete.

Parameters:: max_iterations (int) – The desired maximum iterations

set_method(method_name)

Sets the Dakota gradient based method to be used by the study. The default method is a least squares method “nl2sol”. Other least squares methods include “optpp_g_newton” and “nlssol_sqp”.

Optionally, gradient based methods that operate on objective functions can be chosen which is recommended for problems with large numbers of residuals such as some full-field interpolation objective. These methods include “npsol_sqp”, “dot_sqp” , “optpp_q_newton”, and “conmin_mfd”.

Some gradient methods that use an objective that are available but not recommended included “dot_slp”, “dot_mmfd”, and “optpp_fd_newton”. These performed poorly on our production level tests, so the other methods are recommended unless you have a specific case where these are required.

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_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_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_step_size(value=5e-05)

Sets the finite difference step sizes for the gradient decent optimizations. Default step size is a relative step of 5e-5.

Parameters:: step_size (float) – the desired step_size

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.local_calibration_studies.MeshAdaptiveSearchCalibrationStudy(*parameters)[source]

The Mesh Adaptive Search algorithm is a local optimization method that exhibits some robustness to noisy objective functions. The true global minimum may not be found, but this method can find a nearby minimum even if the objective function is not smooth. This method can require more iterations than a gradient based method but is cheaper than global search methods. It is useful if you are calibrating to a couple models with only a couple states and you know a decent initial guess for the parameters. This is the MatCal implementation of the mesh_adaptive_search method from Dakota.

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_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_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_variable_neighborhood_search()

Returns the variable neighborhood search for the study. Returns None if a value is not user specified

Return type:: float or None

get_variable_tolerance(): Returns the variable tolerance size for the study. Returns None if it has not been specified. :rtype: float or None

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

Dakota calibration studies return calibration information which include the best fit parameter set, the objective or residuals for that parameter set and the evaluation ID for the parameter set.

This information is stored in a dictionary with the keys “parameters”, “objectives”, and “evaluation IDs”.

The value for results[“parameters”] is a dictionary of parameter values and names for the best parameter set.

The value for results[“objectives”] is a list of objectives for the best evaluation from the study where the objectives are floats.

The value for results[“evaluation IDs”] is an integer corresponding to the evaluation number for the best parameter set.

If the study returns multiple best parameter sets, such as with a MultiObjectiveGACalibrationStudy, the study will return a list of each of the above, where the indices of the lists match the best parameter results together.

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_convergence_tolerance(value)

Sets the convergence tolerance for the calibration algorithm. See the Dakota manual for specifics. A value greater than 0.0 and less than 1.0 is expected.

Parameters:: value (float) – The desired convergence tolerance

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_max_function_evaluations(value)

Sets the maximum function evaluation the calibration algorithm can run.

Parameters:: value (int) – The desired maximum iterations

set_max_iterations(max_iterations)

Sets the maximum iterations the calibration can complete.

Parameters:: max_iterations (int) – The desired maximum iterations

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_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_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_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_variable_neighborhood_search(value)

Set the variable neighborhood search parameter for the algorithm. It increases the number of objective function evaluations each iteration to search more of the space in an attempt to escape local minimums. For specifics, see the Dakota user manual. A value of 0 to 1.0 is expected.

Parameters:: value (float) – the desired variable tolerance

set_variable_tolerance(value)

Set the variable convergence tolerance which limits the minimum step length for the algorithm and is a measure of algorithm convergence. A value greater than 0.0 and less than 1.0 is expected. For specifics, see the Dakota user manual.

Parameters:: value (float) – the desired variable tolerance

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.local_calibration_studies.CobylaCalibrationStudy(*parameters)[source]

The Cobyla algorithm is a local optimization method that exhibits some robustness to noisy objective functions. The true global minimum may not be found, but this method can find a nearby minimum even if the objective function is not smooth. This method can require more iterations than a gradient based method but is cheaper than global search methods. It is useful if you are calibrating to a couple models with only a couple states and you know a decent initial guess for the parameters. This is the MatCal implementation of the coliny_cobyla method from Dakota.

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_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_solution_target()

Returns the solution target for the study. Returns None if it has not been set.

Return type:: float or 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_variable_tolerance(): Returns the variable tolerance size for the study. Returns None if it has not been specified. :rtype: float or None

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

Dakota calibration studies return calibration information which include the best fit parameter set, the objective or residuals for that parameter set and the evaluation ID for the parameter set.

This information is stored in a dictionary with the keys “parameters”, “objectives”, and “evaluation IDs”.

The value for results[“parameters”] is a dictionary of parameter values and names for the best parameter set.

The value for results[“objectives”] is a list of objectives for the best evaluation from the study where the objectives are floats.

The value for results[“evaluation IDs”] is an integer corresponding to the evaluation number for the best parameter set.

If the study returns multiple best parameter sets, such as with a MultiObjectiveGACalibrationStudy, the study will return a list of each of the above, where the indices of the lists match the best parameter results together.

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_convergence_tolerance(value)

Sets the convergence tolerance for the calibration algorithm. See the Dakota manual for specifics. A value greater than 0.0 and less than 1.0 is expected.

Parameters:: value (float) – The desired convergence tolerance

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_max_function_evaluations(value)

Sets the maximum function evaluation the calibration algorithm can run.

Parameters:: value (int) – The desired maximum iterations

set_max_iterations(max_iterations)

Sets the maximum iterations the calibration can complete.

Parameters:: max_iterations (int) – The desired maximum iterations

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_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_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_solution_target(value)

Specifies a target value for the objective function. Once the objective function goes below or reaches this value, the calibration will stop.

Parameters:: value (float) – solution target value

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_variable_tolerance(value)

Set the variable convergence tolerance which limits the minimum step length for the algorithm and is a measure of algorithm convergence. A value greater than 0.0 and less than 1.0 is expected. For specifics, see the Dakota user manual.

Parameters:: value (float) – the desired variable tolerance

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.local_calibration_studies.SolisWetsCalibrationStudy(*parameters)[source]

The Solis Wets algorithm is a local optimization method that exhibits some robustness to noisy objective functions. The true global minimum may not be found, but this method can find a nearby minimum even if the objective function is not smooth. This method can require more iterations than a gradient based method but is cheaper than global search methods. It is useful if you are calibrating to a couple models with only a couple states and you know a decent initial guess for the parameters. This is the MatCal implementation of the coliny_solis_wets method from Dakota.

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_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_solution_target()

Returns the solution target for the study. Returns None if it has not been set.

Return type:: float or 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_variable_tolerance(): Returns the variable tolerance size for the study. Returns None if it has not been specified. :rtype: float or None

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

Dakota calibration studies return calibration information which include the best fit parameter set, the objective or residuals for that parameter set and the evaluation ID for the parameter set.

This information is stored in a dictionary with the keys “parameters”, “objectives”, and “evaluation IDs”.

The value for results[“parameters”] is a dictionary of parameter values and names for the best parameter set.

The value for results[“objectives”] is a list of objectives for the best evaluation from the study where the objectives are floats.

The value for results[“evaluation IDs”] is an integer corresponding to the evaluation number for the best parameter set.

If the study returns multiple best parameter sets, such as with a MultiObjectiveGACalibrationStudy, the study will return a list of each of the above, where the indices of the lists match the best parameter results together.

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_convergence_tolerance(value)

Sets the convergence tolerance for the calibration algorithm. See the Dakota manual for specifics. A value greater than 0.0 and less than 1.0 is expected.

Parameters:: value (float) – The desired convergence tolerance

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_max_function_evaluations(value)

Sets the maximum function evaluation the calibration algorithm can run.

Parameters:: value (int) – The desired maximum iterations

set_max_iterations(max_iterations)

Sets the maximum iterations the calibration can complete.

Parameters:: max_iterations (int) – The desired maximum iterations

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_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_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_solution_target(value)

Specifies a target value for the objective function. Once the objective function goes below or reaches this value, the calibration will stop.

Parameters:: value (float) – solution target value

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_variable_tolerance(value)

Set the variable convergence tolerance which limits the minimum step length for the algorithm and is a measure of algorithm convergence. A value greater than 0.0 and less than 1.0 is expected. For specifics, see the Dakota user manual.

Parameters:: value (float) – the desired variable tolerance

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.local_calibration_studies.PatternSearchCalibrationStudy(*parameters)[source]

The Pattern Search algorithm is a local optimization method that exhibits some robustness to noisy objective functions. The true global minimum may not be found, but this method can find a nearby minimum even if the objective function is not smooth. This method can require more iterations than a gradient based method but is cheaper than global search methods. It is useful if you are calibrating to a couple models with only a couple states and you know a decent initial guess for the parameters. This is the MatCal implementation of the coliny_pattern_search method from Dakota.

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_exploratory_moves()

Returns the exploratory moves pattern for the study. Returns None if it is not user specified.

Return type:: str or None

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_solution_target()

Returns the solution target for the study. Returns None if it has not been set.

Return type:: float or 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_variable_tolerance(): Returns the variable tolerance size for the study. Returns None if it has not been specified. :rtype: float or None

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

Dakota calibration studies return calibration information which include the best fit parameter set, the objective or residuals for that parameter set and the evaluation ID for the parameter set.

This information is stored in a dictionary with the keys “parameters”, “objectives”, and “evaluation IDs”.

The value for results[“parameters”] is a dictionary of parameter values and names for the best parameter set.

The value for results[“objectives”] is a list of objectives for the best evaluation from the study where the objectives are floats.

The value for results[“evaluation IDs”] is an integer corresponding to the evaluation number for the best parameter set.

If the study returns multiple best parameter sets, such as with a MultiObjectiveGACalibrationStudy, the study will return a list of each of the above, where the indices of the lists match the best parameter results together.

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_convergence_tolerance(value)

Sets the convergence tolerance for the calibration algorithm. See the Dakota manual for specifics. A value greater than 0.0 and less than 1.0 is expected.

Parameters:: value (float) – The desired convergence tolerance

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_exploratory_moves(value)

This can be used to set the way the pattern for the search is updated each iteration. Available options are “basic_pattern”, “adaptive_pattern”, and “multi_step”. The default is currently “basic_pattern”, which is subject to change. See Dakota manual for specifics.

Parameters:: value (str) – the exploratory move type to be used

set_max_function_evaluations(value)

Sets the maximum function evaluation the calibration algorithm can run.

Parameters:: value (int) – The desired maximum iterations

set_max_iterations(max_iterations)

Sets the maximum iterations the calibration can complete.

Parameters:: max_iterations (int) – The desired maximum iterations

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_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_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_solution_target(value)

Specifies a target value for the objective function. Once the objective function goes below or reaches this value, the calibration will stop.

Parameters:: value (float) – solution target value

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_variable_tolerance(value)

Set the variable convergence tolerance which limits the minimum step length for the algorithm and is a measure of algorithm convergence. A value greater than 0.0 and less than 1.0 is expected. For specifics, see the Dakota user manual.

Parameters:: value (float) – the desired variable tolerance

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.local_calibration_studies.ParallelDirectSearchCalibrationStudy(*parameters)[source]

The Parallel Direct Search algorithm is a local optimization method that exhibits some robustness to noisy objective functions. The true global minimum may not be found, but this method can find a nearby minimum even if the objective function is not smooth. This method can require more iterations than a gradient based method but is cheaper than global search methods. It is useful if you are calibrating to a couple models with only a couple states and you know a decent initial guess for the parameters. This is the MatCal implementation of the optpp_pds method from Dakota. Note that although the algorithm is designed for parallel execution, Dakota has not yet implemented it as parallel so it runs in serial.

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_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_search_scheme_size()

Returns the search scheme for the study.

Return type:: int

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

Dakota calibration studies return calibration information which include the best fit parameter set, the objective or residuals for that parameter set and the evaluation ID for the parameter set.

This information is stored in a dictionary with the keys “parameters”, “objectives”, and “evaluation IDs”.

The value for results[“parameters”] is a dictionary of parameter values and names for the best parameter set.

The value for results[“objectives”] is a list of objectives for the best evaluation from the study where the objectives are floats.

The value for results[“evaluation IDs”] is an integer corresponding to the evaluation number for the best parameter set.

If the study returns multiple best parameter sets, such as with a MultiObjectiveGACalibrationStudy, the study will return a list of each of the above, where the indices of the lists match the best parameter results together.

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_convergence_tolerance(value)

Sets the convergence tolerance for the calibration algorithm. See the Dakota manual for specifics. A value greater than 0.0 and less than 1.0 is expected.

Parameters:: value (float) – The desired convergence tolerance

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_max_function_evaluations(value)

Sets the maximum function evaluation the calibration algorithm can run.

Parameters:: value (int) – The desired maximum iterations

set_max_iterations(max_iterations)

Sets the maximum iterations the calibration can complete.

Parameters:: max_iterations (int) – The desired maximum iterations

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_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_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_search_scheme_size(value)

Set the number of samples used for creating the simplex each iteration. Dakota has a default of 32 and MatCal has a default of 10. This should be at least N+1 where N is the number of parameters being calibrated.

Parameters:: value (int) – the search scheme size

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.