Robust Binary Optimization#

`RobustBinaryReinforceOptimizer`([configs])	Robust Binary Optimization by stochastic learning.
`RobustBinaryReinforceOptimizerConfigs`(*[, ...])	Configuration dataclass for the `RobustBinaryReinforceOptimizer`.
`RobustBinaryReinforceOptimizerResults`(*[, ...])	Container for results/data generated by the `RobustBinaryReinforceOptimizer`.

A module providing access to multiple Robust Binary optimization routines.

class RobustBinaryReinforceOptimizerConfigs(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', size=None, name='RobustBinaryReinforceOptimizer: Robust Binary Optimization via Stochastic Learning', screen_output_iter=1, file_output_iter=100, fun=None, initial_policy=None, maximize=True, def_stepsize=0.1, decay_step=False, Newton_step=False, stochastic_gradient_sample_size=32, baseline='optimal', optimal_baseline_batch_size=32, optimal_sample_size=5, objective_value_tracker=None, maxiter=100, pgtol=1e-12, monitor_iterations=True, random_seed=None, antithetic=True, uniform_random_sample_size=0, num_resets=0, uncertain_parameter_size=None, maxmin=True, fun_grad_parameter=None, fun_grad_design=None, uncertain_parameter_sample=<factory>, uncertain_parameter_bounds=None, solve_by_relaxation=False, reset_initial_guess=False, deterministic_optimization_routine='Scipy-L-BFGS-B', tol=1e-12, outer_opt_maxiter=1000, inner_opt_maxiter=10000, uncertain_parameter_max_num_digits=12)[source]#

Bases: BinaryReinforceOptimizerConfigs

Configuration dataclass for the RobustBinaryReinforceOptimizer. This inherits all keys/configurations/attributes of BinaryReinforceOptimizerConfigs with the additional keys/attributes described below. The RobustBinaryReinforceOptimizer is a modification from Polyak’s algorithm developed for stochastic optimization with proper maxmin formulation.

Parameters:

verbose (bool) – a boolean flag to control verbosity of the object.
debug (bool) – a boolean flag that enables adding extra functionlity in a debug mode
output_dir (str | Path) – the base directory where the output files will be saved.
name (str) – name of the optimizer. Default is None.
screen_output_iter (int) – iteration interval for screen output. Default is 1. Note that this should be a positive integer to enforce proper effect.
file_output_iter (int) – iteration interval for file output. Default is 1. Note that this should be a positive integer to enforce proper effect.
size (int | None) – dimension of the target/solution variable. Must be a positive integer
fun (Callable | None) – the objective function to be optimization. For a given binary state/design of size size it returns a scalar.
initial_policy (ndarray | Iterable | None) – the initial probabilistic policy parameter (activation/success probability of the Bernoulli distribution)
maximize (bool) – if True the objective is to be maximized, otherwise minimization is assumed
def_stepsize (float) – default step size (learning rate) in the direction (or the opposite) of the gradient. Default is 1.
decay_step (bool) – if True reduce the learning rate (step size) as the algorithm proceeds
Newton_step (bool) – if True use second-order derivative to define the update direction
stochastic_gradient_sample_size (int) – size of the sample to generate (from current policy at each iteration) to estimate (using MC) the policy gradient
baseline (str | None) –
name/type of the baseline used to reduce variability of the stochastic estimate of the gradient to use (if any); possible values are None, ‘none’, ‘optimal’, ‘heuristic’. These are explained as follows:
- ’none’ | None: no baseline is used.
- ’heuristic’: evaluate an empirical baseline \((J(0)+J(1))/2\) with \(J\) being the passed fun.
- ’optimal’: a constant baseline is found by approximating the optimal baseline where optimality is defined as minimum variability of the estimator.
optimal_baseline_batch_size (int) – size of the batch/sample to use for optimal baseline estimation; used if baseline==True.
optimal_sample_size (int) – size of the sample to return from the final/optimal policy upon termination of the optimizer
objective_value_tracker (dict | None) –
a dictionary that holds values of the objective function for sampled binary vectors. This can be helpful if the optimizer was run previously and objective vlaues have been saved. This is used as the initializer of the tracker used while solving the optimization problem.

Note

The objective_value_tracker in the configurations object is not updated as the solver proceeds. It is only used as the initializer of the internal tracker. The results returned from the optimizer contain another copy of the objective_value_tracker with updated sampled binary vectors and corresponding objectives.
uniform_random_sample_size (int) – size of a random sample generated uniformly (0.5 probability) for performance evaluation.
num_resets (None | int) – number of resets during optimization
uncertain_parameter_size (int | None) – The dimension/size of the uncertain parameter
maxmin (bool) – if True, a max-min optimization prolem is assumed, otherwise, a min-max problem is considere.
fun_grad_parameter (Callable | None) – If this is callable, it is (similar to fun configuration required by the parent class,) a function that accepts a binary design, and a realization of the the uncertain parameter (design, parameter). This is a function that calculates the gradient of of the objective function ‘fun’ with respect to the uncertainty paramter. If None, finite differences is used to calculate such gradient, though this will be expensive.
fun_grad_design (Callable | None) – if given, a function that calculates the gradient of fun with respect to the relaxed design; similar to fun, this function accepts two paramters (design, param).
maxiter (int) – maximum number of iterations of Polyak algorithm. This controls the number of times the algorithms alternates between updating the policy/design and the uncertain parameter. The updates for each of those is carried out by the corresponding optimizers which have their own number of iterations set by outer_opt_maxiter and inner_opt_maxiter, respectively.
outer_opt_maxiter (int) – maximum number of iterations of the optimizaer solving the outer optimization problem (maximization of the design/policy). This sets the maximum number of iterations of the optimization algorithm that updates the policy (outer optimization). This controls maxiter passed to the stochastic (or relaxed) optimization algorithm that optimizes for a design or policy parameters.
inner_opt_maxiter (int) – maximum number of iterations of the inner optimization problem. This is passed to the inner loop optimizer that solves the inner optimization for an optimal uncertain parameter.
uncertain_parameter_sample (Iterable[ndarray]) – sample from the uncertain parameter space (param). This is used as the initializer of the tracker used while solving the optimization problem.
uncertain_parameter_bounds (Tuple[None, None] | Iterable[Tuple[float | None, float | None]] | None) – bounds/domain of the uncertain parameter.
solve_by_relaxation (bool) – whether to allow relaxation of the design or use stochastic binary approach if True, then fun_grad_design should be given, otherwise finite differences is used to approximate it.
deterministic_optimization_routine (str) – Name of the optimization routine to be used for the inner optimization problem (over the uncertain parameter. This is also used for the outer optimization problem is solve_by_relaxation is True.
tol (float) – tolerance used for termination of inner optimization steps (over the uncertain parameter). This is different from pgtol used for the outer stochastic binary optimization termination.

uncertain_parameter_size: int | None#

maxmin: bool#

fun_grad_parameter: Callable | None#

fun_grad_design: Callable | None#

uncertain_parameter_sample: Iterable[ndarray]#

uncertain_parameter_bounds: Tuple[None, None] | Iterable[Tuple[float | None, float | None]] | None#

solve_by_relaxation: bool#

reset_initial_guess: bool#

deterministic_optimization_routine: str#

tol: float#

outer_opt_maxiter: int#

inner_opt_maxiter: int#

uncertain_parameter_max_num_digits: int#

__init__(*, debug=False, verbose=False, output_dir='./_PYOED_RESULTS_', size=None, name='RobustBinaryReinforceOptimizer: Robust Binary Optimization via Stochastic Learning', screen_output_iter=1, file_output_iter=100, fun=None, initial_policy=None, maximize=True, def_stepsize=0.1, decay_step=False, Newton_step=False, stochastic_gradient_sample_size=32, baseline='optimal', optimal_baseline_batch_size=32, optimal_sample_size=5, objective_value_tracker=None, maxiter=100, pgtol=1e-12, monitor_iterations=True, random_seed=None, antithetic=True, uniform_random_sample_size=0, num_resets=0, uncertain_parameter_size=None, maxmin=True, fun_grad_parameter=None, fun_grad_design=None, uncertain_parameter_sample=<factory>, uncertain_parameter_bounds=None, solve_by_relaxation=False, reset_initial_guess=False, deterministic_optimization_routine='Scipy-L-BFGS-B', tol=1e-12, outer_opt_maxiter=1000, inner_opt_maxiter=10000, uncertain_parameter_max_num_digits=12)#

class RobustBinaryReinforceOptimizerResults(*, optimal_policy=None, optimal_policy_sample=None, optimal_policy_sample_objval=None, optimal_design=<factory>, optimal_design_objval=None, uncertain_parameter_sample=None, optimal_uncertain_parameter=None, optimization_trajectory=None, optimization_trajectory_objval=None, optimization_trajectory_stoch_objval=None, inner_optimization_results=None, outer_optimization_results=None, converged=False, maxiter_reached=False, message=<property object>, objective_value_tracker=None, configurations=None)[source]#

Bases: OptimizerResults

Container for results/data generated by the RobustBinaryReinforceOptimizer.

Parameters:

optimal_policy (ndarray | None) – the parameters of the optimal policy (probability of activation of each entry of the design)
optimal_policy_sample (ndarray | None) – design sample generated by sampling the optimal policy (Bernoulli samples with probababilities set to the optimal policy parameters optimal_policy_parameters)
optimal_policy_sample_objval (ndarray | None) – value of the objective function \(J\) evaluated at each design in optimal_sample
optimal_design (ndarray) – the optimal design (binary vector) sampled from the optimal_policy.
optimal_design_objval (float | None) – the value of the objective function evaluated at the above optimal design.
uncertain_parameter_sample (list[ndarray] | None) – sample from the uncertain parameter space (param) expanded by the solution algorithm
optimal_uncertain_parameter (ndarray | None) – the value of the uncertain parameter corresponding the the optimal solution.
optimization_trajectory (list[ndarray, ndarray] | None) – trajectory (consecutive parameters) of the policy parameters generated along the optimization iterations; populated only if monitor_iterations configuration is set to True. The optimization trajectory is on the form [(d0, p0), (d1, p1), ...] where di is either the design (binary) variable or the Bernoulli parameters, and pi is the uncertain parameter.
optimization_trajectory_objval (list[float] | None) – value of the deterministic objective function, that is \(J\) along the optimization trajectory; populated only if solve_by_relaxation configuration is set to True. This is the fomr [J(d0, p0), J(d1, p1), ...] where `J is the fun in the configurations.
optimization_trajectory_stoch_objval (list[float] | None) – value (MC estimate) of the stochastic objective function, that is \(E[J]\) along the optimization trajectory; populated only if solve_by_relaxation configuration is set to False. This is the fomr [E(J(d0, p0)), E(J(d1, p1)), ...] where the expection E is estimated by averaging (monte carlo estimate).
inner_optimization_results (list[dict] | None) – a list holding results for each of the inner optimization iterations.
outer_optimization_results (list[dict] | None) – a list holding results for each of the outer optimization iterations.
converged (bool) – True if the algorithm converged, False otherwise.
msg – a string message describing the final status of the algorithm
objective_value_tracker (dict | None) – a dictionary containing the value of the objective function evaluated through the course of the algorithm. The dictionary is indexed by the integer indexes of the generated binary states.
configurations (None | dict) – a dictionary holding problem configurations. This can be obtained by calling asdict() of the configurations object used by the optimizer, e.g., BinaryReinforceOptimizerConfigs.

optimal_policy: ndarray | None#

optimal_policy_sample: ndarray | None#

optimal_policy_sample_objval: ndarray | None#

optimal_design: ndarray#

optimal_design_objval: float | None#

uncertain_parameter_sample: list[ndarray] | None#

optimal_uncertain_parameter: ndarray | None#

optimization_trajectory: list[ndarray, ndarray] | None#

optimization_trajectory_objval: list[float] | None#

optimization_trajectory_stoch_objval: list[float] | None#

inner_optimization_results: list[dict] | None#

outer_optimization_results: list[dict] | None#

converged: bool#

maxiter_reached: bool#

objective_value_tracker: dict | None#

configurations: None | dict#

property x: ndarray#: The optimal solution of the optimization problem.

property success: bool#: Whether or not the optimizer exited successfully.

message: str#

property fun: float#: Value of objective function at the optimal solution x.

property jac: ndarray#: Value of the Jacobian of the objective function at the optimal solution x (if available).

property hess: object#: Value of the Hessian of the objective function at the optimal solution x (if available).

property hess_inv: object#: Value of the inverse of Hessian of the objective function at the optimal solution x (if available).

property nfev: int#: Number of evaluations of the objective functions.

property njev: int#: Number of evaluations of the the Jacobian of the objective function.

property nhev: int#: Number of evaluations of the the Hessian of the objective function.

property nit: int#: Number of iterations performed by the optimizer.

__init__(*, optimal_policy=None, optimal_policy_sample=None, optimal_policy_sample_objval=None, optimal_design=<factory>, optimal_design_objval=None, uncertain_parameter_sample=None, optimal_uncertain_parameter=None, optimization_trajectory=None, optimization_trajectory_objval=None, optimization_trajectory_stoch_objval=None, inner_optimization_results=None, outer_optimization_results=None, converged=False, maxiter_reached=False, message=<property object>, objective_value_tracker=None, configurations=None)#

class RobustBinaryReinforceOptimizer(configs=None)[source]#

Bases: BinaryReinforceOptimizer

Robust Binary Optimization by stochastic learning. The objective is to solve one of the following optimization problems \(\max_{d} E[ \min_{\lambda} J(d, \lambda)]\) or \(\min_{d} E[ \max_{\lambda} J(d, \lambda)]\) based on the value of the configuration key maxmin, where \(J\) is an objective function (specified in the configurations dictionary by fun) that accepts a binary design vector \(d\) and an uncertain parameter \(\lambda\).

Additional details of the approach underlying this implementation can be found in [1].

Parameters:: configs (RobustBinaryReinforceOptimizerConfigs | dict | None) – Configurations of the RobustBinaryReinforceOptimizer, either as an instance of RobustBinaryReinforceOptimizerConfigs, a dictionary, or None. The default is None, in which case, the default configurations provided by RobustBinaryReinforceOptimizerConfigs are used.

..note::: The optimization is assumed to be unconstrained and any soft (e.g., budget) constraints are already absorbed into fun passed in the configurations dictionary.

References:

Ahmed Attia, Sven Leyffer, and Todd S. Munson. “Robust A-optimal experimental design for Bayesian inverse problems.” arXiv preprint arXiv:2305.03855 (2023).

__init__(configs=None)[source]#

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

Check the passed configuratios and make sure they are conformable with each other, and with current configurations once combined. This guarantees that any key-value pair passed in configs can be properly used

Note

Here only the locally-defined configurations in RobustBinaryReinforceOptimizerConfigs are validated. Finally, super classes validators are called.

Parameters:

configs (dict | BinaryReinforceOptimizerConfigs) – full or partial (subset) configurations to be validated
raise_for_invalid (bool) – if True raise TypeError for invalid configrations type/key. Default True

Returns:

flag indicating whether passed configurations dictionary is valid or not

Raises:

AttributeError – if any (or a group) of the configurations does not exist in the model configurations RobustBinaryReinforceOptimizerConfigs.
PyOEDConfigsValidationError – if the configurations are invalid and raise_for_invalid is set to True.

Return type:

bool

update_configurations(**kwargs)[source]#

Take any set of keyword arguments, and lookup each in the configurations, and update as nessesary/possible/valid

Raises:: PyOEDConfigsValidationError – if invalid configurations passed

create_stochastic_optimizer()[source]#

generate_design_sample(theta=None, sample_size=1, dtype=<class 'bool'>)[source]#

generate_uncertain_parameter_sample(sample_size=1)[source]#

Create a sample (list) of randomly generated uncertain parameter values based on the uncertain parameter configurations.

..note::: This function is not supposed (does not need to be) directly called by the user. It is only created to help validation/verification of configurations.

objective_function_value(design, param)[source]#

A function to prevent redundant computations of the objective (utility function) by looking up tracker before evaluation

Parameters:

design – binary state/design variable to evaluate objective value at
param – a realization of the unceratin parameter

Returns:

value of the objective/utility function at the passed design

Raises:

TypeError if the passed design is not of the right size

objective_function_grad_design(design, param)[source]#

A function to evaluate the gradient of the objective function at the passed design, and uncertain parameter value, with respect to the relaxed design. This function is used only for relaxation approach of the binary design, and is used only for comparison with the incorrect relaxation approach for the outer optimization problem.

..note::: If no valid function is registered in the configurations, finite differences is used to approximate the gradient

Parameters:

design – binary state/design variable to evaluate objective value at
param – a realization of the unceratin parameter

Returns:

derivative of the objective/utility function with respect to teh design at the passed design

Raises:

TypeError if the passed design and/or uncertain parmaeter are not of the right sizes

objective_function_grad_parameter(design, param)[source]#

A function to evaluate the gradient of the objective function at the passed design, and uncertain parameter value with respect to the uncertain parameter.

..note::: If no valid function is registered in the configurations, finite differences is used to approximate the gradient

Parameters:

design – binary state/design variable to evaluate objective value at
param – a realization of the unceratin parameter

Returns:

derivative of the objective/utility function with respect to teh design at the passed design

Raises:

TypeError if the passed design and/or uncertain parmaeter are not of the right sizes

objective_function_sample_min(design, parameter_sample)[source]#: Find minium value of the utility/objective function fun(d, p) over finite sample of the uncertainty parameter parameter_sample; for the given design.

objective_function_sample_min_grad_design(design, parameter_sample)[source]#

Find the generalized gradient of deterministic_objective_min with respect to the design, which is the gradient at the param value that minimizes deterministic_objective over the parameter sampler.

..note::: This is used for the relaxation approach only.

stochastic_objective_estimate(param, theta=None, design_sample=None)[source]#: Estimate the value of the the stochastic objective function \((E(U(d, p)))\), where \(U\) is the utility/objective function, \(d\) is the design, and \(p\) is the uncertain parmater value. The estimate is found by Monte Carlo, that is by averaging over finite sample (design_sample) sampled from Bernoulli distribution with parameter theta. This is the objctive of the inner minimization problem

stochastic_objective_estimate_grad_parameter(param, design_sample)[source]#: Gradient of the function stochastic_objective_estimate with respect to the uncertain parameter param. This is the gradient of the inner minimization problem

stochastic_objective_estimate_min(parameter_sample, theta=None, design_sample=None)[source]#: Find minium of (estimates of the) stochastic objective \((E(U(d, p)))\) over finite sample of the uncertainty parameter; for the same sample of designs. This is the objective of the outer maximization problem in stochastic settings; No gradient of this is required as REINFORCE is used.

stochastic_policy_objective_value(theta, param, fun=None, sample=None, sample_size=32, exact=False)[source]#

Evaluate the value (exact expectation or approximate using MC sampling) of the stochastic objective function reformulation of the binary optimization problem.

Here, we define the stochastic objective function \(E(J(x, p))\) where \(U\) is the deterministic objective fun (utility function) defined in the configurations, and \(x\) is a binary design variable following a multivariate Bernoulli distribution with parameter (success probability) \(\theta\), and \(p\) is the realization of the uncertain parametr.

If exact is False, this function returns a Monte Carlo (MC) approximation of the stochastic objective (stochastic average approximation). `If `exact is True`, this function evaluates the expectation by enumeration (over all possible designs) and returns the expected value. This option is provided for testing purposes.

..note::: This function is a wrapper around the same function in the super class stochastic_policy_objective_value() which just modifies the objective function by setting the uncertain parameter before calling super’s functionality.

Parameters:

theta (numpy.ndarray|iterable) – the policy parameters (success probability of the underlying Bernoulli distribution)
param – the uncertain parameter
fun (callable) – the utility/objective function to calculate the stochastic objective. If None, the fun from the configurations dictionary is used (that is obtained by calling self.objective_function_value()). This argument is provided to enable altering the objective while calculating the derivatives (e.g., by adding a baseline) to reduce variance of the estimator(s).
sample (numpy.ndarray) – a sample generated from the passed policy (provided in case samples are generated by other routines). This is discarded if exact is True. Each row is one sample point.
sample_size (int) – number of sample points to generate (if sample is None and exact is False). This is ignored if sample is not None (sample_size is updated to the length of the provided sample in this case ) or exact is True
exact (bool) – whether to evaluate the exact (expected value over all possible binary designs) objective value or a Monte Carlo approximation (stochastic average approximation) of the objective/expectation.

Returns:

value of the stochastic objective value (exact or approximate)

Return type:

float

stochastic_policy_objective_gradient(theta, param, fun=None, sample=None, sample_size=32, exact=False)[source]#

Evaluate the gradient (exact expectation gradient or approximate using MC sampling) of the stochastic objective function reformulation of the binary optimization problem. This evaluates the gradient of stochastic_policy_objective_value() with respect to the policy parameter theta, that is the success/activate probability. The uncertain parameter param is assumed to be identical/fixed (for both function and gradient)

If exact is False, this function returns a Monte Carlo (MC) approximation of the gradient of the stochastic objective (stochastic average approximation). `If `exact is True, this function evaluates the expectation gradient by enumeration (over all possible designs) and returns the gradient of the expected value. This option is provided for testing purposes.

..note::: This function is a wrapper around the same function in the super class stochastic_policy_objective_gradient() which just modifies the objective function by setting the uncertain parameter before calling super’s functionality.

Parameters:

theta (numpy.ndarray|iterable) – the policy parameters (success probability of the underlying Bernoulli distribution)
param – the uncertain parameter
fun (callable) – the utility/objective function to calculate the stochastic objective. If None, the fun from the configurations dictionary is used (that is obtained by calling self.objective_function_value()). This argument is provided to enable altering the objective while calculating the derivatives (e.g., by adding a baseline) to reduce variance of the estimator(s).
sample (numpy.ndarray) – a sample generated from the passed policy (provided in case samples are generated by other routines). This is discarded if exact is True. Each row is one sample point.
sample_size (int) – number of sample points to generate (if sample is None and exact is False). This is ignored if sample is not None (sample_size is updated to the length of the provided sample in this case ) or exact is True
obj_val_tracker (dict) – optional dictionary holding values of the objective function (will be updated in-place if passed). Default is None.
apply_projection (bool) – if True, the gradient is projected (by truncation) onto the box [-1,1]. Default is False.
exact (bool) – whether to evaluate the exact (expected value over all possible binary designs) objective value or a Monte Carlo approximation (stochastic average approximation) of the objective/expectation.

Returns:

gradient of the stochastic objective value (exact or approximate)

Return type:

numpy.ndarray

optimal_baseline_estimate(theta, param, fun=None, sample=None, batch_size=32, epochs=10)[source]#

Use the passed sample to calculate a sample based estimate of the optimal baseline value.

..note::: This function is a wrapper around the same function in the super class optimal_baseline_estimate() which just modifies the objective function by setting the uncertain parameter before calling super’s functionality.
..note::: This function is not employed in the optimization at all. It is just added to avoid an confusion in arguments with the super class.

Parameters:

theta (numpy.ndarray|iterable) – the policy parameters (success probability of the underlying Bernoulli distribution)
param – the uncertain parameter
fun (callable) – the utility/objective function to calculate the stochastic objective. If None, the fun from the configurations dictionary is used. This argument is provided to enable altering the objective while calculating the derivatives (e.g., by adding a baseline) to reduce variance of the estimator(s).
sample – Given sample
batch_size (int) – number of samples to use for the MC approximation. Default is 32.
epochs (int) – number of epochs to use to approximate gradient. Default is 10.

Remarks:

If more than one epoch is required:

if sample is None, batch_size is generated for each epochs
if sample is not None, batch_size is derived as: sample // epochs

Returns:

optimal baseline estimate

Return type:

float

bruteforce_objective_values(param, fun=None, num_active=None)[source]#: Evaluate the value of the objective (obj) at all possible binary combinations for a given realization of the uncertain parameter;

full_Hessian_estimate(theta, fun=None, alpha=1.0, sample=None, sample_size=32)[source]#

Estimate the Hessian matrix of the stochastic objective function \(E[J(d)]\) for a given probability of success theta.

\[(\alpha I + \mathcal{H}) x\]

Parameters:

theta (numpy.ndarray|iterable) – the policy parameters (success probability of the underlying Bernoulli distribution)
alpha (float) – As defined in the equation above. Default is 1.0.
fun (callable) – the utility/objective function to calculate the stochastic objective. If None, the fun from the configurations dictionary is used. This argument is provided to enable altering the objective while calculating the derivatives (e.g., by adding a baseline) to reduce variance of the estimator(s).
sample – samples to use in estimation. If not provided, they’re sampled. Default is None.
sample_size (int) – sample size to use in estimation. Default is 32.

Returns:

estimate of the Hessian matrix

Hessian_estimate_vector_prod(theta, param, x, fun=None, alpha=1.0, sample=None, sample_size=32)[source]#

Compute the product of the Hessian matrix (see full_Hessian_estimate()) of the objective function by a given vector x

\[(\alpha I + \mathcal{H}) x\]

Parameters:

theta (numpy.ndarray|iterable) – the policy parameters (success probability of the underlying Bernoulli distribution)
x (np.ndarray) – vector to multiply the Hessian with.
alpha (float) – As defined in the equation above. Default is 1.0.
fun (callable) – the utility/objective function to calculate the stochastic objective. If None, the fun from the configurations dictionary is used. This argument is provided to enable altering the objective while calculating the derivatives (e.g., by adding a baseline) to reduce variance of the estimator(s).
sample – samples to use in estimation. If not provided, they’re sampled. Default is None.
sample_size (int) – default sample size to use if sample is

Returns:

the product of the Hessian matrix of the objective function J at theta with x.

Return type:

np.ndarray

solve(initial_guess=None, parameter_sample=None)[source]#

Start solving the robust binary optimization problem using the stochastic or relaxed formulatioon based on the configurations.

Note

This function only makes a choice between self._solve_by_relaxation() and self._solve_by_stochastic_learning based on the configuration attribute self.configurations.solve_by_relaxation. These methods all have the same signature/input/output

Parameters:

initial_policy – None or ``iterable` to be used as the initial policy parameter of the underlying Bernoulli distribution
parameter_sample – None or ``iterable` to be used as the initial ensemble of the uncertain parameter. If None, the uncertain parameter sample registered in the configurations dictionary under key uncertain_parameter_sample is used.

Returns:

an instance of RobustBinaryReinforceOptimizerResults.

Raises:

TypeError if the initial policy has wrong size or any of the values fall outside the interval [0, 1]

update_bruteforce_results(bruteforce_results=None, parameter_sample=None, num_active=None, saveto=None)[source]#

Calculate/Update the brute-force results. Bruteforce results are obtained here by enumerating all possible designs for each realization of the uncertain parameter in the uncertain parameter sample. The bruteforce_results dictionary (input/output) has the following structure:

design_size: int,

uncertain_parameter_sample: list,

results: dict structured as follows:

“parameter”: parameter_val,

“design_size”: self.oed_problem.design_size,

“candidates”: indexes of binary candidates,

“objective_values”: list of objective_values,

Parameters:

bruteforce_results (dict) – the dictionary cotaining (all/no/partial) bruteforce results. If a dictionary is passed, it used as initializer of the bruteforce results dictionary to be returned.
parameter_sample – None or ``iterable` to be used as the initial ensemble of the uncertain parameter. If None, the uncertain parameter sample is read from bruteforce_results if valid dictionary is passed. Otherwise, the sample registered in the configurations object self.configurations.uncertain_parameter_sample is used.
num_active – number of non-zero entries to consider in the bruteforce search. If None, all realization of the binary variable are considered. This is useful for budget constraints.
saveto – filepath to dump the bruteforce dictionary (if passed)

Returns:

an updated (or new) version of bruteforce_results with all bruteforce search results.

exhaustive_parameter_search(uncertain_parameter_sample=None, num_test_points=22, saveto=None)[source]#

A function implemented to create data for plotting a 3D surface plot for the case when two candidate sensors are proposed. A surface (of the stochastic objective) is generated for each value of the uncertain parameter.

..note::: This function is by no means general. It is developed for explainatory purposes and works only for two candidate sensors

Parameters:

uncertain_parameter_sample – Sample of the uncertain parameter to create surfaces at. If None, the uncertain_paramaeter_sample associated with the object (in the configurations dictionary) is used.
num_test_points (int) – number of points in [0, 1] to take for theta (success probability) or the relaxed design

..note::: This function is developed for two-dimensional settings, that is when both the design is of size 2. This is useful for surface plotting to visualize the optimization problem.

Raises:: TypeError is raised if the design size is not equal to 2.
Raises:: TypeError is raised if oed_results is not an instance of RobustOEDResults
Raises:: TypeError is raised if the oed_results is not properly configured, that is if any of the attributes is invalid (e.g., the OED problem is not solved properly before creating the oed_results object).
Returns:: a dictionary with the following keys: - ‘uncertain_parameter_sample’: - ‘design_grid’: - ‘policy_grid’: - ‘stochastic_objective_values’: - ‘objective_values’:

plot_results(results, overwrite=False, bruteforce_results=None, num_active=None, uncertain_parameter_sample=None, exhaustive_parameter_search_results=None, show_legend=True, output_dir=None, keep_plots=False, fontsize=20, line_width=2, usetex=True, show_axis_grids=True, axis_grids_alpha=(0.25, 0.4), plots_format='pdf', **kwargs)[source]#

Warning

This is a Work-In-Progress method to visualize optimization results generated by :py:meth`pyoed.optimization.binary_optimization.RobustBinaryReinforceOptimizer.solve`.

Given the results returned by solve(), visualize optimization results. This function, creates the following plots:

Values of the objective function over the optimization trajectory

Note

Adding additional kwargs to enable high flexibility in calling this method.

Parameters:

results – a dictionary or an instance of oed.oed.OEDResults holding all results generated.
line_width – width (in points) of lines plotted
overwrite (bool) – if True, overwrite existing plots (if any)
output_dir – path/dir name to spit out plots (created if non-existant); if None, current directory is used
verbose – output information to screen

Returns:

a dictionary with the following entries/keys:

figures a dictionary indexed by plot identifier with value set to the corresponding figure handle (or None if keep_plots is set to False)
stats: a dictionary holding statistics including number of function evaluations, and percentage of space explored.
extras: additional results:
- global_optimum: an estimate (e.g., using MC) of the global optimum value
- global_optimal_design: an estimate (e.g., using MC) of the global optimal design

plot_objective_surfaces(results, fontsize=22, usetex=True, azim=20, elev=20, xyticks=array([0., 0.2, 0.4, 0.6, 0.8, 1.]), xylim=(-0.1, 1.1), xylabelpad=35, zlabelpad=20, show_xy_projection=False, offset_dist_factor=0.1, show_legend=True, all_legend_labels=False, show_colorbar=False, colorbar_orientation='horizontal', sample_uncertain_parameter=False, num_test_points=20, keep_plots=False, output_dir=None, plots_format='pdf')[source]#

Given the output of exhaustive_parameter_search(), plot 3D surfaces and return the figure.

Parm results:

Parm fontsize:

Parm azim:

Parm elev:

Parm xyticks:

Parm xylim:

Parm xylabelpad:

Parm zlabelpad:

Parm show_xy_projection:

Parm offset_dist_factor:

Parm show_legend:

Parameters:

all_legend_labels
keep_plots
verbose

Parm show_colorbar:

Parm colorbar_orientation:

Parm sample_uncertain_parameter:

Parm num_test_points:

Parm output_dir:

Parm plots_format:

Remarks:

This is valid only for Design space of size 2 (e.g., 2 candidate sensor locations).

property stochastic_binary_optimizer#: The stochastic binary optimizer used to solve the outer binary optimization problem if the probabilistic approach is selected (that is when self.configurations.solve_by_relaxation is set to False which is the default value).

property uncertain_parameter_size#: The size of the uncertain parameter (as an iterable)

property uncertain_parameter_sample#: The uncertain parameter expandable sample

property uncertain_parameter_bounds#: The size of the uncertain parameter (as an iterable)