matcal.core.objective

The objective module contains the classes related to objectives. This includes the metric functions, the base objectives, specialized objectives, objective sets. User facing classes only include metric functions and objectives.

Classes

`L1NormMetricFunction`()	Produces the $l_1$ Norm of the residual for the objective.
`L2NormMetricFunction`()	Produces the $l_2$ Norm of the residual for the objective.
`NormMetricFunction`([order])	This is the general norm metric function.
`Objective`(*fields_of_interest)	The Objective class handles the calculation of the residual vector and merit functions when comparing sets of 1D vector for a study evaluation set.
`ObjectiveCollection`(name, *objectives)	A collection of `Objective` objects.
`ObjectiveSet`(objective_collection, ...[, ...])	Not intended for users.
`SimulationResultsSynchronizer`(...[, left, ...])	This objective will interpolate the simulation values for the dependent fields to the user specified independent field values.
`SumSquaresMetricFunction`()	Produces the square of the $l_2$ norm of the residual, otherwise known as the sum of squares error (SSE).

class matcal.core.objective.NormMetricFunction(order=None)[source]

This is the general norm metric function. It is a wrapper for NumPy’s linalg.norm function. Any order valid for vectors with the linalg.norm function can be used to initialize this metric function.

This metric function is only used to form an objective for algorithms that are not least squares algorithms. However, it does provide normalization information that will act on the residuals for least squares algorithms.

Note

Least squares algorithms should use the L2NormMetricFunction unless specific behavior is desired.

Note

Normalization due to the number of data sets in a state and the length of the data are not applied when using an order of 0. They also are not relevant when using the infinity norms.

Warning

The order 0 and infinity norms will likely not perform well when using multiple states, models or data sets. They also may not to perform well in gradient calibrations.

property name

Returns:: The name of the metric method used.

class matcal.core.objective.L2NormMetricFunction[source]

Produces the $l_2$ Norm of the residual for the objective. The $l_2$ Norm is calculated using

$l_2=\sqrt{\sum_i \left(r_i\right)^2}$

where $\mathbf{r}$ is the residual for this objective.

property name

Returns:: The name of the metric method used.

class matcal.core.objective.L1NormMetricFunction[source]

Produces the $l_1$ Norm of the residual for the objective. The $l_1$ Norm is calculated using

$l_1=\sum_i \left|r_i\right|$

where $\mathbf{r}$ is the residual for this objective.

property name

Returns:: The name of the metric method used.

class matcal.core.objective.SumSquaresMetricFunction[source]

Produces the square of the $l_2$ norm of the residual, otherwise known as the sum of squares error (SSE). it is calculated using

$SSE=\sum_i \left(r_i\right)^2$

where $\mathbf{r}$ is the residual for this objective.

property name

Returns:: The name of the metric method used.

class matcal.core.objective.Objective(*fields_of_interest)[source]

The Objective class handles the calculation of the residual vector and merit functions when comparing sets of 1D vector for a study evaluation set. See add_evaluation_set().

The user must specify the fields of interest for the objective. The residual vector is calculated by subtracting the experimental data from the simulation data and assumes that this subtraction is as desired. If either data set must be manipulated before the comparison use the set_qoi_extractors(), set_simulation_qoi_extractor() or set_experiment_qoi_extractor() to do so.

Parameters:: fields_of_interest (list(str)) – the fields to be evaluated in the objective
Raises:: Objective.TypeError – If the wrong types are passed into the constructor.

has_independent_field(): Returns true if the objective has an independent field. An independent field is required for some studies.

set_as_large_data_sets_objective(large_data_sets=True)

Identify the objective as working with large data sets. If this is used, the data saved and written to file is reduced. The simulation and experimental data are not saved. Also, the conditioned simulation and experimental QoIs and the conditioned and weighted residuals are not saved.

Parameters:: large_data_sets (bool) – set the value as True or False. Can be used to allow saving data for default large data set objectives if set to False.

set_experiment_qoi_extractor(qoi_extractor)

