cadaques 0.1.0__py3-none-any.whl

cadaques/__init__.py

@@ -0,0 +1,18 @@
+"""CADAQUES — Cost-Aware Dual Architecture for QUery-Efficient diScovery.
+
+An open-source framework for autonomous discovery campaigns:
+any oracle, any driver, one budget. Every query counts.
+"""
+
+from .core.campaign import Campaign, CampaignResult, DriverStopped
+from .core.cost import Budget, BudgetExceeded, BudgetView, Cost
+from .core.ledger import Ledger, Transaction
+from .core.protocols import Driver, Oracle, Query, Result
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Budget", "BudgetExceeded", "BudgetView", "Campaign", "CampaignResult",
+    "Cost", "Driver", "DriverStopped", "Ledger", "Oracle", "Query",
+    "Result", "Transaction", "__version__",
+]

cadaques/core/__init__.py

@@ -0,0 +1,4 @@
+from .campaign import Campaign, CampaignResult, DriverStopped
+from .cost import Budget, BudgetExceeded, BudgetView, Cost
+from .ledger import Ledger, Transaction
+from .protocols import Driver, Oracle, Query, Result

cadaques/core/campaign.py

@@ -0,0 +1,146 @@
+"""The Campaign runner: the discovery loop with an accountant inside.
+
+The loop is deliberately small. Its one structural commitment is the
+framework's thesis: *every query counts*. Each iteration prices the
+oracle query before committing, meters the driver's decision, and the
+campaign ends when the budget is exhausted — not when an iteration
+counter runs out.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Literal, Sequence
+
+from .cost import Budget, Cost
+from .ledger import Ledger
+from .protocols import Driver, Oracle, Result
+
+StopReason = Literal["budget_exhausted", "max_queries", "driver_stopped"]
+
+
+class DriverStopped(Exception):
+    """A Driver may raise this to end a campaign early."""
+
+
+@dataclass
+class CampaignResult:
+    best: Result | None
+    history: list[Result]
+    ledger: Ledger
+    budget: Budget
+    stop_reason: StopReason
+
+    @property
+    def n_queries(self) -> int:
+        return len(self.history)
+
+    def trace(self, currency: str = "seconds") -> list[tuple[float, float]]:
+        """(cumulative settled cost, best-so-far value) — the signature
+        cost-normalized curve of a CADAQUES campaign."""
+        points: list[tuple[float, float]] = []
+        best: float | None = None
+        for tx, running in self.ledger.cumulative():
+            if tx.kind != "oracle":
+                continue
+            value = tx.meta.get("value")
+            if value is None:
+                continue
+            best = value if best is None else max(best, value) if self._maximize else min(best, value)
+            points.append((getattr(running, currency), best))
+        return points
+
+    _maximize: bool = field(default=True, repr=False)
+
+
+class Campaign:
+    """Couple one Oracle to one Driver under one Budget."""
+
+    def __init__(
+        self,
+        oracle: Oracle,
+        driver: Driver,
+        budget: Budget,
+        *,
+        maximize: bool = True,
+        meter_driver: bool = True,
+    ) -> None:
+        self.oracle = oracle
+        self.driver = driver
+        self.budget = budget
+        self.maximize = maximize
+        self.meter_driver = meter_driver
+        self.ledger = Ledger()
+        self.history: list[Result] = []
+
+    # ------------------------------------------------------------------
+    def run(self, max_queries: int | None = None) -> CampaignResult:
+        stop_reason: StopReason = "budget_exhausted"
+        best: Result | None = None
+
+        while True:
+            if max_queries is not None and len(self.history) >= max_queries:
+                stop_reason = "max_queries"
+                break
+
+            # -- driver decision (metered) -------------------------------
+            t0 = time.perf_counter()
+            try:
+                query = self.driver.propose(self.history, self.budget.view())
+            except DriverStopped:
+                stop_reason = "driver_stopped"
+                break
+            elapsed = time.perf_counter() - t0
+
+            driver_cost = Cost()
+            if self.meter_driver:
+                driver_cost = Cost(seconds=elapsed) + getattr(
+                    self.driver, "last_proposal_cost", Cost()
+                )
+                self.budget.charge(driver_cost, settle=True)
+            self.ledger.record(
+                "driver",
+                label=type(self.driver).__name__,
+                declared=driver_cost,
+                settled=driver_cost,
+            )
+
+            # -- oracle query: price, afford, evaluate, settle ------------
+            declared = self.oracle.price(query)
+            if not self.budget.can_afford(declared):
+                stop_reason = "budget_exhausted"
+                break
+
+            result = self.oracle.evaluate(query)
+            self.budget.charge(result.cost, settle=True)
+            self.ledger.record(
+                "oracle",
+                label=type(self.oracle).__name__,
+                declared=declared,
+                settled=result.cost,
+                value=result.value,
+                params=dict(result.query.params),
+                fidelity=dict(result.query.fidelity),
+            )
+
+            self.history.append(result)
+            self.driver.observe(result)
+
+            if best is None or self._improves(result, best):
+                best = result
+
+        campaign_result = CampaignResult(
+            best=best,
+            history=self.history,
+            ledger=self.ledger,
+            budget=self.budget,
+            stop_reason=stop_reason,
+        )
+        campaign_result._maximize = self.maximize
+        return campaign_result
+
+    def _improves(self, candidate: Result, incumbent: Result) -> bool:
+        if self.maximize:
+            return candidate.value > incumbent.value
+        return candidate.value < incumbent.value

cadaques/core/cost.py

@@ -0,0 +1,138 @@
+"""Cost primitives: the first-class citizens of CADAQUES.
+
+Every oracle query and every driver decision is priced in a
+multi-currency :class:`Cost` and charged against a single
+:class:`Budget`. Campaigns end when the budget is exhausted,
+not when an iteration counter runs out.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field, replace
+from typing import Iterator, Mapping
+
+#: Currencies tracked by the framework. Heterogeneous by design:
+#: a DFT relaxation, a beamline measurement and an LLM call are
+#: not the same kind of expense.
+CURRENCIES: tuple[str, ...] = ("seconds", "cpu_hours", "euros", "tokens")
+
+
+@dataclass(frozen=True, slots=True)
+class Cost:
+    """An immutable multi-currency cost vector.
+
+    All components default to zero, so ``Cost(seconds=3.0)`` prices a
+    3-second query and ``Cost()`` is the free cost.
+    """
+
+    seconds: float = 0.0
+    cpu_hours: float = 0.0
+    euros: float = 0.0
+    tokens: float = 0.0
+
+    # -- arithmetic -------------------------------------------------
+    def __add__(self, other: "Cost") -> "Cost":
+        return Cost(**{c: getattr(self, c) + getattr(other, c) for c in CURRENCIES})
+
+    def __sub__(self, other: "Cost") -> "Cost":
+        return Cost(**{c: getattr(self, c) - getattr(other, c) for c in CURRENCIES})
+
+    def scaled(self, factor: float) -> "Cost":
+        return Cost(**{c: getattr(self, c) * factor for c in CURRENCIES})
+
+    # -- queries ----------------------------------------------------
+    def items(self) -> Iterator[tuple[str, float]]:
+        for c in CURRENCIES:
+            yield c, getattr(self, c)
+
+    def as_dict(self) -> dict[str, float]:
+        return dict(self.items())
+
+    @property
+    def is_free(self) -> bool:
+        return all(v == 0 for _, v in self.items())
+
+    def dominated_by(self, other: "Cost") -> bool:
+        """True if every component of ``self`` is <= that of ``other``."""
+        return all(getattr(self, c) <= getattr(other, c) for c in CURRENCIES)
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, float]) -> "Cost":
+        unknown = set(data) - set(CURRENCIES)
+        if unknown:
+            raise ValueError(f"Unknown cost currencies: {sorted(unknown)}")
+        return cls(**{k: float(v) for k, v in data.items()})
+
+    def __repr__(self) -> str:  # compact: only non-zero currencies
+        nonzero = ", ".join(f"{c}={v:g}" for c, v in self.items() if v)
+        return f"Cost({nonzero or '0'})"
+
+
+class BudgetExceeded(RuntimeError):
+    """Raised when a charge is attempted beyond the campaign budget."""
+
+
+@dataclass(frozen=True, slots=True)
+class BudgetView:
+    """A read-only snapshot of the budget, exposed to Drivers.
+
+    Drivers may adapt their strategy to the remaining budget (e.g.
+    explore early, exploit when funds run low) but cannot mutate it.
+    """
+
+    total: Cost
+    spent: Cost
+
+    @property
+    def remaining(self) -> Cost:
+        return self.total - self.spent
+
+    @property
+    def fraction_used(self) -> float:
+        """Largest used fraction across the currencies with a limit."""
+        fractions = [
+            getattr(self.spent, c) / getattr(self.total, c)
+            for c in CURRENCIES
+            if getattr(self.total, c) > 0
+        ]
+        return max(fractions, default=0.0)
+
+
+@dataclass
+class Budget:
+    """The single budget of a discovery campaign.
+
+    Only currencies with a positive ``total`` component are limited;
+    the rest are tracked but unbounded. Declared costs are checked
+    with :meth:`can_afford` *before* a query is issued; settled costs
+    are charged unconditionally with ``charge(..., settle=True)`` —
+    in the real world one discovers an overrun after paying for it,
+    and the ledger keeps the evidence.
+    """
+
+    total: Cost
+    spent: Cost = field(default_factory=Cost)
+
+    def can_afford(self, cost: Cost) -> bool:
+        prospective = self.spent + cost
+        return all(
+            getattr(prospective, c) <= getattr(self.total, c)
+            for c in CURRENCIES
+            if getattr(self.total, c) > 0
+        )
+
+    def charge(self, cost: Cost, *, settle: bool = False) -> None:
+        if not settle and not self.can_afford(cost):
+            raise BudgetExceeded(f"Cannot afford {cost}; remaining {self.remaining}")
+        self.spent = self.spent + cost
+
+    @property
+    def remaining(self) -> Cost:
+        return self.total - self.spent
+
+    @property
+    def exhausted(self) -> bool:
+        return not self.can_afford(Cost())
+
+    def view(self) -> BudgetView:
+        return BudgetView(total=replace(self.total), spent=replace(self.spent))

