matcal.core.parameter_studies

This module contains pure MatCal implementations of parameter studies. These do not invoke external algorithm libraries.

Functions

sample_multivariate_normal(nsamples, mean, ...)

Sample the multivariate normal distributions for the study parameters using the mean and covariance matrix provided by a LaplaceStudy or other UQ method.

Classes

ClassicLaplaceStudy(*parameters)	Use the MatCal ClassicLaplaceStudy to evaluate the Hessian (and gradient) at an optimal point in parameter space.
FiniteDifference(center_point[, ...])
HaltonStudy(*parameters)
LaplaceStudy(*parameters)	Use the MatCal LaplaceStudy to evaluate the gradient of the calibration residuals at an optimal point in parameter space.
ParameterStudy(*parameters)	Use the MatCal ParameterStudy to run models and evaluate objectives for a user specified set of parameters values.

class matcal.core.parameter_studies.ParameterStudy(*parameters)

Use the MatCal ParameterStudy to run models and evaluate objectives for a user specified set of parameters values. This can be used for brute-force manual calibrations, sensitivity studies when the user prefers to post process the results/chose evaluation parameters and building surrogates for the models using python based surrogate algorithms not directly supported in MatCal.

Parameters:

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

Raises:

StudyTypeError – if parameters is of incorrect type.

add_parameter_evaluation(**parameters)

Add parameter sets to be evaluated to the study. This function can be called as many times as needed to evaluate several different parameter sets. They will be evaluated in the order they are added. All parameters that were passed into the study on initialization must also have a value specified when adding a parameter set to be evaluated with this function.

Parameters:

parameters (dict(str, float)) – the parameters values to be added as an evaluated parameter set for the study.

Raises:

ValueError – If all study parameters do not have a value passed to this function when called.

make_total_objective_study()

This changes the stored total objectives to be a summation of all metric function results.

make_residuals_study()

This changes the stored total objectives to be the L2 norm of one long concatenated residual from all objectives added using add_evaluation_set()

restart()

Sets the study to launch in restart mode. The study will use existing results from previous launches to populate the results instead of running the simulations again. Note that this feature requires that no changes to the study to be made in order for the study to produce correct results.

Files from previous runs are read in to this study, they should not be deleted. Missing files may cause errors in the restart.

If any random number generation is used in the calculation. It is important to set the same seed value as used previously

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

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

launch()

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

Returns:

study specific results.

Raises:

StudyError – if no evaluation sets have been added.

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.

property results

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

run_in_serial()

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

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

set_cleanup_mode(new_pruner: DirectoryPrunerBase)

Changes the pruner to the object passed as an argument

set_core_limit(core_limit, override_max_limit=False)

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

Parameters:

• core_limit (int) – The max number of cores that the study can use at any time.

• override_max_limit – Override the default max cores that can be specified for a given study. The current limit of 500 is recommended by the MatCal team but might not be best for all cases.

Raises:

StudyTypeError – if the passed value is not an int.

set_parameters(*parameters)

Parameters:

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

Raises:

StudyTypeError – if the parameters are of incorrect type.

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

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

Parameters:

• data (bool) – Store the raw data for each simulation and the raw experimental data for each objective for each desired evaluation.

• qois (bool) – Store the QoIs for each objective for each desired evaluation. This includes both experiment and simulation QoIs

• residuals (bool) – Store the residuals for each objective for each desired evaluation.

• objectives (bool) – Store the objective by state and evaluation set for each desired evaluation.

• weighted_conditioned (bool) – Store the weighted and conditioned values for each desired evaluation. This will save the weighted and conditioned, residuals, simulation qois and experiment qois.

• results_save_frequency (int) – Set how the results save interval. For studies where finite difference derivatives are used, an interval of will exclude finite difference results from the saved results history.

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

class matcal.core.parameter_studies.HaltonStudy(*parameters)

Parameters:

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

Raises:

StudyTypeError – if parameters is of incorrect type.

set_seed(seed)

Set the random seed for the random generator that the study uses to generate the samples. The method should be called before launch() to guarantee reproducibility.

Parameters:

seed (int) – Integer seed for the pseudo‑random number generator.

set_Halton_scramble(scramble=True)

Parameters:

scramble (bool) – set the scramble keyword for the numpy Halton object.

set_number_of_samples(nsamples=20, skip=None)

Set the number of samples for the study.

Parameters:

• nsamples (int) – Number of parameter samples to generate from Halton sequence.

• skip (int) – When continuing an existing design, the user may optionally skip ahead in the Halton sequence by an amount determined by ‘skip’.

launch()

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

Returns:

study specific results.

Raises:

StudyError – if no evaluation sets have been added.

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

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

make_residuals_study()

This changes the stored total objectives to be the L2 norm of one long concatenated residual from all objectives added using add_evaluation_set()

