ensemble

Descriptive description.

Ensemble

Bases: Ensemble

Class to store control states and evaluate objective functions.

Methods:

Name	Description
get_state	Returns control vector as ndarray
get_final_state	Returns final control vector between [lb,ub]
get_cov	Returns the ensemble covariance matrix
function	Objective function called during optimization
gradient	Ensemble gradient
hessian	Ensemble hessian
calc_ensemble_weights	Calculate weights used in sequential monte carlo optimization

__init__(keys_en, sim, obj_func)

Parameters:

Name	Type	Description	Default
keys_en	dict	Options for the ensemble class disable_tqdm: supress tqdm progress bar for clean output in the notebook ne: number of perturbations used to compute the gradient state: name of state variables passed to the .mako file prior_: the prior information the state variables, including mean, variance and variable limits num_models: number of models (if robust optimization) (default 1) transform: transform variables to [0,1] if true (default true)	required
sim	callable	The forward simulator (e.g. flow)	required
obj_func	callable	The objective function (e.g. npv)	required

calc_ensemble_weights(x, *args, **kwargs)

Calculate weights used in sequential monte carlo optimization.

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

function(x, *args, **kwargs)

This is the main function called during optimization.

Parameters:

Name	Type	Description	Default
x	ndarray	Control vector, shape (number of controls, number of perturbations)	required

Returns:

Name	Type	Description
obj_func_values	ndarray	Objective function values, shape (number of perturbations, )

get_bounds()

Returns:

Name	Type	Description
bounds	list	(min, max) pairs for each element in x. None is used to specify no bound.

get_cov()

Returns:

Name	Type	Description
cov	ndarray	Covariance matrix, shape (number of controls, number of controls)

get_final_state(return_dict=False)

Parameters:

Name	Type	Description	Default
return_dict	bool	Retrun dictionary if true	False

Returns:

Name	Type	Description
x	ndarray	Control vector as ndarray, shape (number of controls, number of perturbations)

get_state()

Returns:

Name	Type	Description
x	ndarray	Control vector as ndarray, shape (number of controls, number of perturbations)

gradient(x, *args, **kwargs)

Calculate the preconditioned gradient associated with ensemble, defined as:

\[ S \approx C_x \times G^T \]

where \(C_x\) is the state covariance matrix, and \(G\) is the standard gradient. The ensemble sensitivity matrix is calculated as:

\[ S = X \times J^T /(N_e-1) \]

where \(X\) and \(J\) are ensemble matrices of \(x\) (or control variables) and objective function perturbed by their respective means. In practice (and in this method), \(S\) is calculated by perturbing the current control variable with Gaussian random numbers from \(N(0, C_x)\) (giving \(X\)), running the generated ensemble (\(X\)) through the simulator to give an ensemble of objective function values (\(J\)), and in the end calculate \(S\). Note that \(S\) is an \(N_x \times 1\) vector, where \(N_x\) is length of the control vector and the objective function is scalar.

Parameters:

Name	Type	Description	Default
x	ndarray	Control vector, shape (number of controls, )	required
args	tuple	Covarice (\(C_x\)), shape (number of controls, number of controls)	()

Returns:

Name	Type	Description
gradient	ndarray	The gradient evaluated at x, shape (number of controls, )

hessian(x=None, *args)

Calculate the hessian matrix associated with ensemble, defined as:

\[ H = J(XX^T - \Sigma)/ (N_e-1) \]

where \(X\) and \(J\) are ensemble matrices of \(x\) (or control variables) and objective function perturbed by their respective means.

Note

state and ens_func_values are assumed to already exist from computation of the gradient. Save time by not running them again.

Parameters:

Name	Type	Description	Default
x	ndarray	Control vector, shape (number of controls, number of perturbations)	None

Returns:

Name	Type	Description
hessian	ndarray	The hessian evaluated at x, 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