physbo.search.utility module

Utility helpers for the search module.

This module collects helpers used across the search policies:

  • Simulator wraps a test function so it can be called by action index.

  • make_grid() builds a grid of candidate points for a discrete search.

  • plot_pareto_front() and plot_pareto_front_all() visualize the Pareto front stored in a multi-objective history.

  • the remaining show_* / is_learning helpers format progress messages and drive the search loop.

class physbo.search.utility.Simulator(test_X, test_function, negate=False)[source]

Bases: object

Simulator class wrapping the test function for discrete search space.

Parameters:

  • test_X (numpy.ndarray) – The test points. Each row is a candidate.

  • test_function (physbo.test_functions.base.TestFunction) – The test function.

  • negate (bool, default=False) – If True, the test function value is negated before returning.

physbo.search.utility.finite_mask(t)[source]

Return the mask of valid (finite) observations.

An observation is valid when all of its objective values are finite; a NaN or an infinite value marks a failed evaluation.

Parameters:

t (numpy.ndarray) – N dimensional array (single objective) or N x k dimensional array (k objectives) of objective values.

Returns:

mask – True for valid observations, False for failed ones.

Return type:

numpy.ndarray of bool, shape (N,)

physbo.search.utility.is_learning(n, interval)[source]

Decide whether to (re)learn the hyperparameters at search step n.

Parameters:

  • n (int) – Zero-based index of the current search step.

  • interval (int) –

    Hyperparameter learning interval.

    • interval == 0: learn only at the first step (n == 0).

    • interval > 0: learn every interval steps.

    • interval < 0: never learn.

Returns:

True if hyperparameters should be learned at this step.

Return type:

bool

physbo.search.utility.length_vector(t)[source]

Return the number of elements of t.

Parameters:

t (array-like or scalar) – Input object.

Returns:

len(t) if t is sized, otherwise 1 (treating t as a scalar).

Return type:

int

physbo.search.utility.make_grid(min_X: list[float] | ndarray, max_X: list[float] | ndarray, num_X: int | list[int] | ndarray, constraint=None) → ndarray[source]

Make a grid of points in the search space.

Parameters:

  • min_X (np.ndarray | list[float] | float) – Minimum value of search space for each dimension

  • max_X (np.ndarray | list[float] | float) – Maximum value of search space for each dimension

  • num_X (int | list[int] | np.ndarray) – Number of points in each dimension

Returns:

The grid of points in the search space The output is a numpy array of shape (N, d), where N is the number of points and d is the dimension of the search space

Return type:

np.ndarray

Raises:

ValueError – If min_X and max_X have different number of dimensions If num_X has different number of dimensions from min_X and max_X

physbo.search.utility.mask_rows(Z, mask)[source]

Select the observations given by mask from a basis array Z.

Parameters:

  • Z (numpy.ndarray or None) – (N, n) array, or (k, N, n) array (one basis per objective), or None.

  • mask (numpy.ndarray of bool, shape (N,))

Returns:

Z restricted to the rows where mask is True (None if Z is None).

Return type:

numpy.ndarray or None

physbo.search.utility.plot_pareto_front(history, x=0, y=1, steps_begin=0, steps_end=None, ax=None, xlim=None, ylim=None, grid=True, style_common: dict = {}, style_pareto_front: dict = {}, style_dominated: dict = {})[source]

Plot the Pareto front of the history in the projection to the (x, y)-plane (objective x and y).

Parameters:

  • history (History) – The history of the search.

  • x (int, default=0) – The index of the objective to plot on the x-axis.

  • y (int, default=1) – The index of the objective to plot on the y-axis.

  • steps_begin (int, default=0) – The index (inclusive) of the step to begin plotting.

  • steps_end (int, optional) – The index (exclusive) of the step to end plotting. If None, plot until the end.

  • ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure is created.

  • xlim (tuple, optional) – The x-axis limits. If None, the limits are determined automatically.

  • ylim (tuple, optional) – The y-axis limits. If None, the limits are determined automatically.

  • grid (bool, default=True) – Whether to plot the grid.

  • style_common (dict, optional) – The common setting for plotting the points.

  • style_pareto_front (dict, optional) – The setting for plotting the Pareto front.

  • style_dominated (dict, optional) – The setting for plotting the dominated points.

