Skip to content

Calibrations Options

The calibrate method can be used to perform calibration of the micromechanical models to experiments. The following keyword options can be used to control the calibration process.

Note

In the following options, the keys to the calibration parameters can also be an instance of the CalibrationKey class or its subclasses to allow custom calibration parameters in addition to the material properties. Options such as the number of particles per volume (npv) and radius (radius), or fabric coefficients (fabric_coefs) can be set as calibration parameters with the help of the CalibrationKey class.

Experiments

experiments (None)

A dictionary or a list of experiments, a string or a list of strings specify names of the experiments, or a single experiment to be used in the calibration process. If None, the experiments will be set to the all the experiments in the model.

Initial guess, bounds, and standard deviations for calibration parameters

x0 (None)

A dictionary of floats for the initial guess of the calibration parameters. Missing parameters will be set to the default values.

bounds (None)

A dictionary of tuples of two floats for the bounds of the calibration parameters. Missing parameters will be set to the default bounds.

stds (None)

A dictionary of floats for the standard deviations of the calibration parameters. Missing parameters will be set to the default standard deviations.

Note

The stds option is only valid for the PYCMA-CMAES optimizer.

Parameter selection

includes (None)

A list of strings or instances of CalibrationKey or its subclasses for the names of the calibration parameters to be included in the calibration process. If None, all required parameters returned by ModelBase.requiredParameters for the current model will be included.

include_additions (None)

A list of strings or instances of CalibrationKey or its subclasses for the names of the calibration parameters to be included in the calibration process in addition to includes. If None, no additional parameters will be included.

excludes (None)

A list of strings or instances of CalibrationKey or its subclasses for the names of the calibration parameters to be excluded from the calibration process. If None, no parameters will be excluded.

experiment_specific_parameters (None)

A list of strings or instances of CalibrationKey or its subclasses for the names of the calibration parameters that are specific to the experiment, which means that the parameters are not shared among different experiments. If None, no parameters will be specific to the experiment.

lognormal_parameters (None)

A list of strings or instances of CalibrationKey or its subclasses for the names of the calibration parameters that are lognormally distributed. If None, no parameters are lognormally distributed.

Options to control the evaluation of the objective function

fitness (None)

A custom objective function, which should be a subclass of FitnessBase, an instance of FitnessBase or its subclasses, or a string specify the full path of the custom fitness class. If None, the default CalibrationFitness will be used.

phase_steps (None)

A dictionary of the steps of each phase that overrides the default steps in the experiments. If None, the default steps in the experiments will be used.

experiment_get_kwargs (None)

Keyword arguments for the Experiment.get method when getting the experimental data. If None, no keyword arguments will be passed.

experiment_options (None)

A dictionary of the options for the experiments that overrides the default options in the experiments. If None, the default options in the experiments will be used.

experiment_weights (None)

A dictionary of floats for the weights of the experiments. If None, the weights of the experiments will be set to 1.

experiment_includes (None)

A list of strings for the names of the experiments to be included in the calibration process, support glob patterns. If None, all experiments will be included.

experiment_excludes (None)

A list of strings for the names of the experiments to be skipped in the calibration process, support glob patterns. If None, no experiments will be skipped.

line_additions (None)

A dictionary of the additional lines that can be expressions of the existing lines to be included in the calibration process. If None, no additional lines will be included.

line_experiment_additions (None)

A dictionary of dictionaries of the additional lines that can be expressions of the existing lines to be included in the calibration process for each experiment. The keys of the outer dictionary are the names of the experiments, and the keys of the inner dictionary are the names of the additional lines. If None, no additional lines will be included. This option has higher priority than line_additions.

line_weights (None)

A dictionary of floats for the weights of the lines. If None, the weights of the lines will be set to 1.

line_experiment_weights (None)

A dictionary of dictionaries of floats for the weights of the lines for each experiment. The keys of the outer dictionary are the names of the experiments, and the keys of the inner dictionary are the names of the lines. If None, the weights of the lines will be set to 1. This option has higher priority than line_weights.

line_includes (None)

A list of strings for the names of the lines to be included in the calibration process., support glob patterns If None, all lines will be included.

line_experiment_includes (None)

A dictionary of lists of strings for the names of the lines to be included in the calibration process for each experiment, support glob patterns. The keys of the dictionary are the names of the experiments. If None, all lines will be included. This option has higher priority than line_includes.

line_excludes (None)

A list of strings for the names of the lines to be skipped in the calibration process, support glob patterns. If None, no lines will be skipped.

line_experiment_excludes (None)

A dictionary of lists of strings for the names of the lines to be skipped in the calibration process for each experiment, support glob patterns. The keys of the dictionary are the names of the experiments. If None, no lines will be skipped. This option has higher priority than line_excludes.

