matcal.full_field.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

`InterpolatedFullFieldObjective`(...[, ...])	The InterpolatedFullFieldObjective class handles the calculation of the residual vector and merit functions when comparing point data extracted from 2D surfaces for a `StudyBase` evaluation set.
`MechanicalVFMObjective`([time_field, load_field])	The MechanicalVFMObjective class handles the calculation of the residual vector and merit functions when calibrating a material model using the Virtual Fields Method and full-field displacement data from an experiment.
`PolynomialHWDObjective`(target_coords, ...[, ...])	The PolynomialHWDObjective class handles the calculation of the residual vector and merit functions when comparing point data extracted from 2D surfaces for a study evaluation set.

class matcal.full_field.objective.InterpolatedFullFieldObjective(fem_mesh_file, *dependent_fields, time_variable='time', fem_surface=None)[source]

The InterpolatedFullFieldObjective class handles the calculation of the residual vector and merit functions when comparing point data extracted from 2D surfaces for a StudyBase evaluation set. See add_evaluation_set().

Specify the geometry and fields of interest for the full-filed objective. For full-field objectives it is expected that each frame of data is parameterized by an independent time field. While it does not need to be called time, some field must characterize the order of each frame of full-field data. A frame of data consists of the field values (temperature, displacement, etc.) of all the relevant points for the data set. This method allows the user to specify these fields for the objective. This objective will interpolate the experimental data in space on to the simulation data points, and will interpolate the simulation data in time to align with the experimental time stamps.

This method uses GMLS to interpolate in space. There are two meta-parameters that define this interpolation, polynomial order and search radius multiplier. By default these values are both set to 2, but can me modified. Any modifications should be performed before any objective evaluations occur, because changes to these parameters will not back propagate.

Parameters:

fem_mesh_file – file path pointing to the mesh used for simulation.
dependent_fields (str) – the dependent fields for the objective from as an unpacked list.
time_variable (str) – The name of the time field used to parameterize the frames of full-field data
fem_surface (str) – the name of the surface to extract the data points off of from a mesh if simulation returns more than just the required surface.

set_interpolation_parameters(polynomial_order: int, search_radius_multiplier: float)[source]

Set the interpolation/extrapolation meta-parameters. It is recommend that if much extrapolation is expected that the polynomial order used be kept low(<=2).

Parameters:

polynomial_order (int) – Value used to indicate the polynomial order used by GMLS to determine new values.
search_radius_multiplier (float) – Value used to gather more points past the minimum required for the determination of a polynomial. This value should always be greater than 1. Larger values will tend to smooth out the interpolation while smaller values will allow for sharper changes in value.

data_specific_initialization(exp_data_collection)[source]

Public method used by this class to correctly incorporate experimental data into the initialization of the objective. This is a method meant for use inside of MatCal and is not intended to be used by users.

Parameters:: exp_data_collection (DataCollection) – the DataCollection containing the relevant experimental data that this objective will evaluate.

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.full_field.objective.PolynomialHWDObjective(target_coords, *dependent_fields, time_variable: str = 'time', max_depth: int = 6, polynomial_order: int = 8)[source]

The PolynomialHWDObjective class handles the calculation of the residual vector and merit functions when comparing point data extracted from 2D surfaces for a study evaluation set. See add_evaluation_set().

PolynomialHWDObjective defines its objective in a latent space. The latent space represents the raw point data by weights of different basis modes. These modes represent different patterns the data can take over different parts of the domain. This method can support compression of the full-field data, allowing it to have a much smaller memory foot print than may be required by other methods.

These modes are formed by performing a QR factorization on a moment matrix. This factorization provides a basis matrix(Q) and a change of basis matrix(R). These matrices are used to convert the raw data tot the latent space and to map different latent spaces to each other.

This method generates its moment matrix by generating polynomials across different tiers of subdividing the spatial domain. each tier is a binary split of the last tier, creating a domain decomposition tree, where depth d of the tree has 2^d subdivisions within it. The deeper the tree the more local information can be captured by the objective.

Currently the default behavior for this objective involves a colocation step of the experimental data to the simulation data points. This step may not be necessary in the future as partitioning methods for HWD become better.

Specify the geometry and fields of interest for the full-filed objective. For full-field objectives it is expected that each frame of data is parameterized by an independent time field. While it does not need to be called time, some field must characterize the order of each frame of full-field data. A frame of data consists of the field values (temperature, displacement, etc.) of all the relevant points for the data set. This method allows the user to specify these fields for the objective. This objective will use polynomial HWD to compare experimental data and simulation data in a latent space. To align the data points in time the simulation data will interpolated in time to match the experimental time stamps.

There are two meta-parameters that define the latent space definition, polynomial order and maximum tree depth. polynomial order changes the polynomial order used to generate the moment matrix, and the maximum tree depth dictates how deep of a binary tree can be generated for a given domain.

Parameters:

target_coords – two-dimensional array containing the points to be colocated to to generate a more consistent set of basis modes. If None is passed colocation will be skipped. non-colocated HWD is still in beta at this time an may have unpredictable performance.
dependent_fields (list(str)) – the dependent fields for the objective.
time_variable (str) – The name of the time field used to parameterize the frames of full-field data
max_depth – Specify the maximum depth of binary tree to make. Value must be 0 or greater. Note that the number of subdivisions grow geometrically, and that depths greater than 7 can take a long time to process.
polynomial_order (int) – Specify the order of polynomial used to generate the moment matrix. value must be 0 or greater.

data_specific_initialization(exp_data_collection)[source]

Public method used by this class to correctly incorporate experimental data into the initialization of the objective. This is a method meant for use inside of MatCal and is not intended to be used by users.

Parameters:: exp_data_collection (DataCollection) – the DataCollection containing the relevant experimental data that this objective will evaluate.

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.full_field.objective.MechanicalVFMObjective(time_field='time', load_field='load')[source]

The MechanicalVFMObjective class handles the calculation of the residual vector and merit functions when calibrating a material model using the Virtual Fields Method and full-field displacement data from an experiment. It must be combined with one of MatCal’s VFM models which require a FieldData class object for the boundary condition data. The data passed to add_evaluation_set() along with this type of objective can be of type FieldData or Data since the external virtual power calculation only uses global data. For the internal virtual power calculation, the virtual field functions used are

$\mathbf{v}^*_X=\cos\frac{\pi\bar{Y}}{h}$

$\mathbf{v}^*_Y=\frac{2\bar{Y}+h}{2h}$

where $Y$ is the direction of loading, $\bar{Y}$ is the centered position of the current point of interest in the reference configuration, and $h$ is the total height of the data.

Optionally specify the time and load field names that are required to be in the experiment FieldData class for this objective. These are assumed to be “time” and “load” by default.

Parameters:

time_field – the name of the time field in the data.
load_field (str) – the name of the load field in the data.

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.