actgpr package

Submodules

actgpr.acquisition module

Acquisition function module for active GPR optimisation.

Implements the Expected Improvement (EI) acquisition function for selecting the next input point to evaluate.

References

Jones, D. R., Schonlau, M., & Welch, W. J. (1998).

Efficient Global Optimization of Expensive Black-Box Functions. Journal of Global Optimization, 13(4), 455-492. https://doi.org/10.1023/A:1008306431147

class actgpr.acquisition.Acquisition(surrogate, search_bounds, n_candidates=500)

Bases: object

Expected Improvement acquisition function for active GPR optimisation.

Stores a reference to the surrogate, search bounds, and candidate count. Scores candidate input points and selects the next input point to evaluate.

Public Methods

expected_improvement(f_mean, f_var, current_best)

Compute EI scores for an array of candidate points.

find_next_input_point(current_best)

Generate candidates, score them, and return the best input point.

expected_improvement(f_mean, f_var, current_best)

Compute the Expected Improvement at candidate points.

Parameters:

• f_mean (torch.Tensor of shape (m,)) – Predicted posterior mean at candidate points.

• f_var (torch.Tensor of shape (m,)) – Predicted posterior variance at candidate points.

• current_best (float) – The smallest objective value observed so far.

Returns:

The EI score for each candidate point.

Return type:

torch.Tensor of shape (m,)

Raises:

ValueError – If f_mean and f_var have different shapes.

find_next_input_point(current_best)

Find the next input point to evaluate by maximising Expected Improvement.

Generates a dense grid of candidate points within the search bounds, predicts posterior mean and variance using the surrogate, scores them with Expected Improvement, and returns the candidate with the highest score.

Parameters:

current_best (float) – The smallest objective value observed so far.

Returns:

The input point with the highest EI score.

Return type:

float

Raises:

RuntimeError – If the surrogate has not been fitted prior to calling.

Parameters:

• surrogate (GPyTorchSurrogate)

• search_bounds (tuple[float, float])

• n_candidates (int)

actgpr.mrr module

Minimal Reproducible Run (MRR) file I/O operations.

actgpr.mrr.create_run_dir(base_path, fit_mode, training_iter, ei_threshold, max_iterations, noise, lengthscale, outputscale)

Create a timestamped run directory with parameters in the name.

Parameters:

• base_path (Path) – The root directory where runs are stored (e.g., “results”).

• fit_mode (str) – “training” or “notraining”.

• training_iter (int | None) – Number of training iterations (if fit_mode is “training”).

• ei_threshold (float) – Expected improvement threshold for convergence.

• max_iterations (int) – Maximum number of evaluations.

• noise (float) – Noise level for the surrogate.

• lengthscale (float | None) – Lengthscale (if fit_mode is “notraining”).

• outputscale (float | None) – Outputscale (if fit_mode is “notraining”).

Returns:

The created run directory path.

Return type:

Path

actgpr.mrr.write_config(run_dir, config)

Write all run parameters to config.json.

Parameters:

• run_dir (Path)

• config (dict[str, object])

Return type:

None

actgpr.mrr.write_manifest(run_dir)

Compute SHA-256 of config.json and write manifest.json.

Parameters:

run_dir (Path)

Return type:

None

actgpr.mrr.write_meta(run_dir, run_start, run_end, best_x, best_y, n_iterations, stop_reason)

Write environment and output summary to meta.json.

Includes the package name, version, and repository URL so a meta.json file remains identifiable on its own — e.g. if shared or archived separately from this repository.

Parameters:

• run_dir (Path)

• run_start (datetime)

• run_end (datetime)

• best_x (float)

• best_y (float)

• n_iterations (int)

• stop_reason (str)

Return type:

None

actgpr.mrr.save_hdf5(run_dir, results, config, store_snapshots, final_train_x, final_train_y, best_x, best_y, stop_reason, n_iterations, convergence_snapshot=None)

Write a self-describing HDF5 file with the run history and results.

Layout

/ (root)

Attributes holding the run configuration (bounds, thresholds, …).

history/

Per-iteration scalar series, each a dataset of length n_iterations aligned by the iteration index dataset: next_point, new_y, current_best, max_ei, prediction_error, improvement. This is the single authoritative record of the run’s scalar history. Covers only evaluated iterations — see convergence_snapshot below for the one fit that never reached evaluation.

iterations/iter_NNN/

Written only when store_snapshots is True: the GP snapshot arrays candidates, f_mean, f_var, ei_scores, train_x, train_y for that iteration.