Sets the QoI extractor that will be applied to only the experimental data.

Parameters:: qoi_extractor – A valid QoI extractor from qoi_extractor

set_field_weights(*field_weights)

Parameters:: field_weights (list(ResidualWeightingBase)) – the desired weights to be applied to each objective. Note that this will be applied to every state that is being evaluated for this objective. The states are defined by the data collection or state collection passed to the study evaluation set that the objective is part of.

set_metric_function(metric_function)

Set the metric function to be used. It must be a valid metric function from objective.

Parameters:: metric_function – the desired metric function to be used.

set_name(name)

Sets the name for the objective which is used to extract the data from the study results. A default name is applied based on the order it is added to an evaluation set.

Parameters:: qoi_extractor – A valid QoI extractor from qoi_extractor

set_qoi_extractors(qoi_extractor)

Sets the QoI extractor that will be applied to both the experiment and simulation data.

Parameters:: qoi_extractor – A valid QoI extractor from qoi_extractor

set_simulation_qoi_extractor(qoi_extractor)

Sets the QoI extractor that will be applied to only the simulation data.

Parameters:: qoi_extractor – A valid QoI extractor from qoi_extractor

use_log_residual(): Calculate the residual by subtracting the natural log of the QOI’s. This can be useful when dealing with large ranges of values. Currently, this method requires that all QOI values be positive.

class matcal.core.objective.CurveBasedInterpolatedObjective(independent_field, *dependent_fields, left=None, right=None, period=None)[source]

The CurvedBasedInterpolatedObjective class handles the calculation of the residual vector and merit functions when comparing sets of 2D curves for for a study evaluation set. This objective will attempt to normalize data set size and scale to remove any implicit bias in the data from these factors. See add_evaluation_set().

Specify the fields of interest for the objective. Generally, when comparing data, there is some independent field (e.g. time, displacement, etc.) at which to compare some dependent field (load, temperature, etc.). This method allows the user to specify these fields for the objective. By default, this objective will compare the simulation and experiment dependent fields at the experiment independent field values. To do so, it will interpolate the simulation data to the experimental data independent field values. It does not extrapolate in either direction (independent variable values less than the least simulation output or greater than the greatest simulation output) and handles values outside the simulation limits as is done by NumPy interp.

Parameters:

independent_field (str) – the name of the independent field.
dependent_fields (list(str)) – the dependent fields for the objective.
left (float) – the left parameter as described in the NumPy interp function.
right (float) – the right parameter as described in the NumPy interp function
period (float) – the period parameter as described in the NumPy interp function

Raises:

Objective.TypeError – If the wrong types are passed into the constructor.

has_independent_field(): Returns true if the objective has an independent field. An independent field is required for some studies.

set_as_large_data_sets_objective(large_data_sets=True)

Identify the objective as working with large data sets. If this is used, the data saved and written to file is reduced. The simulation and experimental data are not saved. Also, the conditioned simulation and experimental QoIs and the conditioned and weighted residuals are not saved.

Parameters:: large_data_sets (bool) – set the value as True or False. Can be used to allow saving data for default large data set objectives if set to False.

set_experiment_qoi_extractor(qoi_extractor)

Sets the QoI extractor that will be applied to only the experimental data.

Parameters:: qoi_extractor – A valid QoI extractor from qoi_extractor

set_field_weights(*field_weights)

Parameters:: field_weights (list(ResidualWeightingBase)) – the desired weights to be applied to each objective. Note that this will be applied to every state that is being evaluated for this objective. The states are defined by the data collection or state collection passed to the study evaluation set that the objective is part of.

set_metric_function(metric_function)

Set the metric function to be used. It must be a valid metric function from objective.

Parameters:: metric_function – the desired metric function to be used.

set_name(name)

Sets the name for the objective which is used to extract the data from the study results. A default name is applied based on the order it is added to an evaluation set.

Parameters:: qoi_extractor – A valid QoI extractor from qoi_extractor

set_qoi_extractors(qoi_extractor)

Sets the QoI extractor that will be applied to both the experiment and simulation data.

