trade-study

Development documentation

This site is built from main, currently the unreleased 0.8.0 development line (0.8.0.dev0). Public interfaces may change before release. The latest stable package is 0.7.0 on PyPI; its source and README are preserved at the v0.7.0 tag.

trade-study runs replicated simulation studies and compares configurations against multiple objectives. It supports design grids, multi-fidelity phases, Pareto analysis, response models, sensitivity analysis, and model weighting.

For installation and quick-start examples, see the README.

For a short presentation with live code, tables and saved figures, see the serosurvey design notebook, designed for a mixed IVAC audience.

Overview

trade-study provides a structured workflow for multi-objective design-of-experiments studies:

1. Define observables and design factors via lightweight Protocols
2. Build experimental grids with Design utilities (full factorial, Latin hypercube, Sobol, Halton, and constraints)
3. Run simulations across the grid, with optional replicates, adaptive NSGA-II search, or multi-fidelity allocation (Runner)
4. Score posterior predictive accuracy with proper scoring rules (Scoring)
5. Filter the Pareto front (Pareto)
6. Stack models via Bayesian stacking (Stacking)
7. Orchestrate multi-phase studies with Study
8. Fit and validate surrogates for interpolation, regime-specific recommendations, and post-hoc sensitivity (Surrogates)

API Reference

Module	Description
Protocols	Core types: Observable, Direction, Scorer, Simulator, etc.
Design	Factor, FactorConstraint, build_grid, screen, sobol_indices, reduce_factors
Runner	run_grid, run_adaptive, run_successive_halving, run_hyperband
Study	Phase, Study, top_k_pareto_filter, weighted_sum_filter, feasibility_filter
Scoring	score, coverage_curve
Pareto	extract_front, pareto_rank, hypervolume, igd_plus
Stacking	stack_bayesian, stack_scores, stack_proportional, ensemble_predict
Surrogates	fit_surrogate, cross-validation diagnostics, table-based sensitivity
Regimes	Continuous-regime and bucketed configuration recommendations
Visualization	plot_front, plot_parallel, plot_scores, plot_calibration
I/O	load_results, save_results
Paired comparisons	paired_difference, paired_rank
Decision reports	preference_sweep, regret, practical equivalence
Proportion precision	Wilson intervals and fixed-bank sizing
Result artifacts	Versioned bundles and guarded provenance

run_sequential and ReplicationPolicy supply fixed/adaptive replication with recorded bounds, counts and uncertainty assumptions. EvaluationCache and grid checkpoints support revision-aware reuse and resume.

See capabilities and executable examples for current interfaces, optional dependencies, limitations and the checks that run in CI.