final/

Attributes best_x, best_y, stop_reason, n_iterations and the final train_x/train_y datasets. When stop_reason is "ei_threshold" and convergence_snapshot is given, also holds the GP/EI state of the fit that triggered convergence — attributes converged_max_ei/converged_next_point and datasets converged_candidates/converged_f_mean/ converged_f_var/converged_ei_scores. That fit’s candidate was never evaluated, so it has no place in history/ or iterations/ — this is the only place it is recorded.

param convergence_snapshot:

The GP/EI snapshot of the fit that triggered ei_threshold convergence (OptimisationRun._convergence_snapshot), or None if the run stopped via max_iterations or store_snapshots was False.

type convergence_snapshot:

dict or None, optional

Parameters:

• run_dir (Path)

• results (list[dict[str, object]])

• config (dict[str, object])

• store_snapshots (bool)

• final_train_x (Tensor)

• final_train_y (Tensor)

• best_x (float)

• best_y (float)

• stop_reason (str)

• n_iterations (int)

• convergence_snapshot (dict[str, object] | None)

Return type:

None

actgpr.mrr.setup_file_logger(run_dir)

Add a FileHandler to the actgpr logger and return it.

Parameters:

run_dir (Path)

Return type:

FileHandler

actgpr.objective_fn module

Objective function module for active GPR optimisation.

actgpr.objective_fn.DEFAULT_FUNC(x)

Evaluate the default Objective: x².

Parameters:

x (float)

Return type:

float

class actgpr.objective_fn.ObjectiveFn(func=None)

Bases: object

Objective function for active GPR optimisation.

This class represents the real-valued scalar function being optimised. It can be configured with an arbitrary single-input function. By default, it evaluates the quadratic function: f(x) = x^2.

Parameters:

func (Callable[[float], float] | None)

evaluate(*args)

Evaluate the objective at multiple input points.

Parameters:

*args (float) – Arbitrary positional arguments representing the input values to evaluate.

Returns:

The function evaluation result for each input value in the same order.

Return type:

tuple of float

Raises:

• ValueError – If no input arguments are provided.

• TypeError – If an input value cannot be converted to a float, or if the Objective returns a non-numeric value.

Notes

Exceptions raised inside the Objective itself (e.g. a ValueError from a domain error) propagate unchanged so callers can handle the original error type.

actgpr.plotting module

Plotting utilities for active GPR optimisation.

Functions

plot_gp

Core plotting function: draws GP mean, 95% CI, and training data from raw tensors.

plot_surrogate

Convenience wrapper: extracts tensors from a fitted surrogate, then calls plot_gp.

plot_acquisition

Plots the Expected Improvement acquisition landscape.

plot_iteration_snapshot

Draws one iteration’s GP + EI side by side from a snapshot dict.

plot_run_history

Plots validation metrics vs. iteration from a saved run’s results.h5.

actgpr.plotting.plot_gp(candidates, f_mean, f_var, train_x, train_y, next_point=None, ax=None, show=True)

Plot GP predictions from raw tensors.

This is the core GP plotting function. All other GP plot functions delegate to this one.

Parameters:

• candidates (torch.Tensor of shape (m,)) – The x-axis grid of input points.

• f_mean (torch.Tensor of shape (m,)) – The GP posterior mean at each candidate point.

• f_var (torch.Tensor of shape (m,)) – The GP posterior variance at each candidate point.

• train_x (torch.Tensor of shape (n,)) – The training input points.

• train_y (torch.Tensor of shape (n,)) – The training output values.

• next_point (float or None, optional) – The selected next input point. If provided, a vertical line is drawn.

• ax (matplotlib.axes.Axes or None, optional) – An existing axes to draw on. If None, a new figure and axes are created.

• show (bool, optional) – Whether to call plt.show() immediately, by default True.

Returns:

The figure and axes used for the plot.

Return type:

tuple[Figure, Axes]

actgpr.plotting.plot_surrogate(surrogate, test_x, ax=None, show=True)

Plot surrogate predictions against training data.

Convenience wrapper that extracts prediction tensors from a fitted surrogate model and delegates to plot_gp.

Parameters:

• surrogate (GPyTorchSurrogate) – A fitted surrogate model.

• test_x (torch.Tensor of shape (m,)) – The test input points used to compute predictions for plotting.

• ax (matplotlib.axes.Axes or None, optional) – An existing axes to draw on. If None, a new figure and axes are created.

• show (bool, optional) – Whether to call plt.show() immediately, by default True. Set to False when composing multiple plots.