Parameters:: qoi_extractor – A valid QoI extractor from qoi_extractor

set_simulation_qoi_extractor(qoi_extractor)

Sets the QoI extractor that will be applied to only the simulation data.

Parameters:: qoi_extractor – A valid QoI extractor from qoi_extractor

use_log_residual(): Calculate the residual by subtracting the natural log of the QOI’s. This can be useful when dealing with large ranges of values. Currently, this method requires that all QOI values be positive.

class matcal.core.objective.DirectCurveBasedInterpolatedObjective(independent_field, *dependent_fields, left=None, right=None, period=None)[source]

The DirectCurveBasedInterpolatedObjective class handles the calculation of the residual vector and merit functions when comparing sets of 2D curves for for a study evaluation set. This objective formulation does not do any adjustments of the residual. See add_evaluation_set().

Specify the fields of interest for the objective. Generally, when comparing data, there is some independent field (e.g. time, displacement, etc.) at which to compare some dependent field (load, temperature, etc.). This method allows the user to specify these fields for the objective. By default, this objective will compare the simulation and experiment dependent fields at the experiment independent field values. To do so, it will interpolate the simulation data to the experimental data independent field values. It does not extrapolate in either direction (independent variable values less than the least simulation output or greater than the greatest simulation output) and handles values outside the simulation limits as is done by NumPy interp.

Parameters:

independent_field (str) – the name of the independent field.
dependent_fields (list(str)) – the dependent fields for the objective.
left (float) – the left parameter as described in the NumPy interp function.
right (float) – the right parameter as described in the NumPy interp function
period (float) – the period parameter as described in the NumPy interp function

Raises:

Objective.TypeError – If the wrong types are passed into the constructor.

set_field_weights(*field_weights)[source]

Parameters:: field_weights (list(ResidualWeightingBase)) – the desired weights to be applied to each objective. Note that this will be applied to every state that is being evaluated for this objective. The states are defined by the data collection or state collection passed to the study evaluation set that the objective is part of.

has_independent_field(): Returns true if the objective has an independent field. An independent field is required for some studies.

set_as_large_data_sets_objective(large_data_sets=True)

Identify the objective as working with large data sets. If this is used, the data saved and written to file is reduced. The simulation and experimental data are not saved. Also, the conditioned simulation and experimental QoIs and the conditioned and weighted residuals are not saved.

Parameters:: large_data_sets (bool) – set the value as True or False. Can be used to allow saving data for default large data set objectives if set to False.

set_experiment_qoi_extractor(qoi_extractor)

Sets the QoI extractor that will be applied to only the experimental data.

Parameters:: qoi_extractor – A valid QoI extractor from qoi_extractor

set_metric_function(metric_function)

Set the metric function to be used. It must be a valid metric function from objective.

Parameters:: metric_function – the desired metric function to be used.

set_name(name)

Sets the name for the objective which is used to extract the data from the study results. A default name is applied based on the order it is added to an evaluation set.

Parameters:: qoi_extractor – A valid QoI extractor from qoi_extractor

set_qoi_extractors(qoi_extractor)

Sets the QoI extractor that will be applied to both the experiment and simulation data.

Parameters:: qoi_extractor – A valid QoI extractor from qoi_extractor

set_simulation_qoi_extractor(qoi_extractor)

Sets the QoI extractor that will be applied to only the simulation data.

Parameters:: qoi_extractor – A valid QoI extractor from qoi_extractor

use_log_residual(): Calculate the residual by subtracting the natural log of the QOI’s. This can be useful when dealing with large ranges of values. Currently, this method requires that all QOI values be positive.

class matcal.core.objective.SimulationResultsSynchronizer(independent_field, independent_field_values, *dependent_fields, left=None, right=None, period=None)[source]

This objective will interpolate the simulation values for the dependent fields to the user specified independent field values. It is not used to compare data to other data sources and can be useful for sensitivity and parameter studies. It does not extrapolate in either direction (independent variable values less than the least simulation output or greater than the greatest simulation output) and handles values outside the simulation limits as is done by NumPy interp. In a sense, it is still an “objective” because it is comparing the data to vectors of zero, but also “synchronizes” simulation results to common independent field data locations.

