quantred 2.4.0__py3-none-any.whl

quantred/optimization/parallel.py

@@ -0,0 +1,345 @@
+"""Concurrent trial execution: workers evaluate, the parent records.
+
+Candidate evaluation is embarrassingly parallel — each candidate is an independent
+backtest over the same read-only bars — and the machines this runs on have cores to
+spare. What made parallelism dangerous was never the compute; it was that the trial
+store is built on a **single-writer** assumption: one process appends the journal,
+one process updates the index, and memoization assumes there are no in-flight
+duplicates. Parallelism done naively breaks the store's core promise (an accurate,
+deduplicated campaign trial count) in exactly the silent way this project fights.
+
+The resolution is that the framework already separates *execution* from *recording*.
+Workers never write anything: they receive a fully-described candidate, run it, and
+return numbers. The parent alone journals, updates the index, and answers
+memoization lookups. **Concurrency of execution does not require concurrency of
+journaling**, so nothing about storage changes — no schema, no locking, no
+interleaved journal.
+
+Three properties this module exists to preserve, in order of importance:
+
+1. **The campaign trial count stays exact.** In-flight dedup means a candidate
+   already dispatched is never dispatched twice, and a crashed candidate is still a
+   candidate that was tried. A search that runs faster but miscounts trials is a net
+   loss — it corrupts the deflated Sharpe silently, at scale.
+2. **Results do not depend on scheduling.** Each candidate's seed derives from its
+   own identity, not from dispatch order, and results are returned in submission
+   order regardless of completion order. A parallel run and a sequential run of the
+   same search produce the same set of trials and the same winner.
+3. **Nothing is shared mutably.** Workers build their own strategy, engine, and data
+   client from a picklable description. There are no live clients crossing the
+   process boundary, which is also what makes this work under spawn (macOS,
+   Windows) rather than only under fork.
+"""
+
+import concurrent.futures as futures
+import hashlib
+import json
+import logging
+import os
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any, Callable, Dict, List, Optional, Sequence, Tuple
+
+logger = logging.getLogger(__name__)
+
+#: Conservative by default. Each worker holds its own copy of the bar frames, so
+#: memory scales with workers x per-worker footprint — a wide universe times many
+#: workers can dwarf the sequential run. Raising this is a deliberate act.
+DEFAULT_MAX_WORKERS = 4
+
+
+def resolve_workers(requested: Optional[int]) -> int:
+    """How many workers to actually use.
+
+    ``None`` or anything below 2 means sequential — and sequential is not "a pool of
+    one", it is the original code path, byte for byte. Nobody should pay pickling and
+    process-spawn costs to run one thing at a time.
+    """
+    if not requested or requested < 2:
+        return 1
+    cores = os.cpu_count() or 1
+    return max(1, min(int(requested), cores))
+
+
+# --------------------------------------------------------------------------- #
+# Picklable descriptions (nothing live crosses the process boundary)
+# --------------------------------------------------------------------------- #
+@dataclass(frozen=True)
+class DataSpec:
+    """A recipe for building a data client, rather than a client itself.
+
+    A live market-data client holds sockets and vendor SDK objects and cannot be
+    pickled to a spawned process. Passing the *recipe* keeps workers independent and
+    keeps this module free of any vendor import.
+
+    ``kind="synthetic"`` builds the deterministic keyless feed — the same one the
+    offline demo uses — which makes a genuinely parallel run reproducible with no
+    network and no credentials.
+    """
+
+    kind: str = "cache"
+    seed: int = 42
+    cache_dir: Optional[str] = None
+    offline: bool = False
+
+    def build(self):
+        """Construct this worker's own data client."""
+        from quantred.marketdata.client import MarketDataClient
+
+        if self.kind == "synthetic":
+            from quantred.marketdata.synthetic import SyntheticMarketData
+
+            return MarketDataClient(SyntheticMarketData(seed=self.seed))
+
+        from quantred.services.data import build_data_client
+
+        # Cache-first: the parent warmed the ranges before dispatch, so workers read
+        # local Parquet instead of N processes stampeding the vendor API.
+        return build_data_client(cache=True, offline=self.offline, cache_dir=self.cache_dir)
+
+
+@dataclass(frozen=True)
+class EvalRequest:
+    """One candidate, described completely enough to run anywhere.
+
+    ``key`` is the candidate's dedup identity. It does triple duty: it is what
+    in-flight dedup compares, what the per-candidate seed derives from, and the
+    tie-breaker that makes ranking a total order. All three have to agree, so there
+    is one field rather than three.
+    """
+
+    key: str
+    strategy: str
+    params: Dict[str, Any]
+    symbols: Tuple[str, ...]
+    start: datetime
+    end: datetime
+    capital: float = 100_000.0
+    cost: Optional[Dict[str, Any]] = None
+    data: DataSpec = field(default_factory=DataSpec)
+    base_seed: int = 42
+    #: The book each candidate is evaluated at. Not a tunable param, so a worker that
+    #: built the strategy from ``params`` alone evaluated the class default instead.
+    position_limits: Optional[Dict[str, Any]] = None
+
+    @property
+    def seed(self) -> int:
+        """This candidate's seed, derived from its identity and never from its
+        position in the queue — so the same candidate simulates identically whether
+        it ran first, last, or in the sequential path."""
+        digest = hashlib.sha256(f"{self.base_seed}:{self.key}".encode()).hexdigest()
+        return int(digest[:8], 16)
+
+
+def candidate_key(strategy: str, params: Dict[str, Any], symbols: Sequence[str], start, end) -> str:
+    """The stable identity of one candidate.
+
+    Deliberately reuses the trial store's own hashing, so "the same candidate" means
+    exactly what it means everywhere else — dedup, memoization, and the campaign
+    count. A second definition here would eventually disagree with the store, and
+    the disagreement would show up as a miscounted campaign rather than an error.
+    """
+    from quantred.store.trials import params_hash, universe_hash
+
+    window = f"{_iso(start)}|{_iso(end)}"
+    return f"{strategy}|{universe_hash(symbols)}|{params_hash(params)}|{window}"
+
+
+def _iso(value: Any) -> str:
+    iso = getattr(value, "isoformat", None)
+    return iso() if callable(iso) else str(value)
+
+
+# --------------------------------------------------------------------------- #
+# The worker side
+# --------------------------------------------------------------------------- #
+def evaluate(request: EvalRequest) -> Dict[str, Any]:
+    """Run one candidate and return its numbers. Top-level and picklable by design.
+
+    This is the entire worker contract. It constructs its own strategy, cost model,
+    data client, and engine; it never touches the journal, the trial-store index, or
+    stdout. A failure is *returned*, not raised: one candidate that cannot run must
+    not take the campaign with it, and a crashed candidate is still a configuration
+    that was tried.
+    """
+    try:
+        from quantred.engine.backtest import BacktestEngine
+        from quantred.services.registry import resolve_strategy_class
+        from quantred.strategies.base import build_with_limits
+
+        strategy = build_with_limits(
+            resolve_strategy_class(request.strategy), dict(request.params), request.position_limits
+        )
+        result = BacktestEngine(
+            strategy,
+            request.data.build(),
+            cost_model=_build_cost_model(request.cost),
+        ).run(list(request.symbols), request.start, request.end, request.capital)
+        return {
+            "key": request.key,
+            "params": dict(request.params),
+            "metrics": dict(result.metrics),
+            "error": None,
+        }
+    except Exception as exc:  # noqa: BLE001 - a worker failure is data, not a crash
+        return {
+            "key": request.key,
+            "params": dict(request.params),
+            "metrics": {},
+            "error": f"{type(exc).__name__}: {exc}",
+        }
+
+
+def _build_cost_model(spec: Optional[Dict[str, Any]]):
+    """A cost model from its picklable kwargs; ``None`` means a gross run."""
+    if spec is None:
+        return None
+    from quantred.costs import ParametricCostModel
+
+    return ParametricCostModel(**spec)
+
+
+def cost_spec(cost_model) -> Optional[Dict[str, Any]]:
+    """A live cost model as the kwargs a worker rebuilds it from.
+
+    Reads the model's own attributes back out rather than asking callers to pass the
+    construction arguments twice — two descriptions of one cost model would drift,
+    and the drift would show up as a parallel run pricing trades differently from
+    the sequential one.
+    """
+    if cost_model is None:
+        return None
+    return {
+        "commission_bps": getattr(cost_model, "commission_rate", 0.0) * 1e4,
+        "default_spread_bps": getattr(cost_model, "default_spread", 0.0) * 1e4,
+        "impact_eta": getattr(cost_model, "impact_eta", 0.3),
+        "participation_cap": getattr(cost_model, "participation_cap", 0.10),
+        "annual_borrow_bps": getattr(cost_model, "annual_borrow_rate", 0.0) * 1e4,
+        "linear_impact": bool(getattr(cost_model, "linear_impact", False)),
+    }
+
+
+# --------------------------------------------------------------------------- #
+# The parent side
+# --------------------------------------------------------------------------- #
+@dataclass
+class PoolReport:
+    """What a dispatch produced, including what it deliberately did not run."""
+
+    results: List[Dict[str, Any]] = field(default_factory=list)
+    duplicates: int = 0
+    failures: int = 0
+    interrupted: bool = False
+
+    @property
+    def completed(self) -> int:
+        return len(self.results)
+
+
+def run_pool(
+    requests: Sequence[EvalRequest],
+    workers: int,
+    *,
+    on_result: Optional[Callable[[Dict[str, Any]], None]] = None,
+) -> PoolReport:
+    """Evaluate ``requests`` across a process pool; return results in **submission
+    order**.
+
+    Submission order, not completion order, is the point: it makes downstream
+    aggregation independent of how the scheduler happened to interleave the work.
+    Combined with per-candidate seeds derived from identity, that is what lets a
+    parallel run and a sequential run produce the same answer.
+
+    Duplicates are dropped before dispatch rather than deduplicated afterwards. Two
+    identical candidates are one trial — running both would inflate the campaign's
+    multiple-testing total with work that produced no new information, which is the
+    exact accounting the trial store exists to keep honest.
+
+    Ctrl-C cancels what has not started, keeps what has already finished (that
+    compute was really spent), and reports the run as partial rather than pretending
+    it completed.
+    """
+    unique: List[EvalRequest] = []
+    seen: Dict[str, int] = {}
+    duplicates = 0
+    for request in requests:
+        if request.key in seen:
+            duplicates += 1
+            continue
+        seen[request.key] = len(unique)
+        unique.append(request)
+
+    report = PoolReport(duplicates=duplicates)
+    if not unique:
+        return report
+
+    ordered: List[Optional[Dict[str, Any]]] = [None] * len(unique)
+    try:
+        with futures.ProcessPoolExecutor(max_workers=workers) as pool:
+            pending = {pool.submit(evaluate, request): i for i, request in enumerate(unique)}
+            try:
+                for future in futures.as_completed(pending):
+                    index = pending[future]
+                    ordered[index] = future.result()
+                    if on_result is not None:
+                        # Progress printing happens HERE, in the parent. Workers never
+                        # write to stdout, so N workers' chatter cannot interleave.
+                        on_result(ordered[index])
+            except KeyboardInterrupt:
+                report.interrupted = True
+                for future in pending:
+                    future.cancel()
+                logger.warning("Interrupted; keeping %d completed evaluation(s)", _count(ordered))
+    except KeyboardInterrupt:  # raised while the pool is shutting down
+        report.interrupted = True
+
+    report.results = [row for row in ordered if row is not None]
+    report.failures = sum(1 for row in report.results if row.get("error"))
+    return report
+
+
+def _count(rows: Sequence[Optional[Dict[str, Any]]]) -> int:
+    return sum(1 for row in rows if row is not None)
+
+
+def warm_for(data_spec: DataSpec, symbols: Sequence[str], timeframe: str, start, end) -> None:
+    """Pre-warm the bar cache over the union of what the workers will read.
+
+    Done once, in the parent, before any dispatch. Without it, N workers hitting a
+    cold cache stampede the vendor API for the same ranges simultaneously — N times
+    the requests, N times the rate-limit exposure, for one range of bars. A failure
+    here is logged and swallowed: warming is an optimization, and a worker that has
+    to fetch its own bars still produces the right answer.
+    """
+    if data_spec.kind != "cache":
+        return
+    try:
+        from quantred.services.data import build_data_client
+        from quantred.store.bars import CachedMarketData
+
+        provider = build_data_client(cache=True, cache_dir=data_spec.cache_dir).provider
+        if isinstance(provider, CachedMarketData):
+            provider.warm(list(symbols), timeframe, start, end)
+    except Exception:  # noqa: BLE001 - warming never blocks the run
+        logger.warning("Cache pre-warm failed; workers will fetch their own bars", exc_info=True)
+
+
+def summarize(report: PoolReport) -> str:
+    """A one-line account of a dispatch, including what it dropped.
+
+    Silence about skipped or failed work reads as "everything ran", so the counts
+    are always stated even when they are zero-worthy.
+    """
+    parts = [f"{report.completed} evaluated"]
+    if report.duplicates:
+        parts.append(f"{report.duplicates} duplicate candidate(s) skipped")
+    if report.failures:
+        parts.append(f"{report.failures} failed")
+    if report.interrupted:
+        parts.append("INTERRUPTED — partial run")
+    return ", ".join(parts)
+
+
+def as_json(value: Any) -> str:
+    """Stable JSON for logging a candidate's params in a deterministic order."""
+    return json.dumps(value, sort_keys=True, default=str)