Returns:

The figure and axes used for the plot.

Return type:

tuple[Figure, Axes]

Raises:

RuntimeError – If the surrogate has not been fitted or has no training data.

actgpr.plotting.plot_acquisition(candidates, ei_scores, next_point=None, ax=None, show=True, ylim=None, log_scale=False, ei_threshold=None)

Plot the Expected Improvement acquisition landscape.

Parameters:

• candidates (torch.Tensor of shape (m,)) – The candidate input points that were scored.

• ei_scores (torch.Tensor of shape (m,)) – The EI score for each candidate point.

• next_point (float or None, optional) – The selected next input point. If provided, a vertical line is drawn, along with a marker at (next_point, max EI score) labelled with its value.

• ax (matplotlib.axes.Axes or None, optional) – An existing axes to draw on. If None, a new figure and axes are created.

• show (bool, optional) – Whether to call plt.show() immediately, by default True. Set to False when composing multiple plots.

• ylim (tuple[float, float] or None, optional) – Fixed (min, max) for the y-axis. If None (default), the range is either autoscaled (linear) or derived from ei_threshold (log_scale). Pass a fixed range — e.g. the maximum EI score across an entire run — when comparing EI landscapes across iterations, so a shrinking maximum is visible rather than being autoscaled to fill the axes every time.

• log_scale (bool, optional) – If True, draws the y-axis on a log scale, by default False. EI often shrinks by orders of magnitude as a run converges, which a linear axis compresses into an invisible flat line — log scale keeps that shrinkage visible. EI is exactly 0 at training points (no uncertainty); since a log axis cannot show zero, scores are clamped to the y-axis floor before plotting.

• ei_threshold (float or None, optional) – The run’s convergence threshold. If given, drawn as a horizontal reference line. When log_scale is True and ylim is not given, the y-axis floor defaults to one order of magnitude below this value, so the threshold line sits inside the plot rather than at its edge.

Returns:

The figure and axes used for the plot.

Return type:

tuple[Figure, Axes]

actgpr.plotting.plot_iteration_snapshot(snapshot, axes, ei_ylim=None, ei_log_scale=False, ei_threshold=None)

Draw one iteration’s GP and EI plots onto the given axes pair.

Parameters:

• snapshot (dict) – A snapshot dictionary containing keys: candidates, f_mean, f_var, train_x, train_y, ei_scores, next_point, iteration, current_best, max_ei. prediction_error and improvement are optional — absent for a convergence snapshot, whose next_point was scored but never evaluated.

• axes (tuple[Axes, Axes]) – A pair of axes (gp_ax, ei_ax) to draw on.

• ei_ylim (tuple[float, float] or None, optional) – Fixed (min, max) for the EI subplot’s y-axis, shared across all iterations being browsed. If None (default), the EI axis autoscales to this iteration’s own scores.

• ei_log_scale (bool, optional) – If True, draws the EI subplot’s y-axis on a log scale — see plot_acquisition for why this matters as EI shrinks during a run, by default False.

• ei_threshold (float or None, optional) – The run’s convergence threshold, drawn as a horizontal reference line on the EI subplot. See plot_acquisition.

Return type:

None

actgpr.plotting.plot_run_history(run_dir, ax=None, show=True)

Plot validation metrics vs. iteration from a saved run’s results.h5.

Reads the /history series directly from results.h5 — no OptimisationRun object is needed, so a past run can be visualised from its run directory alone at any later time.

Parameters:

• run_dir (Path or str) – The run directory written by OptimisationRun.run() (the folder containing results.h5, not the file itself).

• ax (matplotlib.axes.Axes or None, optional) – An existing axes to draw on. If None, a new figure and axes are created.

• show (bool, optional) – Whether to call plt.show() immediately, by default True.

Returns:

The figure and axes used for the plot.

Return type:

tuple[Figure, Axes]

Raises:

FileNotFoundError – If run_dir does not contain a results.h5 file.

actgpr.run module

Optimisation run module for active GPR optimisation.

Orchestrates the active learning loop: fit surrogate, maximise acquisition function, evaluate objective, repeat until convergence.

class actgpr.run.OptimisationRun(objective, surrogate, search_bounds, initial_train_x, max_iterations, ei_threshold, n_candidates=500, noise=0.0001, store_snapshots=False, run_dir=None, *, _train_hyperparameters=True, _training_iter=50, _lengthscale=1.0, _outputscale=1.0)

Bases: object

Orchestrates the active GPR optimisation loop.

