Welcome to BOSS documentation!¶
File: bo/bo_main.py¶
-
class
boss.bo.bo_main.
BoMain
(STS)¶ Class for handling Bayesian Optimization
-
_special_quantities
(STS)¶ Calculates special quantities of the current state of data, model and BO
-
_stop
(STS)¶ Check if stopping conditions for BO are met. Returns True if one should stop, False otherwise.
-
run_init
(STS)¶ Reads/Evaluates initial data which may be from restart (rst) file and creates the first GP model
-
run_optimization
(STS)¶ Runs Bayesian optimization iteration by iteration until a stopping condition is met
-
File: bo/model.py¶
-
class
boss.bo.model.
Model
¶ Functionality for creating, refitting and optimizing a GP model
-
static
add_data
(model, newX, newY)¶ Updates the model evidence (observations) dataset appending.
-
static
create
(STS, X, Y)¶ Create the model based on the options and data
-
static
get_all_params
(STS, model)¶ Returns the parameters of the model in format: noise, variance, lengthscales, periods where the last two are 1D lists. There exists a period only for those dimensions which are using a periodic kernel.
-
static
get_unfixed_params
(STS, model)¶ Returns the unfixed parameters of the model in an array where the first element is the variance and the rest are lenghtscales. Note that this function assumes that only variances and lengthscales are free hyperparameters.
-
static
min_prediction
(STS, model)¶ Find and returns the model global minimum prediction xhat and the model mean (muhat) and variance (nuhat) at that point.
-
static
mu
(x, model)¶ Returns model mean given x and a GP model object
-
static
mu_with_grad
(x, model)¶ Returns model mean and its gradient given x and a GP model object
-
static
nu
(x, model)¶ Returns model variance given x and a GP model object
-
static
optimize
(STS, model)¶ Updates the model hyperparameters by maximizing marginal likelihood.
-
static
redefine_data
(model, X, Y)¶ Updates the model evidence (observations) dataset overwriting.
-
static
set_unfixed_params
(model, params, dim)¶ Sets the unfixed parameters of the model (variance, lengthscales) to given values.
-
static
File: bo/kernel_factory.py¶
-
class
boss.bo.kernel_factory.
KernelFactory
¶ This class contains the construction of the kernel.
-
static
_select_kernels
(kerns, STS, forced_hypers)¶ Selects and creates kernel objects for each dimension. Hyperparameters are set to their initial values and default constraints removed.
-
static
_set_constraints
(kerns, STS)¶ Sets hyperparameter constraints on kernels.
-
static
_set_priors
(kerns, STS)¶ Sets hyperparameter priors on kernels.
-
static
construct_kernel
(STS, forced_hypers=None)¶ Creates the kernel.
-
static
File: bo/acq/acq_main.py¶
-
class
boss.bo.acq.acq_main.
AcquisitionMain
¶ Class to wrap the entire acquisition process of acquiring new data in the Bayesian optimization algorithm
-
static
_find_xnext
(STS, acqfunc, model)¶ Minimizes the acquisition function to find the next sampling location ‘xnext’.
-
static
_location_overconfident
(STS, xnext, model)¶ Checks is model variance is lower than tolerance at suggested xnext.
-
static
_model_overconfident
(STS, model)¶ Checks is model variance is lower than tolerance across the domain by doing random tests.
-
static
_too_close_evals
(STS, model)¶ Checks is last two evaluations have been made too closely.
-
static
evaluate_xnew
(STS, xnew)¶ Evaluates user function at given location ‘xnew’ to get the observation scalar ‘ynew’. Later also gradient ‘ydnew’ should be made possible.
-
static
select_xnext
(STS, model, silent=False)¶ Selects the acquisition function to use and returns its xnext location as well as the used acquisition function class.
-
static
File: bo/acq/acqfuncs.py¶
-
class
boss.bo.acq.acqfuncs.
AcquisitionFunction
¶ Abstract base class for all acquisition functions to inherit
-
static
acq_func
(x, model, STS)¶ Empty function left for all heirs of AcquisitionFunction to implement. Should return the value and gradient of the acquisition function in question given a GP model object and Settings.
-
static
-
class
boss.bo.acq.acqfuncs.
LCB
¶ GP-Lower Confidence Bound acquisition function
-
static
acq_func
(x, model, STS)¶ Returns the value and gradient of the LCB acquisition function
-
static
-
class
boss.bo.acq.acqfuncs.
ELCB
¶ GP-Lower Confidence Bound acquisition function with increasing exploration
-
static
acq_func
(x, model, STS)¶ Returns the value and gradient of the ELCB acquisition function
-
static
explr_weight
(STS)¶ e_w = sqrt( 2*log[ ( i^((dim/2) + 2)*pi^(2) ) / ( 3*0.1 ) ] )
-
static
File: io/settings.py¶
-
class
boss.io.settings.
Settings
(inpfile, timer)¶ Reads, interprets and defines the code internal settings based on input.
-
__init__
(inpfile, timer)¶ Sets all settings by reading first the input file, filling in defaults and calculating implicit settings.
-
__weakref__
¶ list of weak references to the object (if defined)
-
_convertstr
(value, type_)¶ Converts the parameter value into the requested type type_ and returns it. Supported types are python’s str, bool, int, float as well as custom types ‘intlist’, ‘floatlist’, ‘strlist’, ‘boollist’ and ‘2Dfloatarray’, where the last is a numpy 2D array.
-
_read_inpfile
()¶ Reads the input file and saves the found keywords to self.keywds dict. Additionally recognizes if the file is a rst file and counts how many lines there are before the rst values.
-
_read_rst_values
()¶ Extracts all information below the keyword ‘RESULTS:’ from an rst file and takes note how many of the data points have model params already.
-
_setopt
(keyword, default, type_)¶ Returns the value of the setting/option variable by first looking for it in self.keywds dictionary and otherwise using default.
-
File: io/main_output.py¶
-
class
boss.io.main_output.
MainOutput
¶ Functionality to write to the main output (*.out) file.
Writes a footer to main output file
-
static
header
(STS)¶ Writes a header to main output file overwriting a possibly existing old output file at the same filepath.
-
static
inpfile_repeat
(STS)¶ Repeats the input file near the beggining of the main output file.
-
static
iteration_start
(STS, init=False)¶ Output section header for the new iteration.
-
static
iteration_summary
(STS, newXs, newYs, best, min_pred, conv, xnext, model_params, time)¶ Outputs info about one BO iteration to main output file
-
static
progress_msg
(STS, msg, priority, preceding_bl=False)¶ Announce progress message to main output file depending on verbosity.
-
static
section_header
(STS, text)¶ Writes a section header to main output file.
-
static
settings
(STS)¶ Outputs the interpreted code variable settings to main output file.
File: io/rst_output.py¶
-
class
boss.io.rst_output.
RstOutput
¶ Functionality to write output to the restart (*.rst) file.
-
static
inpfile_repeat
(STS)¶ Repeats the input file contents at the begginning of the NEW rst file. If the input file is a restart file itself, the parts starting from ‘RESULTS:’ are not repeated at the begginning of the new rst file. Will add the ‘RESULTS:’ line to the new rst file.
-
static
new_data
(STS, X, Y)¶ Outputs a new data point (x,y) to rst file.
-
static
new_model_params
(STS, mod_param)¶ Outputs a new set of model parameters to rst file. Format is variance, lengthscales
-
static
File: io/data_output.py¶
-
class
boss.io.data_output.
DataOutput
¶ Functionality to output raw data on request to files outside of the main output (.out) file and the restart (.rst) file.
-
static
dump_acqfunc
(STS, dest_file, model, acqf, defs)¶ Dumps acquisition function slice (up to 2D) in a grid to acqfuncs/it#.dat
-
static
dump_model
(STS, dest_file, model, mod_params, xhat)¶ Dumps model slice (up to 2D) mean and variance in a grid to models/it#.dat
-
static
dump_truef
(STS, dest_file, last_xhat)¶ Dumps true function slice (up to 2D) in a grid
-
static
File: io/ioutils.py¶
-
class
boss.io.ioutils.
IOutils
¶ Reading/writing files and converting strings into Python variable types.
-
static
append_write
(filepath, text)¶ Writes the text into the given file appending.
-
static
data_line
(X, Q=None, formatString='%15.7E', separ=' ')¶ Returns a line of data. X and Q (optional) should be 1D arrays/lists.
-
static
overwrite
(filepath, text)¶ Writes the text into the given file overwriting.
-
static
readCols
(filepath, skiprows=1)¶ Reads data columns from a file into a numpy array, where each column is separated like col1 = arr[:,0], col2 = arr[:,1] etc.
-
static
writeCols
(filepath, vectorList, space=' ', titleLine=None, formatString='%15.7E')¶ Needs as input a vector of form [ [column1 elements], [column2 elements], … ]
-
static
File: io/parse.py¶
-
class
boss.io.parse.
Parse
¶ Functions to parse files produced by a BOSS optimization.
-
acqs
(filepath)¶ Extracts data acquisitions from all bo iterations in the output file. Returns a numpy array where each element is [npts, x, y]. Note that there may be several acquisitions on the same iteration - especially the initial points at the 0th iteration. Works on output files with all verbosity levels.
-
best_acqs
(filepath)¶ Extracts xbest and ybest from all bo iterations in the output file. Returns a numpy array where each element is [npts, xbest, ybest]. Works only on output files with verbosity levels of at least 1.
-
conv_measures
(filepath)¶ Extracts dx_hat and dmu_hat from all bo iterations in the output file. Returns a numpy array where each element is [npts, dxhat, dmuhat]. Works only on output files with verbosity levels of at least 1.
-
min_preds
(filepath)¶ Extracts xhat, muhat and nuhat from all bo iterations in the output file. Returns a numpy array where each element is [npts, xhat, muhat, nuhat]. Works on output files with all verbosity levels.
-
mod_params
(filepath)¶ Extracts unfixed GP model hyperparameters from all bo iterations in the output file. Returns a numpy array where each element is [npts, variances, lengthscales]. Works only on output files with verbosity levels of at least 2.
-
rst
(filepath)¶ Extracts all information below the keyword ‘RESULTS:’ from an rst file.
-
xnexts
(filepath)¶ Extracts xnext locations from all bo iterations in the output file. Returns a numpy array where each element is [npts, xnext]. Note that this means that the location ‘xnext’ is to be evaluated in the next iteration ‘iter+1’. Works only on output files with verbosity levels of at least 2.
-
File: pp/pp_main.py¶
-
boss.pp.pp_main.
PPmain
(STS, last_model)¶ Controls all the post-processing features
File: pp/plot.py¶
-
class
boss.pp.plot.
Plot
¶ Plotting functionality. All plot functions make PNG images to destination file based on given source array(s) of data.
-
acq_func
(dest_file, acqf_data, acqs=None, xhat=None, xnext=None, axis_labels=None, legends=True)¶ Plots a (max 2D) slice of the acquisition function. Can include also acquisitions, xhat and xnext if those are given.
-
conv_measures
(dest_file, conv_meas, legends=True)¶ Plots quantities related to convergence as a function of iteration.
-
data_acquisitions
(dest_file, acqs, min_preds, legends=True)¶ Plots minimum predictions and uncertainty, acquisition energies and locations as a function of iteration.
-
hyperparameters
(dest_file, hypers, legends=True)¶ Plots GP model unfixed hyperparameters (variances and lengthscales) as a function of iteration.
-
model
(dest_file, model_data, xhat=None, acqs=None, xnext=None, minima=None, truef=None, incl_uncert=True, axis_labels=None, legends=True)¶ Plots a (max 2D) slice of the model.
-
truef
(dest_file, truef_data, axis_labels=None)¶ Plots a (max 2D) slice of the true function.
-
truef_hat
(dest_file, truef_hats, legends=True)¶ Plots true function value at xhat locations as a function of iteration.
-
File: utils/distributions.py¶
-
class
boss.utils.distributions.
Distributions
¶ Utilities for handling distributions.
-
static
gammaparams
(q1, q2, p1=0.1, p2=0.9)¶ A function for parametrizing gamma distributions by specifying two quantiles.
Relevant math can be found in “Determining distribution parameters from quantiles” by John D. Cook, 2010.
Parameters: - q1 – p1-quantile
- q2 – p2-quantile
- p1 – lower percentage (0 < p1 < 1)
- p2 – higher percentage (0 < p2 < 1)
-
static
File: utils/minimization.py¶
-
class
boss.utils.minimization.
Minimization
¶ Minimization utilities
-
static
_remove_duplicates
(original, min_distance)¶ Removes duplicates from a list of found local minima given a minimum distance between distinct minima.
-
static
_run_minimizer
(func, x0, bounds, args, finite_grads=False)¶ Runs a single L-BFGS-B minimization starting from x0
-
static
minimize
(func, bounds, acqs, min_dist_acqs, accuracy=30, args=(), lowest_min_only=True)¶ Tries to find global minimum of func by starting minimizers from accuracy percentage of lowest acquisitions. func has to return both value and gradient given an x of same length as bounds.
-
static
minimize_from_sobol
(func, bounds, num_pts, shift, args=(), lowest_min_only=True)¶ Tries to find global minimum of func by starting minimizers from num_pts shifted sobol points. func has to return both value and gradient given an x of same length as bounds.
-
static
File: utils/timer.py¶
-
class
boss.utils.timer.
Timer
¶ Utility class for wall clock time keeping.
-
getLapTime
()¶ Returns lap time in seconds.
-
getTotalTime
()¶ Returns total time since timer creation in seconds.
-
startLap
()¶ Starts counting lap time from zero.
-
str_lapTime
(units='s')¶ Returns lap time in the given unit of time as a string.
-
str_totalTime
(units='s')¶ Returns total time since timer creation in the given unit of time as a string.
-
File: utils/initial_points.py¶
-
class
boss.utils.initial_points.
InitialPoints
¶ Functions to generate initial points in N-D
-
static
grid
(dim, bounds, npts)¶ Initial points in a grid. Total number of points returned is npts^dim.
-
static
random
(dim, bounds, npts)¶ Initial points randomly
-
static
sobol
(dim, bounds, npts)¶ Initial points with the quasi-random Sobol sequence
-
static