SEAMsurrogates package

Submodules

surmod.bayesian_optimization module

class surmod.bayesian_optimization.BayesianOptimizer(objective_function: str, x_init: ndarray, y_init: ndarray, kernel: str = 'matern', isotropic: bool = False, acquisition_function: str = 'EI', n_acquire: int = 10, seed: int = 42, noise_bounds: Tuple[float, float] | None = None, fixed_noise: float | None = None, init_design: str = 'random', init_design_kwargs: dict | None = None, **acquisition_kwargs)

Bases: object

bayes_opt(df: DataFrame | None = None, n_init: int = 10) → Tuple[ndarray, ndarray, ndarray]
evaluate_objective(x_next: ndarray) → ndarray
gp_model_fit() → GPSurrogate
propose_location(num_restarts: int = 30, raw_samples: int = 1000) → ndarray
score_candidates(x_candidates: ndarray) → ndarray
step(df: DataFrame | None = None, remaining_indices: set[int] | None = None, x_grid: ndarray | None = None, grid_shape: tuple[int, int] | None = None, return_diagnostics: bool = False) → dict
surmod.bayesian_optimization.get_synth_global_optima(objective_function: str) → Tuple[List[List[float]], float]
surmod.bayesian_optimization.plot_acquisition_comparison(max_output_EI: ndarray, max_output_PI: ndarray, max_output_UCB: ndarray, max_output_PV: ndarray, max_output_random: ndarray, kernel: str = 'rbf', n_iter: int = 10, n_init: int = 5, objective_data: str = '___ data', beta: float = 2.0) → None
surmod.bayesian_optimization.sample_data(objective_function: str, bounds_low: float | Sequence[float] | ndarray, bounds_high: float | Sequence[float] | ndarray, n_initial: int, input_size: int = 2, init_design: str = 'random', seed: int | None = None, **design_kwargs) → Tuple[ndarray, ndarray]

Generate input and output samples from the specified synthetic objective.

Parameters:

  • objective_function – Name of the objective function.

  • bounds_low – Lower bounds.

  • bounds_high – Upper bounds.

  • n_initial – Number of initial points.

  • input_size – Input dimension.

  • init_design – One of ‘random’, ‘lhd’, ‘maximin_lhd’.

  • seed – Random seed.

  • design_kwargs – Extra kwargs forwarded to generate_initial_design().

Returns:

x_sample: shape (n_initial, input_size) y_sample: shape (n_initial,)

Return type:

Tuple of

surmod.bayesian_optimization.sample_parabola(n_initial: int, bounds_low: float | Sequence[float] | ndarray, bounds_high: float | Sequence[float] | ndarray, input_size: int, radius: float = 7) → ndarray
surmod.bayesian_optimization.select_initial_dataset_indices(x: ndarray, n_init: int, method: str = 'random', seed: int = 42, **design_kwargs) → ndarray

Select initial dataset rows.

For method=’random’, sample rows uniformly without replacement. For method=’lhd’ or ‘maximin_lhd’, generate a space-filling design in normalized [0,1]^d space and map each design point to the nearest available dataset row, enforcing uniqueness.

Parameters:

  • x – Dataset inputs, assumed already normalized to [0,1], shape (n, d)

  • n_init – Number of initial points

  • method – ‘random’, ‘lhd’, or ‘maximin_lhd’

  • seed – Random seed

  • design_kwargs – Extra arguments forwarded to generate_initial_design()

Returns:

Array of selected row indices, shape (n_init,)

surmod.gaussian_process_regression module

surmod.jag module

surmod.neural_network module

Functions for neural network surrogates.

class surmod.neural_network.NeuralNet(input_size: int, hidden_sizes: List[int], output_size: int, initialize_weights_normal: bool)

Bases: Module

A customizable feedforward neural network for regression tasks.

forward(x: Tensor) → Tensor

Forward pass through the neural network.

Parameters:

x (torch.Tensor) – Input tensor.

Returns:

Output tensor after passing through the network.

Return type:

torch.Tensor

surmod.neural_network.load_test_function(objective_function: str) → SyntheticTestFunction

Load a test function instance for simulating data.

Parameters:

