qpots 2.2.1

Batch Pareto Optimal Thompson Sampling for multiobjective Bayesian optimization

$q\texttt{POTS}$ is a Python package for sample-efficient multiobjective Bayesian optimization. It implements Pareto Optimal Thompson Sampling, a batch acquisition strategy that selects candidates according to their probability of being Pareto optimal under Gaussian-process posterior samples.

The project is maintained by the Computational Complex Engineered Systems Design Laboratory (CSDL) at Penn State.

Why $q\texttt{POTS}$?

Multiobjective optimization often requires many expensive function evaluations before a useful Pareto front emerges. $q\texttt{POTS}$ combines Gaussian-process surrogate modeling with evolutionary optimization over posterior samples, giving users a practical way to propose informative batches without directly optimizing a difficult analytical acquisition function.

Use $q\texttt{POTS}$ when you need to:

• optimize two or more competing objectives with limited evaluation budget;
• propose one or more candidates per Bayesian optimization iteration;
• handle BoTorch benchmark functions or your own custom objectives;
• compare $q\texttt{POTS}$ against common multiobjective acquisition strategies; or
• interoperate with a separately obtained TS-EMO checkout when MATLAB Engine is available.

Installation

Install the latest release from PyPI:

pip install qpots

To install from source:

git clone https://github.com/csdlpsu/qpots
cd qpots
pip install .

$q\texttt{POTS}$ requires Python 3.11 or newer and is continuously tested on Python 3.11, 3.12, 3.13, and 3.14. The core $q\texttt{POTS}$ implementation uses Python dependencies installed by pip, including BoTorch, PyTorch, GPyTorch, NumPy, SciPy, scikit-learn, and pymoo.

Optional MATLAB Engine

The MATLAB Engine is only needed for the optional TS-EMO interoperability layer. The TS-EMO MATLAB source is not bundled with or licensed by qPOTS; obtain an authorized checkout separately and pass its root as tsemo_path. $q\texttt{POTS}$ itself and the BoTorch-based acquisition functions do not require MATLAB. See THIRD_PARTY_NOTICES.md.

Install MATLAB Engine with the version that matches your local MATLAB installation. For example, MATLAB R2023b uses:

pip install matlabengine==23.2.1

See MathWorks' MATLAB Engine for Python installation guide for release-specific instructions.

Quick Start

The example below runs $q\texttt{POTS}$ on the two-objective Branin-Currin benchmark.

from qpots import Function, QPOTSConfig, QPOTSRunner

problem = Function("branincurrin", dim=2, nobj=2)
config = QPOTSConfig(n_initial=20, iterations=50, batch_size=1)
result = QPOTSRunner(problem, config).run()

print(result.train_x)
print(result.train_y)

Runtime Precision And Device

$q\texttt{POTS}$ uses CUDA when PyTorch detects a GPU and otherwise falls back to CPU. Configure newly-created objects without editing the installed package:

import torch
from qpots import RuntimeConfig, set_default_runtime

set_default_runtime(RuntimeConfig(device="cpu", dtype=torch.float64))

Per-object runtime, device, and dtype arguments override this default.

For complete scripts, see:

• Unconstrained Branin
• Constrained optimization
• Decoupled optimization (OSY)
• Custom constrained cantilever design
• qPOTS-Decoupled visualization
• Multiple acquisition functions
• HPC-style runs

qPOTS-Decoupled

Use qPOTS-Decoupled when objectives or constraints can be measured separately. A multitask Gaussian process shares information between outputs, while a total-correlation gate and mutual-information rule select which output tasks to query at each candidate.

See the dedicated qPOTS-Decoupled guide and the decoupled OSY example.

Documentation

The hosted documentation includes installation notes, API references, and worked examples:

qpots.readthedocs.io

Public API and compatibility

The recommended public interfaces are importable directly from qpots. The existing module imports used by qPOTS 2.0 scripts remain supported. See the API compatibility policy for the supported surface, migration guidance, and deprecation policy.

The repository's test and acceptance plan defines the checks required for pull requests and releases.

Main Reference

The main reference for this repository is the AISTATS 2025 paper:

Ashwin Renganathan and Kade Carlson. $q\texttt{POTS}$: Efficient Batch Multiobjective Bayesian Optimization via Pareto Optimal Thompson Sampling. Proceedings of The 28th International Conference on Artificial Intelligence and Statistics, PMLR 258:4051-4059, 2025.

@inproceedings{renganathan2025qpots,
  title={qPOTS: Efficient Batch Multiobjective Bayesian Optimization via Pareto Optimal Thompson Sampling},
  author={Renganathan, Ashwin and Carlson, Kade},
  booktitle={International Conference on Artificial Intelligence and Statistics},
  pages={4051--4059},
  year={2025},
  organization={PMLR}
}

Additional links:

• AISTATS/PMLR paper page
• PDF
• arXiv preprint

Development

Clone the repository and install the package in editable mode with the test dependencies:

git clone https://github.com/csdlpsu/qpots
cd qpots
python -m pip install -e ".[test,docs]"

Run the test suite with:

pytest

The package source lives in qpots/, examples live in examples/, tests live in tests/, and Sphinx documentation lives in docs/.

Contributing And Support

Contributions, bug reports, documentation improvements, and research-use questions are welcome. Please read CONTRIBUTING.md before opening a pull request.

Use the GitHub issue tracker to report bugs, request features, ask usage questions, or seek support. For bug reports, include your qPOTS version, Python version, operating system, relevant dependency versions, CPU/GPU context, and a minimal reproducible example when possible.

qPOTS is maintained by the Computational Complex Engineered Systems Design Laboratory at Penn State. Maintainer response times may vary with academic schedules, but issues with reproducible examples and clear research context are easiest to triage.

License

This project is distributed under the terms of the GNU General Public License v3.0.