make_total_objective_study()

This changes the stored total objectives to be a summation of all metric function results.

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.

restart()

Sets the study to launch in restart mode. The study will use existing results from previous launches to populate the results instead of running the simulations again. Note that this feature requires that no changes to the study to be made in order for the study to produce correct results.

Files from previous runs are read in to this study, they should not be deleted. Missing files may cause errors in the restart.

If any random number generation is used in the calculation. It is important to set the same seed value as used previously

property results

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

run_in_serial()

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

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

set_cleanup_mode(new_pruner: DirectoryPrunerBase)

Changes the pruner to the object passed as an argument

set_core_limit(core_limit, override_max_limit=False)

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

Parameters:

• core_limit (int) – The max number of cores that the study can use at any time.

• override_max_limit – Override the default max cores that can be specified for a given study. The current limit of 500 is recommended by the MatCal team but might not be best for all cases.

Raises:

StudyTypeError – if the passed value is not an int.

set_parameters(*parameters)

Parameters:

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

Raises:

StudyTypeError – if the parameters are of incorrect type.

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

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

Parameters:

• data (bool) – Store the raw data for each simulation and the raw experimental data for each objective for each desired evaluation.

• qois (bool) – Store the QoIs for each objective for each desired evaluation. This includes both experiment and simulation QoIs

• residuals (bool) – Store the residuals for each objective for each desired evaluation.

• objectives (bool) – Store the objective by state and evaluation set for each desired evaluation.

• weighted_conditioned (bool) – Store the weighted and conditioned values for each desired evaluation. This will save the weighted and conditioned, residuals, simulation qois and experiment qois.

• results_save_frequency (int) – Set how the results save interval. For studies where finite difference derivatives are used, an interval of will exclude finite difference results from the saved results history.

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

class matcal.core.parameter_studies.LaplaceStudy(*parameters)

Use the MatCal LaplaceStudy to evaluate the gradient of the calibration residuals at an optimal point in parameter space. The residual gradient can then be used to form a modified Laplace approximation to estimate the parameter covariance matrix for use in uncertainty quantification. We perform this assuming uncertainty is due to model form error.

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.

set_noise_estimate(noise_estimate=0.0)

Set the estimate for the noise in the data. Currently only a single value is accepted for all data. This is the expected standard deviation of the noise.

Parameters:

noise_estimate (float) – value for the noise estimate, must be non-negative

set_calibrate_covariance(calibrate_covaraince=True)

By default, the laplace study will attempt to improve the covariance through a calibraiton. Optionally, turn this off or back on.

Parameters:

calibrate_covariance (bool) – flag to turn the covariance calibration process off or on

update_laplace_estimate(noise_estimate)

Update the laplace study covariance estimate after with an updated noise estimate.

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

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

launch()

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

Returns:

study specific results.

Raises:

StudyError – if no evaluation sets have been added.

make_residuals_study()

This changes the stored total objectives to be the L2 norm of one long concatenated residual from all objectives added using add_evaluation_set()

make_total_objective_study()

This changes the stored total objectives to be a summation of all metric function results.

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.

restart()

Sets the study to launch in restart mode. The study will use existing results from previous launches to populate the results instead of running the simulations again. Note that this feature requires that no changes to the study to be made in order for the study to produce correct results.

Files from previous runs are read in to this study, they should not be deleted. Missing files may cause errors in the restart.

If any random number generation is used in the calculation. It is important to set the same seed value as used previously

property results

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

run_in_serial()

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

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

set_cleanup_mode(new_pruner: DirectoryPrunerBase)

Changes the pruner to the object passed as an argument

set_core_limit(core_limit, override_max_limit=False)

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

Parameters:

• core_limit (int) – The max number of cores that the study can use at any time.

• override_max_limit – Override the default max cores that can be specified for a given study. The current limit of 500 is recommended by the MatCal team but might not be best for all cases.

Raises:

StudyTypeError – if the passed value is not an int.

set_parameter_center(**parameters)

Pass an unpacked dictionary of parameters with valid values to set the center about which to calculate the Hessian for the study objectives. These parameters must be valid for the study parameters and all study parameters must be included. The values must be determined from a calibration and must be located at an objective minimum.

Parameters:

parameters – keyword/value pair of parameter names and values for the location about which to calculate the Hessian

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_results_storage_options(data: bool = True, qois: bool = True, residuals: bool = True, objectives: bool = True, weighted_conditioned: bool = False, results_save_frequency: int = 1)

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

Parameters:

• data (bool) – Store the raw data for each simulation and the raw experimental data for each objective for each desired evaluation.

• qois (bool) – Store the QoIs for each objective for each desired evaluation. This includes both experiment and simulation QoIs

