diff --git a/README.md b/README.md index 2f48054..e1b1b60 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ multi-objective Pareto optimization, and Bayesian model stacking. The core pattern (from [MFAI §4–5](https://github.com/jcm-sci/trade-study)): -1. **Model world** — Generate synthetic ground truth with known latent state +1. **Simulate** — Generate synthetic ground truth with known latent state 2. **Observe** — Apply a realistic observation model (noise, masks, bias) 3. **Score** — Evaluate structured observables against *known truth* using proper scoring rules (not noisy observations) @@ -29,7 +29,7 @@ benchmark), where each phase filters configs for the next. ``` trade_study/ -├── protocols.py ModelWorld, Scorer, Observable, Annotation, ResultsTable +├── protocols.py Simulator, Scorer, Observable, Annotation, ResultsTable ├── design.py Factor screening (SALib) and grid construction (pyDOE3) ├── scoring.py Proper scoring rules (scoringrules) and calibration ├── pareto.py Non-dominated sorting and indicators (pymoo) @@ -83,7 +83,7 @@ grid = build_grid(factors, method="lhs", n_samples=500) # Run hierarchical study study = Study( - world=MyModelWorld(), + world=MySimulator(), scorer=MyScorer(), observables=[coverage, rank_err, wall_time], phases=[ diff --git a/src/trade_study/__init__.py b/src/trade_study/__init__.py index 30dbb50..1c7a59c 100644 --- a/src/trade_study/__init__.py +++ b/src/trade_study/__init__.py @@ -7,10 +7,10 @@ from .protocols import ( Annotation, Direction, - ModelWorld, Observable, ResultsTable, Scorer, + Simulator, Tier, TrialResult, ) @@ -19,11 +19,11 @@ __all__ = [ "Annotation", "Direction", - "ModelWorld", "Observable", "Phase", "ResultsTable", "Scorer", + "Simulator", "Study", "Tier", "TrialResult", diff --git a/src/trade_study/protocols.py b/src/trade_study/protocols.py index ef57f40..b5dd4de 100644 --- a/src/trade_study/protocols.py +++ b/src/trade_study/protocols.py @@ -43,10 +43,10 @@ class Observable: @runtime_checkable -class ModelWorld(Protocol): +class Simulator(Protocol): """Protocol for generating ground truth and observations. - A model world produces (truth, observations) pairs where truth is the + A simulator produces (truth, observations) pairs where truth is the known latent state and observations are what a real system would see. """ @@ -76,8 +76,8 @@ def score( """Score a single trial, returning values for each observable. Args: - truth: Known latent state from the model world. - observations: Observed data from the model world. + truth: Known latent state from the simulator. + observations: Observed data from the simulator. config: The configuration that produced this trial. Returns: @@ -88,7 +88,7 @@ def score( @dataclass class TrialResult: - """Result of a single model world trial.""" + """Result of a single simulation trial.""" config: dict[str, Any] scores: dict[str, float] @@ -100,7 +100,7 @@ class TrialResult: class Annotation: """External information attached to configurations. - Used for costs, constraints, or metadata not computed by the model world + Used for costs, constraints, or metadata not computed by the simulator (e.g. dollar costs from a surveillance costing sheet). Attributes: diff --git a/src/trade_study/runner.py b/src/trade_study/runner.py index ae0e544..53cb328 100644 --- a/src/trade_study/runner.py +++ b/src/trade_study/runner.py @@ -14,10 +14,10 @@ from .protocols import ( Annotation, Direction, - ModelWorld, Observable, ResultsTable, Scorer, + Simulator, TrialResult, ) @@ -28,7 +28,7 @@ def _run_single( - world: ModelWorld, + world: Simulator, scorer: Scorer, config: dict[str, Any], ) -> TrialResult: @@ -45,7 +45,7 @@ def _run_single( def run_grid( - world: ModelWorld, + world: Simulator, scorer: Scorer, grid: list[dict[str, Any]], observables: list[Observable], @@ -56,7 +56,7 @@ def run_grid( """Run all configurations in a grid. Args: - world: Model world that generates (truth, observations). + world: Simulator that generates (truth, observations). scorer: Scorer that evaluates observables. grid: List of config dicts to evaluate. observables: Observable definitions (for column ordering). @@ -99,7 +99,7 @@ def run_grid( def run_adaptive( - world: ModelWorld, + world: Simulator, scorer: Scorer, factors: list[Factor], observables: list[Observable], @@ -110,7 +110,7 @@ def run_adaptive( """Run adaptive multi-objective optimization via optuna. Args: - world: Model world. + world: Simulator. scorer: Scorer for observables. factors: Factor definitions (from design module). observables: Observable definitions. diff --git a/src/trade_study/study.py b/src/trade_study/study.py index 78e1ad5..ae614af 100644 --- a/src/trade_study/study.py +++ b/src/trade_study/study.py @@ -22,10 +22,10 @@ from .protocols import ( Annotation, - ModelWorld, Observable, ResultsTable, Scorer, + Simulator, ) @@ -89,7 +89,7 @@ class Study: """Multi-phase model criticism study. Attributes: - world: Model world generating (truth, observations). + world: Simulator generating (truth, observations). scorer: Scorer evaluating observables against truth. observables: Observable definitions. phases: Ordered list of study phases. @@ -97,7 +97,7 @@ class Study: factors: Factor definitions (needed for adaptive mode). """ - world: ModelWorld + world: Simulator scorer: Scorer observables: list[Observable] phases: list[Phase]