PARyOpt package¶

Subpackages¶

Submodules¶

PARyOpt.acquisition_functions module¶

PARyOpt.acquisition_functions.expected_improvement(mean: float, variance: float, curr_best: float = 0.0, _: float = 1.0) → float[source]¶

Expected improvement of objective function ‘A Tutorial on Bayesian Optimization of Expensive Cost Functions, with Application to Active User Modeling and Hierarchical Reinforcement Learning’

Parameters:	mean – mean of surrogate variance – variance of surrogate curr_best – current best evaluated point kappa – exploration - exploitation tradeoff parameter
Returns:	expectation of improvement

PARyOpt.acquisition_functions.lower_confidence_bound(mean: float, variance: float, curr_best: float = 0.0, kappa: float = 1.0) → float[source]¶

lower confidence bound of improvement : used for minimization problems

Parameters:	mean – mean of surrogate variance – variance of surrogate curr_best – current best evaluated point kappa – exploration - exploitation tradeoff parameter
Returns:	lower confidence bound

PARyOpt.acquisition_functions.probability_improvement(mean: float, variance: float, curr_best: float = 0.0, _: float = 1.0) → float[source]¶

Probability of improvement of objective function ‘A Tutorial on Bayesian Optimization of Expensive Cost Functions, with Application to Active User Modeling and Hierarchical Reinforcement Learning’

Parameters:	mean – mean of surrogate variance – variance of surrogate curr_best – current best evaluated point kappa – exploration - exploitation tradeoff parameter
Returns:	probability of improvement

PARyOpt.acquisition_functions.upper_confidence_bound(mean: float, variance: float, curr_best: float = 0.0, kappa: float = 1.0) → float[source]¶

upper confidence bound of improvement: used in the case of maximization problems

Parameters:	mean – mean of surrogate variance – variance of surrogate curr_best – current best evaluated point kappa – exploration - exploitation tradeoff parameter
Returns:	upper confidence bound

PARyOpt.paryopt module¶

class PARyOpt.paryopt.BayesOpt(cost_function: Union[Callable[[List[<built-in function array>]], Tuple[List[Tuple[<built-in function array>, float]], List[<built-in function array>], List[<built-in function array>]]], Callable[[List[<built-in function array>], List[<built-in function array>]], Tuple[List[Tuple[<built-in function array>, float]], List[<built-in function array>], List[<built-in function array>]]]], l_bound: <built-in function array>, u_bound: <built-in function array>, n_dim: int, n_opt: int = 1, n_init: int = 0, init_strategy: Callable[[int, int, <built-in function array>, <built-in function array>], List[<built-in function array>]] = None, do_init: bool = True, kern_function: Union[str, PARyOpt.kernel.kernel_function.KernelFunction] = None, acq_func: Union[str, Callable[[float, float, float, float], float]] = None, acq_func_optimizer: Callable = None, kappa_strategy: Union[List[Callable[[int], float]], Callable[[int], float], NoneType] = None, constraints: List[Callable[[<built-in function array>], bool]] = [], if_restart: bool = None, restart_filename: str = 'opt_state.dat') → None[source]¶

Bases: object

Bayesian optimization class.

Variables:

curr_iter – iteration number of optimizer
n_surrogate_opt – number of optima to get during surrogate optimization
n_init – initial population size (>2)
n_dim – dimensions of optimization
u_bound (l_bound,) – lower and upper bounds on variables
total_population – total set of population: list of arrays
func_vector – functional values for the population : scalar for each population
K – covariance matrix
K_inv – inverse of covariance matrix
K_inv_y – K_inv * func_vector : pre-computation to save costly / unstable inversion
acquisition_function – acquisition function to optimize the surrogate
cost_function – cost function to MINIMIZE: should be able to take a vector of locations
constraints – list of constraint functions (only points that satisfy these functions will be visited) NOT enforced in the default init strategy!!
if_restart – whether it should restart or not
restart_filename – file to restart from. it will be opt_state.dat if nothing is specified
acq_func_optimizer – optimizer for acquisition function. Should take in function, initial guess, bounds and function derivative. Returns the optimal location

