dfbench 0.2.0__tar.gz → 0.2.1__tar.gz

{dfbench-0.2.0 → dfbench-0.2.1}/.gitignore

@@ -23,6 +23,7 @@ temp/
 results/
 notebooks/
 .DS_Store
+.github/
 
 # IDE related
 .vscode/

{dfbench-0.2.0 → dfbench-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dfbench
-Version: 0.2.0
+Version: 0.2.1
 Summary: Differometor Benchmark - Optimization algorithms and problem definitions
 Project-URL: Homepage, https://github.com/artificial-scientist-lab/Differometor-Benchmark
 Project-URL: Repository, https://github.com/artificial-scientist-lab/Differometor-Benchmark
@@ -88,11 +88,14 @@ Provides-Extra: torch
 Requires-Dist: torch>=2.9.1; extra == 'torch'
 Description-Content-Type: text/markdown
 
+> [!IMPORTANT]
+> **BETA RELEASE:** This repository is currently in beta. The official competition will start on **July ~7**.
+
 # Differometor Benchmark
 
 A benchmarking framework for optimization algorithms on gravitational-wave detector design problems, built on top of the [Differometor](https://github.com/artificial-scientist-lab/Differometor) simulator.
 
-> **For detailed documentation, see the [Wiki](docs/Home.md).**
+> **For detailed documentation, see the [Wiki](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki).**
 
 ## TL;DR (I want to try my own algorithm)
 
@@ -171,11 +174,11 @@ This adds negligible overhead compared to the objective function itself.
 
 Both constrained problems accept a `power_penalty_fn(value, threshold)` callable to control how power-constraint violations are penalized.  Built-in presets: `squashed_relu_penalty` (default), `relu_penalty`, `zero_penalty`. Feel free to try own ones. The penalty function can also be swapped after construction via `obj.set_penalty_fn(fn)` (before `obj.start_logging()`), which re-traces the objective so the change takes effect. The unconstrained Voyager problems reject this call because they have no power-constraint path.
 
-Constrained problems also expose aux diagnostics. `obj.value_aux(params)` and `obj.vmap_value_aux(batch)` return `(loss, aux)` where `aux` carries the loss decomposition, a physical `is_feasible` flag, per-constraint violations, and the raw per-group power arrays. Enable `save` tokens like `is_feasible`, `power_values`, or the `aux` alias and the standard `obj.value` / `obj.value_and_grad` loop records the enabled aux fields in the same forward pass, with no code change. See [Problems](docs/Problems.md) for the aux schema and [Objective API Reference](docs/Objective-API-Reference.md) for the full method set.
+Constrained problems also expose aux diagnostics. `obj.value_aux(params)` and `obj.vmap_value_aux(batch)` return `(loss, aux)` where `aux` carries the loss decomposition, a physical `is_feasible` flag, per-constraint violations, and the raw per-group power arrays. Enable `save` tokens like `is_feasible`, `power_values`, or the `aux` alias and the standard `obj.value` / `obj.value_and_grad` loop records the enabled aux fields in the same forward pass, with no code change. See [Problems](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Problems) for the aux schema and [Objective API Reference](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Objective-API-Reference) for the full method set.
 
 All problems also support `bounds_overrides` (e.g. `{"tuning": (0, 45)}`) to narrow default property bounds and `signal_floor` to floor detector signal magnitudes before sensitivity normalization. `signal_floor` defaults to `1e-20`. Use `problem.print_bounds()` to inspect effective bounds.
 
-See [Problems](docs/Problems.md) for details on loss computation, parameter meanings, and constraints.
+See [Problems](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Problems) for details on loss computation, parameter meanings, and constraints.
 
 ---
 
@@ -212,7 +215,7 @@ pip install -e .                         # CPU-only editable install
 pip install -e ".[all,cuda13,analysis]"  # All backends, CUDA 13, and analysis extras
 ```
 
-See [Installation](docs/Installation.md) for GPU setup details and HPC notes.
+See [Installation](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Installation) for GPU setup details and HPC notes.
 
 ---
 
@@ -235,7 +238,7 @@ OptimizationAlgorithm.optimize()
 
 **Design Idea:** Algorithms never create their own `Objective`, they receive a pre-configured one. This lets the benchmark harness or user script control budgets, seeds, and history settings uniformly. The algorithm only has to implement its optimization logic.
 
-See [Architecture Overview](docs/Architecture-Overview.md) for full design details.
+See [Architecture Overview](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Architecture-Overview) for full design details.
 
 ---
 
@@ -337,7 +340,7 @@ benchmark.print_summary(results)
 - `save_csv`: Writes a CSV with all metrics computed at evenly-spaced time points.
 - `save_run_data`: Persists raw loss/params/time histories to NPZ files for later re-evaluation.
 
-See [Benchmarking](docs/Benchmarking.md) for full configuration options and [Metrics Reference](docs/Metrics-Reference.md) for what gets computed.
+See [Benchmarking](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Benchmarking) for full configuration options and [Metrics Reference](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Metrics-Reference) for what gets computed.
 
 ### Native-JAX Custom/Hybrid Batch
 
@@ -360,7 +363,7 @@ see `scripts/voyager_native_jax_custom_batch.py`.
 
 The interface is designed to make this as simple as possible. You write the optimization logic; `Objective` handles everything else (timing, logging, budget enforcement, file I/O).
 
-> **Full step-by-step tutorial:** [Implementing a New Algorithm](docs/Implementing-a-New-Algorithm.md)
+> **Full step-by-step tutorial:** [Implementing a New Algorithm](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Implementing-a-New-Algorithm)
 
 ### The Contract
 
@@ -495,7 +498,7 @@ obj.loss_history            # full loss history
 obj.time_steps              # elapsed time at each evaluation
 ```
 
-See [Objective API Reference](docs/Objective-API-Reference.md) for the complete interface.
+See [Objective API Reference](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Objective-API-Reference) for the complete interface.
 
 ---
 
@@ -538,7 +541,7 @@ See [Objective API Reference](docs/Objective-API-Reference.md) for the complete
 | `ReSTIR` | Surrogate | GPU-native kNN surrogate, scales to 100k+ candidates |
 | `VAESampling` | Generative | Latent-space compression + BO |
 
-See [Algorithms](docs/Algorithms.md) for hyperparameter details and usage examples.
+See [Algorithms](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Algorithms) for hyperparameter details and usage examples.
 
 ---
 
@@ -568,13 +571,13 @@ For in-depth documentation beyond this README:
 
 | Page | Content |
 |------|---------|
-| [Architecture Overview](docs/Architecture-Overview.md) | Design, module map, data-flow diagrams |
-| [Objective API Reference](docs/Objective-API-Reference.md) | Complete `Objective` class reference |
-| [Problems](docs/Problems.md) | Loss computation, parameter meanings, constraints |
-| [Algorithms](docs/Algorithms.md) | All built-in algorithms with hyperparameters |
-| [Implementing a New Algorithm](docs/Implementing-a-New-Algorithm.md) | Full step-by-step contributor tutorial |
-| [Benchmarking](docs/Benchmarking.md) | Running benchmarks, saving/loading results |
-| [Metrics Reference](docs/Metrics-Reference.md) | Every benchmark metric explained |
-| [Utilities & Helpers](docs/Utilities-and-Helpers.md) | `t2j`/`j2t`, CLI config, inverse sigmoid |
-| [Installation](docs/Installation.md) | Environment setup, GPU support, HPC notes |
-| [FAQ](docs/FAQ.md) | Common pitfalls and troubleshooting |
+| [Architecture Overview](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Architecture-Overview) | Design, module map, data-flow diagrams |
+| [Objective API Reference](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Objective-API-Reference) | Complete `Objective` class reference |
+| [Problems](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Problems) | Loss computation, parameter meanings, constraints |
+| [Algorithms](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Algorithms) | All built-in algorithms with hyperparameters |
+| [Implementing a New Algorithm](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Implementing-a-New-Algorithm) | Full step-by-step contributor tutorial |
+| [Benchmarking](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Benchmarking) | Running benchmarks, saving/loading results |
+| [Metrics Reference](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Metrics-Reference) | Every benchmark metric explained |
+| [Utilities & Helpers](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Utilities-and-Helpers) | `t2j`/`j2t`, CLI config, inverse sigmoid |
+| [Installation](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Installation) | Environment setup, GPU support, HPC notes |
+| [FAQ](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/FAQ) | Common pitfalls and troubleshooting |

{dfbench-0.2.0 → dfbench-0.2.1}/README.md

@@ -1,8 +1,11 @@
+> [!IMPORTANT]
+> **BETA RELEASE:** This repository is currently in beta. The official competition will start on **July ~7**.
+
 # Differometor Benchmark
 
 A benchmarking framework for optimization algorithms on gravitational-wave detector design problems, built on top of the [Differometor](https://github.com/artificial-scientist-lab/Differometor) simulator.
 
-> **For detailed documentation, see the [Wiki](docs/Home.md).**
+> **For detailed documentation, see the [Wiki](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki).**
 
 ## TL;DR (I want to try my own algorithm)
 
@@ -81,11 +84,11 @@ This adds negligible overhead compared to the objective function itself.
 
 Both constrained problems accept a `power_penalty_fn(value, threshold)` callable to control how power-constraint violations are penalized.  Built-in presets: `squashed_relu_penalty` (default), `relu_penalty`, `zero_penalty`. Feel free to try own ones. The penalty function can also be swapped after construction via `obj.set_penalty_fn(fn)` (before `obj.start_logging()`), which re-traces the objective so the change takes effect. The unconstrained Voyager problems reject this call because they have no power-constraint path.
 
-Constrained problems also expose aux diagnostics. `obj.value_aux(params)` and `obj.vmap_value_aux(batch)` return `(loss, aux)` where `aux` carries the loss decomposition, a physical `is_feasible` flag, per-constraint violations, and the raw per-group power arrays. Enable `save` tokens like `is_feasible`, `power_values`, or the `aux` alias and the standard `obj.value` / `obj.value_and_grad` loop records the enabled aux fields in the same forward pass, with no code change. See [Problems](docs/Problems.md) for the aux schema and [Objective API Reference](docs/Objective-API-Reference.md) for the full method set.
+Constrained problems also expose aux diagnostics. `obj.value_aux(params)` and `obj.vmap_value_aux(batch)` return `(loss, aux)` where `aux` carries the loss decomposition, a physical `is_feasible` flag, per-constraint violations, and the raw per-group power arrays. Enable `save` tokens like `is_feasible`, `power_values`, or the `aux` alias and the standard `obj.value` / `obj.value_and_grad` loop records the enabled aux fields in the same forward pass, with no code change. See [Problems](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Problems) for the aux schema and [Objective API Reference](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Objective-API-Reference) for the full method set.
 
 All problems also support `bounds_overrides` (e.g. `{"tuning": (0, 45)}`) to narrow default property bounds and `signal_floor` to floor detector signal magnitudes before sensitivity normalization. `signal_floor` defaults to `1e-20`. Use `problem.print_bounds()` to inspect effective bounds.
 
-See [Problems](docs/Problems.md) for details on loss computation, parameter meanings, and constraints.
+See [Problems](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Problems) for details on loss computation, parameter meanings, and constraints.
 
 ---
 
@@ -122,7 +125,7 @@ pip install -e .                         # CPU-only editable install
 pip install -e ".[all,cuda13,analysis]"  # All backends, CUDA 13, and analysis extras
 ```
 
-See [Installation](docs/Installation.md) for GPU setup details and HPC notes.
+See [Installation](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Installation) for GPU setup details and HPC notes.
 
 ---
 
@@ -145,7 +148,7 @@ OptimizationAlgorithm.optimize()
 
 **Design Idea:** Algorithms never create their own `Objective`, they receive a pre-configured one. This lets the benchmark harness or user script control budgets, seeds, and history settings uniformly. The algorithm only has to implement its optimization logic.
 
-See [Architecture Overview](docs/Architecture-Overview.md) for full design details.
+See [Architecture Overview](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Architecture-Overview) for full design details.
 
 ---
 
@@ -247,7 +250,7 @@ benchmark.print_summary(results)
 - `save_csv`: Writes a CSV with all metrics computed at evenly-spaced time points.
 - `save_run_data`: Persists raw loss/params/time histories to NPZ files for later re-evaluation.
 
-See [Benchmarking](docs/Benchmarking.md) for full configuration options and [Metrics Reference](docs/Metrics-Reference.md) for what gets computed.
+See [Benchmarking](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Benchmarking) for full configuration options and [Metrics Reference](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Metrics-Reference) for what gets computed.
 
 ### Native-JAX Custom/Hybrid Batch
 
@@ -270,7 +273,7 @@ see `scripts/voyager_native_jax_custom_batch.py`.
 
 The interface is designed to make this as simple as possible. You write the optimization logic; `Objective` handles everything else (timing, logging, budget enforcement, file I/O).
 
-> **Full step-by-step tutorial:** [Implementing a New Algorithm](docs/Implementing-a-New-Algorithm.md)
+> **Full step-by-step tutorial:** [Implementing a New Algorithm](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Implementing-a-New-Algorithm)
 
 ### The Contract
 
@@ -405,7 +408,7 @@ obj.loss_history            # full loss history
 obj.time_steps              # elapsed time at each evaluation
 ```
 
-See [Objective API Reference](docs/Objective-API-Reference.md) for the complete interface.
+See [Objective API Reference](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Objective-API-Reference) for the complete interface.
 
 ---
 
@@ -448,7 +451,7 @@ See [Objective API Reference](docs/Objective-API-Reference.md) for the complete
 | `ReSTIR` | Surrogate | GPU-native kNN surrogate, scales to 100k+ candidates |
 | `VAESampling` | Generative | Latent-space compression + BO |
 
-See [Algorithms](docs/Algorithms.md) for hyperparameter details and usage examples.
+See [Algorithms](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Algorithms) for hyperparameter details and usage examples.
 
 ---
 
@@ -478,13 +481,13 @@ For in-depth documentation beyond this README:
 
 | Page | Content |
 |------|---------|
-| [Architecture Overview](docs/Architecture-Overview.md) | Design, module map, data-flow diagrams |
-| [Objective API Reference](docs/Objective-API-Reference.md) | Complete `Objective` class reference |
-| [Problems](docs/Problems.md) | Loss computation, parameter meanings, constraints |
-| [Algorithms](docs/Algorithms.md) | All built-in algorithms with hyperparameters |
-| [Implementing a New Algorithm](docs/Implementing-a-New-Algorithm.md) | Full step-by-step contributor tutorial |
-| [Benchmarking](docs/Benchmarking.md) | Running benchmarks, saving/loading results |
-| [Metrics Reference](docs/Metrics-Reference.md) | Every benchmark metric explained |
-| [Utilities & Helpers](docs/Utilities-and-Helpers.md) | `t2j`/`j2t`, CLI config, inverse sigmoid |
-| [Installation](docs/Installation.md) | Environment setup, GPU support, HPC notes |
-| [FAQ](docs/FAQ.md) | Common pitfalls and troubleshooting |
+| [Architecture Overview](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Architecture-Overview) | Design, module map, data-flow diagrams |
+| [Objective API Reference](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Objective-API-Reference) | Complete `Objective` class reference |
+| [Problems](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Problems) | Loss computation, parameter meanings, constraints |
+| [Algorithms](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Algorithms) | All built-in algorithms with hyperparameters |
+| [Implementing a New Algorithm](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Implementing-a-New-Algorithm) | Full step-by-step contributor tutorial |
+| [Benchmarking](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Benchmarking) | Running benchmarks, saving/loading results |
+| [Metrics Reference](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Metrics-Reference) | Every benchmark metric explained |
+| [Utilities & Helpers](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Utilities-and-Helpers) | `t2j`/`j2t`, CLI config, inverse sigmoid |
+| [Installation](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/Installation) | Environment setup, GPU support, HPC notes |
+| [FAQ](https://github.com/artificial-scientist-lab/Differometor-Benchmark/wiki/FAQ) | Common pitfalls and troubleshooting |

{dfbench-0.2.0 → dfbench-0.2.1}/docs/Objective-API-Reference.md

@@ -22,6 +22,7 @@ Objective(
     max_time: float | None = None,
     save_time_steps: bool = True,
     save_params_history: bool = True,
+    save_batched_params_history: bool = False,
     save: list[str] | None = None,
     verbose: int = 0,
     print_every: int = 100,
@@ -46,7 +47,8 @@ Objective(
 | `max_time` | `float \| None` | `None` | Maximum wall-clock seconds beginning at the time `obj.start_logging()` was called. `None` = unlimited. |
 | `save_time_steps` | `bool` | `True` | Record elapsed-time timestamp for each evaluation. |
 | `save_params_history` | `bool` | `True` | Record the parameter vector at each evaluation. |
-| `save` | `list[str] \| None` | `None` | List of advanced save tokens for recording additional / batched histories. Standard tokens: `"grad"`, `"hessian"`, `"eval_type"`, `"batched_loss"`, `"batched_grad"`, `"batched_hessian"`, `"batched_param"`, `"batched"` (convenience alias expanding to all four batched tokens). Aux diagnostics tokens (recorded by the `*_aux` evaluation methods on problems that opt into the power-penalty contract): `"sensitivity_loss"`, `"penalty"`, `"is_feasible"`, `"power_values"`, `"violations"`, `"aux"` (convenience alias expanding to all five), plus per-field `batched_*` variants and `"batched_aux"` (see Choosing what to save). The active configuration is recorded as a `SaveConfig` and embedded in every checkpoint so a resumed run can detect mismatches. |
+| `save_batched_params_history` | `bool` | `False` | Store full `(batch, n_params)` parameter arrays for batched evals instead of the reduced representative point. |
+| `save` | `list[str] \| None` | `None` | List of advanced save tokens for recording additional / batched histories. Standard tokens: `"grad"`, `"hessian"`, `"eval_type"`, `"batched_loss"`, `"batched_grad"`, `"batched_hessian"`, `"batched"` (convenience alias expanding to the three batched tokens above). Aux diagnostics tokens (recorded by the `*_aux` evaluation methods on problems that opt into the power-penalty contract): `"sensitivity_loss"`, `"penalty"`, `"is_feasible"`, `"power_values"`, `"violations"`, `"aux"` (convenience alias expanding to all five), plus per-field `batched_*` variants and `"batched_aux"` (see Choosing what to save). The active configuration is recorded as a `SaveConfig` and embedded in every checkpoint so a resumed run can detect mismatches. |
 | `verbose` | `int` | `0` | Verbosity level. `0` = silent; `1` = periodic progress prints; `2` is WIP. |
 | `print_every` | `int` | `100` | When `verbose ≥ 1`, print a progress summary every N evaluations. |
 | `algorithm_str` | `str \| None` | `None` | If `None`, this is set by the algorithm via `prepare()` of `OptimizationAlgorithm`. Optional identifier string used in file names and logs. |
@@ -125,12 +127,13 @@ You do **not** need to handle bounds scaling — the Objective does that automat
 
 ### Choosing what to save
 
-The Objective always records losses. Two standard boolean flags control the most commonly toggled histories:
+The Objective always records losses. Three standard boolean flags control the most commonly toggled histories:
 
 | Flag | Default | Effect |
 |------|---------|--------|
 | `save_time_steps` | `True` | Record elapsed-time timestamps per evaluation |
 | `save_params_history` | `True` | Record parameter vectors (reduced for batches) |
+| `save_batched_params_history` | `False` | Store full `(batch, n_params)` parameter arrays instead of the reduced representative point |
 
 For advanced combinations (gradients, Hessians, eval types, full batched arrays), pass a list of string tokens to `save`:
 
@@ -142,8 +145,7 @@ For advanced combinations (gradients, Hessians, eval types, full batched arrays)
 | `"batched_loss"` | Store full `(batch,)` loss vectors instead of batch min |
 | `"batched_grad"` | Store full `(batch, n_params)` gradient arrays |
 | `"batched_hessian"` | Store full `(batch, n_params, n_params)` Hessian arrays |
-| `"batched_param"` | Store full `(batch, n_params)` parameter arrays |
-| `"batched"` | Convenience alias expanding to all four `batched_*` tokens above |
+| `"batched"` | Convenience alias expanding to the three `batched_*` tokens above |
 
 Aux diagnostics tokens are recorded by the `*_aux` evaluation methods, and also by the standard loss-bearing methods (`value`, `value_and_grad`, `vmap_value`, `vmap_value_and_grad`, `value_grad_and_hessian`, `vmap_value_grad_and_hessian`) when auto-logging is active. Auto-logging turns on when at least one aux token is in the `save` list and the problem opts into the power-penalty contract (`ConstrainedVoyagerProblem`, `UIFOProblem`); the standard methods then run the aux objective in the same forward pass and populate the aux histories without changing their return signatures (see [Auto-logging aux](#auto-logging-aux-from-the-standard-methods)). Each token controls one aux field, so enabling `is_feasible` does not force storing the bulky `power_values` arrays.
 
@@ -544,7 +546,7 @@ Saves the full optimization state to a checkpoint file via the internal `Checkpo
 
 The checkpoint embeds `RunMetadata` (problem/algo/budget identity, `SaveConfig`, and the problem's typed `ProblemSpec` container; see [Problems](Problems)), so the file is fully self-describing.
 
-Default path (built by `RunPathResolver`): `data/objective_run_data/{budget_dir}/{algo}_{hyper_param_str}/{problem}_{algo}_{timestamp}.npz`
+Default path (built by `RunPathResolver`, then anchored to a directory by `LocalFilesystemBackend`): `<checkpoint_dir>/{budget_dir}/{problem}_{algo}_{hyper_param_str}_{timestamp}.npz`, absolute on disk. `checkpoint_dir` defaults to `./data/objective_run_data`. Set `RunPathResolver(algo_directory=True)` to add an `{algo}_{hyper_param_str}` subdirectory under `{budget_dir}`.
 
 The first save without explicit overrides caches the path; subsequent periodic saves overwrite the same file.
 
@@ -603,7 +605,7 @@ Every evaluation method follows the same pipeline internally:
 3. **`_log_evals(params, loss, grad, hessian, time_exceeded)`** — record histories; update `best_loss` / `best_params`; update `improvement_count` / `evals_since_improvement`; check eval budget. Receives `time_exceeded` as an explicit parameter from `_log()` to ensure a consistent time snapshot.
 4. **`_log_to_file()`** — calls `CheckpointManager.tick(eval_count, state_factory)`, which checks the cadence (`save_every`, set from `save_to_file_every`), lazily builds a `RunState` only when a checkpoint is due, saves it through the internal `StorageBackend`, and returns the wall-clock duration of the save. The Objective advances `_start_time` by that duration so the checkpoint write does not consume wall-clock budget.
 
-> **Important:** These are private methods — do not call `_log()`, `_log_evals()`, or `_log_to_file()` directly from algorithm code. If you want manual logging, use the public `log_evaluation(params, loss, grad, hessian=None)` method instead, which delegates to `_log()`. See the [JIT-compiled loop guide](Implementing-a-New-Algorithm.md#custom-jit-compiled-loops-with-log_evaluation) for details.
+> **Important:** These are private methods — do not call `_log()`, `_log_evals()`, or `_log_to_file()` directly from algorithm code. If you want manual logging, use the public `log_evaluation(params, loss, grad, hessian=None)` method instead, which delegates to `_log()`. See the [JIT-compiled loop guide](Implementing-a-New-Algorithm#custom-jit-compiled-loops-with-log_evaluation) for details.
 
 Budget enforcement happens *after* the evaluation returns. This means the algorithm always receives a valid result, but once any budget is exceeded the history stops growing and `budget_exceeded` becomes `True`.
 

{dfbench-0.2.0 → dfbench-0.2.1}/docs/Problems.md

@@ -224,12 +224,12 @@ The constrained problems also expose a JIT-compiled `objective_function_aux(para
 | `sensitivity_loss` | scalar | The unpenalised sensitivity loss. |
 | `penalty` | scalar | The summed penalty contribution. |
 | `is_feasible` | scalar bool | `True` iff every per-group power is at or below its threshold. This is a physical check, independent of the active `power_penalty_fn` preset, so it stays meaningful even when the penalty is disabled with `zero_penalty`. |
-| `violations` | `(n_constraints, n_freq)` | Per-constraint penalty values. |
+| `violations` | `(n_constraints,)` | Per-constraint penalty values. |
 | `power_values` | dict with `hard`, `soft`, `detector` leaves | Raw per-group power arrays. |
 
 Because `aux` is a JAX pytree, `objective_function_aux` vmapps cleanly: a batched call adds a leading batch dim to every leaf, including the `power_values` sub-arrays.
 
-The `Objective` wraps this with `value_aux`, `value_and_grad_aux`, `vmap_value_aux`, and `vmap_value_and_grad_aux`. These thread aux through logging and the save-token system: each aux field has its own token (`sensitivity_loss`, `penalty`, `is_feasible`, `power_values`, `violations`) plus a `batched_*` variant and `aux` / `batched_aux` convenience aliases. When a `batched_*` token is off and the non-batched token is on, batched aux entries are reduced to the representative point picked by the loss minimum, so the recorded `is_feasible` and `violations` reflect that best point. `Objective.best_is_feasible` reports the feasibility of the best-loss point from that recorded history. Full reference in the [Objective API Reference](Objective-API-Reference.md).
+The `Objective` wraps this with `value_aux`, `value_and_grad_aux`, `vmap_value_aux`, and `vmap_value_and_grad_aux`. These thread aux through logging and the save-token system: each aux field has its own token (`sensitivity_loss`, `penalty`, `is_feasible`, `power_values`, `violations`) plus a `batched_*` variant and `aux` / `batched_aux` convenience aliases. When a `batched_*` token is off and the non-batched token is on, batched aux entries are reduced to the representative point picked by the loss minimum, so the recorded `is_feasible` and `violations` reflect that best point. `Objective.best_is_feasible` reports the feasibility of the best-loss point from that recorded history. Full reference in the [Objective API Reference](Objective-API-Reference).
 
 ---
 

{dfbench-0.2.0 → dfbench-0.2.1}/docs/Storage-and-Checkpointing.md

@@ -154,7 +154,7 @@ manager = CheckpointManager(serializer=JsonCheckpointSerializer())
 
 ## Storage Backends
 
-A `StorageBackend` is a small protocol (`save_bytes` / `load_bytes` / `exists` / `delete`). Keeping it this narrow means the local filesystem can be swapped for memory, S3, or any other target without touching the serializers or the `CheckpointManager`.
+A `StorageBackend` is a small protocol (`save_bytes` / `load_bytes` / `exists` / `delete` / `resolve`). Keeping it this narrow means the local filesystem can be swapped for memory, S3, or any other target without touching the serializers or the `CheckpointManager`.
 
 ### `LocalFilesystemBackend` (default)
 
@@ -172,27 +172,50 @@ backend = LocalFilesystemBackend(root="./data/objective_run_data")
 
 **Why atomic writes:** HPC jobs get killed without warning, and a half-written checkpoint is worse than no checkpoint. The temp-then-replace pattern guarantees a reader always sees either the previous complete file or the new complete file, never a partial one.
 
+`resolve(key)` returns the absolute on-disk path where `key` lives. `CheckpointManager.save` uses it to hand callers back a path they can `exists()` / `open()` directly.
+
 ---
 
 ## `RunPathResolver`: structured path construction
 
-`RunPathResolver` builds filesystem paths from semantic components, so no `./data/...` string is hardcoded inside `Objective`. The root directory is configurable, letting users redirect all artifacts without editing library code.
+`RunPathResolver` builds relative paths from semantic components, so no `./data/...` string is hardcoded inside `Objective`. The storage root (a directory on disk, an S3 prefix, etc.) exists on the `StorageBackend`, not the resolver; the resolver just gives relative paths that the backend joins onto its root.
+
+Default path layout (flat inside the budget directory):
+
+```
+{budget_dir}/{problem}_{algo}_{hyper_param_str}_{timestamp}.{ext}
+```
 
-Saving layout:
+Set `algo_directory=True` to insert an `{algo}_{hyper_param_str}` segment after `{budget_dir}` (collapsing to just `{algo}` when `hyper_param_str` is empty/None):
 
 ```
-{root}/{budget_dir}/{algo}_{hyper_param_str}/{problem}_{algo}_{timestamp}.{ext}
+{budget_dir}/{algo}_{hyper_param_str}/{problem}_{algo}_{hyper_param_str}_{timestamp}.{ext}
 ```
 
-where `budget_dir` is e.g. `time100s_evals1000` or `unlimited`. When
-`hyper_param_str` is empty/None the directory segment collapses to just
-`.../{algo}/...`.
+`budget_dir` is e.g. `time100s_evals1000` or `unlimited`. The algorithm and hyperparameter string are always part of the filename, so a file is self-describing even when copied out of its directory.
 
 ```python
-from dfbench.core.storage import RunPathResolver
+from dfbench.core.storage import RunPathResolver, LocalFilesystemBackend
+
+resolver = RunPathResolver(extension="npz")  # flat default
+key = resolver.checkpoint_path(
+    problem_name="voyager",
+    algorithm_name="adam_gd",
+    timestamp="2026-01-01_00-00-00",
+    hyper_param_str="lr0.1",
+    max_time=100.0,
+    max_evals=1000,
+)
+# -> time100s_evals1000/voyager_adam_gd_lr0.1_2026-01-01_00-00-00.npz
+
+# The backend joins the key onto its root:
+backend = LocalFilesystemBackend(root="./data/objective_run_data")
+on_disk = backend.resolve(key)
+# -> /cwd/data/objective_run_data/time100s_evals1000/voyager_adam_gd_lr0.1_2026-01-01_00-00-00.npz
 
-resolver = RunPathResolver(root="./data/objective_run_data", extension="npz")
-path = resolver.checkpoint_path(
+# Opt into the per-algorithm subdirectory layout:
+resolver = RunPathResolver(extension="npz", algo_directory=True)
+key = resolver.checkpoint_path(
     problem_name="voyager",
     algorithm_name="adam_gd",
     timestamp="2026-01-01_00-00-00",
@@ -200,7 +223,7 @@ path = resolver.checkpoint_path(
     max_time=100.0,
     max_evals=1000,
 )
-# → ./data/objective_run_data/time100s_evals1000/adam_gd_lr0.1/voyager_adam_gd_2026-01-01_00-00-00.npz
+# -> time100s_evals1000/adam_gd_lr0.1/voyager_adam_gd_lr0.1_2026-01-01_00-00-00.npz
 ```
 
 ---
@@ -241,12 +264,13 @@ from dfbench.core.storage import CheckpointManager, LocalFilesystemBackend, NpzC
 manager = CheckpointManager(
     backend=LocalFilesystemBackend(root="./data/objective_run_data"),
     serializer=NpzCheckpointSerializer(),
-    resolver=RunPathResolver(root="./data/objective_run_data"),
+    resolver=RunPathResolver(),
     save_every=1000,
 )
 
 # Save
 path = manager.save(state)
+# `path` is the absolute on-disk Path (backend.resolve(key)); `manager.load(path)` round-trips.
 
 # Load
 state = manager.load(path)

{dfbench-0.2.0 → dfbench-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dfbench"
-version = "0.2.0"
+version = "0.2.1"
 description = "Differometor Benchmark - Optimization algorithms and problem definitions"
 readme = "README.md"
 requires-python = ">=3.11,<3.14"

{dfbench-0.2.0 → dfbench-0.2.1}/src/dfbench/algorithms/surrogate_based/botorch/botorch_bo.py

@@ -136,7 +136,10 @@ class BotorchBO(OptimizationAlgorithm):
 
         # Evaluate initial samples
         train_Y_raw, valid_mask = evaluate_y(
-            X=train_X, bounds=problem_bounds_torch, obj=obj
+            X=train_X,
+            bounds=problem_bounds_torch,
+            obj=obj,
+            batch_size=self.batch_size,
         )
         train_Y_raw = train_Y_raw.unsqueeze(-1)
 
@@ -192,7 +195,10 @@ class BotorchBO(OptimizationAlgorithm):
 
             # Evaluate candidates
             new_Y_raw, valid_mask_batch = evaluate_y(
-                candidates, problem_bounds_torch, obj
+                candidates,
+                problem_bounds_torch,
+                obj,
+                batch_size=self.batch_size,
             )
             new_Y_raw = new_Y_raw.unsqueeze(-1)
 

{dfbench-0.2.0 → dfbench-0.2.1}/src/dfbench/algorithms/surrogate_based/botorch/botorch_turbo.py

@@ -286,7 +286,10 @@ class BotorchTuRBO(OptimizationAlgorithm):
                 train_X = torch.cat([init_X, train_X], dim=0)
 
             train_Y_raw, valid_mask = evaluate_y(
-                X=train_X, bounds=problem_bounds_torch, obj=obj
+                X=train_X,
+                bounds=problem_bounds_torch,
+                obj=obj,
+                batch_size=self.batch_size,
             )
             train_Y_raw = train_Y_raw.unsqueeze(-1)
 
@@ -342,7 +345,10 @@ class BotorchTuRBO(OptimizationAlgorithm):
 
                 # Evaluate new candidates
                 Y_next_raw, valid_mask_next = evaluate_y(
-                    X_next, problem_bounds_torch, obj
+                    X=X_next,
+                    bounds=problem_bounds_torch,
+                    obj=obj,
+                    batch_size=self.batch_size,
                 )
                 Y_next_raw = Y_next_raw.unsqueeze(-1)
 

{dfbench-0.2.0 → dfbench-0.2.1}/src/dfbench/core/objective.py

@@ -49,8 +49,8 @@ class Objective:
 
     3. **History tracking** – maintains aligned histories of losses, params,
        gradients, evaluation types, and elapsed time.  The ``save`` list of
-       string tokens (plus the two standard flags ``save_time_steps`` and
-       ``save_params_history``) controls what is stored; the active
+       string tokens (plus the three standard flags ``save_time_steps``,
+       ``save_params_history``, and ``save_batched_params_history``) controls what is stored; the active
        configuration is recorded as a :class:`SaveConfig` and embedded in
        every checkpoint so a resumed run can detect mismatches.
 
@@ -217,6 +217,7 @@ class Objective:
         max_time: float | None = None,
         save_time_steps: bool = True,
         save_params_history: bool = True,
+        save_batched_params_history: bool = False,
         save: list[str] | None = None,
         verbose: int = 0,
         print_every: int = 100,
@@ -239,11 +240,14 @@ class Objective:
             max_time: Maximum wall-clock time in seconds. None for unlimited.
             save_time_steps: Whether to track timestamps for each evaluation.
             save_params_history: Whether to save parameter history.
+            save_batched_params_history: Whether to store full ``(batch, n_params)``
+                parameter arrays for batched evals instead of the reduced
+                representative point. Defaults to False.
             save: List of advanced save tokens for recording additional /
                 batched histories. Valid tokens: ``"grad"``, ``"hessian"``,
                 ``"eval_type"``, ``"batched_loss"``, ``"batched_grad"``,
-                ``"batched_hessian"``, ``"batched_param"``, ``"batched"``
-                (convenience alias expanding to all four batched tokens).
+                ``"batched_hessian"``, ``"batched"``
+                (convenience alias expanding to the three batched tokens above).
                 Defaults to ``None`` (no advanced histories).
             verbose: Verbosity level (0=silent, 1=warnings, 2=info). Defaults to 0.
             print_every: Print progress every N evaluations (if verbose >= 1). Defaults to 100.
@@ -256,7 +260,7 @@ class Objective:
                 dashboard with progress bars.  ``"log"`` prints traditional
                 multi-line log blocks that scroll the terminal.
             unit_mapping: Optional function that maps unbounded
-                parameters to the **[0, 1] range** (unit interval).  Can be a
+                parameters to the [0, 1] range (unit interval).  Can be a
                 scalar function (e.g. ``jax.nn.sigmoid``) or a vector function
                 operating element-wise on arrays — both work because JAX
                 broadcasts element-wise operations.  The Objective handles
@@ -300,6 +304,7 @@ class Objective:
         self._save_config = SaveConfig.from_flags(
             save_time_steps=save_time_steps,
             save_params_history=save_params_history,
+            save_batched_params_history=save_batched_params_history,
             save=save,
         )
         self._display_mode = display_mode
@@ -412,11 +417,12 @@ class Objective:
     ) -> None:
         """Assemble the storage stack from user-facing knobs.
 
-        Maps ``checkpoint_format`` to a serializer, roots the resolver and
-        backend at ``checkpoint_dir`` (defaulting to the historical
+        Maps ``checkpoint_format`` to a serializer, anchors the backend
+        at ``checkpoint_dir`` (defaulting to the historical
         ``./data/objective_run_data``), and wires the
-        :class:`CheckpointManager`. Subclasses override this to swap a custom
-        serializer / backend / resolver / exporter.
+        :class:`CheckpointManager`. The resolver just builds relative
+        paths; the backend the root. Subclasses override this to
+        swap a custom serializer / backend / resolver / exporter.
         """
         fmt = checkpoint_format.lower()
         if fmt not in self._SERIALIZERS:
@@ -427,14 +433,14 @@ class Objective:
         self._checkpoint_format = fmt
         self._checkpoint_dir = checkpoint_dir
         self._serializer = self._SERIALIZERS[fmt]
-        self._resolver = RunPathResolver(
+        self._resolver = RunPathResolver()
+        self._backend = LocalFilesystemBackend(
             root=(
                 str(checkpoint_dir)
                 if checkpoint_dir is not None
                 else "./data/objective_run_data"
             )
         )
-        self._backend = LocalFilesystemBackend(root=self._resolver.root)
         self._exporter = RunDataExporter()
         self._checkpoint_manager = CheckpointManager(
             backend=self._backend,
@@ -1535,10 +1541,11 @@ class Objective:
         custom_path: str | None = None,
         hyper_param_str: str | None = None,
     ) -> Path:
-        """Generate run data file path via the configured path resolver.
+        """Generate the run data file path via the resolver + backend.
 
-        Delegates to :class:`~dfbench.core.storage.RunPathResolver` so the
-        path layout is not hardcoded here.
+        Asks :class:`~dfbench.core.storage.RunPathResolver` for the
+        relative path, then :meth:`StorageBackend.resolve` for the
+        absolute on-disk path, so the layout is not hardcoded here.
 
         Args:
             algorithm_name: Name of the optimization algorithm.
@@ -1548,7 +1555,7 @@ class Objective:
                 organization.
 
         Returns:
-            Path object for the run data file.
+            Absolute :class:`~pathlib.Path` for the run data file.
         """
         if custom_path is not None:
             return Path(custom_path)
@@ -1556,7 +1563,7 @@ class Objective:
         problem_name = (
             self._problem.name if hasattr(self._problem, "name") else "problem"
         )
-        path = self._resolver.checkpoint_path(
+        key = self._resolver.checkpoint_path(
             problem_name=problem_name,
             algorithm_name=algorithm_name,
             timestamp=self._timestamp,
@@ -1564,7 +1571,7 @@ class Objective:
             max_time=self._max_time,
             max_evals=self._max_evals,
         )
-        return path
+        return Path(self._backend.resolve(key))
 
     def __repr__(self) -> str:
         """String representation for debugging."""
@@ -2742,10 +2749,12 @@ class Objective:
             Path to the saved run data file.
 
         Example:
-            >>> obj.save_run_data(algorithm_name="adam_gd")
-            Path('data/objective_run_data/time100s_evals1000/voyager_adam_gd_2026-01-26_15-30-45.npz')
-            >>> obj.save_run_data(algorithm_name="adam_gd", hyper_param_str="lr0.1")
-            Path('data/objective_run_data/time100s_evals1000/lr0.1/voyager_adam_gd_2026-01-26_15-30-45.npz')
+            >>> path = obj.save_run_data(algorithm_name="adam_gd")
+            >>> path = obj.save_run_data(algorithm_name="adam_gd", hyper_param_str="lr0.1")
+
+        The returned path is absolute (the backend joins the resolver's
+        relative path onto ``checkpoint_dir``). Pass it to
+        ``load_run_data`` to resume.
         """
         if algorithm_name is None:
             algorithm_name = self.algorithm_str or "unknown"
@@ -2782,8 +2791,9 @@ class Objective:
             FileNotFoundError: If run data file doesn't exist.
 
         Example:
-            >>> obj.load_run_data("data/objective_run_data/.../voyager_adam_gd_2026-01-26_15-30-45.npz")
-            >>> obj.warmup_value_and_grad()   # OK — logging not yet active
+            >>> path = obj.save_run_data(algorithm_name="adam_gd")
+            >>> obj.load_run_data(path)
+            >>> obj.warmup_value_and_grad()   # OK, logging not yet active
             >>> obj.start_logging()           # resume wall-clock timer
             >>> print(f"Resuming from {obj.eval_count} evaluations")
         """