line_xptps (None)

A dictionary of floats for the x-axis peak-to-peak values of the lines to normalize the experimental data. If None, the peak-to-peak values of the lines will be calculated from the experimental data.

line_experiment_xptps (None)

A dictionary of floats for the x-axis peak-to-peak values of the lines to normalize the experimental data for each experiment. If None, the peak-to-peak values of the lines will be calculated from the experimental data. This option has higher priority than line_xptps.

line_yptps (None)

A dictionary of floats for the y-axis peak-to-peak values of the lines to normalize the experimental data. If None, the peak-to-peak values of the lines will be calculated from the experimental data.

line_experiment_yptps (None)

A dictionary of floats for the y-axis peak-to-peak values of the lines to normalize the experimental data for each experiment. If None, the peak-to-peak values of the lines will be calculated from the experimental data. This option has higher priority than line_yptps.

line_override_xydata (None)

A dictionary of a tuple of two lists of floats for the variable that override the experimental data. The keys of the dictionary are the names of the variables. If None, the experimental data will not be overridden.

line_experiment_override_xydata (None)

A dictionary of dictionaries of a tuple of two lists of floats for the variable that override the experimental data for specific. The keys of the outer dictionary are the names of the experiments, and the keys of the inner dictionary are the names of the variables. If None, the experimental data will not be overridden. This option has higher priority than line_override_xydata.

line_ensure_increasing_xdata (None)

A list of strings for the names of the lines to ensure xdata is increasing by reconstructing the data with positive differences between every two points. If None, the xdata will not be ensured to be increasing.

line_experiment_ensure_increasing_xdata (None)

A dictionary of lists of strings for the names of the lines to ensure xdata is increasing by reconstructing the data with positive differences between every two points for each experiment. The keys of the dictionary are the names of the experiments. If None, the xdata will not be ensured to be increasing. This option has higher priority than line_ensure_increasing_xdata.

line_clip_state_variables (None)

A dictionary of a tuple of two floats for the clipping range of the state variables. The keys of the dictionary are the names of the state variables. For example, [0, 1] keeps all the values, [0, 0.5] keeps the first 50% of the values, and [0.5, 1] keeps the last 50% of the values. If None, the lines will not be clipped.

line_experiment_clip_state_variables (None)

A dictionary of a dictionary of a tuple of two floats for the clipping range of the state variables that override the default clipping range in the state variables. For example, [0, 1] keeps all the values, [0, 0.5] keeps the first 50% of the values, and [0.5, 1] keeps the last 50% of the values. The keys of the outer dictionary are the names of the experiments, and the keys of the inner dictionary are the names of the state variables. If None, the default clipping range in the state variables will be used. This option has higher priority than clip_lines.

line_xys (None)

A dictionary of a tuple of two strings for the names of the x and y variables of the lines. The keys of the dictionary are the names of the lines. If None, all the lines will be calibrated (i.e. a dictionary of line.name: (line.x, line.y) for all lines).

line_experiment_xys (None)

A dictionary of a dictionary of a tuple of two strings for the names of the x and y variables of the lines for each experiment. The keys of the outer dictionary are the names of the experiments, and the keys of the inner dictionary are the names of the lines. If None, all the lines will be calibrated (i.e. a dictionary of line.name: (line.x, line.y) for all lines). This option has higher priority than line_xys.

error_fitness (1e10)

A float for the error fitness.

error_raise (false)

Whether to raise an error if the fitness is not valid.

similarity_method (interpolate)

A string for the method to calculate the similarity between the experimental and simulated data. The following methods are available:

  • interpolate: Interpolate the simulated data to the experimental data.
  • pcm: Partial curve mapping area between the experimental and simulated data.
  • area: Area between the experimental and simulated data.
  • frechet-dist: Frechet distance between the experimental and simulated data.
  • curve-length: Curve length between the experimental and simulated data.
  • dtw: Dynamic Time Warping distance between the experimental and simulated data.

data_get_kwargs (None)

A dictionary of keyword arguments for the SVExporter.get method when getting the simulated data. If None, no keyword arguments will be passed.

check_smoothness (False)

A boolean to check the smoothness of the simulated data.

smoothness_threshold (0.05)

A float for the threshold to check the smoothness of the simulated data.

Options to save the optimization results

save_to (None)

A string for the JSON file to save the optimization results. If None, the optimization results will not be saved.

Optimization options

method (PYCMA-CMAES)

The optimization method. The following methods are available:

maxiter

Maximum number of iterations for the optimization method. This options is ignored for Scipy-TNC method.

maxfun

Maximum number of function evaluations for the optimization method. For Scipy-Powell and Scipy-TNC method, this option will be set to maxfev if the maxfev option is not set.

Other options are specific to the optimization method.