cadaques/core/ledger.py

@@ -0,0 +1,92 @@
+"""The campaign ledger: every transaction, declared and settled.
+
+The ledger is the accounting record of a discovery campaign and,
+almost for free, its provenance and replay substrate: exporting it
+to JSONL yields a complete, reproducible trace of what was asked,
+what it was expected to cost, and what it actually cost.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Iterator, Literal, Mapping
+
+from .cost import Cost
+
+TransactionKind = Literal["oracle", "driver"]
+
+
+@dataclass(frozen=True)
+class Transaction:
+    kind: TransactionKind
+    label: str
+    declared: Cost
+    settled: Cost
+    timestamp: float = field(default_factory=time.time)
+    meta: Mapping[str, Any] = field(default_factory=dict)
+
+    @property
+    def overrun(self) -> Cost:
+        """Settled minus declared: the price of optimism."""
+        return self.settled - self.declared
+
+
+@dataclass
+class Ledger:
+    """Append-only record of all campaign transactions."""
+
+    transactions: list[Transaction] = field(default_factory=list)
+
+    def record(
+        self,
+        kind: TransactionKind,
+        label: str,
+        declared: Cost,
+        settled: Cost,
+        **meta: Any,
+    ) -> Transaction:
+        tx = Transaction(kind=kind, label=label, declared=declared, settled=settled, meta=meta)
+        self.transactions.append(tx)
+        return tx
+
+    # -- aggregation ------------------------------------------------
+    def total(self, kind: TransactionKind | None = None) -> Cost:
+        total = Cost()
+        for tx in self.transactions:
+            if kind is None or tx.kind == kind:
+                total = total + tx.settled
+        return total
+
+    def cumulative(self, kind: TransactionKind | None = None) -> Iterator[tuple[Transaction, Cost]]:
+        """Yield (transaction, running settled total) pairs."""
+        running = Cost()
+        for tx in self.transactions:
+            if kind is None or tx.kind == kind:
+                running = running + tx.settled
+                yield tx, running
+
+    def __len__(self) -> int:
+        return len(self.transactions)
+
+    # -- persistence ------------------------------------------------
+    def to_jsonl(self, path: str | Path) -> Path:
+        path = Path(path)
+        with path.open("w", encoding="utf-8") as fh:
+            for tx in self.transactions:
+                fh.write(
+                    json.dumps(
+                        {
+                            "kind": tx.kind,
+                            "label": tx.label,
+                            "declared": tx.declared.as_dict(),
+                            "settled": tx.settled.as_dict(),
+                            "timestamp": tx.timestamp,
+                            "meta": dict(tx.meta),
+                        }
+                    )
+                    + "\n"
+                )
+        return path

cadaques/core/protocols.py

@@ -0,0 +1,80 @@
+"""The dual architecture: the :class:`Oracle` and :class:`Driver` protocols.
+
+CADAQUES is agnostic on both sides of the discovery loop:
+
+* an **Oracle** is anything that answers queries at a declared price —
+  a simulator, a laboratory instrument, an analytic function;
+* a **Driver** is anything that decides what to ask next — random
+  search, Bayesian optimization, gradient methods, an LLM agent.
+
+Both sides are metered: the campaign runner charges oracle queries
+*and* driver decisions against one budget.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Mapping, Protocol, Sequence, runtime_checkable
+
+from .cost import BudgetView, Cost
+
+
+@dataclass(frozen=True)
+class Query:
+    """A single question to an Oracle.
+
+    ``params`` are the design/search variables; ``fidelity`` are the
+    knobs that trade accuracy for cost (lattice size, mesh density,
+    integration time, ...). Keeping fidelity explicit is what makes
+    multi-fidelity, cost-aware campaigns first-class citizens.
+    """
+
+    params: Mapping[str, Any]
+    fidelity: Mapping[str, Any] = field(default_factory=dict)
+    tag: str = ""
+
+
+@dataclass(frozen=True)
+class Result:
+    """An Oracle's answer, carrying its *settled* (actual) cost."""
+
+    query: Query
+    value: float
+    cost: Cost
+    info: Mapping[str, Any] = field(default_factory=dict)
+
+
+@runtime_checkable
+class Oracle(Protocol):
+    """Anything that answers queries at a price.
+
+    ``price`` declares the expected cost *ex ante* so the runner can
+    check affordability before committing; ``evaluate`` performs the
+    query and reports the *settled* cost inside the Result. Real
+    oracles deviate from their declared price — the ledger records
+    both, and that discrepancy is itself an observable.
+    """
+
+    def price(self, query: Query) -> Cost:
+        ...
+
+    def evaluate(self, query: Query) -> Result:
+        ...
+
+
+@runtime_checkable
+class Driver(Protocol):
+    """Anything that decides what to ask next.
+
+    ``propose`` receives the full history and a read-only view of the
+    budget, enabling budget-aware strategies. ``observe`` feeds the
+    settled result back. Drivers that incur their own accountable
+    costs beyond wall time (e.g. LLM tokens) may expose a
+    ``last_proposal_cost`` attribute, which the runner will charge.
+    """
+
+    def propose(self, history: Sequence[Result], budget: BudgetView) -> Query:
+        ...
+
+    def observe(self, result: Result) -> None:
+        ...