quantred/optimization/param_space.py

@@ -0,0 +1,309 @@
+"""Parameter search space derived from a ``PARAM_RANGES`` declaration.
+
+Turns the ``{name: {min, max, step, default, type}}`` spec that strategies and
+scanners already declare into the concrete things an optimizer needs:
+
+* full **grid** of step-aligned combinations,
+* **random** samples,
+* **normalize/denormalize** to a ``[0, 1]`` vector (for surrogate models).
+
+Only parameters that declare ``min``/``max``/``step`` are searched; everything
+else is held at its default, so a search is always a complete, valid config.
+
+A space may also declare **constraints** between parameters - ``exit_period``
+below ``entry_period``, say. They are enforced by construction rather than by
+rejection: the grid never contains an invalid point and the random sampler never
+draws one, because an evaluated invalid combination is a journaled trial, and a
+journaled trial permanently raises the deflation bar for every future candidate in
+its family. Wasted trials are not just wasted compute.
+"""
+
+import math
+import operator
+from itertools import product
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+import numpy as np
+
+from quantred.utils.numeric import step_decimals
+
+#: The comparisons a declarative constraint may use. Deliberately a fixed table
+#: rather than an expression to evaluate: a space is data a sampler introspects, and
+#: something that has to be executed to be understood cannot be introspected at all.
+_OPERATORS = {
+    "<": operator.lt,
+    "<=": operator.le,
+    ">": operator.gt,
+    ">=": operator.ge,
+    "==": operator.eq,
+    "!=": operator.ne,
+}
+
+#: One declared constraint: ``(left, op, right)``, where each side is either the name
+#: of a parameter in the same space or a literal number.
+Constraint = Tuple[str, str, Any]
+
+
+class ParameterConstraints:
+    """The declared relationships between parameters in one space.
+
+    Two questions, and they are not the same one: ``holds`` asks whether a complete
+    assignment is valid, and ``feasible`` asks whether a *partial* one can still be
+    completed. The sampler needs the second - that is what lets it narrow each
+    parameter's candidate values as it goes, instead of drawing a whole point and
+    throwing it away.
+    """
+
+    def __init__(self, declared: Sequence[Constraint], names: Sequence[str]):
+        self.declared: Tuple[Constraint, ...] = tuple(declared)
+        for left, op, right in self.declared:
+            if op not in _OPERATORS:
+                raise ValueError(f"Unknown constraint operator {op!r}; expected one of {sorted(_OPERATORS)}")
+            for side in (left, right):
+                if isinstance(side, str) and side not in names:
+                    raise ValueError(f"Constraint references unknown parameter {side!r}")
+
+    def __bool__(self) -> bool:
+        return bool(self.declared)
+
+    def _resolve(self, side: Any, params: Dict[str, Any]) -> Any:
+        """A side's value, or ``None`` when it names a parameter not yet assigned."""
+        if isinstance(side, str):
+            return params.get(side)
+        return side
+
+    def holds(self, params: Dict[str, Any]) -> bool:
+        """Whether a complete assignment satisfies every declared constraint."""
+        return self.violations(params) == ()
+
+    def violations(self, params: Dict[str, Any]) -> Tuple[str, ...]:
+        """Every constraint this assignment breaks, rendered for a human.
+
+        Returned rather than raised: a caller screening a user-supplied config wants
+        to report all of them at once, and a caller sampling wants a boolean.
+        """
+        broken = []
+        for left, op, right in self.declared:
+            lhs, rhs = self._resolve(left, params), self._resolve(right, params)
+            if lhs is None or rhs is None:
+                continue  # not fully assigned; `feasible` is the question for that
+            if not _OPERATORS[op](lhs, rhs):
+                broken.append(f"{left} {op} {right} (got {lhs} {op} {rhs})")
+        return tuple(broken)
+
+    def feasible(self, params: Dict[str, Any]) -> bool:
+        """Whether a partial assignment still violates nothing it has decided.
+
+        A constraint with an unassigned side is not yet judged: it may still be
+        satisfiable, and refusing it here would prune valid regions of the space.
+        """
+        return self.violations(params) == ()
+
+    def describe(self) -> Tuple[str, ...]:
+        return tuple(f"{left} {op} {right}" for left, op, right in self.declared)
+
+    def can_bind(self, extremes: Dict[str, Tuple[Any, Any]]) -> bool:
+        """Whether any declared constraint could exclude a point in these ranges.
+
+        ``extremes`` maps a parameter to its ``(lowest, highest)`` declared value. A
+        constraint that every combination of the extremes already satisfies cannot
+        remove anything, and saying so is worth the few lines: it lets a space whose
+        constraints are decorative keep drawing exactly the points it drew before one
+        was declared. A declaration that changes nothing should change nothing —
+        including which configs a seeded random search happens to visit.
+
+        Conservative by construction: equality operators, and anything it cannot
+        bound, answer "yes, it could".
+        """
+        for left, op, right in self.declared:
+            lo_l, hi_l = self._extreme(left, extremes)
+            lo_r, hi_r = self._extreme(right, extremes)
+            if None in (lo_l, hi_l, lo_r, hi_r):
+                return True
+            # The worst case for each ordering: the combination most likely to fail.
+            if op == "<" and hi_l < lo_r:
+                continue
+            if op == "<=" and hi_l <= lo_r:
+                continue
+            if op == ">" and lo_l > hi_r:
+                continue
+            if op == ">=" and lo_l >= hi_r:
+                continue
+            return True
+        return False
+
+    @staticmethod
+    def _extreme(side: Any, extremes: Dict[str, Tuple[Any, Any]]) -> Tuple[Any, Any]:
+        if isinstance(side, str):
+            return extremes.get(side, (None, None))
+        return (side, side)
+
+
+class ParameterSpace:
+    """A searchable view over a ``PARAM_RANGES`` mapping."""
+
+    def __init__(self, param_ranges: Dict[str, Dict[str, Any]], constraints: Sequence[Constraint] = ()):
+        self.param_ranges = param_ranges
+        self.searchable: List[str] = [
+            name for name, spec in param_ranges.items() if all(k in spec for k in ("min", "max", "step"))
+        ]
+        self.defaults: Dict[str, Any] = {
+            name: spec["default"] for name, spec in param_ranges.items() if "default" in spec
+        }
+        self.constraints = ParameterConstraints(constraints, list(param_ranges))
+
+    @classmethod
+    def for_class(cls, strategy_class) -> "ParameterSpace":
+        """The space a strategy (or scanner) class declares, constraints included.
+
+        One construction path, so a class that declares constraints gets them applied
+        wherever its space is built. Building ``ParameterSpace(cls.PARAM_RANGES)``
+        directly is what silently drops them, which is the failure this exists to
+        prevent - an invalid combination that gets evaluated is a journaled trial.
+        """
+        return cls(
+            getattr(strategy_class, "PARAM_RANGES", {}) or {},
+            getattr(strategy_class, "PARAM_CONSTRAINTS", ()) or (),
+        )
+
+    def _values_for(self, name: str) -> List[Any]:
+        spec = self.param_ranges[name]
+        decimals = step_decimals(spec["step"])
+        n_steps = int(round((spec["max"] - spec["min"]) / spec["step"])) + 1
+        values = []
+        for i in range(n_steps):
+            value = round(spec["min"] + i * spec["step"], decimals)
+            value = min(spec["max"], max(spec["min"], value))
+            value = int(value) if spec["type"] == "int" else value
+            if value not in values:
+                values.append(value)
+        return values
+
+    def unconstrained_grid_size(self) -> int:
+        """Points in the full Cartesian product, before constraints remove any."""
+        return math.prod(len(self._values_for(name)) for name in self.searchable) if self.searchable else 0
+
+    def grid_size(self) -> int:
+        """Number of *valid* points in the full grid.
+
+        Computed without materializing the product when nothing is constrained. With
+        constraints it enumerates, because the count a caller budgets against has to
+        be the count it will actually get - reporting the unconstrained size and then
+        yielding fewer points is how a cap ends up meaning something different from
+        what it said.
+        """
+        if not self._constraints_can_bind():
+            return self.unconstrained_grid_size()
+        return len(self.grid())
+
+    def grid(self) -> List[Dict[str, Any]]:
+        """Every step-aligned, constraint-satisfying combination of searchable params.
+
+        Note: this is the full Cartesian product and can be enormous for
+        many-parameter spaces. Callers that cap the number of evaluations should
+        check :meth:`grid_size` first and fall back to :meth:`random_samples`.
+        """
+        axes = [self._values_for(name) for name in self.searchable]
+        points = [{**self.defaults, **dict(zip(self.searchable, combo))} for combo in product(*axes)]
+        if not self._constraints_can_bind():
+            return points
+        return [point for point in points if self.constraints.holds(point)]
+
+    def random_samples(self, n: int, rng: np.random.Generator) -> List[Dict[str, Any]]:
+        """``n`` random step-aligned configs, none of which violate a constraint.
+
+        Drawn parameter by parameter, each one restricted to the values still
+        consistent with what has already been decided - so an invalid region is
+        unreachable rather than reached and discarded. A draw that paints itself into
+        a corner (no value left for a later parameter) is restarted rather than
+        returned half-built; the restart budget is bounded so a space whose
+        constraints admit nothing fails loudly instead of hanging.
+        """
+        if not self._constraints_can_bind():
+            samples = []
+            for _ in range(n):
+                params = dict(self.defaults)
+                for name in self.searchable:
+                    params[name] = rng.choice(self._values_for(name)).item()
+                samples.append(params)
+            return samples
+
+        samples = []
+        attempts = 0
+        budget = max(20 * n, 100)
+        while len(samples) < n and attempts < budget:
+            attempts += 1
+            drawn = self._draw_constrained(rng)
+            if drawn is not None:
+                samples.append(drawn)
+        if len(samples) < n:
+            raise ValueError(
+                f"Could only draw {len(samples)} of {n} configs satisfying "
+                f"{', '.join(self.constraints.describe())} — the constraints may admit "
+                f"little or none of the declared ranges"
+            )
+        return samples
+
+    def _draw_constrained(self, rng: np.random.Generator) -> Optional[Dict[str, Any]]:
+        """One constraint-satisfying draw, or ``None`` if this attempt dead-ended."""
+        params = dict(self.defaults)
+        for name in self.searchable:
+            allowed = [v for v in self._values_for(name) if self.constraints.feasible({**params, name: v})]
+            if not allowed:
+                return None
+            params[name] = allowed[int(rng.integers(len(allowed)))]
+            if isinstance(params[name], np.generic):
+                params[name] = params[name].item()
+        return params if self.constraints.holds(params) else None
+
+    # --- normalization, for surrogate-model optimizers -------------------- #
+    def to_unit_vector(self, params: Dict[str, Any]) -> np.ndarray:
+        """Map a config to a ``[0, 1]`` vector over the searchable parameters."""
+        vec = []
+        for name in self.searchable:
+            spec = self.param_ranges[name]
+            vec.append((params[name] - spec["min"]) / (spec["max"] - spec["min"]))
+        return np.array(vec, dtype="float64")
+
+    def from_unit_vector(self, vec: np.ndarray) -> Dict[str, Any]:
+        """Inverse of :meth:`to_unit_vector`, snapped to the step grid.
+
+        The one path constraints cannot be enforced *by construction*: a surrogate
+        proposes a point in a continuous box and snapping it can land outside the
+        feasible region. The caller checks :meth:`is_valid` and drops such a proposal
+        before evaluating it, so it still costs no trial — but this is why
+        reject-after-draw is not the design anywhere it can be avoided.
+        """
+        params = dict(self.defaults)
+        for i, name in enumerate(self.searchable):
+            spec = self.param_ranges[name]
+            raw = vec[i] * (spec["max"] - spec["min"]) + spec["min"]
+            snapped = round(raw / spec["step"]) * spec["step"]
+            snapped = min(spec["max"], max(spec["min"], round(snapped, step_decimals(spec["step"]))))
+            params[name] = int(snapped) if spec["type"] == "int" else snapped
+        return params
+
+    def _constraints_can_bind(self) -> bool:
+        """Whether the declared constraints can exclude anything in this space."""
+        if not self.constraints:
+            return False
+        extremes = {}
+        for name in self.searchable:
+            values = self._values_for(name)
+            if values:
+                extremes[name] = (min(values), max(values))
+        for name, value in self.defaults.items():
+            extremes.setdefault(name, (value, value))
+        return self.constraints.can_bind(extremes)
+
+    def is_valid(self, params: Dict[str, Any]) -> bool:
+        """Whether a complete assignment satisfies every declared constraint."""
+        return self.constraints.holds(params)
+
+    def violations(self, params: Dict[str, Any]) -> Tuple[str, ...]:
+        """Every constraint ``params`` breaks, for a caller that has to explain why."""
+        return self.constraints.violations(params)
+
+    @property
+    def dimensions(self) -> int:
+        return len(self.searchable)