objective_function (str) – Name of the test function to load. Must be one of: “Ackley”, “SixHumpCamel”, “Griewank”.

Returns:

An instance of the requested BoTorch synthetic test function.

Return type:

SyntheticTestFunction

Raises:

ValueError – If the objective_function name is not recognized.

surmod.neural_network.plot_losses(train_losses: List[float], test_losses: List[float], objective_data: str = '___ data') → None

Plot and save the training and testing loss curves across epochs.

Parameters:

  • train_losses (List[float]) – List of training loss values (MSE) for each epoch.

  • test_losses (List[float]) – List of testing loss values (MSE) for each epoch.

  • objective_data (str, optional) – Name or description of the objective function or dataset. Used in the plot title and filename. Defaults to “___ data”.

surmod.neural_network.plot_losses_multiplot(train_losses_grid: List[List[List[float]]], test_losses_grid: List[List[List[float]]], learning_rates: List[float], hid_dims: List[int], axs: Sequence[Sequence[Axes]], objective_data: str = '___ data') → None

Plots training and test losses for multiple runs on a grid of subplots.

Each subplot corresponds to a specific combination of hidden dimension and learning rate, displaying the training and test loss curves over epochs. The final test loss (RMSE) is shown in each subplot title. The resulting multiplot figure is saved to ‘plots’ directory with a filename that includes the objective data and a timestamp.

Parameters:

  • train_losses_grid (Sequence[Sequence[List[float]]]) – 2D grid where each element is a list of training losses per epoch for a specific (hidden_dim, learning_rate) pair.

  • test_losses_grid (Sequence[Sequence[List[float]]]) – 2D grid where each element is a list of test losses per epoch for a specific (hidden_dim, learning_rate) pair.

  • learning_rates (List[float]) – List of learning rates corresponding to the columns of the subplot grid.

  • hid_dims (List[int]) – List of hidden dimensions corresponding to the rows of the subplot grid.

  • axs (Sequence[Sequence[matplotlib.axes.Axes]]) – 2D grid of matplotlib Axes objects for plotting.

  • objective_data (str, optional) – String identifier for the data/objective function, used in the saved filename.

surmod.neural_network.plot_losses_verbose(train_losses: List[float], test_losses: List[float], learning_rate: float, batch_size: int, hidden_sizes: List[int], normalize_x: bool, scale_x: bool, normalize_y: bool, scale_y: bool, train_data_size: int, test_data_size: int, objective_data: str = '___ data') → None

Plot and save training and testing loss curves across epochs, with hyperparameter values in the plot title.

Parameters:

  • train_losses (List[float]) – List of training loss values (MSE) for each epoch.

  • test_losses (List[float]) – List of testing loss values (MSE) for each epoch.

  • learning_rate (float) – Learning rate used during training.

  • batch_size (int) – Batch size used during training.

  • hidden_sizes (List[int]) – List of hidden layer sizes in the model.

  • normalize_x (bool) – Whether input features (x) were normalized.

  • scale_x (bool) – Whether input features (x) were scaled.

  • normalize_y (bool) – Whether target values (y) were normalized.

  • scale_y (bool) – Whether target values (y) were scaled.

  • train_data_size (int) – Number of samples in the training set.

  • test_data_size (int) – Number of samples in the testing set.

  • objective_data (str, optional) – Name or description of the objective function or dataset. Used in the plot title and filename. Defaults to “___ data”.

surmod.neural_network.plot_predictions(y_test: Tensor, predictions: Tensor, final_test_mse: float, objective_data: str = '___ data') → None

Plots the actual test values against the predicted values.

This function creates a parity plot comparing the true test values to the model’s predictions. A reference line for perfect prediction is included. The final test loss (RMSE) is displayed in the plot title. The plot is saved in the ‘plots’ directory, with a filename that includes the objective data and a timestamp.

Parameters:

  • y_test (torch.Tensor) – The true target values for the test set.

  • predictions (torch.Tensor) – The predicted values from the model for the test set.

  • final_test_mse (float) – The final mean squared error on the test set.

  • objective_data (str, optional) – Identifier for the data/objective, used in the filename. Defaults to “___ data”.

