Source Code Documentation

Documentation for the core MXMC classes.

Optimizer Module

class optimizer.Optimizer(*args, **kwargs)

User interface for accessing all MXMC variance minimization optimizers for computing optimal sample allocations.

Parameters:
  • model_costs (list of floats) – cost (run time) of all models
  • covariance (2D np.array) – Covariance matrix defining covariance (of outputs) among all available models. Size MxM where M is # models.
static get_algorithm(algorithm_name)

Returns a reference to a class indicated by the provided name.

static get_algorithm_names()

Returns a list of strings containing the names of all available optimization algorithms.

optimize(algorithm, target_cost, auto_model_selection=False)

Performs variance minimization optimization to determine the optimal sample allocation across available models within a specified target computational cost.

Parameters:
  • algorithm (string) – name of method to use for optimization (e.g., “mlmc”, “mfmc”, “acvkl”).
  • target_cost (float) – total target cost constraint so that optimizer finds sample allocation that requires less than or equal computation time.
  • auto_model_selection (Boolean) – flag to use automatic model selection in optimization to test all subsets of models for best set.
Returns:

An OptimizationResult namedtuple with entries for cost, variance, and sample_array. cost (float) is expected cost of all model evaluations prescribed in sample_array (np.array). variance is the minimized variance from the optimization.

Sample Allocation Module

class sample_allocations.SampleAllocation

Base class for managing the allocations of random input samples (model evaluations) across available models. Provides a user with number of model evaluations required to generate an estimator and how to partition input samples to do so, after the sample allocation optimization problem is solved.

Parameters:

compressed_allocation (2D np.array) – a two dimensional array completely describing a MXMC sample allocation; returned by each optimizer class as the result of sample allocation optimization. See docs for a description and example of the format.

Variables:
  • num_total_samples – number of total input samples needed across all available models
  • _utilized_models – list of indices corresponding to models with samples allocated to them
  • num_models – total number of available models
get_number_of_samples_per_model()

Returns the total number of samples allocated to each available model :type: (list of integers)

get_sample_indices_for_model()
Parameters:model_index (int) – index of model to return indices for (from 0 to #models-1)

Returns binary array with indices of samples required by specified model

Type:(np.array with length of num_total_samples)
allocate_samples_to_models()

Allocates a given array of all input samples across all available models according to the sample allocation determined by an MXMX optimizer.

Parameters:all_samples (2D np.array) – array of user-generated random input samples with length equal to num_total_samples

Returns individual arrays of input samples for all available models :type: (list of np.arrays with length equal to num_models)

Output Processor Module

class output_processor.OutputProcessor

Class to estimate covariance matrix from collection of output samples from multiple models. Handles the general case where each models’ outputs were not computed from the same set of random inputs and pairwise overlaps between samples are identified using a SampleAllocation object.

static compute_covariance_matrix(model_outputs, sample_allocation=None)

Estimate covariance matrix from collection of output samples from multiple models. In the simple case, the outputs for each model were generated from the same collection of inputs and covariance can be straightforwardly computed. In the general case, the outputs were not computed from the same inputs and a SampleAllocation object must be supplied to identify overlap between samples to compute covariance.

Parameters:
  • model_outputs (list of np.array) – list of arrays of outputs for each model. Each array must be the same size unless a sample allocation is provided.
  • sample_allocation (SampleAllocation object.) – An MXMC sample allocation object defining the indices of samples that each model output was generated for, if applicable. Default is None indicating that all supplied model output arrays are the same size and were generated for the same inputs.
Returns:

covariance matrix among all model outputs (2D np.array with size equal to the number of models).

Estimator Module

class estimator.Estimator

Class to create MXMC estimators given an optimal sample allocation and outputs from high & low fidelity models.

Parameters:
  • allocation (SampleAllocation object) – SampleAllocation object defining the optimal sample allocation using an MXMC optimizer.
  • covariance (2D np.array) – Covariance matrix defining covariance among all models being used for estimator. Size MxM where M is # models.

Utilities Module

generic_numerical_optimization.perform_slsqp_then_nelder_mead(constraints, initial_guess, obj_func, obj_func_and_grad)
generic_numerical_optimization.perform_slsqp(constraints, initial_guess, obj_func_and_grad)
generic_numerical_optimization.perform_nelder_mead(constraints, initial_guess, obj_func)
read_sample_allocation.read_sample_allocation()

Read sample allocation from file

Parameters:filename (string) – name of hdf5 sample allocation file
Returns:appropriate child of the SampleAllocationBase class based on the optimization method stored in the hdf5 file.
sample_modification.adjust_sample_allocation_to_cost(target_cost, model_costs, covariance)

Tests all possible increases to sample counts per group and returns sample allocation with the lowest variance while limiting total cost to be within the specified target_cost.