ADR Suggestion Sampler factory structure

[rozyczko]

Context

PR #257 adds Bayesian MCMC sampling (resume/extend of BUMPS DREAM chains). The sampling entry point is a single Sampler class that binds one (x, y, weights) dataset to a configured Fitter and drives BUMPS' DREAM sampler through Bumps.mcmc_sample.

Backend selection today is inside Sampler._run: it checks that the
active minimizer's package == 'bumps' and raises otherwise. That check is documented (in the Sampler class and _run docstrings) as the seam where a second backend would plug in.

The wider fitting subsystem already has an established shape for "one abstract capability, several interchangeable backends":

• Enum registry — AvailableMinimizers
  (an Enum of a package/method/enum_id dataclass), gated by *_engine_available import probes, plus a from_string_to_enum helper.
• Abstract base — MinimizerBase
  (ABCMeta, with a package class attribute and @abstractmethods like fit, convert_to_pars_obj, supported_methods).
• Concrete backends — LMFit, Bumps, DFO, one file each under minimizers/.
• Factory — factory() dispatching on minimizer_enum.package to construct the right backend.

The review of PR #257 raised the question of whether the sampler should adopt this same structure.
We can:

1. Mirror the minimizer structure now. Copying the factory/enum/base-class layout makes the codebase uniform: reviewers meet the same shape everywhere, the extension point is explicit rather than an if package == 'bumps' guard, and adding a backend is a well-worn path.
2. Defer until a second backend exists. There is exactly one sampler (DREAM) and one backend (BUMPS). A factory + enum + base class for a single implementation is speculative generality: the abstraction would be guessed from one case rather than derived from two. The _run BUMPS check is already the documented seam, so nothing is lost by waiting.

This ADR exists to record that decision and, if/when we build the abstraction, to fix its target shape so it lands consistently.

Decision proposal

Defer the factory/enum/base-class structure until a second sampler backend is actually implemented, but commit now to the target shape below so the eventual refactor is mechanical rather than a fresh design.

Concretely:

1. Now (this PR / near term): keep the single Sampler class and the package == 'bumps' guard in _run as the backend seam. Do not introduce AvailableSamplers, a SamplerBase ABC, or a sampler factory() for one backend.

2. Trigger: the first concrete proposal for a second MCMC backend (e.g. an emcee affine-invariant sampler, or a second BUMPS algorithm exposed as a distinct sampler). At that point, extract the abstraction from the two real cases in the same PR that adds the second backend.

3. Target shape (when the trigger fires) — mirror the minimizer subsystem:

   • AvailableSamplers enum in fitting/available_samplers.py, entries gated by *_engine_available probes, carrying at least package (and a stable enum_id if we want parity with the minimizer registry), plus a from_string_to_enum helper.
   • SamplerBase ABC in fitting/samplers/sampler_base.py with a package class attribute and @abstractmethods for the backend-specific surface (sample, extend, save, load_state, and the state/results accessors). The persistence sidecar contract (save_chain/load_chain, _SIDECAR_SCHEMA_VERSION) and the SamplingResults dataclass stay backend-agnostic and shared.
   • Concrete backends one file each under fitting/samplers/ (e.g. sampler_dream.py), each declaring its package.
   • factory(sampler_enum, fitter, ...) dispatching on sampler_enum.package, replacing the inline package == 'bumps' guard in _run.

   The current Sampler becomes either the SamplerBase subclass for the DREAM/BUMPS backend or a thin data-binding orchestrator that delegates to a factory-constructed backend — decided when the second backend clarifies which responsibilities are genuinely shared.

Alternatives considered

• Build the full factory/enum/base-class stack now (option 1 above).
  Rejected as premature: maximises uniformity but pays indirection for a single backend and risks encoding a one-case guess as the interface. Reconsider immediately if a second backend is already on the near-term roadmap rather than hypothetical.
• Do nothing and never formalise the seam. Rejected: leaves the extension point as an undocumented convention and invites divergence from the minimizer structure. Recording the target shape now is the cheap insurance.

[rozyczko]

Proposed initial implementation

fitting/
├── engine_base.py 
├── fitter.py   
├── multi_fitter.py
├── sampler.py   
├── samplers/
│   ├── __init__.py 
│   └── sampler_dream.py      NEW  DreamSampler(EngineBase)  DREAM run, resume
│                                  validation, ring-buffer/population recovery
└── minimizers/
    ├── minimizer_base.py
    ├── minimizer_bumps.py 
    ├── minimizer_lmfit.py 
    ├── minimizer_dfo.py 
    └── bumps_utils/               shared BUMPS helpers (used by Bumps AND DreamSampler)
        ├── eval_counter.py 
        ├── progress_monitor.py
        ├── problem.py        NEW  build_curve_problem(engine, x, y, weights, ...)
        └── validation.py     NEW  validate_arrays(x, y, weights, *, check_finite_xy)

[rozyczko]

Data flow after the refactor:

Sampler._run()
  ├─ check bumps_engine_available (import probe: NOT the active minimizer)
  ├─ fitter._precompute_reshaping(...)          (MultiFitter-aware; unchanged)
  ├─ wrapped = fitter._fit_function_wrapper(x_new, flatten=True)
  ├─ engine = DreamSampler(obj=fitter.fit_object, fit_function=wrapped)
  └─ engine.run(x=x_fit, y=y_new, weights=w_new, samples=, burn=, thin=,
                population=, resume_state=, sampler_kwargs=,
                progress_callback=, abort_test=)