surmod.neural_network.train_neural_net(x_train: Tensor, y_train: Tensor, x_test: Tensor, y_test: Tensor, hidden_sizes: List[int], num_epochs: int, learning_rate: float, batch_size: int, seed: int, initialize_weights_normal: bool) → Tuple[Module, List[float], List[float]]

Train a feedforward neural network and evaluate its performance.

Parameters:

  • x_train (torch.Tensor) – Training input features of shape (n_samples, n_features).

  • y_train (torch.Tensor) – Training target values of shape (n_samples,) or (n_samples, 1).

  • x_test (torch.Tensor) – Test input features of shape (n_test_samples, n_features).

  • y_test (torch.Tensor) – Test target values of shape (n_test_samples,) or (n_test_samples, 1).

  • hidden_sizes (List[int]) – List specifying the number of units in each hidden layer.

  • num_epochs (int) – Number of epochs to train the network.

  • learning_rate (float) – Learning rate for the optimizer.

  • batch_size (int) – Number of samples per training batch.

  • seed (int) – Random seed for reproducibility.

  • initialize_weights_normal (bool) – If True, initialize weights with a normal distribution.

Returns:

Trained neural network model, list of training losses per epoch, and list of test losses per epoch.

Return type:

Tuple[nn.Module, List[float], List[float]]

surmod.parabola module

surmod.sensitivity_functions module

surmod.sensitivity_analysis module

Utility functions for simulating, evaluating, and visualizing surrogate modeling sensitivity analysis experiments using benchmark engineering test problems.

surmod.sensitivity_analysis.load_test_settings(objective_function: str) → Tuple[int, Callable[[ndarray, float, float, float], ndarray]]

Load the test function and its input dimension for simulating data.

Parameters:

objective_function (str) – Name of the objective function to load. Must be one of ‘parabola’, ‘otlcircuit’, ‘wingweight’, or ‘piston’.

Returns:

A tuple containing:
  • out_dim (int): The number of input dimensions for the selected

    test function.

  • test_function (Callable): The test function to simulate data

    from.

Return type:

Tuple[int, Callable[[np.ndarray, float, float, float], np.ndarray]]

Raises:

ValueError – If the provided objective_function is not recognized.

surmod.sensitivity_analysis.plot_test_predictions(x_test, y_test, gp_model, objective_function: str) → None

Plot test set predictions vs. ground truth for a GP model.

Compatible with GPSurrogate.predict(), which returns (mean, std) and does not accept return_std=…

surmod.sensitivity_analysis.simulate_data(objective_function: str, num_train: int, num_test: int, b1: float, b2: float, b12: float) → Tuple[ndarray, ndarray, ndarray, ndarray]

Simulate training and testing data from a selected test function.

Parameters:

  • objective_function (str) – Name of the objective function to use. Must be one of ‘parabola’, ‘otlcircuit’, ‘wingweight’, or ‘piston’.

  • num_train (int) – Number of training samples to generate.

  • num_test (int) – Number of testing samples to generate.

  • b1 (float) – First coefficient parameter for the test function.

  • b2 (float) – Second coefficient parameter for the test function.

  • b12 (float) – Interaction coefficient parameter for the test function.

Returns:

  • x_train (np.ndarray): Training input data of shape (num_train, input_dim).

  • x_test (np.ndarray): Testing input data of shape (num_test, input_dim).

  • y_train (np.ndarray): Training output data.

  • y_test (np.ndarray): Testing output data.

Return type:

Tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]

surmod.sensitivity_analysis.sobol_plot(S1: Sequence[float], ST: Sequence[float], variables: List[str], S1_conf: Sequence[float], ST_conf: Sequence[float], objective_function: str)

Plots first and total order Sobol sensitivity indices with confidence intervals and saves the figure.

Parameters:

  • S1 (Sequence[float]) – First order sensitivity indices for each variable.

  • ST (Sequence[float]) – Total order sensitivity indices for each variable.

  • variables (List[str]) – List of variable names.

  • S1_conf (Sequence[float]) – Confidence intervals for first order indices.

  • ST_conf (Sequence[float]) – Confidence intervals for total order indices.

  • objective_function (str) – Name of the objective function, used in the saved plot filename.

Returns:

None, for visualization purposes only.

Module contents