Coordinates the ObjectiveFn, Surrogate, and Acquisition components to iteratively find the minimum of the ObjectiveFn within the search bounds.

The loop terminates when either the maximum EI score falls below ei_threshold (nothing left to gain) or the number of optimisation iterations reaches max_iterations (budget cap) — whichever fires first.

Use the classmethods with_training and without_training to construct an OptimisationRun. The raw __init__ is available for advanced use but the classmethods are the preferred entry points.

Public Methods

with_training()

Construct an OptimisationRun that optimises GP hyperparameters each iteration.

without_training()

Construct an OptimisationRun with fixed GP hyperparameters.

run()

Execute the optimisation loop and return the results.

plot_iterations()

Open an interactive matplotlib slider to browse GP snapshots per iteration.

classmethod with_training(objective, surrogate, search_bounds, initial_train_x, max_iterations, ei_threshold, n_candidates=500, training_iter=50, noise=0.0001, store_snapshots=False, run_dir=None)

Construct an OptimisationRun that optimises GP hyperparameters.

Each iteration fits the surrogate and optimises the kernel lengthscale, outputscale, and noise variance using Adam.

Parameters:

• objective (ObjectiveFn) – The objective function to minimise.

• surrogate (GPyTorchSurrogate) – The GP surrogate model used to approximate the objective.

• search_bounds (tuple[float, float]) – The closed interval (lo, hi) within which input points are considered.

• initial_train_x (torch.Tensor or list[float] of shape (n,)) – The initial input points to seed the optimisation loop.

• max_iterations (int) – Maximum number of active optimisation iterations — GPR fit cycles — to execute (budget cap).

• ei_threshold (float) – The loop stops when the maximum EI score falls below this value.

• n_candidates (int, optional) – Number of candidate points for the acquisition function, by default 500.

• training_iter (int, optional) – Number of hyperparameter optimisation iterations per surrogate fit, by default 50.

• noise (float, optional) – Initial observation noise variance for the GP likelihood, by default 1e-4.

• store_snapshots (bool, optional) – If True, also stores GP snapshots for interactive plotting via plot_iterations(), by default False. The prediction_error and improvement history used by plotting.plot_run_history() is recorded either way, regardless of this flag.

• run_dir (Path | str | None)

Returns:

A configured OptimisationRun that will train hyperparameters.

Return type:

OptimisationRun

classmethod without_training(objective, surrogate, search_bounds, initial_train_x, max_iterations, ei_threshold, n_candidates=500, lengthscale=1.0, outputscale=1.0, noise=0.0001, store_snapshots=False, run_dir=None)

Construct an OptimisationRun with fixed GP hyperparameters.

Each iteration fits the surrogate with the given lengthscale, outputscale, and noise — no hyperparameter optimisation takes place.

Parameters:

• objective (ObjectiveFn) – The objective function to minimise.

• surrogate (GPyTorchSurrogate) – The GP surrogate model used to approximate the objective.

• search_bounds (tuple[float, float]) – The closed interval (lo, hi) within which input points are considered.

• initial_train_x (torch.Tensor or list[float] of shape (n,)) – The initial input points to seed the optimisation loop.

• max_iterations (int) – Maximum number of active optimisation iterations — GPR fit cycles — to execute (budget cap).

• ei_threshold (float) – The loop stops when the maximum EI score falls below this value.

• n_candidates (int, optional) – Number of candidate points for the acquisition function, by default 500.

• lengthscale (float, optional) – The RBF kernel lengthscale, by default 1.0.

• outputscale (float, optional) – The kernel outputscale (signal variance), by default 1.0.

• noise (float, optional) – The observation noise variance, by default 1e-4.

• store_snapshots (bool, optional) – If True, also stores GP snapshots for interactive plotting via plot_iterations(), by default False. The prediction_error and improvement history used by plotting.plot_run_history() is recorded either way, regardless of this flag.

• run_dir (Path | str | None)

Returns:

A configured OptimisationRun with fixed hyperparameters.

Return type:

OptimisationRun

run()

Execute the optimisation loop.

Iteratively fits the surrogate, finds the next input point via the acquisition function, and evaluates the objective until convergence.

Returns:

A dictionary containing the optimisation results:

• ”best_x”: float — the input point with the lowest Objective value.

• ”best_y”: float — the lowest Objective value found.

• ”train_x”: torch.Tensor — all evaluated input points.

• ”train_y”: torch.Tensor — all Objective outputs.

• ”n_iterations”: int — number of loop iterations executed.