acquisition(x: <built-in function array>, kappa: float, avoid: List[<built-in function array>] = None, opt_indx: int = 0) → float[source]¶

Calculates the acquisition function + penalty function at the given query location. If the query point is outside the bounds, it will return an infinity This is the function that needs to be optimized.

Parameters:	x – location to evaluate acquisition function : shape: (1, self.n_dim) kappa – kappa value to pass to acquisition function avoid – list of x values to avoid (forwarded to penalty function) opt_indx – index of acquisition function that is being called
Returns:	scalar acquisition function at x

add_point(x: <built-in function array>, y: float = None, if_check_nearness: bool = True, is_failed: bool = False) → None[source]¶

Adds ONLY ONE point to the current set of data we have. if_check_nearness specifies if it is needed to check nearness constraints before adding the point into total_population. This should be true if the user is manually adding points into the population. Updates following variables: K, K_inv, total_population, func_vector If the point is a failed evaluation, then it does not add into total_population and func_vector

Parameters:	x – array of shape (1, self.n_dim) y – cost function value at that location if_check_nearness – boolean, whether to check nearness or not. is_failed – boolean, whether the point to add is a failed evaluation or not
Returns:	None

estimate_best_kernel_parameters(theta_bounds=None) → None[source]¶

Calculates and sets the best shape-parameter/characteristic length-scale for RBF kernel function and applies it to the current model.

Parameters:	theta_bounds – array of bounds for theta
Returns:	None

evaluate_surrogate_at(x: <built-in function array>, include_failed: bool = False) → tuple[source]¶

Evaluates the surrogate at given point Taken from : https://arxiv.org/pdf/1012.2599.pdf : “A Tutorial on Bayesian Optimization of Expensive Cost Functions, with Application to Active User Modeling and Hierarchical Reinforcement Learning” Note that it returns sigma^2 and not sigma

The mean of the surrogate will not be affected by the failed points, they will only affect the variance of the surrogate

Parameters:	x – location to evaluate the surrogate rbf approximation include_failed – whether to include failed points for surrogate
Returns:	mean(mu), variance (sigma^2)

export_csv(path: str, **kwargs) → None[source]¶

Writes the data from all completed function evaluations (i.e. x, y pairs) to a CSV file. The file starts with the following header row: x0, x1, …, x[n_dim-1], y. Additional arguments will be forwarded to the csv.writer function, which can be used to control the formatting of the CSV file. To write a TSV instead of CSV, you can pass dialect=’excel-tab’.

Parameters:	path – Path to write the file to. If the file already exists, it will be overwritten. kwargs – Forwarded to csv.writer(), can be used to override the CSV dialect and set formatting options.

get_current_best() → tuple[source]¶

returns the location of current best and value of current best

Returns:	location, func_value

get_current_iteration() → int[source]¶

Returns the current iteration number

Returns:	integer

get_total_population() → Tuple[List[<built-in function array>], List[float]][source]¶

returns the total population : for visualization purposes

Returns:	total_population and function values at that location

penalty_function(x: <built-in function array>, kappa: float, avoid: List[<built-in function array>] = []) → float[source]¶

Calculates the penalty function, to prevent local optima to repeat

Parameters:	x – location kappa – kappa value used in acquisition function avoid – extra points to avoid (other than self.total_pop/self.pending/self.failed)
Returns:	penalty function value at x

set_new_kernel_parameters(theta: Union[float, <built-in function array>] = 1.0, theta0: float = 1.0) → None[source]¶

sets the kernel parameters: called from the user script. The covariance matrix needs to be re-calculated when this function is called

Parameters:	theta – scaling of dimensions used with the distance function theta0 – scaling of kernel function
Returns:	None

update_iter(iter_max: int = 1) → None[source]¶

Finds the next query point and updates the data for the next iteration

Returns:	None

update_surrogate() → None[source]¶

