Welcome to BOSS documentation!

File: __main__.py

boss.__main__.main(args=None)

The main routine.

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.

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.

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.

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.

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

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 ) ] )

class boss.bo.acq.acqfuncs.Explore

Purely exploring acquisition function

static acq_func(x, model, STS)

Returns the value and gradient of a purely exploring acquisition function

class boss.bo.acq.acqfuncs.Exploit

Purely exploiting acquisition function

static acq_func(x, model, STS)

Returns the value and gradient of a purely exploiting acquisition function

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.

static footer(STS)

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

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

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], … ]

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)

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.

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

Indices and tables