• ”stop_reason”: str — “ei_threshold” if EI dropped below ei_threshold, “max_iterations” if budget cap was reached.

Return type:

dict

plot_iterations(log_scale=False)

Open an interactive matplotlib figure to browse iterations.

Creates a figure with two subplots (GP predictions on top, EI landscape on bottom) and a slider to scrub through iterations.

The Slider is kept alive via self._active_slider for as long as the OptimisationRun exists. Matplotlib does not keep its own strong reference to a Slider — if the only reference were a local variable here, it would be garbage collected as soon as this method returns, which happens immediately whenever plt.show() does not block (backend- and environment-dependent). The slider would still be drawn, but would silently stop responding to drags.

Parameters:

log_scale (bool, optional) – If True, draws the EI subplot’s y-axis on a log scale, with the ei_threshold convergence criterion marked as a reference line. EI often shrinks by orders of magnitude as a run converges, which a linear axis compresses into an invisible flat line — log scale keeps that shrinkage visible. By default False.

Return type:

None

Notes

If the run converged via ei_threshold, the final frame is the fit that triggered convergence — its next_point was scored but never evaluated, shown with a title noting “(converged — not evaluated)” instead of the usual pred_error/improvement values.

Raises:

RuntimeError – If store_snapshots was False or no snapshots were recorded.

Parameters:

log_scale (bool)

Return type:

None

Parameters:

• objective (ObjectiveFn)

• surrogate (GPyTorchSurrogate)

• search_bounds (tuple[float, float])

• initial_train_x (torch.Tensor | list[float])

• max_iterations (int)

• ei_threshold (float)

• n_candidates (int)

• noise (float)

• store_snapshots (bool)

• run_dir (Path | str | None)

• _train_hyperparameters (bool)

• _training_iter (int)

• _lengthscale (float)

• _outputscale (float)

actgpr.surrogate module

Surrogate model module for active GPR optimisation.

class actgpr.surrogate.ExactGPModel(train_x, train_y, likelihood)

Bases: ExactGP

An exact Gaussian Process model with Constant mean and scaled RBF kernel.

This class defines the structural prior components (mean and covariance) of the GP model.

Parameters:

• train_x (Tensor)

• train_y (Tensor)

• likelihood (GaussianLikelihood)

forward(x)

Compute the prior distribution at input points x.

Parameters:

x (torch.Tensor of shape (m,)) – The input points to evaluate the prior mean and covariance at.

Returns:

The prior multivariate normal distribution.

Return type:

gpytorch.distributions.MultivariateNormal

class actgpr.surrogate.GPyTorchSurrogate

Bases: object

A Gaussian Process surrogate model backend wrapper using GPyTorch.

This class packages model definition, parameter optimization, and posterior prediction, hiding GPyTorch-specific API details from external callers.

fit_and_train(train_x, train_y, training_iter=50, lr=0.1, noise=0.0001)

Fit the GP model and optimise hyperparameters automatically.

Optimises the kernel lengthscale, outputscale, and noise variance using PyTorch’s Adam optimiser.

Parameters:

• train_x (torch.Tensor of shape (n,)) – The input points where the objective was evaluated.

• train_y (torch.Tensor of shape (n,)) – The corresponding evaluations of the objective.

• training_iter (int, optional) – Number of iterations for hyperparameter optimisation, by default 50.

• lr (float, optional) – Learning rate for the optimiser, by default 0.1.

• noise (float, optional) – Initial observation noise variance for the likelihood, by default 1e-4.

Return type:

None

fit_no_training(train_x, train_y, lengthscale=1.0, outputscale=1.0, noise=0.0001)

Fit the GP model with user-specified hyperparameters (no training).

Sets the kernel lengthscale, outputscale, and noise to the given values and freezes all parameters so no optimisation takes place.

Parameters:

• train_x (torch.Tensor of shape (n,)) – The input points where the objective was evaluated.

• train_y (torch.Tensor of shape (n,)) – The corresponding evaluations of the objective.

• lengthscale (float, optional) – The RBF kernel lengthscale, by default 1.0.

• outputscale (float, optional) – The kernel outputscale (signal variance), by default 1.0.

• noise (float, optional) – The observation noise variance, by default 1e-4.

Return type:

None

predict(test_x, n_samples=0)

Predict the posterior distributions at test points.

Parameters:

• test_x (torch.Tensor of shape (m,)) – The test input points to predict at.

• n_samples (int, optional) – Number of samples to draw from the latent function’s predictive posterior, by default 0. Sampling is skipped entirely when 0, which keeps predictions cheap inside the optimisation loop.