• residuals (bool) – Store the residuals for each objective for each desired evaluation.

• objectives (bool) – Store the objective by state and evaluation set for each desired evaluation.

• weighted_conditioned (bool) – Store the weighted and conditioned values for each desired evaluation. This will save the weighted and conditioned, residuals, simulation qois and experiment qois.

• results_save_frequency (int) – Set how the results save interval. For studies where finite difference derivatives are used, an interval of will exclude finite difference results from the saved results history.

set_step_size(step_size=0.001)

Sets the finite difference step sizes for the LaplaceStudy hessian and gradient approximations. This is a relative step size. Default step size is a relative step of 1e-3. The value must be between zero and one.

Parameters:

step_size (float) – the desired step_size

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.

matcal.core.parameter_studies.sample_multivariate_normal(nsamples, mean, covariance_matrix, seed=None, param_names=None)

Sample the multivariate normal distributions for the study parameters using the mean and covariance matrix provided by a LaplaceStudy or other UQ method.

Parameters:

• nsamples (int) – the number of samples to return from the distribution

• mean (Array-like) – the mean value for the parameters. This would be the calibrated value for most MatCal studies.

• covariance_matrix (Array-like) – parameter covariance matrix from which to generate samples from.

• seed (int) – an optional seed for the random number generator performing the sampling

• param_names (list(str)) – optionally provide a list with the parameter names in the correct order. so that the resulting samples will be returned in a dictionary format where each parameter name key will have a list of parameter values associated with it with length nsamples.

Returns:

a dictionary for the generated samples where the keys are the parameter names (if provided) and the values are arrays storing the sampled values. If parameter names are not provided a name is generated of the form “parameter_#”.

Return type:

dict(str, list(float))

class matcal.core.parameter_studies.ClassicLaplaceStudy(*parameters)

Use the MatCal ClassicLaplaceStudy to evaluate the Hessian (and gradient) at an optimal point in parameter space. The Hessian can then be used to form the Laplace approximation to the parameter covariance matrix for use in uncertainty quantification. We perform this assuming uncertainty is due to noise in the data alone for the classical approach the Laplace Approximation.

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

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

launch()

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

Returns:

study specific results.

Raises:

StudyError – if no evaluation sets have been added.

make_residuals_study()

This changes the stored total objectives to be the L2 norm of one long concatenated residual from all objectives added using add_evaluation_set()

make_total_objective_study()

This changes the stored total objectives to be a summation of all metric function results.

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.

restart()

Sets the study to launch in restart mode. The study will use existing results from previous launches to populate the results instead of running the simulations again. Note that this feature requires that no changes to the study to be made in order for the study to produce correct results.

Files from previous runs are read in to this study, they should not be deleted. Missing files may cause errors in the restart.

If any random number generation is used in the calculation. It is important to set the same seed value as used previously

property results

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

run_in_serial()

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

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

set_cleanup_mode(new_pruner: DirectoryPrunerBase)

Changes the pruner to the object passed as an argument

set_core_limit(core_limit, override_max_limit=False)

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

Parameters:

• core_limit (int) – The max number of cores that the study can use at any time.

• override_max_limit – Override the default max cores that can be specified for a given study. The current limit of 500 is recommended by the MatCal team but might not be best for all cases.

Raises:

StudyTypeError – if the passed value is not an int.

set_parameter_center(**parameters)

Pass an unpacked dictionary of parameters with valid values to set the center about which to calculate the Hessian for the study objectives. These parameters must be valid for the study parameters and all study parameters must be included. The values must be determined from a calibration and must be located at an objective minimum.

Parameters:

parameters – keyword/value pair of parameter names and values for the location about which to calculate the Hessian

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_results_storage_options(data: bool = True, qois: bool = True, residuals: bool = True, objectives: bool = True, weighted_conditioned: bool = False, results_save_frequency: int = 1)

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

Parameters:

• data (bool) – Store the raw data for each simulation and the raw experimental data for each objective for each desired evaluation.

• qois (bool) – Store the QoIs for each objective for each desired evaluation. This includes both experiment and simulation QoIs

• residuals (bool) – Store the residuals for each objective for each desired evaluation.

• objectives (bool) – Store the objective by state and evaluation set for each desired evaluation.

• weighted_conditioned (bool) – Store the weighted and conditioned values for each desired evaluation. This will save the weighted and conditioned, residuals, simulation qois and experiment qois.

• results_save_frequency (int) – Set how the results save interval. For studies where finite difference derivatives are used, an interval of will exclude finite difference results from the saved results history.

set_step_size(step_size=0.001)

Sets the finite difference step sizes for the LaplaceStudy hessian and gradient approximations. This is a relative step size. Default step size is a relative step of 1e-3. The value must be between zero and one.

Parameters:

step_size (float) – the desired step_size

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.