Skip to content

Odyssey

Odyssey is a FastAPI service. The main components are the HTTP layer (main.py, routers.py), the request/response schemas (schemas.py), and the BoTorch-backed optimiser classes under optimisers/.

Application entry point

odyssey.main builds the FastAPI app and mounts two routers from odyssey.routers:

  • suggest_router — the Bayesian-optimisation and design endpoints (/single/suggest, /mobo/suggest, /mobo/qNEHVI-suggest, /design/{method}).
  • viz_router — the visualisation and mixture-design endpoints (/umap_overview, /parallel_coords, /pairwise_grid, /convergence, /simplex/design, /simplex/fit, /simplex_model).

A PayloadError exception (odyssey.schemas.PayloadError) is registered with a global handler in main.py that returns a structured 400 response (error, message, hint).

Request schemas

odyssey.schemas defines the pydantic request models:

  • Parameter — a named parameter with bounds: [low, high] and an optional discrete step.
  • BORequestMeta — single-objective suggest request: objectives, goals ("max"/"min"), parameter_space, optional noise_se, total_constraint, plot, and an OptimiserSpec (acquisition function + params).
  • MOBOBORequestMeta — the multi-objective analogue, with a MOBOOptimiserSpec (qLogNEHVI/qNParEGO).
  • SamplingRequestMeta — space-filling design request: parameter_space, n_points, seed, optional total_constraint.

Both BORequestMeta and MOBOBORequestMeta use extra = "forbid", so unrecognised fields in meta_json are rejected rather than silently ignored.

Optimiser classes

odyssey.optimisers.BO_base.BOBase is the abstract base class shared by both optimisers: it validates goals/param_bounds/NOISE_SE, holds the device/dtype, and declares the _fit()/_suggest() interface.

  • Botorch_singleGP.BotorchSingleGP — single-objective optimiser. Fits a SingleTaskGP (plus a small constraint GP), then optimises the selected acquisition function (qLogNEI, qLogEI, PI, UCB) via optimize_acqf (continuous parameters) or optimize_acqf_discrete (when any parameter has a step).
  • Botorch_multiGPlist.BotorchMultiGPlist — multi-objective optimiser. Fits a ModelListGP (one SingleTaskGP per objective) and optimises qLogNoisyExpectedHypervolumeImprovement (or qNParEGO scalarisation) to suggest the next candidate, returning the current Pareto front alongside it.

Both support an optional total_constraint (equality constraint: the suggested parameters must sum to a fixed total — useful for mixture problems) and per-parameter discrete step sizes.

Utilities and plotting

odyssey.utils and odyssey.simplex hold the request-independent helper functions used by the routers: NPZ loading (load_npz_from_upload, _safe_npz_load), noise/grid helpers (resolve_noise, snap_to_grid), UMAP/PCA embedding (_compute_embedding), GP posterior plotting (make_posterior_plot), and Scheffé simplex design/response-surface plotting.