quantecarlo 0.1.0__py3-none-any.whl

quantecarlo/__init__.py

@@ -0,0 +1,3 @@
+from quantecarlo.bo_sampler import DimSpec, qEISampler
+
+__all__ = ["DimSpec", "qEISampler"]

quantecarlo/bo_sampler.py

@@ -0,0 +1,195 @@
+# quantecarlo/bo_sampler.py
+from __future__ import annotations
+
+import json
+import threading
+import urllib.error
+import urllib.request
+import warnings
+from collections import deque
+from dataclasses import asdict, dataclass
+from typing import Any
+
+import optuna
+from optuna.distributions import (
+    BaseDistribution,
+    FloatDistribution,
+    IntDistribution,
+)
+from optuna.samplers import BaseSampler, RandomSampler
+from optuna.trial import TrialState
+
+
+@dataclass
+class DimSpec:
+    """Describes one dimension of the search space."""
+    name: str
+    type: str          # "float" | "int"  (categorical deferred)
+    low: float
+    high: float
+    log: bool = False
+    step: float | None = None  # grid step for int dims (default 1)
+
+
+class qEISampler(BaseSampler):
+    """Optuna sampler that outsources GP fitting and q-EI scoring to a remote endpoint.
+
+    Fills a local cache with q suggestions on the first ask after the cache empties,
+    then hands them out one at a time. Falls back to random sampling during startup
+    and if the API call fails.
+
+    Thread-safety: a single threading.Lock ensures only one API call fires per batch
+    even when study.optimize(n_jobs=q) drives concurrent sample_relative calls.
+    """
+
+    def __init__(
+        self,
+        search_space: list[DimSpec],
+        api_url: str = "https://markshipman4273--bo-gp-service-gp-suggest.modal.run",
+        n_startup_trials: int = 8,
+        q: int = 4,
+        n_candidates: int = 512,
+        train_steps: int = 60,
+        lr: float = 0.1,
+        xi: float = 0.01,
+        mode: str = "production",
+        seed: int | None = None,
+        timeout: float = 120.0,
+    ) -> None:
+        self._api_url = api_url
+        self._search_space = search_space
+        self._n_startup_trials = n_startup_trials
+        self._q = q
+        self._n_candidates = n_candidates
+        self._train_steps = train_steps
+        self._lr = lr
+        self._xi = xi
+        self._mode = mode
+        self._timeout = timeout
+        self._independent_sampler = RandomSampler(seed=seed)
+        self._pending: deque[dict[str, Any]] = deque()
+        self._lock = threading.Lock()
+
+    # ------------------------------------------------------------------
+    # BaseSampler interface
+    # ------------------------------------------------------------------
+
+    def infer_relative_search_space(
+        self,
+        study: optuna.Study,
+        trial: optuna.trial.FrozenTrial,
+    ) -> dict[str, BaseDistribution]:
+        # Use the explicit construction-time space rather than intersection_search_space
+        # so the sampler works immediately without waiting for multiple param-overlapping
+        # trials to accumulate.
+        result: dict[str, BaseDistribution] = {}
+        for dim in self._search_space:
+            if dim.type == "float":
+                result[dim.name] = FloatDistribution(
+                    dim.low, dim.high, log=dim.log, step=dim.step
+                )
+            elif dim.type == "int":
+                result[dim.name] = IntDistribution(
+                    int(dim.low),
+                    int(dim.high),
+                    log=dim.log,
+                    step=int(dim.step) if dim.step is not None else 1,
+                )
+        return result
+
+    def sample_relative(
+        self,
+        study: optuna.Study,
+        trial: optuna.trial.FrozenTrial,
+        search_space: dict[str, BaseDistribution],
+    ) -> dict[str, Any]:
+        with self._lock:
+            # Serve from cache first — no API call needed.
+            if self._pending:
+                return self._pending.popleft()
+
+            # Cache empty: check whether we have enough data to fit the GP.
+            complete_trials = study.get_trials(
+                deepcopy=False, states=(TrialState.COMPLETE,)
+            )
+            if len(complete_trials) < self._n_startup_trials:
+                return {}  # → Optuna falls back to sample_independent (random)
+
+            param_names = [dim.name for dim in self._search_space]
+            usable = [
+                t for t in complete_trials
+                if all(n in t.params for n in param_names)
+            ]
+            if len(usable) < self._n_startup_trials:
+                return {}
+
+            # Build the observation matrices and call the remote API.
+            X = [[float(t.params[n]) for n in param_names] for t in usable]
+            # q-EI maximises, so negate trial values: minimisation targets become
+            # maximisation targets (lower error → higher negated value → q-EI seeks it).
+            y = [-float(t.value) for t in usable]
+
+            payload = {
+                "X": X,
+                "y": y,
+                "search_space": [asdict(dim) for dim in self._search_space],
+                "q": self._q,
+                "n_candidates": self._n_candidates,
+                "train_steps": self._train_steps,
+                "lr": self._lr,
+                "xi": self._xi,
+                "mode": self._mode,
+            }
+
+            try:
+                data = self._post(payload)
+                if self._mode == "debug" and data.get("ei_all") is not None:
+                    ei_all = data["ei_all"]
+                    display = [round(v, 6) if v is not None else "NaN" for v in ei_all]
+                    print(f"\n[debug] ei_all ({len(ei_all)} batches): {display}")
+                    valid = [v for v in ei_all if v is not None]
+                    if valid:
+                        print(f"[debug] max ei : {max(valid):.6f}  winning batch ei_score: {data.get('ei_scores')}")
+            except Exception as exc:
+                warnings.warn(
+                    f"qEISampler: API call failed ({exc}), falling back to random."
+                )
+                return {}
+
+            # Populate cache; snap int dims to Python int so suggest_int is happy.
+            for candidate in data["candidates"]:
+                params: dict[str, Any] = {}
+                for i, dim in enumerate(self._search_space):
+                    val = float(candidate["x"][i])
+                    if dim.type == "int":
+                        val = int(round(val))  # type: ignore[assignment]
+                    params[dim.name] = val
+                self._pending.append(params)
+
+            return self._pending.popleft() if self._pending else {}
+
+    def sample_independent(
+        self,
+        study: optuna.Study,
+        trial: optuna.trial.FrozenTrial,
+        param_name: str,
+        param_distribution: BaseDistribution,
+    ) -> Any:
+        return self._independent_sampler.sample_independent(
+            study, trial, param_name, param_distribution
+        )
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _post(self, payload: dict) -> dict:
+        body = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(
+            self._api_url,
+            data=body,
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with urllib.request.urlopen(req, timeout=self._timeout) as resp:
+            return json.loads(resp.read().decode("utf-8"))

quantecarlo-0.1.0.dist-info/METADATA

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: quantecarlo
+Version: 0.1.0
+Summary: Batch Bayesian optimization sampler (q-EI) for Optuna, backed by a remote GP service
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: optuna>=3.0
+
+# quantecarlo
+
+Batch Bayesian optimization for [Optuna](https://optuna.org) using **q-Expected Improvement (q-EI)**. Drop in one sampler, point it at a hosted GP endpoint, and get a batch of `q` well-chosen candidates back per iteration instead of one at a time.
+
+---
+
+## Quickstart
+
+```bash
+pip install quantecarlo
+```
+
+```python
+import optuna
+from quantecarlo import DimSpec, qEISampler
+
+# Define what you're optimizing — here, a simple 2-D quadratic.
+# In practice this is your training run, simulation, or experiment.
+def objective(trial):
+    x = trial.suggest_float("x", -5.0, 5.0)
+    y = trial.suggest_float("y", -5.0, 5.0)
+    return (x - 1.3) ** 2 + (y + 0.7) ** 2   # minimum at (1.3, -0.7)
+
+# The DimSpec names and bounds must match the suggest_* calls above.
+search_space = [
+    DimSpec(name="x", type="float", low=-5.0, high=5.0),
+    DimSpec(name="y", type="float", low=-5.0, high=5.0),
+]
+
+sampler = qEISampler(
+    search_space=search_space,
+    q=4,
+)
+
+study = optuna.create_study(direction="minimize", sampler=sampler)
+study.optimize(objective, n_trials=40, n_jobs=4)
+print(study.best_params)
+```
+
+See `demo.py` for a full ask-tell example using an MLP on the breast-cancer dataset, with explicit batching and a per-iteration progress table.
+
+---
+
+## What's happening under the hood (you don't need to touch any of this)
+
+Each time the local suggestion cache runs dry, `qEISampler` POSTs your observed `(X, y)` pairs to a remote GP service. That service:
+
+1. **Normalises** each parameter to [0, 1] (log-scale for `log=True` dims).
+2. **Rank-transforms** `y` to standard-normal via the Probability Integral Transform — so the GP always sees well-behaved Gaussian targets regardless of the shape of your objective's distribution.
+3. **Fits an ExactGP** (Matérn-5/2 ARD kernel) on a GPU via Adam on the marginal log-likelihood.
+4. **Draws `n_candidates` random candidate batches** of size `q` and scores each batch jointly with q-EI.
+5. **Returns the highest-scoring batch** decoded back to your original parameter scale. Int dims are snapped to the nearest integer.
+
+The sampler then hands out one candidate per `study.ask()` call from the local cache. The next API call doesn't fire until the cache is exhausted — so `q` threads share a single round-trip.
+
+---
+
+## Parameters
+
+### `DimSpec`
+
+Describes one dimension of your search space.
+
+| Field  | Type                    | Description |
+|--------|-------------------------|-------------|
+| `name` | `str`                   | Must match the corresponding `suggest_*` call in your objective. |
+| `type` | `"float"` \| `"int"`   | Continuous float or integer. Int dims are snapped on decode. |
+| `low`  | `float`                 | Lower bound (inclusive). |
+| `high` | `float`                 | Upper bound (inclusive). |
+| `log`  | `bool`                  | Log-uniform sampling. Use for parameters that span orders of magnitude (learning rates, weight decay). Default `False`. |
+| `step` | `float \| None`         | Grid step for `int` dims. Default `1`. |
+
+Categorical dimensions are not yet supported.
+
+### `qEISampler`
+
+| Parameter         | Default        | Description |
+|-------------------|----------------|-------------|
+| `search_space`    | —              | List of `DimSpec`, one per hyperparameter. |
+| `api_url`         | *(hosted)*     | GP endpoint URL. Override only if self-hosting. |
+| `n_startup_trials`| `8`            | Number of random trials before the GP is used. Too few observations make GP fitting unreliable. |
+| `q`               | `4`            | Batch size. Set `n_jobs=q` in `study.optimize` to evaluate the batch in parallel. |
+| `n_candidates`    | `512`          | Random candidate batches scored per API call. Larger = better coverage; diminishing returns above ~1024 for most spaces. |
+| `train_steps`     | `60`           | Adam steps for GP kernel hyperparameter optimisation. Increase for tighter fits on noisy objectives. |
+| `lr`              | `0.1`          | Adam learning rate for GP training. |
+| `xi`              | `0.01`         | EI exploration bonus. Larger values bias toward uncertain regions; smaller values exploit the current best. |
+| `mode`            | `"production"` | `"debug"` returns the full GP posterior surface in the API response — useful for diagnostics. |
+| `seed`            | `None`         | Random seed for the fallback random sampler. |
+| `timeout`         | `120.0`        | HTTP timeout in seconds for the API call. |
+
+---
+
+## Why q-EI instead of just adding more threads?
+
+Running `study.optimize(n_jobs=q)` with a standard sampler (TPE, random) does parallelize objective evaluation, but each worker samples **independently** — it has no idea what the other `q-1` workers are about to try. You often end up with a batch where several candidates cluster near the same local optimum.
+
+**q-EI scores the whole batch jointly.** It computes the expected improvement of the *best point in the batch* over the current best, taking into account the full joint posterior covariance across the `q` candidates. The optimizer naturally diversifies: a second candidate near an already-selected point contributes little to the joint maximum, so the algorithm spreads the batch across promising but distinct regions.
+
+In practice this means each batch of `q` trials carries more information than `q` independently-drawn trials. You cover the space more efficiently and tend to reach good solutions in fewer total function evaluations — which matters when each evaluation is expensive (a training run, an experiment, a simulation).
+
+The cost is one API call per batch (a few seconds for a warm GP endpoint) in exchange for a smarter set of `q` candidates. That tradeoff is almost always worth it when objective evaluations take more than a minute.

quantecarlo-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+quantecarlo/__init__.py,sha256=dfGWRCi6978K4yNNWP190EjU2l35RZkvqAq8cIklNoU,92
+quantecarlo/bo_sampler.py,sha256=pdJ0_ZwgN4DVzhWbN0uzQ2INyQYjW_Ico-D-x3Cm32Y,7234
+quantecarlo-0.1.0.dist-info/METADATA,sha256=ZHP8fMSY1Z4igsnsZsdiz2c9QdtmbLy5zwPLBd_1tbM,6232
+quantecarlo-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+quantecarlo-0.1.0.dist-info/top_level.txt,sha256=9Uqqo4mnRkD3qQa9kvNqv_ITuyHG1Ha7uLBrqdhFHy8,12
+quantecarlo-0.1.0.dist-info/RECORD,,

quantecarlo-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

quantecarlo-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+quantecarlo