KL-Divergence Optimality Criteria#

class EvaluationMethod(value)[source]#

Bases: StrEnum

EXACT = '\\Aexact\\Z'#

RANDOMIZED = '\\A(random|randomized)\\Z'#

class BayesianInversionKLDivergenceGaussianConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', oed_problem=None, lp_behavior=LP_Behavior.LINEAR, evaluation_method='exact', sample_size=50, optimize_sample_size=False, min_sample_size=10, max_sample_size=100, distribution='Rademacher', randomization_vectors=None, random_seed=None, accuracy=0.01)[source]#

Bases: BayesianInversionCriterionConfigs

Configuration class for Bayesian KL-Divergence (between Gaussians) criterion. This configurations class holds configurations/attributes for configuring

Parameters:

verbose (bool) – a boolean flag to control verbosity of the object.
debug (bool) – a boolean flag that enables adding extra functionality in a debug mode
output_dir (str | Path) – the base directory where the output files will be saved.
oed_problem (InversionOED | None) – OED problem for which the utility function is defined. This must be an instance of InversionOED.
lp_behavior (LP_Behavior | str) –
behavior of the linearization point (MAP, prior, manual). By default, this is set to LP_Behavior.LINEAR which detects whether the problem is linear or nonlinear and decides what to do accordingly:
- ’linear’: This automates the selection of the selection of the linearization point based on whether the problem is linear or not. If the problem is linear, the linearization point is typically set to None, otherwise it is set to the MAP estimate from the posterior.
- ’map’: The linearization point is set to the MAP estimate. The MAP estimate is used even if the problem is linear in this case. Only use this if the problem is nonlinear. Note that the MAP point depends on the design, and thus, the MAP estimate will be reevaluated if the design changes
- ’prior’: Use the mean of the prior regardless of the design and whether the problem is linear or not.
- ’manual’: The assigned linearization point will be forecefully used whether it is valid or not.
evaluation_method (str) –
A string describing the method to use for computing the criterion and its gradients. Supported are:
- "exact": Compute the exact value of the criterion. Potentially
  intractable if problem is too large.
- "randomized": Use randomized algorithms to compute the
  criterion value. Potentially faster for large problems but may be inaccurate.
sample_size (int) – The number of samples to use for randomized algorithms. Default is 50.
optimize_sample_size (bool) – If True, the sample size is optimized based on the problem size. Default is False.
min_sample_size (int) – The minimum sample size to use for randomized algorithms. Default is 10.
max_sample_size (int) – The maximum sample size to use for randomized algorithms. Default is 100.
distribution (str) – The distribution to use for randomization. Default is “Rademacher”.
randomization_vectors (None | ndarray | Sequence) – The randomization vectors to use for randomized algorithms. Default is None. Note, if None, the randomization vectors are constructed and saved for future use during the first evaluation.
random_seed (None | int) – The random seed to use for randomized algorithms. Default is None.

evaluation_method: str#

sample_size: int#

optimize_sample_size: bool#

min_sample_size: int#

max_sample_size: int#

distribution: str#

randomization_vectors: None | ndarray | Sequence#

random_seed: None | int#

accuracy: float#

__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', oed_problem=None, lp_behavior=LP_Behavior.LINEAR, evaluation_method='exact', sample_size=50, optimize_sample_size=False, min_sample_size=10, max_sample_size=100, distribution='Rademacher', randomization_vectors=None, random_seed=None, accuracy=0.01)#

class BayesianInversionKLDivergenceGaussian(configs=None)[source]#

Bases: BayesianInversionCriterion

An implementation of the Kullback-Leibler divergence criterion for Bayesian Optimal Design of Experiments. This particular version is under the assumption that BOTH the prior and the posterior are Gaussian. This is true if the inverse problem is linear, but in the case it isn’t, this assumption corresponds to the Laplace approximation of the posterior. The criterion is defined as

\[D_{\text{KL}}\left({\mathcal {N}}_{0}\parallel {\mathcal {N}}_{1}\right) ={\frac {1}{2}}\left(\operatorname {tr} \left(\Sigma_{1}^{-1}\Sigma_{0}\right) +\left(\mu_{1}-\mu_{0}\right)^{\mathsf{T}}\Sigma_{1}^{-1}\left(\mu_{1}-\mu_{0}\right) -k+\ln \left({\frac {\det \Sigma_{1}}{\det \Sigma_{0}}}\right)\right)\]

Note

See https://en.wikipedia.org/wiki/Kullback%E2%80%93Leibler_divergence

__init__(configs=None)[source]#

Constructor for utility functions / optimality criteria.

Parameters:: configs (dict) – Object holding configurations for the criterion.

validate_configurations(configs, raise_for_invalid=True)[source]#

A method to check the passed configurations and make sure they are conformable with each other, and with current configurations (or default of not set)

Parameters:

configs (dict | BayesianInversionKLDivergenceGaussianConfigs) – an object holding key/value configurations
raise_for_invalid (bool) – if True raise TypeError for invalid configrations key

Returns:

True/False flag indicating whether passed configurations is valid or not

update_evaluation_method(evaluation_method)[source]#: Update the evaluation method.

update_configurations(**kwargs)[source]#

Update one or more configurations given their name and value. Each configuration key/value is validated against current values (more precedence to passed, then current settings).

If all passed configurations are conformable with each other, and with current configurations, the passed configurations updated the underlying configurations dictionary.

evaluate(design)[source]#

Evaluate the KL Divergence for the given OED problem at the given design.

Warning

Currently, oed.problem_is_linear is ignored, which results in non-linear problems receiving the Gaussian approximation around the MAP point. This behavior is not guaranteed and may change in the future.

Parameters:: design – an observational design vector conformable with the observation operator and the observation error covariance matrix operator.
Returns:: KL-Divergence between prior and (Gaussian) posterior.
Return type:: float

property evaluation_method#

The method used for computing the criterion value and its gradients. Two options:

‘exact’: Compute the exact value. Potentially slow but accurate.
‘randomized’: Use randomized algorithms. Fast but potentially inaccurate.

property sample_size#: Return the sample size for randomized algorithms

property optimize_sample_size#: Return the flag indicating whether to optimize the sample size

property min_sample_size#: Return the minimum sample size for randomized algorithms

property max_sample_size#: Return the maximum sample size for randomized algorithms

property distribution#: Return the distribution used for randomization

property randomization_vectors#: Return the randomization vectors used for randomized algorithms;

Note

This assumes randomization is in the inference parameter space.

property random_seed#: Return the random seed used for randomized algorithms

property accuracy#: Return the accuracy used for randomized algorithms