matcal.core.parameters

This module contains all classes related to study parameters.

Functions

`serialize_parameter`(parameter)	Converts a parameter into a dictionary that can be serialized with `matcal.core.serializer_wrapper.matcal_save()`
`serialize_parameter_collection`(...)	Converts a parameter collection into a dictionary that can be serialized with `matcal.core.serializer_wrapper.matcal_save()`

Classes

`Parameter`(name, lower_bound, upper_bound[, ...])	The MatCal Parameter class is used to create parameters for a MatCal study.
`ParameterCollection`(name, *parameters)	A collection of `Parameter` objects.
`UserDefinedParameterPreprocessor`(function[, ...])	Use a python function as a preprocessor that will modify incoming parameters before they are passed to the model.

class matcal.core.parameters.Parameter(name, lower_bound, upper_bound, current_value=None, distribution='continuous_design', units=None, preprocessing_tags=[])[source]

The MatCal Parameter class is used to create parameters for a MatCal study.

Parameters:

name (str) – The name for the parameter. This name (wrapped by curly brackets “{name}”) is what MatCal will replace in external executable simulation input and material files. This name will be passed into PythonModels as the keyword for a keyword argument.
lower_bound (float) – This provides the lower bound value for the parameter being created.
upper_bound (float) – This provides the upper bound value for the parameter being created.
current_value (float) – Some MatCal study algorithms require an initial or current value for a parameter. The user can provide it here if required. If one is not provided and it is required for an algorithm, it will be set to the average of the lower bound and upper bound.
distribution (str) – This specifies the distribution type for the parameters. The distribution type for a parameter is required for certain MatCal studies. By default, the distribution is set to “continuous_design”. Valid distribution types that are currently supported are defined in the class member “VALID_DISTRIBUTIONS”.
units (str) – specify units for the parameter, optional
preprocessing_tags (list) – [Currently in Development] Pass in tags for MatCal based scaling of a parameter. Scaling parameters to the unit or log scale has the potential to improve parameter study performance.

Raises:

InvalidDistributionError – if an invalid distribution type is passed to the distribution parameter.
InvalidNameError – The name is not a string.
InvalidRangeError – The initial value is not within the bounds or the lower bound is greater than the upper bound.
InvalidBoundError – If the bounds are not numbers.
InvalidCurrentValueError – If the current value is not a number.
InvalidUnitsError – If the units parameter is not a string.

class distributions[source]: Supported parameter distributions in MatCal.

property name

Returns:: Returns the parameter name.
Return type:: str

get_current_value()[source]

Returns:: Returns the parameter initial value.
Return type:: float

get_lower_bound()[source]

Returns:: Returns the parameter lower bound.
Return type:: float

get_upper_bound()[source]

Returns:: Returns the parameter upper bound.
Return type:: float

get_name()[source]

Returns:: Returns the parameter name.
Return type:: str

get_units()[source]

Returns:: Returns the units for the parameter
Return type:: str

get_distribution()[source]

Returns:: Returns the parameter distribution.
Return type:: str

property preprocessing_tags: Get the a list of tags used for parameter preprocessing done by MatCal explicitly, and not by an external library. :return: Returns a list of preprocessing tags :rtype: list

class matcal.core.parameters.ParameterCollection(name, *parameters)[source]

A collection of Parameter objects. This is used to combine multiple parameter objects so that they can be passed to a MatCal study. MatCal will use all parameters in the parameter collections as the study parameters. Currently, a parameter collection requires that all parameters have the same distribution.

Parameters:

name (str) – The name of the parameter collection.
parameters (list(class:~matcal.core.parameters.Parameter)) – the parameters to be added to the collection.

Raises:

CollectionValueError – If name is 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.

add(param)[source]

This adds a Parameter to the parameter collection.

Parameters:: param (Parameter) – the parameter object to be added to the collection

update_from_results(final_parameters: dict)[source]

Updates the initial value of each parameter in a parameter collection using the results from a study. Can be used for workflows where the results of a study are used as the initial point for another study.

Parameters:: final_parameters (dict) – the results from a completed MatCal Study

update_parameters(**parameter_updates)[source]

Updates the initial value of parameters in a parameter collection using keyword arguments where the keyword is the parameter name and the value are the updated parameter initial value.

Parameters:: parameter_updates – the keyword/value pairs that will be used to update the parameter collection.

get_distribution()[source]

Returns:: the distribution of the parameter collection.

get_current_value_dict()[source]

Returns:: returns a dictionary where the keys are the parameter names, and the values are the parameter current value
Return type:: dict

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.parameters.UserDefinedParameterPreprocessor(function, filename=None)[source]

Use a python function as a preprocessor that will modify incoming parameters before they are passed to the model. It takes two forms of input:

Pass in a locally defined function for the parameter function.
Pass in the name of the python function for the parameter function as a string and a string which gives the full path of the file where the python function is defined. Since MatCal will import from this file, it is recommended that nothing is defined or executed in the global names space of that file.

The python function should take in a dictionary that contains all calibration parameters with keys being the parameter name and values being the current value passed in by the study. It should return a dictionary with updated parameter values. Note that this can also be used to add new parameter values derived from the passed in parameters. Just add a new key-value pair to the dictionary.

Parameters:

function (Callable or str) – locally defined function or name of function defined in another file.
filename (str) – Name of the file where the function is defined if not in the MatCal python input file.

Returns:

an updated parameter dictionary with the keys being the parameter names, and the values being the updated values. Note that new values can be added, and these values can be strings derived from the incoming parameters.

Return type:

dict

matcal.core.parameters.serialize_parameter(parameter)[source]

Converts a parameter into a dictionary that can be serialized with matcal.core.serializer_wrapper.matcal_save()

Parameters:: parameter (Parameter) – a parameter to be serialized
Returns:: a dictionary with all of the parameter attributes
Return type:: dict

matcal.core.parameters.serialize_parameter_collection(parameter_collection)[source]

Converts a parameter collection into a dictionary that can be serialized with matcal.core.serializer_wrapper.matcal_save()

Parameters:: parameter_collection (ParameterCollection) – a parameter collection to be serialized
Returns:: a dictionary with all of the parameter and parameter collection attributes
Return type:: dict