pyopmat.optimize: calibrating parameters against data

Objects and helper functions to help with deterministic model calibration and statistical inference.

These include the key classes

which implement

  • deterministic model prediction and optimization

  • single-level statistical model prediction and inference

  • hierarchical statistical model prediction and inference

These three classes share some common features. One input to all three is the “model maker” function. This is a function that takes as input as *args a set of parameters (which can be torch tensors, torch Parameters, or :py:mod`:pyro samples as appropriate) and returns a valid torch.nn.Module. Calling this module in turn provides the integrated model predictions. The maker function can also take **kwargs, for example to provide values that should not be optimized or hyperparameters describing how to integrate the model results.

The classes also take a list of str names, one for each parameter the maker function takes as input. These names are used to describe the various torch Parameters or pyro samples and parameters. The specific details of how these are used depends on the type of model.

Parameter values, for example as starting locations or descriptions of the priors, are given as lists of torch.tensor objects, again one for each model parameter.

class pyoptmat.optimize.DeterministicModel(maker, names, ics)

Bases: Module

Wrap a material model to provide a pytorch deterministic model

Parameters:

  • maker (function) – function that returns a valid model as a pytorch.nn.Module, given the input parameters

  • names (list(str)) – names to use for the parameters

  • ics (list(torch.tensor)) – initial conditions to use for each parameter

forward(exp_data, exp_cycles, exp_types, exp_control)

Integrate forward and return the results.

See the pyoptmat.experiments module for detailed on how to format the input to this function

Parameters:

  • exp_data (torch.tensor) – formatted input experimental data

  • exp_cycles (torch.tensor) – cycle counts for each test

  • exp_types (torch.tensor) – experiment types, as integers

  • exp_control (torch.tensor) – stress/strain control flag

get_params()

Return the parameters for input to the model

class pyoptmat.optimize.HierarchicalStatisticalModel(maker, names, loc_loc_priors, loc_scale_priors, scale_scale_priors, noise_prior, loc_suffix='_loc', scale_suffix='_scale', param_suffix='_param', include_noise=False, weights=None)

Bases: PyroModule

Wrap a material model to provide a hierarchical pyro statistical model

This type of statistical model does two levels of sampling for each parameter in the base model.

First it samples a random variable to select the mean and scale of the population of parameter values

Then, based on this “top level” location and scale it samples each parameter independently – i.e. each experiment is drawn from a different “heat”, with population statistics given by the top samples

At least for the moment the population means are selected from normal distributions, the population standard deviations from HalfNormal distributions, and then each parameter population comes from a Normal distribution

Parameters:

  • maker (function) – function that returns a valid :py:class`torch.nn.Module`, given the input parameters

  • names (list(str)) – names to use for the parameters

  • loc_loc_priors (list(tensor)) – location of the prior for the mean of each parameter

  • loc_scale_priors (list(tensor)) – scale of the prior of the mean of each parameter

  • scale_scale_priors (list(tensor)) – scale of the prior of the standard deviation of each parameter

  • noise_priors (list or scalar) – random noise, can be either a single scalar or a 1D tensor if it’s a 1D tensor then each entry i represents the noise in test type i

Keyword Arguments:

  • loc_suffix (str) – append to the variable name to give the top level sample for the location, default "_loc"

  • scale_suffix (str) – append to the variable name to give the top level sample for the scale, default "_scale"

  • param_suffix (str) – append to the variable name to give the corresponding pyro.param name, default "_param"

  • include_noise (str) – if True include white noise in the inference, default False

  • weights (dict or None) – weights for each test type given as a dict mapping {test_type: weight}. If None then weight all test types equally

forward(exp_data, exp_cycles, exp_types, exp_control, exp_results=None)

Evaluate the forward model, optionally conditioned by the experimental data.

Optionally condition on the actual data

See the pyoptmat.experiments module for detailed on how to format the input to this function

Parameters:

  • exp_data (torch.tensor) – formatted input experimental data

  • exp_cycles (torch.tensor) – cycle counts for each test

  • exp_types (torch.tensor) – experiment types, as integers

  • exp_control (torch.tensor) – stress/strain control flag

Keyword Arguments:

exp_results (torch.tensor) – true results for conditioning

get_extra_params()

Actually list the extra parameters required for the adjoint solve.

We can’t determine this by introspection on the base model, so it needs to be done here

make_guide()

Make the guide and cache the extra parameter names the adjoint solver is going to need

property nparams

Number of parameters in model

sample_bot()

Sample the bottom level variables

sample_top()

Sample the top level variables

class pyoptmat.optimize.StatisticalModel(maker, names, locs, scales, eps, nan_num=False)

Bases: PyroModule

Wrap a material model to provide a py:mod:pyro single-level statistical model

Single level means each parameter is sampled once before running all the tests – i.e. each test is run on the same material properties.

Generally this is not appropriate for fitting models (see pyoptmat.optimize.HierarchicalStatisticsModel) but can be a nice way to evaluate models (i.e. run all tests on a single “heat” of material multiple times to sample heat-to-heat variation).

Parameters:

  • maker (function) – function that returns a valid torch.nn.Module, given the input parameters

  • names (list(str)) – names to use for the parameters

  • loc (list(torch.tensor)) – parameter location priors

  • scales (list(torch.tensor) – parameter scale priors

  • eps (list or scalar) – random noise, can be either a single scalar or a 1D tensor if it’s a 1D tensor then each entry i represents the noise in test type i

forward(exp_data, exp_cycles, exp_types, exp_control, exp_results=None)

Integrate forward and return the result

Optionally condition on the actual data

See the pyoptmat.experiments module for detailed on how to format the input to this function

Parameters:

  • exp_data (torch.tensor) – formatted input experimental data

  • exp_cycles (torch.tensor) – cycle counts for each test

  • exp_types (torch.tensor) – experiment types, as integers

  • exp_control (torch.tensor) – stress/strain control flag

Keyword Arguments:

exp_results (torch.tensor) – true results for conditioning

get_params()

Return the sampled parameters for input to the model

pyoptmat.optimize.bound_and_scale(scale, bounds)

Combination of scaling and bounding

Parameters:

  • scale (torch.tensor) – divide input by this value

  • bounds (torch.tensor) – tuple, clamp to (bounds[0], bounds[1])

pyoptmat.optimize.bound_factor(mean, factor, min_bound=None)

Apply the bounded_scale_function map but set the upper bound as mean*(1+factor) and the lower bound as mean*(1-factor)

Parameters:

  • mean (torch.tensor) – center value

  • factor (torch.tensor) – bounds factor

Keyword Arguments:

min_bound (torch.tensor) – clip to avoid going lower than this value

pyoptmat.optimize.bounded_scale_function(bounds, min_bound=None)

Sets up a scaling function that maps (0,1) to (bounds[0], bounds[1]) and clips the values to remain in that range

Parameters:

bounds (tuple(torch.tensor,torch.tensor)) – tuple giving the parameter bounds

Additional Args:

min_bounds (torch.tensor): clip to avoid going lower than this value

pyoptmat.optimize.clamp_scale_function(bounds)

Just clamp to bounds

Parameters:

bounds (tuple(torch.tensor, torch.tensor)) – tuple giving the parameter bounds

pyoptmat.optimize.log_bound_and_scale(scale, bounds)

Scale, de-log, and bound

Parameters:

  • scale (torch.tensor) – divide input by this value, then take exp

  • bounds (torch.tensor) – tuple, clamp to (bounds[0], bounds[1])