Note

  • Items in style_* are passed to the scatter method of matplotlib.pyplot.

  • For each item, style_pareto_front and style_dominated are higher priority than style_common.

  • By default, the marker is “o”.

  • By default, the color is “blue” for dominated points and “red” for Pareto front.

physbo.search.utility.plot_pareto_front_all(history, steps_begin=0, steps_end=None, ax=None, xlim=None, ylim=None, grid=True, style_common: dict = {}, style_pareto_front: dict = {}, style_dominated: dict = {})[source]

Plot the Pareto front of the history for all pairs of objectives.

Parameters:

  • history (History) – The history of the search.

  • steps_begin (int, optional) – The index (inclusive) of the step to begin plotting. If None, plot from the beginning.

  • steps_end (int, optional) – The index (exclusive) of the step to end plotting. If None, plot until the end.

  • ax (matplotlib.axes.Axes, optional) – The axes to plot on. If None, a new figure is created.

  • xlim (tuple, optional) – The x-axis limits. If None, the limits are determined automatically.

  • ylim (tuple, optional) – The y-axis limits. If None, the limits are determined automatically.

  • grid (bool, default=True) – Whether to plot the grid.

  • style_common (dict, optional) – The common setting for plotting the points.

  • style_pareto_front (dict, optional) – The setting for plotting the Pareto front.

  • style_dominated (dict, optional) – The setting for plotting the dominated points.

Note

  • Items in style_* are passed to the scatter method of matplotlib.pyplot.

  • For each item, style_pareto_front and style_dominated are higher priority than style_common.

  • By default, the marker is “o”.

  • By default, the color is “blue” for dominated points and “red” for Pareto front.

physbo.search.utility.require_finite(X, t, max_shown=5)[source]

Raise an error if t contains a failed (non-finite) observation.

For the policies with a continuous search space. A failed point cannot be removed from a continuous search space, and hence it would be proposed again and again if it were only excluded from the training data.

Parameters:

  • X (numpy.ndarray) – N x d dimensional array. The inputs of the observations.

  • t (numpy.ndarray) – N x k dimensional array. The objective values of the observations.

  • max_shown (int) – The maximum number of the failed observations shown in the message.

Raises:

ValueError – If any objective value is NaN or +-Inf.

physbo.search.utility.require_training_data(training)[source]

Raise an error if there is no observation to train the predictor with.

Parameters:

training (physbo.Variable) – The training dataset.

Raises:

RuntimeError – If the training dataset is empty.

physbo.search.utility.show_interactive_mode(simulator, history)[source]

Print a message when an interactive search session starts.

The message is shown only at the very first step (empty history) of an interactive run, i.e. when no simulator is provided.

Parameters:

  • simulator (callable or None) – The simulator, or None for interactive mode.

  • history (History) – The search history.

physbo.search.utility.show_search_results(history, N)[source]

Print a summary of the last N single-objective search steps.

Parameters:

  • history (History) – The search history.

  • N (int) – Number of most recent steps to display. Capped at the total number of searches performed so far.

physbo.search.utility.show_search_results_mo(history, N, disp_pareto_set=False)[source]

Print a summary of the last N multi-objective search steps.

Parameters:

  • history (History) – The multi-objective search history.

  • N (int) – Number of most recent steps to display. Capped at the total number of searches performed so far.

  • disp_pareto_set (bool, default=False) – If True, also display the current Pareto set.

Print the header announcing a multiple-probe search step.

Parameters:

  • N (int) – Zero-based index of the current search round; the printed index is N + 1.

  • score (str, optional) – Name of the acquisition function. If None, "random" is shown.