ensembles⚓︎
Ensembles that estimate objective gradients and Hessians for popt's optimizers.
GaussianEnsemble
⚓︎
Bases: EnsembleOptimizationBase
Gaussian Ensemble class for ensemble-based optimization.
Methods:
| Name | Description |
|---|---|
gradient |
Ensemble gradient |
hessian |
Ensemble hessian |
calc_ensemble_weights |
Calculate weights used in sequential monte carlo optimization |
__init__(options, simulator, objective)
⚓︎
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
options
|
dict
|
Options for the ensemble class
|
required |
simulator
|
callable
|
The forward simulator (e.g. flow) |
required |
objective
|
callable
|
The objective function (e.g. npv) |
required |
calc_ensemble_weights(x, *args, **kwargs)
⚓︎
Calculate weights used in sequential monte carlo optimization. Updated version that accommodates new base class changes.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
x
|
ndarray
|
Control vector, shape (number of controls, ) |
required |
args
|
tuple
|
Inflation factor, covariance (\(C_x\), shape (number of controls, number of controls)) and survival factor |
()
|
Returns:
| Type | Description |
|---|---|
sens_matrix, best_ens, best_func : tuple
|
The weighted ensemble, the best ensemble member, and the best objective function value |
gradient(x, *args, **kwargs)
⚓︎
Estimate the ensemble gradient (EnOpt) at a given state.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
x
|
ndarray
|
Control vector, shape (number of controls, ). |
required |
args
|
tuple
|
First positional argument must be the covariance matrix with shape (number of controls, number of controls). |
()
|
Returns:
| Type | Description |
|---|---|
ndarray
|
Ensemble gradient, shape (number of controls, ). |
Raises:
| Type | Description |
|---|---|
ValueError
|
If required inputs are missing or have invalid shapes. |
hessian(x=None, *args, **kwargs)
⚓︎
Ensemble-based Hessian.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
x
|
ndarray
|
Control vector, shape (number of controls, ). If None, use the last x used in gradient. If x is not None and it does not match the last x used in gradient, recompute the gradient first. |
None
|
args
|
tuple
|
Additional arguments passed to function |
()
|
Returns:
| Name | Type | Description |
|---|---|---|
hessian |
ndarray
|
Ensemble hessian, shape (number of controls, number of controls) |
References
Zhang, Y., Stordal, A.S. & Lorentzen, R.J. A natural Hessian approximation for ensemble based optimization. Comput Geosci 27, 355–364 (2023). https://doi.org/10.1007/s10596-022-10185-z
GeneralizedEnsemble
⚓︎
Bases: EnsembleOptimizationBase
Control perturbations with a non-Gaussian marginal (beta, logistic, truncated Gaussian, or Gaussian) coupled by a Gaussian copula, and the mutation-based gradient and Hessian estimates that go with them.
Perturbations are drawn as correlated standard normals enZ mapped through the marginal's quantile
function; the gradient of the expected objective follows from the score of the sampling density
(gradient/hessian), and its derivative with respect to the marginal's own parameter theta
(mutation_gradient/mutation_hessian) lets the distribution itself be adapted.
__init__(options, simulator, objective)
⚓︎
get_corr()
⚓︎
The correlation matrix of the Gaussian copula.
get_theta()
⚓︎
The marginal's parameters, one row per control.
gradient(x, *args, **kwargs)
⚓︎
Estimate the gradient of the expected objective at x from the sampled members (enX, enZ, enF may be passed in; else sampled and evaluated). Also sets avg_hess.
hessian(x, *args, **kwargs)
⚓︎
The Hessian estimate from the last gradient call (recomputed when sample=True).
mutation_gradient(x, *args, **kwargs)
⚓︎
Gradient of the expected objective with respect to the marginal's parameter theta, for adapting the distribution. Also sets nat_hess.
With return_ensembles=True it returns (nat_grad, {'gaussian': enZ,
'objective': enF}) instead, so a caller adapting the correlation matrix --
:class:~popt.optimization_methods.subroutines.cma.CMA -- can reuse the
ensemble this gradient came from rather than drawing and simulating another.
mutation_hessian(x, *args, **kwargs)
⚓︎
The theta Hessian estimate from the last mutation_gradient call (recomputed when sample=True).
sample(size=None)
⚓︎
Draw size perturbed controls: correlated normals enZ through the marginal's quantile function, clipped to the bounds. Returns (enX, enZ).
var2eps()
⚓︎
Half-width of the beta perturbation interval that reproduces the control variance.