PARyOpt package

Subpackages

• PARyOpt.evaluators package
  • Submodules
  • PARyOpt.evaluators.async module
  • PARyOpt.evaluators.async_local module
  • PARyOpt.evaluators.async_parse_result_local module
  • PARyOpt.evaluators.async_sbatch module
  • PARyOpt.evaluators.connection module
  • Module contents
• PARyOpt.kernel package
  • Submodules
  • PARyOpt.kernel.kernel_function module
  • PARyOpt.kernel.matern module
  • PARyOpt.kernel.squared_exponential module
  • Module contents

Submodules

PARyOpt.acquisition_functions module

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

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

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

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

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

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

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

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

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

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

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

returns the location of current best and value of current best

Returns:location, func_value

get_current_iteration() → int

Returns the current iteration number

Returns:integer

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

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

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

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

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

Returns:None

update_surrogate() → None

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

1. Create the surrogate (K,K_inv) with only the successfully evaluated points
2. 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

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

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)

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)

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

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

Module contents