Returns:

A dictionary containing prediction components:

• ”f_preds”: predictive distribution (MultivariateNormal) of the latent function f(test_x).

• ”observed_pred”: predictive distribution (MultivariateNormal) of observed targets y(test_x) = f(test_x) + noise.

• ”f_mean”: predicted posterior mean of the latent function, torch.Tensor of shape (m,).

• ”f_var”: predicted posterior variance of the latent function, torch.Tensor of shape (m,).

• ”f_covar”: predicted posterior covariance matrix, torch.Tensor of shape (m, m).

• ”f_samples”: samples drawn from the latent function’s predictive posterior, torch.Tensor of shape (n_samples, m). Only present when n_samples > 0.

Return type:

dict[str, torch.Tensor | gpytorch.distributions.MultivariateNormal]

Raises:

RuntimeError – If fit_and_train() or fit_no_training() has not been called prior to predicting.

Module contents

Active GPR (Gaussian Process Regression) Optimisation package.

This package finds the minimum of an expensive-to-evaluate scalar objective function by iteratively fitting a Gaussian Process surrogate and using active learning.

Exported classes

OptimisationRun

Orchestrates the active optimisation loop and MRR artifact writes.

ObjectiveFn

Wraps the scalar Objective function being minimised.

GPyTorchSurrogate

Gaussian Process surrogate backend built on GPyTorch.

Acquisition

Expected Improvement acquisition function.

class actgpr.Acquisition(surrogate, search_bounds, n_candidates=500)

Bases: object

Expected Improvement acquisition function for active GPR optimisation.

Stores a reference to the surrogate, search bounds, and candidate count. Scores candidate input points and selects the next input point to evaluate.

Public Methods

expected_improvement(f_mean, f_var, current_best)

Compute EI scores for an array of candidate points.

find_next_input_point(current_best)

Generate candidates, score them, and return the best input point.

expected_improvement(f_mean, f_var, current_best)

Compute the Expected Improvement at candidate points.

Parameters:

• f_mean (torch.Tensor of shape (m,)) – Predicted posterior mean at candidate points.

• f_var (torch.Tensor of shape (m,)) – Predicted posterior variance at candidate points.

• current_best (float) – The smallest objective value observed so far.

Returns:

The EI score for each candidate point.

Return type:

torch.Tensor of shape (m,)

Raises:

ValueError – If f_mean and f_var have different shapes.

find_next_input_point(current_best)

Find the next input point to evaluate by maximising Expected Improvement.

Generates a dense grid of candidate points within the search bounds, predicts posterior mean and variance using the surrogate, scores them with Expected Improvement, and returns the candidate with the highest score.

Parameters:

current_best (float) – The smallest objective value observed so far.

Returns:

The input point with the highest EI score.

Return type:

float

Raises:

RuntimeError – If the surrogate has not been fitted prior to calling.

Parameters:

• surrogate (GPyTorchSurrogate)

• search_bounds (tuple[float, float])

• n_candidates (int)

class actgpr.ObjectiveFn(func=None)

Bases: object

Objective function for active GPR optimisation.

This class represents the real-valued scalar function being optimised. It can be configured with an arbitrary single-input function. By default, it evaluates the quadratic function: f(x) = x^2.

Parameters:

func (Callable[[float], float] | None)

evaluate(*args)

Evaluate the objective at multiple input points.

Parameters:

*args (float) – Arbitrary positional arguments representing the input values to evaluate.

Returns:

The function evaluation result for each input value in the same order.

Return type:

tuple of float

Raises:

• ValueError – If no input arguments are provided.

• TypeError – If an input value cannot be converted to a float, or if the Objective returns a non-numeric value.

Notes

Exceptions raised inside the Objective itself (e.g. a ValueError from a domain error) propagate unchanged so callers can handle the original error type.

class actgpr.OptimisationRun(objective, surrogate, search_bounds, initial_train_x, max_iterations, ei_threshold, n_candidates=500, noise=0.0001, store_snapshots=False, run_dir=None, *, _train_hyperparameters=True, _training_iter=50, _lengthscale=1.0, _outputscale=1.0)

Bases: object

Orchestrates the active GPR optimisation loop.

Coordinates the ObjectiveFn, Surrogate, and Acquisition components to iteratively find the minimum of the ObjectiveFn within the search bounds.

The loop terminates when either the maximum EI score falls below ei_threshold (nothing left to gain) or the number of optimisation iterations reaches max_iterations (budget cap) — whichever fires first.

