proposal

This module provides different classes to generate random proposals within the prior or trust bounds, to be used as initial samples for the active learning cycle, or as starting points from which to optimize the acquisition function.

The way these points are proposed becomes increasingly important with higher dimensions as the volume of the parameter space grows exponentially.

Every proposer has a get method which returns a random sample from the proposer.

gpry.proposal.check_in_bounds(get_method)

Decorator for get methods of Proposer sub-classes, that call the method until the returned proposal falls within the bounds defined as an attribute.

Print a warning every 1000 failed attempts.

It does not need to be used if the returned proposals are guaranteed to fulfil it.

class gpry.proposal.Proposer

Bases: object

Base proposer class. All other proposers inherit from it. If you want to define your own custom proposer it should also inherit from it.

abstract get(rng=None)

Returns a random sample (given a certain random state) in the parameter space for getting initial training samples or the acquisition function to be optimized from.

If the output is not guaranteed by construction to be within the bounds defined in the bounds attribute, decorated this method with check_in_bounds.

Parameters:

rng (int or numpy.random.Generator, optional) – The generator used to propose points. If an integer is given, it is used as a seed for the default global numpy random number generator.

update_bounds(bounds)

Updates the bounds for the proposal.

Parameters:

bounds (array) – Bounds in which to optimize the acquisition function, assumed to be of shape (d,2) for d dimensional prior

update(surrogate)

Updates the internal GP instance if it has been updated with new data.

Parameters:

surrogate (SurrogateModel) – The surrogate instance that has been updated.

class gpry.proposal.InitialPointProposer

Bases: object

Base proposer class for all proposers which work for initial point generation.

class gpry.proposal.ReferenceProposer(truth, bounds=None)

Bases: Proposer, InitialPointProposer

Generates proposals from the “reference” distribution defined in the Truth. If no reference distribution is defined it defaults to the prior.

Parameters:

truth (Truth) – The true model from which to draw the samples.

get(*args, **kwargs)

Returns a random sample (given a certain random state) in the parameter space for getting initial training samples or the acquisition function to be optimized from.

If the output is not guaranteed by construction to be within the bounds defined in the bounds attribute, decorated this method with check_in_bounds.

Parameters:

rng (int or numpy.random.Generator, optional) – The generator used to propose points. If an integer is given, it is used as a seed for the default global numpy random number generator.

class gpry.proposal.PriorProposer(truth, bounds=None)

Bases: Proposer, InitialPointProposer

Generates proposals from the prior of the problem.

Parameters:

truth (Truth) – The true model from which to draw the samples.

get(*args, **kwargs)

Returns a random sample (given a certain random state) in the parameter space for getting initial training samples or the acquisition function to be optimized from.

If the output is not guaranteed by construction to be within the bounds defined in the bounds attribute, decorated this method with check_in_bounds.

Parameters:

rng (int or numpy.random.Generator, optional) – The generator used to propose points. If an integer is given, it is used as a seed for the default global numpy random number generator.

class gpry.proposal.UniformProposer(bounds)

Bases: Proposer, InitialPointProposer

Generates proposals uniformly in a hypercube determined by the bounds

Parameters:

bounds (array-like, shape=(n_dims,2)) – Array of bounds of the prior [lower, upper] along each dimension.

update_bounds(bounds)

Updates the bounds for the proposal.

Parameters:

bounds (array) – Bounds in which to optimize the acquisition function, assumed to be of shape (d,2) for d dimensional prior

get(rng=None)

Returns a random sample (given a certain random state) in the parameter space for getting initial training samples or the acquisition function to be optimized from.

If the output is not guaranteed by construction to be within the bounds defined in the bounds attribute, decorated this method with check_in_bounds.

Parameters:

rng (int or numpy.random.Generator, optional) – The generator used to propose points. If an integer is given, it is used as a seed for the default global numpy random number generator.

class gpry.proposal.PartialProposer(bounds, true_proposer, random_proposal_fraction=0.25)

Bases: Proposer, InitialPointProposer

Combines any of the other proposers with a UniformProposer with a fraction drawn from the uniform proposer to encourage exploration.

Warning

If you want to use this proposer for initial point generation make sure that your true_proposer is compatible.

Parameters:

• bounds (array-like, shape=(n_dims,2)) – Array of bounds of the prior [lower, upper] along each dimension.

• true_proposer (Proposer) – The initialized Proposer instance to use instead of uniform for a fraction of samples.

• random_proposal_fraction (float, between 0 and 1, optional (default=0.25)) – The fraction of proposals that is drawn from the UniformProposer.

get(rng=None)

Returns a random sample (given a certain random state) in the parameter space for getting initial training samples or the acquisition function to be optimized from.

If the output is not guaranteed by construction to be within the bounds defined in the bounds attribute, decorated this method with check_in_bounds.

Parameters:

rng (int or numpy.random.Generator, optional) – The generator used to propose points. If an integer is given, it is used as a seed for the default global numpy random number generator.

update(surrogate)

Updates the internal GP instance if it has been updated with new data.

Parameters:

surrogate (SurrogateModel) – The surrogate instance that has been updated.

update_bounds(bounds)

Updates the bounds for the proposal.

Parameters:

bounds (array) – Bounds in which to optimize the acquisition function, assumed to be of shape (d,2) for d dimensional prior

class gpry.proposal.MeanCovProposer(bounds, mean, cov, include_mean=False)

Bases: Proposer, InitialPointProposer

Generates proposals from a multivariate normal distribution given a mean vector and covariance matrix.

Parameters:

• mean (array-like, shape=(n_dims,)) – Mean-vector of the multivariate normal distribution.

• cov (array-like, shape=(n_dims, n_dims)) –

  Covariance matrix of the multivariate normal distribution.

  Note

  We conduct no explicit checks on whether the covariance matrix you provide is singular. Make sure that your matrix is a valid covariance matrix!

• include_mean (bool (defaulf: False)) – If True, returns the mean in the first call to get (only for the 1st MPI rank)

get(*args, **kwargs)

Returns a random sample (given a certain random state) in the parameter space for getting initial training samples or the acquisition function to be optimized from.

If the output is not guaranteed by construction to be within the bounds defined in the bounds attribute, decorated this method with check_in_bounds.

Parameters:

rng (int or numpy.random.Generator, optional) – The generator used to propose points. If an integer is given, it is used as a seed for the default global numpy random number generator.

class gpry.proposal.CentroidsProposer(bounds, lambd=1.0)

Bases: Proposer

Proposes points at the centroids of subsets of dim-1 training points. It perturbs some of the proposals away from the centroids to encourage exploration.

boundsarray-like, shape=(n_dims,2)

Array of bounds of the prior [lower, upper] along each dimension.

lambda: float, optional (default=1)

Controls the scale of the perturbation of samples. Lower values correspond to more exploration.

property d

Dimensionality of the prior.

get(rng=None)

Returns a random sample (given a certain random state) in the parameter space for getting initial training samples or the acquisition function to be optimized from.

If the output is not guaranteed by construction to be within the bounds defined in the bounds attribute, decorated this method with check_in_bounds.

Parameters:

rng (int or numpy.random.Generator, optional) – The generator used to propose points. If an integer is given, it is used as a seed for the default global numpy random number generator.

update(surrogate)

Updates the internal GP instance if it has been updated with new data.

Parameters:

surrogate (SurrogateModel) – The surrogate instance that has been updated.

update_bounds(bounds)

Updates the bounds for the proposal.

Parameters:

bounds (array) – Bounds in which to optimize the acquisition function, assumed to be of shape (d,2) for d dimensional prior