Decoupled OSY example

This executable example applies qPOTS-Decoupled to the constrained OSY benchmark. OSY has six design variables, two objectives, and six inequality constraints, giving eight output oracles in total.

Why OSY is useful here

A coupled batch of two designs requires 16 scalar oracle evaluations. In qPOTS-Decoupled mode, the acquisition returns a task subset for each design. Values from tasks outside that subset are stored as NaN and excluded from the next multitask Gaussian-process fit.

Key configuration

config = QPOTSConfig(
    n_initial=60,
    iterations=50,
    batch_size=2,
    n_constraints=6,
    generations=20,
    multitask=True,
    partial_evaluations=True,
    correlation_threshold=1e-4,
    seed=1023,
)

The multitask model shares information across all eight outputs. partial_evaluations enables output selection, while correlation_threshold activates the total-correlation gate and mutual-information subset rule.

Complete script

decoupled_osy_example.py

"""Run decoupled qPOTS oracle selection on the constrained OSY benchmark."""

from __future__ import annotations

import argparse
from pathlib import Path

import torch

from qpots import Function, QPOTSConfig, QPOTSRunner, RuntimeConfig


def parse_args() -> argparse.Namespace:
    """Parse example runtime and output settings."""
    parser = argparse.ArgumentParser()
    parser.add_argument("--n-initial", type=int, default=60)
    parser.add_argument("--iterations", type=int, default=50)
    parser.add_argument("--batch-size", type=int, default=2)
    parser.add_argument("--generations", type=int, default=20)
    parser.add_argument("--threshold", type=float, default=1e-4)
    parser.add_argument("--seed", type=int, default=1023)
    parser.add_argument("--output-dir", type=Path, default=Path("."))
    parser.add_argument(
        "--quick",
        action="store_true",
        help="Use a small CPU configuration for an end-to-end smoke test.",
    )
    return parser.parse_args()


def report(result):
    queried = (~torch.isnan(result.observed_values)).sum().item()
    print(
        f"Iteration {result.iteration}: queried "
        f"{queried}/{result.observed_values.numel()} scalar oracles"
    )


def main() -> None:
    """Run the example and save its partially observed training data."""
    args = parse_args()
    if args.quick:
        args.n_initial = 12
        args.iterations = 1
        args.batch_size = 2
        args.generations = 2

    runtime = RuntimeConfig(device="cpu", dtype=torch.float64)
    problem = Function("osy", dim=6, nobj=2, runtime=runtime)
    config = QPOTSConfig(
        n_initial=args.n_initial,
        iterations=args.iterations,
        batch_size=args.batch_size,
        n_constraints=6,
        generations=args.generations,
        multitask=True,
        partial_evaluations=True,
        correlation_threshold=args.threshold,
        seed=args.seed,
    )
    result = QPOTSRunner(problem, config, runtime=runtime, callbacks=[report]).run()
    args.output_dir.mkdir(parents=True, exist_ok=True)
    torch.save(result.train_x.cpu(), args.output_dir / "osy_train_x.pt")
    torch.save(result.train_y.cpu(), args.output_dir / "osy_partial_train_y.pt")
    queried = sum(int((~torch.isnan(step.observed_values)).sum()) for step in result.iterations)
    possible = args.iterations * args.batch_size * result.train_y.shape[-1]
    print(f"Selected {queried}/{possible} possible infill oracle evaluations")


if __name__ == "__main__":
    main()

The callback reports how many scalar outputs were retained from each possible 16-output batch. The saved osy_partial_train_y.pt tensor contains objective columns first and constraint columns second, with NaN at unobserved tasks.

Run the example

python -m examples.decoupled_osy_example

For a small end-to-end check on CPU, use:

python -m examples.decoupled_osy_example --quick --output-dir /tmp/qpots-osy

These commands assume a source checkout. With a PyPI-only installation, save the complete script above as main.py and replace python -m examples.decoupled_osy_example with python main.py. See Running the repository examples.

This example is substantially more expensive than the introductory examples because it refits a joint multitask Gaussian process after every partially observed batch. Reduce n_initial, iterations, and generations while validating a local environment.

The built-in OSY function is fully evaluated for benchmark bookkeeping, but only selected values enter model training. See Benchmarking versus real oracle calls for the distinction between this emulation and an external workflow that avoids unselected oracle calls entirely.

The saved output order is always two objectives followed by six constraints. When a complete row is available, it is feasible only if every constraint is greater than or equal to zero. NaN denotes an output that was not queried; it is not a feasibility value.