Use the classmethods with_training and without_training to construct an OptimisationRun. The raw __init__ is available for advanced use but the classmethods are the preferred entry points.

Public Methods

with_training()

Construct an OptimisationRun that optimises GP hyperparameters each iteration.

without_training()

Construct an OptimisationRun with fixed GP hyperparameters.

run()

Execute the optimisation loop and return the results.

plot_iterations()

Open an interactive matplotlib slider to browse GP snapshots per iteration.

classmethod with_training(objective, surrogate, search_bounds, initial_train_x, max_iterations, ei_threshold, n_candidates=500, training_iter=50, noise=0.0001, store_snapshots=False, run_dir=None)

Construct an OptimisationRun that optimises GP hyperparameters.

Each iteration fits the surrogate and optimises the kernel lengthscale, outputscale, and noise variance using Adam.

Parameters:

• objective (ObjectiveFn) – The objective function to minimise.

• surrogate (GPyTorchSurrogate) – The GP surrogate model used to approximate the objective.

• search_bounds (tuple[float, float]) – The closed interval (lo, hi) within which input points are considered.

• initial_train_x (torch.Tensor or list[float] of shape (n,)) – The initial input points to seed the optimisation loop.

• max_iterations (int) – Maximum number of active optimisation iterations — GPR fit cycles — to execute (budget cap).

• ei_threshold (float) – The loop stops when the maximum EI score falls below this value.

• n_candidates (int, optional) – Number of candidate points for the acquisition function, by default 500.

• training_iter (int, optional) – Number of hyperparameter optimisation iterations per surrogate fit, by default 50.

• noise (float, optional) – Initial observation noise variance for the GP likelihood, by default 1e-4.

• store_snapshots (bool, optional) – If True, also stores GP snapshots for interactive plotting via plot_iterations(), by default False. The prediction_error and improvement history used by plotting.plot_run_history() is recorded either way, regardless of this flag.

• run_dir (Path | str | None)

Returns:

A configured OptimisationRun that will train hyperparameters.

Return type:

OptimisationRun

classmethod without_training(objective, surrogate, search_bounds, initial_train_x, max_iterations, ei_threshold, n_candidates=500, lengthscale=1.0, outputscale=1.0, noise=0.0001, store_snapshots=False, run_dir=None)

Construct an OptimisationRun with fixed GP hyperparameters.

Each iteration fits the surrogate with the given lengthscale, outputscale, and noise — no hyperparameter optimisation takes place.

Parameters:

• objective (ObjectiveFn) – The objective function to minimise.

• surrogate (GPyTorchSurrogate) – The GP surrogate model used to approximate the objective.

• search_bounds (tuple[float, float]) – The closed interval (lo, hi) within which input points are considered.

• initial_train_x (torch.Tensor or list[float] of shape (n,)) – The initial input points to seed the optimisation loop.

• max_iterations (int) – Maximum number of active optimisation iterations — GPR fit cycles — to execute (budget cap).

• ei_threshold (float) – The loop stops when the maximum EI score falls below this value.

• n_candidates (int, optional) – Number of candidate points for the acquisition function, by default 500.

• lengthscale (float, optional) – The RBF kernel lengthscale, by default 1.0.

• outputscale (float, optional) – The kernel outputscale (signal variance), by default 1.0.

• noise (float, optional) – The observation noise variance, by default 1e-4.

• store_snapshots (bool, optional) – If True, also stores GP snapshots for interactive plotting via plot_iterations(), by default False. The prediction_error and improvement history used by plotting.plot_run_history() is recorded either way, regardless of this flag.

• run_dir (Path | str | None)

Returns:

A configured OptimisationRun with fixed hyperparameters.

Return type:

OptimisationRun

run()

Execute the optimisation loop.

Iteratively fits the surrogate, finds the next input point via the acquisition function, and evaluates the objective until convergence.

Returns:

A dictionary containing the optimisation results:

• ”best_x”: float — the input point with the lowest Objective value.

• ”best_y”: float — the lowest Objective value found.

• ”train_x”: torch.Tensor — all evaluated input points.

• ”train_y”: torch.Tensor — all Objective outputs.

• ”n_iterations”: int — number of loop iterations executed.

• ”stop_reason”: str — “ei_threshold” if EI dropped below ei_threshold, “max_iterations” if budget cap was reached.

Return type:

dict

plot_iterations(log_scale=False)

Open an interactive matplotlib figure to browse iterations.