cadaques/drivers/__init__.py

@@ -0,0 +1 @@
+from .reference import AnnealedLocalDriver, RandomDriver

cadaques/drivers/reference.py

@@ -0,0 +1,96 @@
+"""Reference drivers.
+
+Two deliberately simple strategies that already span the design
+space CADAQUES cares about:
+
+* :class:`RandomDriver` — the universal, budget-oblivious baseline
+  against which every intelligent driver must justify its cost.
+* :class:`AnnealedLocalDriver` — a budget-*aware* strategy: it
+  explores globally while funds are plentiful and contracts around
+  the incumbent as the budget runs out, reading the remaining
+  fraction from the ``BudgetView`` it receives each iteration.
+
+Bayesian optimization, gradient-based and LLM-agent drivers plug in
+through the same two-method protocol.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Mapping, Sequence
+
+import numpy as np
+
+from ..core.cost import BudgetView
+from ..core.protocols import Query, Result
+
+SearchSpace = Mapping[str, tuple[float, float]]
+
+
+def _uniform_sample(space: SearchSpace, rng: np.random.Generator) -> dict[str, float]:
+    return {k: float(rng.uniform(low, high)) for k, (low, high) in space.items()}
+
+
+@dataclass
+class RandomDriver:
+    """Uniform random search over a box-bounded space."""
+
+    space: SearchSpace
+    fidelity: Mapping[str, int] = field(default_factory=dict)
+    seed: int | None = None
+
+    def __post_init__(self) -> None:
+        self._rng = np.random.default_rng(self.seed)
+
+    def propose(self, history: Sequence[Result], budget: BudgetView) -> Query:
+        return Query(params=_uniform_sample(self.space, self._rng), fidelity=dict(self.fidelity))
+
+    def observe(self, result: Result) -> None:  # random search learns nothing
+        pass
+
+
+@dataclass
+class AnnealedLocalDriver:
+    """Gaussian local search whose step size anneals with the budget.
+
+    The proposal is a perturbation of the best point seen so far,
+    with standard deviation ``sigma_max`` at the start of the
+    campaign shrinking linearly to ``sigma_min`` as
+    ``budget.fraction_used`` approaches 1 — spend on exploration
+    while rich, on exploitation while poor.
+    """
+
+    space: SearchSpace
+    fidelity: Mapping[str, int] = field(default_factory=dict)
+    sigma_max: float = 0.5
+    sigma_min: float = 0.02
+    maximize: bool = True
+    seed: int | None = None
+
+    def __post_init__(self) -> None:
+        self._rng = np.random.default_rng(self.seed)
+        self._best: Result | None = None
+
+    # -- Driver protocol ------------------------------------------------
+    def propose(self, history: Sequence[Result], budget: BudgetView) -> Query:
+        if self._best is None:
+            return Query(params=_uniform_sample(self.space, self._rng), fidelity=dict(self.fidelity))
+
+        frac = min(max(budget.fraction_used, 0.0), 1.0)
+        sigma_rel = self.sigma_max + (self.sigma_min - self.sigma_max) * frac
+
+        params: dict[str, float] = {}
+        for key, (low, high) in self.space.items():
+            width = high - low
+            center = float(self._best.query.params[key])
+            proposal = center + self._rng.normal(0.0, sigma_rel * width)
+            params[key] = float(np.clip(proposal, low, high))
+        return Query(params=params, fidelity=dict(self.fidelity))
+
+    def observe(self, result: Result) -> None:
+        if self._best is None or self._improves(result):
+            self._best = result
+
+    def _improves(self, result: Result) -> bool:
+        assert self._best is not None
+        return result.value > self._best.value if self.maximize else result.value < self._best.value

cadaques/oracles/__init__.py

@@ -0,0 +1,2 @@
+from .analytic import AnalyticOracle, quadratic_bowl
+from .ising import Ising2DOracle, T_C_EXACT

cadaques/oracles/analytic.py

@@ -0,0 +1,50 @@
+"""Analytic oracles: exact functions with synthetic cost models.
+
+Useful for unit tests and for controlled driver-benchmarking
+experiments where the ground truth and the cost model are both known
+exactly.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Callable, Mapping
+
+from ..core.cost import Cost
+from ..core.protocols import Query, Result
+
+
+@dataclass
+class AnalyticOracle:
+    """Wrap ``fn(params) -> float`` as a metered Oracle.
+
+    ``price_fn`` maps a query to its declared cost (default: a flat
+    one-second tariff), letting tests exercise heterogeneous-cost
+    scenarios deterministically. The settled cost equals the declared
+    cost plus the (negligible) measured evaluation wall time, keeping
+    the declared/settled distinction alive even in toy settings.
+    """
+
+    fn: Callable[[Mapping[str, float]], float]
+    price_fn: Callable[[Query], Cost] = field(default=lambda _q: Cost(seconds=1.0))
+    name: str = "analytic"
+
+    def price(self, query: Query) -> Cost:
+        return self.price_fn(query)
+
+    def evaluate(self, query: Query) -> Result:
+        t0 = time.perf_counter()
+        value = float(self.fn(query.params))
+        elapsed = time.perf_counter() - t0
+        settled = self.price_fn(query) + Cost(seconds=elapsed)
+        return Result(query=query, value=value, cost=settled, info={"oracle": self.name})
+
+
+def quadratic_bowl(center: Mapping[str, float]) -> Callable[[Mapping[str, float]], float]:
+    """Negative squared distance to ``center`` (maximum 0 at the center)."""
+
+    def fn(params: Mapping[str, float]) -> float:
+        return -sum((float(params[k]) - float(v)) ** 2 for k, v in center.items())
+
+    return fn