updates the inverse of covariance function. In order to incorporate failed locations as interpolated values, this update is 2 staged:

Create the surrogate (K,K_inv) with only the successfully evaluated points
1. Evaluate the mean of the surrogate at the failed points
2. Incorporate the interpolated failed locations into the surrogate and update the surrogate (K,K_inv)

Updates the values of self.K_success, self.K_inv_success, self.K_inv_y_success, self.K_inv and self.K_inv_y

Returns:	None

PARyOpt.utils module¶

PARyOpt.utils.cdf_normal(x: <built-in function array>, mean: <built-in function array> = 0.0, sigma_sq: <built-in function array> = 1.0) → float[source]¶

Cumulative distribution function of standard normal distribution

Parameters:	x – scalar / location mean – mean of distribution sigma_sq – variance of distribution (sigma^2)
Returns:	cdf of normal distribution

PARyOpt.utils.distance(x1: <built-in function array>, x2: <built-in function array>) → float[source]¶

returns the distance between two query points

Parameters:	x1 – point 1 x2 – point 2
Returns:	euclidean distance between the two points

PARyOpt.utils.erf(x)[source]¶

error function of x: used in calculating cumulative distribution. Unable to import from scipy, so writing our own function

Parameters:	x – float
Returns:	error function of x

PARyOpt.utils.lhs(n: int, samples: int = None, criterion: str = None, iterations: int = None)[source]¶

Generate a latin-hypercube design

Parameters:	n – The number of factors to generate samples for samples – The number of samples to generate for each factor (Default: n) criterion – Allowable values are “center” or “c”, “maximin” or “m”, “centermaximin” or “cm”, and “correlation” or “corr”. If no value given, the design is centermaximin. iterations – The number of iterations in the maximin and correlations algorithms (Default: 5).
Return H:	An n-by-samples design matrix that has been normalized so factor values are uniformly spaced between zero and one.
Example:

A 3-factor design (defaults to 3 samples):

>>> lhs(3)
array([[ 0.40069325,  0.08118402,  0.69763298],
       [ 0.19524568,  0.41383587,  0.29947106],
       [ 0.85341601,  0.75460699,  0.360024  ]])

A 4-factor design with 6 samples:

>>> lhs(4, samples=6)
array([[ 0.27226812,  0.02811327,  0.62792445,  0.91988196],
       [ 0.76945538,  0.43501682,  0.01107457,  0.09583358],
       [ 0.45702981,  0.76073773,  0.90245401,  0.18773015],
       [ 0.99342115,  0.85814198,  0.16996665,  0.65069309],
       [ 0.63092013,  0.22148567,  0.33616859,  0.36332478],
       [ 0.05276917,  0.5819198 ,  0.67194243,  0.78703262]])

A 2-factor design with 5 centered samples:

>>> lhs(2, samples=5, criterion='center')
array([[ 0.3,  0.5],
       [ 0.7,  0.9],
       [ 0.1,  0.3],
       [ 0.9,  0.1],
       [ 0.5,  0.7]])

A 3-factor design with 4 samples where the minimum distance between all samples has been maximized:

>>> lhs(3, samples=4, criterion='maximin')
array([[ 0.02642564,  0.55576963,  0.50261649],
       [ 0.51606589,  0.88933259,  0.34040838],
       [ 0.98431735,  0.0380364 ,  0.01621717],
       [ 0.40414671,  0.33339132,  0.84845707]])

A 4-factor design with 5 samples where the samples are as uncorrelated as possible (within 10 iterations):

>>> lhs(4, samples=5, criterion='correlate', iterations=10)

PARyOpt.utils.pdf_normal(x: <built-in function array>, mean: <built-in function array> = 0.0, sigma_sq: float = 1.0) → float[source]¶

Probability distribution function of standard normal distribution, returns the pdf of a location from given mean with variance sigma_sq

Parameters:	x – scalar/location mean – mean of distribution sigma_sq – variance of distribution (sigma^2)
Returns:	pdf of normal distribution