Creates a figure with two subplots (GP predictions on top, EI landscape on bottom) and a slider to scrub through iterations.

The Slider is kept alive via self._active_slider for as long as the OptimisationRun exists. Matplotlib does not keep its own strong reference to a Slider — if the only reference were a local variable here, it would be garbage collected as soon as this method returns, which happens immediately whenever plt.show() does not block (backend- and environment-dependent). The slider would still be drawn, but would silently stop responding to drags.

Parameters:

log_scale (bool, optional) – If True, draws the EI subplot’s y-axis on a log scale, with the ei_threshold convergence criterion marked as a reference line. EI often shrinks by orders of magnitude as a run converges, which a linear axis compresses into an invisible flat line — log scale keeps that shrinkage visible. By default False.

Return type:

None

Notes

If the run converged via ei_threshold, the final frame is the fit that triggered convergence — its next_point was scored but never evaluated, shown with a title noting “(converged — not evaluated)” instead of the usual pred_error/improvement values.

Raises:

RuntimeError – If store_snapshots was False or no snapshots were recorded.

Parameters:

log_scale (bool)

Return type:

None

Parameters:

• objective (ObjectiveFn)

• surrogate (GPyTorchSurrogate)

• search_bounds (tuple[float, float])

• initial_train_x (torch.Tensor | list[float])

• max_iterations (int)

• ei_threshold (float)

• n_candidates (int)

• noise (float)

• store_snapshots (bool)

• run_dir (Path | str | None)

• _train_hyperparameters (bool)

• _training_iter (int)

• _lengthscale (float)

• _outputscale (float)

class actgpr.GPyTorchSurrogate

Bases: object

A Gaussian Process surrogate model backend wrapper using GPyTorch.

This class packages model definition, parameter optimization, and posterior prediction, hiding GPyTorch-specific API details from external callers.

fit_and_train(train_x, train_y, training_iter=50, lr=0.1, noise=0.0001)

Fit the GP model and optimise hyperparameters automatically.

Optimises the kernel lengthscale, outputscale, and noise variance using PyTorch’s Adam optimiser.

Parameters:

• train_x (torch.Tensor of shape (n,)) – The input points where the objective was evaluated.

• train_y (torch.Tensor of shape (n,)) – The corresponding evaluations of the objective.

• training_iter (int, optional) – Number of iterations for hyperparameter optimisation, by default 50.

• lr (float, optional) – Learning rate for the optimiser, by default 0.1.

• noise (float, optional) – Initial observation noise variance for the likelihood, by default 1e-4.

Return type:

None

fit_no_training(train_x, train_y, lengthscale=1.0, outputscale=1.0, noise=0.0001)

Fit the GP model with user-specified hyperparameters (no training).

Sets the kernel lengthscale, outputscale, and noise to the given values and freezes all parameters so no optimisation takes place.

Parameters:

• train_x (torch.Tensor of shape (n,)) – The input points where the objective was evaluated.

• train_y (torch.Tensor of shape (n,)) – The corresponding evaluations of the objective.

• lengthscale (float, optional) – The RBF kernel lengthscale, by default 1.0.

• outputscale (float, optional) – The kernel outputscale (signal variance), by default 1.0.

• noise (float, optional) – The observation noise variance, by default 1e-4.

Return type:

None

predict(test_x, n_samples=0)

Predict the posterior distributions at test points.

Parameters:

• test_x (torch.Tensor of shape (m,)) – The test input points to predict at.

• n_samples (int, optional) – Number of samples to draw from the latent function’s predictive posterior, by default 0. Sampling is skipped entirely when 0, which keeps predictions cheap inside the optimisation loop.

Returns:

A dictionary containing prediction components:

• ”f_preds”: predictive distribution (MultivariateNormal) of the latent function f(test_x).

• ”observed_pred”: predictive distribution (MultivariateNormal) of observed targets y(test_x) = f(test_x) + noise.

• ”f_mean”: predicted posterior mean of the latent function, torch.Tensor of shape (m,).

• ”f_var”: predicted posterior variance of the latent function, torch.Tensor of shape (m,).

• ”f_covar”: predicted posterior covariance matrix, torch.Tensor of shape (m, m).

• ”f_samples”: samples drawn from the latent function’s predictive posterior, torch.Tensor of shape (n_samples, m). Only present when n_samples > 0.

Return type:

dict[str, torch.Tensor | gpytorch.distributions.MultivariateNormal]

Raises:

RuntimeError – If fit_and_train() or fit_no_training() has not been called prior to predicting.