cadaques/oracles/ising.py

@@ -0,0 +1,134 @@
+"""Canonical illustrative oracle: the two-dimensional Ising model.
+
+The campaign it supports is a textbook discovery task with an exact
+analytic answer: locate the critical temperature of the 2D Ising
+model by maximizing the magnetic susceptibility. Onsager (1944):
+
+    T_c = 2 / ln(1 + sqrt(2)) ≈ 2.269185  (J = k_B = 1)
+
+The oracle is a checkerboard-Metropolis Monte Carlo simulation whose
+*fidelity knobs* — lattice size ``L`` and number of measurement
+``sweeps`` — carry genuine, heterogeneous cost: accuracy is bought
+with compute. This makes it a faithful miniature of real discovery
+oracles, where every answer has a price and better answers cost more.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+
+import numpy as np
+
+from ..core.cost import Cost
+from ..core.protocols import Query, Result
+
+#: Onsager's exact critical temperature (J = k_B = 1).
+T_C_EXACT: float = 2.0 / np.log(1.0 + np.sqrt(2.0))
+
+
+@dataclass
+class Ising2DOracle:
+    """Metered Monte Carlo oracle for the 2D Ising model.
+
+    Parameters
+    ----------
+    default_L, default_sweeps, default_equilibration:
+        Fidelity defaults used when a query does not specify them.
+    seconds_per_spin_sweep:
+        Ex-ante cost model: declared price is proportional to
+        ``L**2 * (equilibration + sweeps)``. The settled cost inside
+        each Result is the *measured* wall time, so declared/settled
+        discrepancies are visible in the ledger by construction.
+    seed:
+        Base seed; each evaluation derives an independent stream.
+    """
+
+    default_L: int = 24
+    default_sweeps: int = 400
+    default_equilibration: int = 200
+    seconds_per_spin_sweep: float = 2.5e-8
+    seed: int | None = None
+
+    def __post_init__(self) -> None:
+        self._seed_sequence = np.random.SeedSequence(self.seed)
+
+    # -- helpers ------------------------------------------------------
+    def _fidelity(self, query: Query) -> tuple[int, int, int]:
+        fid = query.fidelity
+        L = int(fid.get("L", self.default_L))
+        sweeps = int(fid.get("sweeps", self.default_sweeps))
+        equilibration = int(fid.get("equilibration", self.default_equilibration))
+        if L < 2 or sweeps < 1 or equilibration < 0:
+            raise ValueError(f"Invalid fidelity: L={L}, sweeps={sweeps}, eq={equilibration}")
+        return L, sweeps, equilibration
+
+    # -- Oracle protocol ----------------------------------------------
+    def price(self, query: Query) -> Cost:
+        L, sweeps, equilibration = self._fidelity(query)
+        seconds = self.seconds_per_spin_sweep * L * L * (sweeps + equilibration)
+        return Cost(seconds=seconds, cpu_hours=seconds / 3600.0)
+
+    def evaluate(self, query: Query) -> Result:
+        T = float(query.params["T"])
+        if T <= 0:
+            raise ValueError(f"Temperature must be positive, got T={T}")
+        L, sweeps, equilibration = self._fidelity(query)
+        rng = np.random.default_rng(self._seed_sequence.spawn(1)[0])
+
+        t0 = time.perf_counter()
+        chi, abs_m = _susceptibility(T=T, L=L, sweeps=sweeps, equilibration=equilibration, rng=rng)
+        elapsed = time.perf_counter() - t0
+
+        settled = Cost(seconds=elapsed, cpu_hours=elapsed / 3600.0)
+        return Result(
+            query=query,
+            value=chi,
+            cost=settled,
+            info={"abs_magnetization": abs_m, "L": L, "sweeps": sweeps, "T": T},
+        )
+
+
+# ----------------------------------------------------------------------
+# Vectorized checkerboard Metropolis
+# ----------------------------------------------------------------------
+
+def _neighbor_sum(spins: np.ndarray) -> np.ndarray:
+    return (
+        np.roll(spins, 1, axis=0)
+        + np.roll(spins, -1, axis=0)
+        + np.roll(spins, 1, axis=1)
+        + np.roll(spins, -1, axis=1)
+    )
+
+
+def _sweep(spins: np.ndarray, beta: float, masks: tuple[np.ndarray, np.ndarray], rng: np.random.Generator) -> None:
+    """One full Metropolis sweep via two checkerboard half-updates."""
+    for mask in masks:
+        delta_e = 2.0 * spins * _neighbor_sum(spins)
+        accept = (delta_e <= 0) | (rng.random(spins.shape) < np.exp(-beta * delta_e))
+        spins[mask & accept] *= -1
+
+
+def _susceptibility(
+    *, T: float, L: int, sweeps: int, equilibration: int, rng: np.random.Generator
+) -> tuple[float, float]:
+    """Magnetic susceptibility per spin, chi = beta * N * (<m^2> - <|m|>^2)."""
+    beta = 1.0 / T
+    spins = rng.choice(np.array([-1, 1], dtype=np.int8), size=(L, L)).astype(np.int8)
+
+    ii, jj = np.indices((L, L))
+    checkerboard = (ii + jj) % 2 == 0
+    masks = (checkerboard, ~checkerboard)
+
+    for _ in range(equilibration):
+        _sweep(spins, beta, masks, rng)
+
+    m_samples = np.empty(sweeps)
+    for k in range(sweeps):
+        _sweep(spins, beta, masks, rng)
+        m_samples[k] = spins.mean()
+
+    abs_m = float(np.abs(m_samples).mean())
+    chi = beta * L * L * float((m_samples**2).mean() - abs_m**2)
+    return chi, abs_m

cadaques-0.1.0.dist-info/METADATA

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: cadaques
+Version: 0.1.0
+Summary: Cost-Aware Dual Architecture for QUery-Efficient diScovery: autonomous discovery campaigns — any oracle, any driver, one budget.
+Project-URL: Repository, https://github.com/jorgebravoabad/cadaques
+Author-email: Jorge Bravo-Abad <jorge.bravo@uam.es>
+License: MIT
+License-File: LICENSE
+Keywords: active-learning,autonomous-discovery,bayesian-optimization,cost-aware,materials-science,self-driving-labs
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CADAQUES
+
+**Cost-Aware Dual Architecture for QUery-Efficient diScovery**
+
+*An open-source framework for autonomous discovery campaigns: any oracle, any driver, one budget.*
+
+CADAQUES decouples autonomous discovery into two symmetric protocols. A metered
+**Oracle** abstracts anything that answers queries at a price — a simulator, a
+laboratory instrument, an analytic function. A **Driver** abstracts anything that
+decides what to ask next — random search, Bayesian optimization, gradient methods,
+LLM agents. Between them sits the framework's one structural commitment: **cost is
+a first-class primitive**. Every oracle query and every driver decision is priced
+in heterogeneous currencies (wall time, CPU hours, euros, tokens) and charged
+against a single campaign budget. Campaigns end when the budget is exhausted, not
+when an iteration counter runs out, and all results are reported as performance
+per unit cost. *Every query counts.*
+
+## Installation
+
+```bash
+pip install git+https://github.com/jorgebravoabad/cadaques.git
+```
+
+Or, for development:
+
+```bash
+git clone https://github.com/jorgebravoabad/cadaques.git
+cd cadaques
+pip install -e .
+```
+
+A PyPI release is planned; see the roadmap below.
+
+## Quickstart: a discovery campaign with an exact answer
+
+Locate the critical temperature of the 2D Ising model by maximizing the magnetic
+susceptibility under a fixed compute budget. Onsager's exact result,
+T_c = 2/ln(1+√2) ≈ 2.269, provides the ground truth against which any driver
+can be validated.
+
+```python
+from cadaques import Budget, Campaign, Cost
+from cadaques.drivers import AnnealedLocalDriver
+from cadaques.oracles import Ising2DOracle, T_C_EXACT
+
+oracle = Ising2DOracle(seed=0)
+driver = AnnealedLocalDriver(
+    space={"T": (1.5, 3.5)},
+    fidelity={"L": 24, "sweeps": 400},
+    seed=0,
+)
+campaign = Campaign(oracle, driver, Budget(total=Cost(seconds=30.0)))
+
+outcome = campaign.run()
+print(f"Best T = {outcome.best.query.params['T']:.3f}  (exact: {T_C_EXACT:.3f})")
+print(f"Queries: {outcome.n_queries}, stop reason: {outcome.stop_reason}")
+print(f"Spent: {outcome.budget.spent}")
+```
+
+## Design principles
+
+- **Dual agnosticism.** Oracles and Drivers are `typing.Protocol` classes with
+  two methods each. Anything that speaks the protocol plugs in.
+- **Declared vs. settled cost.** Oracles declare a price *ex ante*
+  (`oracle.price(query)`); the actual cost is settled *ex post* inside each
+  `Result`. Real oracles deviate from their estimates — the ledger records both,
+  and the discrepancy is itself an observable.
+- **Both sides are metered.** Driver decisions cost wall time — and tokens, if the
+  driver is an LLM agent. A campaign's economics include the price of intelligence,
+  enabling the question: *when does an expensive smart driver beat a cheap dumb one?*
+- **Budget-aware strategies.** Drivers receive a read-only `BudgetView` and may
+  adapt: the reference `AnnealedLocalDriver` explores while rich and exploits
+  while poor.
+- **The ledger is the provenance.** Every transaction (declared, settled,
+  timestamped) exports to JSONL: a complete, replayable trace of the campaign.
+
+## Status and roadmap
+
+`0.1.0` — core protocols, campaign runner, multi-currency budget and ledger,
+reference drivers, and a canonical Ising-2D oracle with fidelity-dependent cost.
+
+This is an early release: the API may evolve until `1.0`. Planned next steps
+include a Bayesian-optimization driver, campaign replay, expanded documentation,
+a PyPI release, and an LLM-agent driver adapter.
+
+## Citation
+
+If you use CADAQUES in academic work, please cite it (see `CITATION.cff`).
+A Zenodo DOI badge will appear here upon release.
+
+## License
+
+MIT.

cadaques-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+cadaques/__init__.py,sha256=TetRVyC7IYAxmdTWbxF6yseU1tq1MKaVBIY0zLxFXJI,659
+cadaques/core/__init__.py,sha256=WIiWii9CPJCJZYZsd8O2CkkquhSUBWkzCPyBlhS6qMo,214
+cadaques/core/campaign.py,sha256=4jBRHHCb7qV6Sz5DgirKbdNC-hs0mo4mTXjNiXNog-g,4826
+cadaques/core/cost.py,sha256=kiPTCg-LrCd2fx7BoV6Np-F3Hejzh4zbe3W27pSGpyo,4619
+cadaques/core/ledger.py,sha256=cYUwS5Zy7AEGZ3JNTAWeZWMobgS3nqa0w745w8QaqR0,2933
+cadaques/core/protocols.py,sha256=KWnYeIy7ioBkq8sHq5nzi7Ppjfb2oVG2-Ty8AcffGjk,2518
+cadaques/drivers/__init__.py,sha256=Kn4JwKQdqZPbpzL5DA3I6AU_sBF5lPeuaoWe4I_8S1Y,57
+cadaques/drivers/reference.py,sha256=v7mgzpP6RBMnZFLyTT74DEriNHpSzzJikynZ2xsb38E,3483
+cadaques/oracles/__init__.py,sha256=7kaO5ZYTW0z1bInWd-t4PBjljfuVbcLLkKP_dqoOkTg,97
+cadaques/oracles/analytic.py,sha256=vE6A3GtmOMm9NAyB011968lN5ekBxy9ula3l8ErSYIQ,1730
+cadaques/oracles/ising.py,sha256=USYLUfDoTET_r-OXFwgtXQvQAA9eQUKEMsel9PbWs1g,5002
+cadaques-0.1.0.dist-info/METADATA,sha256=hStmEClW3GM2lbgir1SNZVV2B8KSBXTdPhIowTWGFas,4664
+cadaques-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+cadaques-0.1.0.dist-info/licenses/LICENSE,sha256=4B8R4NG-iP-hN4YOpwtjgYINw_ZeOX_uaLeIYQMrnso,1073
+cadaques-0.1.0.dist-info/RECORD,,

cadaques-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cadaques-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jorge Bravo-Abad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.