No data normalization or conditioning is provided for this objective by default and weighting is not available.

Note

The metric function for this objective is the L2NormMetricFunction which is more relevant to sensitivity and parameter studies for which this objective was intended.

Parameters:

independent_field (str) – the name of the independent field.
independent_field_values (ArrayLike) – the values of the independent field.
dependent_fields (list(str)) – the dependent fields for the objective.
left (float) – the left parameter as described in the NumPy interp function.
right (float) – the right parameter as described in the NumPy interp function
period (float) – the period parameter as described in the NumPy interp function

Raises:

Objective.TypeError – If the wrong types are passed into the constructor.

has_independent_field(): Returns true if the objective has an independent field. An independent field is required for some studies.

set_as_large_data_sets_objective(large_data_sets=True)

Identify the objective as working with large data sets. If this is used, the data saved and written to file is reduced. The simulation and experimental data are not saved. Also, the conditioned simulation and experimental QoIs and the conditioned and weighted residuals are not saved.

Parameters:: large_data_sets (bool) – set the value as True or False. Can be used to allow saving data for default large data set objectives if set to False.

set_experiment_qoi_extractor(qoi_extractor)

Sets the QoI extractor that will be applied to only the experimental data.

Parameters:: qoi_extractor – A valid QoI extractor from qoi_extractor

set_field_weights(*field_weights)

Parameters:: field_weights (list(ResidualWeightingBase)) – the desired weights to be applied to each objective. Note that this will be applied to every state that is being evaluated for this objective. The states are defined by the data collection or state collection passed to the study evaluation set that the objective is part of.

set_metric_function(metric_function)

Set the metric function to be used. It must be a valid metric function from objective.

Parameters:: metric_function – the desired metric function to be used.

set_name(name)

Sets the name for the objective which is used to extract the data from the study results. A default name is applied based on the order it is added to an evaluation set.

Parameters:: qoi_extractor – A valid QoI extractor from qoi_extractor

set_qoi_extractors(qoi_extractor)

Sets the QoI extractor that will be applied to both the experiment and simulation data.

Parameters:: qoi_extractor – A valid QoI extractor from qoi_extractor

set_simulation_qoi_extractor(qoi_extractor)

Sets the QoI extractor that will be applied to only the simulation data.

Parameters:: qoi_extractor – A valid QoI extractor from qoi_extractor

use_log_residual(): Calculate the residual by subtracting the natural log of the QOI’s. This can be useful when dealing with large ranges of values. Currently, this method requires that all QOI values be positive.

class matcal.core.objective.ObjectiveCollection(name, *objectives)[source]

A collection of Objective objects. This is used to combine multiple objective objects so that they can be passed to a MatCal study evaluation set.

Parameters:

name (str) – The name of the objective collection.
objectives (list(Objective)) – the objectives to be added to the collection.

Raises:

CollectionValueError – If name is a an empty string.
CollectionTypeError – If name is not a string and the parameters to be added to the collection are not of the correct type.

dict()

Returns:: the collection as a dictionary of items with name/value pairs.

classmethod get_collection_type()

Returns:: the data type the collection stores

get_item_names()

Returns:: a list of the names of all items added to the collection.

get_number_of_items()

Returns:: the number of items in the collection

items()

Returns:: a list of tuples of key, value pairs contained in the collection.

keys()

Returns:: a list of all available keys in the collection.

property name

Returns:: the name of the collection
Return type:: str

set_name(name)

Sets the name of the collection.

Parameters:: name (str) – the new collection name

values()

Returns:: a list of all values in the collection.

class matcal.core.objective.ObjectiveSet(objective_collection, data_collection, state_collection, conditioner_class=<class 'matcal.core.data.RangeDataConditioner'>)[source]: Not intended for users. A set of data and objectives to be calculated for a model for a given state collection.