quantized-lab 0.8.0__py3-none-any.whl

quantized/routes/fitting.py

@@ -0,0 +1,379 @@
+"""Thin fitting routes: list models, auto-guess, run a bounded NLLS fit.
+
+No algorithms here — the math is in ``calc.fitting``/``calc.fit_models``/
+``calc.fit_autoguess``. The model is chosen by name and resolved through the
+registry (no eval); the curve_fit ``model_fcn`` is a closure over ``evaluate``.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+from fastapi import APIRouter, HTTPException
+from numpy.typing import NDArray
+from pydantic import BaseModel
+
+from quantized.calc.fit_autoguess import auto_guess
+from quantized.calc.fit_bootstrap import bootstrap_fit, fit_posterior
+from quantized.calc.fit_equation import default_guesses, equation_model
+from quantized.calc.fit_findxy import find_x, find_y
+from quantized.calc.fit_models import FIT_MODELS, evaluate
+from quantized.calc.fit_scan import scan_models
+from quantized.calc.fitting import curve_fit
+from quantized.routes._payload import to_jsonable
+
+ModelFn = Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]]
+
+router = APIRouter(prefix="/api/fitting", tags=["fitting"])
+
+
+class GuessRequest(BaseModel):
+    model: str
+    x: list[float]
+    y: list[float]
+
+
+class FitRequest(BaseModel):
+    model: str
+    x: list[float]
+    y: list[float]
+    p0: list[float] | None = None
+    lower: list[float] | None = None
+    upper: list[float] | None = None
+    weights: list[float] | None = None
+    fixed: list[bool] | None = None
+    calc_errors: bool = True
+
+
+def _require_model(name: str) -> None:
+    if name not in FIT_MODELS:
+        raise HTTPException(status_code=422, detail=f"unknown model: {name}")
+
+
+@router.get("/models")
+def list_models() -> dict[str, Any]:
+    """Registry of fit models with their parameter names and defaults."""
+    models = [
+        {
+            "name": name,
+            "category": spec["category"],
+            "paramNames": spec["paramNames"],
+            "nParams": spec["nParams"],
+            "p0": spec["p0"],
+            "lb": spec["lb"],
+            "ub": spec["ub"],
+        }
+        for name, spec in FIT_MODELS.items()
+    ]
+    return {"models": to_jsonable(models)}
+
+
+@router.post("/autoguess")
+def autoguess(req: GuessRequest) -> dict[str, Any]:
+    """Initial-parameter guess for ``model`` given (x, y)."""
+    _require_model(req.model)
+    try:
+        p0 = auto_guess(req.model, req.x, req.y)
+    except (ValueError, KeyError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return {"p0": to_jsonable(p0)}
+
+
+@router.post("/fit")
+def fit(req: FitRequest) -> dict[str, Any]:
+    """Bounded nonlinear least-squares fit of a named model to (x, y)."""
+    _require_model(req.model)
+
+    def model_fcn(
+        xx: NDArray[np.float64], pp: NDArray[np.float64]
+    ) -> NDArray[np.float64]:
+        return evaluate(req.model, xx, pp)
+
+    try:
+        p0 = req.p0 if req.p0 is not None else auto_guess(req.model, req.x, req.y)
+        result = curve_fit(
+            req.x,
+            req.y,
+            model_fcn,
+            p0,
+            lower=req.lower,
+            upper=req.upper,
+            weights=req.weights,
+            fixed=req.fixed,
+            calc_errors=req.calc_errors,
+        )
+    except (ValueError, KeyError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return to_jsonable(result)  # type: ignore[no-any-return]
+
+
+class BootstrapRequest(BaseModel):
+    model: str
+    x: list[float]
+    y: list[float]
+    p0: list[float]
+    n_boot: int = 500
+    method: str = "residual"
+    seed: int = 0
+    alpha: float = 0.05
+    lower: list[float] | None = None
+    upper: list[float] | None = None
+    # Opt-in (gap #29): the full bootstrap replicate matrix, for corner-plot
+    # rendering. Default False keeps the ordinary response small.
+    return_samples: bool = False
+
+
+@router.post("/bootstrap")
+def bootstrap(req: BootstrapRequest) -> dict[str, Any]:
+    """Bootstrap parameter CIs for a registry-model fit (calc.fit_bootstrap)."""
+    _require_model(req.model)
+
+    def model_fcn(xa: NDArray[np.float64], p: NDArray[np.float64]) -> NDArray[np.float64]:
+        return np.asarray(evaluate(req.model, xa, p), dtype=float)
+
+    try:
+        return to_jsonable(  # type: ignore[no-any-return]
+            bootstrap_fit(
+                np.asarray(req.x, dtype=float),
+                np.asarray(req.y, dtype=float),
+                model_fcn,
+                req.p0,
+                n_boot=req.n_boot,
+                method=req.method,
+                seed=req.seed,
+                alpha=req.alpha,
+                lower=req.lower,
+                upper=req.upper,
+                return_samples=req.return_samples,
+            )
+        )
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+# ── Custom equation models (GOTO #1) ────────────────────────────────────────
+# The equation text is the model; calc.fit_equation parses it with the no-eval
+# RPN interpreter (the ONLY equation-evaluation path) and the fit runs through
+# the same curve_fit engine as registry models, so the result shape (params/
+# errors/R2/chiSqRed/RMSE/AIC/yFit) is identical.
+
+
+class EquationValidateRequest(BaseModel):
+    equation: str
+
+
+class EquationFitRequest(BaseModel):
+    equation: str
+    x: list[float]
+    y: list[float]
+    guesses: list[float] | None = None
+    # Bounds may hold null entries = unbounded on that side (JSON cannot
+    # carry Infinity); mapped to -inf/+inf before curve_fit.
+    lower: list[float | None] | None = None
+    upper: list[float | None] | None = None
+    weights: list[float] | None = None
+    fixed: list[bool] | None = None
+    calc_errors: bool = True
+
+
+@router.post("/equation/validate")
+def equation_validate(req: EquationValidateRequest) -> dict[str, Any]:
+    """Validate a custom fit equation; 200 with ok/params[]/error (live UI)."""
+    try:
+        _, names = equation_model(req.equation)
+    except (ValueError, IndexError) as exc:
+        return {"ok": False, "params": [], "error": str(exc)}
+    return {"ok": True, "params": names}
+
+
+@router.post("/equation/fit")
+def equation_fit(req: EquationFitRequest) -> dict[str, Any]:
+    """Fit a custom equation model to (x, y); same result shape as /fit."""
+    try:
+        fcn, names = equation_model(req.equation)
+        if not names:
+            raise ValueError("equation has no free parameters to fit")
+        p0 = req.guesses if req.guesses is not None else default_guesses(names)
+        if len(p0) != len(names):
+            raise ValueError(f"expected {len(names)} guesses, got {len(p0)}")
+        lower = (
+            [-math.inf if v is None else v for v in req.lower]
+            if req.lower is not None
+            else None
+        )
+        upper = (
+            [math.inf if v is None else v for v in req.upper]
+            if req.upper is not None
+            else None
+        )
+        result = curve_fit(
+            req.x,
+            req.y,
+            fcn,
+            p0,
+            lower=lower,
+            upper=upper,
+            weights=req.weights,
+            fixed=req.fixed,
+            calc_errors=req.calc_errors,
+        )
+    except (ValueError, KeyError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    out: dict[str, Any] = to_jsonable(result)
+    out["paramNames"] = names
+    return out
+
+
+# ── AICc model quick-scan (GOTO #6) ─────────────────────────────────────────
+
+
+class ScanEquationCandidate(BaseModel):
+    name: str
+    equation: str
+    guesses: list[float] | None = None
+
+
+class ScanRequest(BaseModel):
+    x: list[float]
+    y: list[float]
+    # Optional per-point 1-sigma errors -> fit weights 1/dy^2.
+    dy: list[float] | None = None
+    # None -> the default candidate set: every registry model with
+    # nParams < n/3 (calc.fit_scan.default_candidates explains the cut).
+    models: list[str] | None = None
+    # Saved custom equation models ride along as extra candidates.
+    equations: list[ScanEquationCandidate] | None = None
+
+
+@router.post("/scan")
+def scan(req: ScanRequest) -> dict[str, Any]:
+    """Fit all candidate models and rank by AICc (calc.fit_scan.scan_models).
+
+    Per-candidate failures come back as error entries in ``results`` — only
+    invalid scan INPUT (length mismatch, bad dy, too few points) is a 422.
+    """
+    try:
+        result = scan_models(
+            req.x,
+            req.y,
+            dy=req.dy,
+            models=req.models,
+            equations=(
+                [e.model_dump() for e in req.equations] if req.equations is not None else None
+            ),
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return to_jsonable(result)  # type: ignore[no-any-return]
+
+
+class PosteriorRequest(BaseModel):
+    model: str
+    x: list[float]
+    y: list[float]
+    p0: list[float]
+    num_steps: int = 10000
+    burn_in: int = 1000
+    seed: int = 0
+    lower: list[float] | None = None
+    upper: list[float] | None = None
+
+
+@router.post("/posterior")
+def posterior(req: PosteriorRequest) -> dict[str, Any]:
+    """MCMC posterior for a registry-model fit (calc.fit_bootstrap.fit_posterior)."""
+    _require_model(req.model)
+
+    def model_fcn(xa: NDArray[np.float64], p: NDArray[np.float64]) -> NDArray[np.float64]:
+        return np.asarray(evaluate(req.model, xa, p), dtype=float)
+
+    try:
+        return to_jsonable(  # type: ignore[no-any-return]
+            fit_posterior(
+                np.asarray(req.x, dtype=float),
+                np.asarray(req.y, dtype=float),
+                model_fcn,
+                req.p0,
+                num_steps=req.num_steps,
+                burn_in=req.burn_in,
+                seed=req.seed,
+                lower=req.lower,
+                upper=req.upper,
+            )
+        )
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+# ── Find X from Y / Y from X on a fitted curve (MAIN #15) ──────────────────
+# Inverse-evaluates a fit result the UI already holds (model/equation name +
+# fitted params) -- no re-fit involved. Accepts EITHER a registry ``model``
+# name or a saved custom ``equation`` string (mutually exclusive): both
+# resolve to the same ``fcn(x, p) -> y`` shape (calc.fit_models.evaluate /
+# calc.fit_equation.equation_model), so custom-equation fits get find-X/Y
+# for free, not just registry models.
+
+
+class FindXYRequest(BaseModel):
+    model: str | None = None
+    equation: str | None = None
+    params: list[float]
+    x_min: float
+    x_max: float
+    # Exactly one of x (find Y) / y (find X, all crossings) must be set.
+    x: float | None = None
+    y: float | None = None
+    grid_points: int = 2000
+
+
+@router.post("/find-xy")
+def find_xy(req: FindXYRequest) -> dict[str, Any]:
+    """Find Y at a given X, or every X where the fitted curve equals a given Y.
+
+    ``x`` set -> ``{"y": <float | null>}`` (a single evaluation).
+    ``y`` set -> ``{"x": [<float>, ...]}`` (every crossing within
+    ``[x_min, x_max]``; an empty list is a valid "no crossing" answer, not
+    an error).
+    """
+    if (req.model is None) == (req.equation is None):
+        raise HTTPException(
+            status_code=422, detail="specify exactly one of model or equation"
+        )
+    if (req.x is None) == (req.y is None):
+        raise HTTPException(
+            status_code=422, detail="specify exactly one of x (find Y) or y (find X)"
+        )
+    if req.x_max <= req.x_min:
+        raise HTTPException(status_code=422, detail="x_max must be greater than x_min")
+
+    fcn: ModelFn
+    if req.model is not None:
+        model_name = req.model
+        _require_model(model_name)
+
+        def fcn(xa: NDArray[np.float64], pp: NDArray[np.float64]) -> NDArray[np.float64]:
+            return evaluate(model_name, xa, pp)
+    else:
+        equation = req.equation
+        assert equation is not None  # narrowed by the "exactly one" check above
+        try:
+            fcn, names = equation_model(equation)
+        except (ValueError, IndexError) as exc:
+            raise HTTPException(status_code=422, detail=str(exc)) from exc
+        if len(req.params) != len(names):
+            raise HTTPException(
+                status_code=422,
+                detail=f"expected {len(names)} params for this equation, got {len(req.params)}",
+            )
+
+    try:
+        if req.x is not None:
+            return {"y": to_jsonable(find_y(fcn, req.params, req.x))}
+        assert req.y is not None  # narrowed by the "exactly one" check above
+        xs = find_x(fcn, req.params, req.y, req.x_min, req.x_max, grid_points=req.grid_points)
+        return {"x": to_jsonable(xs)}
+    except (ValueError, IndexError, ZeroDivisionError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc

quantized/routes/fitting_bumps.py

@@ -0,0 +1,97 @@
+"""Thin route for the optional bumps fit engine (GOTO #10).
+
+``POST /api/fitting/bumps`` — the fast engines (amoeba / lm / de) run
+synchronously and return the fit dict; ``engine='dream'`` submits to the
+poll-model job runner (GOTO #9) and returns ``{"job_id": ...}``: poll
+``GET /api/jobs/{id}`` for progress and fetch ``GET /api/jobs/{id}/result``
+for the same fit dict on completion. All math lives in
+``calc.fit_bumps``; the MATLAB-parity engine (``POST /api/fitting/fit``)
+remains the default fit path.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from quantized.calc.fit_autoguess import auto_guess
+from quantized.calc.fit_bumps import BUMPS_ENGINES, bumps_available, fit_bumps
+from quantized.calc.fit_models import FIT_MODELS
+from quantized.jobs import AbortFn, ProgressFn, jobs
+from quantized.routes._payload import to_jsonable
+
+router = APIRouter(prefix="/api/fitting", tags=["fitting"])
+
+
+class BumpsFitRequest(BaseModel):
+    model: str
+    x: list[float]
+    y: list[float]
+    dy: list[float] | None = None
+    p0: list[float] | None = None
+    lower: list[float] | None = None
+    upper: list[float] | None = None
+    engine: str = "amoeba"
+    # dream-only tuning (ignored by the synchronous engines)
+    samples: int = 10_000
+    burn: int = 100
+    pop: int = 10
+    return_samples: bool = False
+
+
+@router.post("/bumps")
+def bumps_fit(req: BumpsFitRequest) -> dict[str, Any]:
+    """Fit a registry model with a bumps engine (sync) or queue a DREAM job."""
+    if req.model not in FIT_MODELS:
+        raise HTTPException(status_code=422, detail=f"unknown model: {req.model}")
+    if req.engine not in BUMPS_ENGINES:
+        raise HTTPException(
+            status_code=422,
+            detail=f"unknown engine: {req.engine} (choose from {', '.join(BUMPS_ENGINES)})",
+        )
+    if not bumps_available():
+        raise HTTPException(
+            status_code=422,
+            detail=(
+                "bumps is not installed - the optional fit engine needs "
+                "'pip install quantized[bumps]'"
+            ),
+        )
+    try:
+        p0 = req.p0 if req.p0 is not None else auto_guess(req.model, req.x, req.y)
+    except (ValueError, KeyError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    kwargs: dict[str, Any] = {
+        "model": req.model,
+        "p0": [float(v) for v in p0],
+        "lower": req.lower,
+        "upper": req.upper,
+        "param_names": list(FIT_MODELS[req.model]["paramNames"]),
+        "engine": req.engine,
+        "samples": req.samples,
+        "burn": req.burn,
+        "pop": req.pop,
+        "return_samples": req.return_samples,
+    }
+
+    if req.engine == "dream":
+        # Long-running: submit through the poll-model job runner (GOTO #9).
+        def run_job(progress: ProgressFn, abort_check: AbortFn) -> Any:
+            def on_fraction(fraction: float) -> None:
+                progress(fraction, "sampling posterior")
+
+            result = fit_bumps(
+                req.x, req.y, req.dy,
+                progress_callback=on_fraction, abort_check=abort_check, **kwargs,
+            )
+            return to_jsonable(result)
+
+        return {"job_id": jobs.submit(run_job)}
+
+    try:
+        result = fit_bumps(req.x, req.y, req.dy, **kwargs)
+    except (ValueError, KeyError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return to_jsonable(result)  # type: ignore[no-any-return]

quantized/routes/import_template.py

@@ -0,0 +1,97 @@
+"""Thin route: Origin graph templates (``.otp``/``.otpu``) -> a
+``GraphTemplate`` JSON (gap-ecosystem plan item 5, decode-plan #21).
+
+Template files carry no worksheet data (see
+``io/origin_project/templates.py``'s module docstring), so this is a
+SEPARATE import surface from the dataset importers in ``routes/parsers.py``
+-- ``.otp``/``.otpu`` are deliberately never registered in ``io/registry.py``
+(the single-registry rule governs DATA parsers; a template is a style
+preset, not a DataStruct).
+
+Two ways in, mirroring ``routes/parsers.py``'s ``/import``+``/upload`` split:
+``GET`` reads a path the server can already see (desktop / CLI use, the same
+containment guard as ``parsers.py``'s ``/import``); ``POST /upload`` takes
+the file's bytes from the browser (file-picker / drag-drop). The frontend
+wrapper (``api.ts`` client method + an "Import Origin template..." UI
+hook-in) is explicitly OUT of scope for this item -- booked separately.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, UploadFile
+
+from quantized.io.origin_project.container import OriginProjectError
+from quantized.io.origin_project.templates import read_origin_template
+
+router = APIRouter(prefix="/api/import/template", tags=["import"])
+
+
+def _allowed_roots() -> tuple[str, ...]:
+    """Mirrors ``routes/parsers.py``'s containment allowlist (home / cwd /
+    temp, widened by ``QZ_DATA_ROOTS``) -- duplicated rather than imported so
+    the path-traversal guard below stays inline in the function the static
+    analyzer traces end to end (see ``parsers.py``'s identical comment)."""
+    raw = [Path.home(), Path.cwd(), Path(tempfile.gettempdir())]
+    raw += [Path(p) for p in os.environ.get("QZ_DATA_ROOTS", "").split(os.pathsep) if p.strip()]
+    roots: list[str] = []
+    for r in raw:
+        try:
+            roots.append(os.path.realpath(r))
+        except OSError:
+            continue
+    return tuple(roots)
+
+
+@router.get("")
+def import_template(path: str) -> dict[str, Any]:
+    """Read a server-visible Origin graph template (``.otp``/``.otpu``) by
+    path into a ``GraphTemplate``-shaped dict.
+
+    The path is ``os.path.realpath``-normalized (collapsing ``..`` and
+    symlinks) and confined to an allowed root (home / cwd / temp, widen via
+    ``QZ_DATA_ROOTS``) before any filesystem access -- the same guard
+    ``routes/parsers.py``'s ``/import`` uses.
+    """
+    try:
+        resolved = os.path.realpath(path)
+    except (OSError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail="invalid path") from exc
+    within_allowed = False
+    for root in _allowed_roots():
+        try:
+            if os.path.commonpath((root, resolved)) == root:
+                within_allowed = True
+                break
+        except ValueError:
+            continue  # different drives (Windows) -> not under this root
+    if not within_allowed:
+        raise HTTPException(
+            status_code=403,
+            detail="path is outside the allowed roots (set QZ_DATA_ROOTS to widen)",
+        )
+    if not os.path.isfile(resolved):
+        raise HTTPException(status_code=404, detail=f"file not found: {path}")
+    try:
+        return read_origin_template(Path(resolved))
+    except OriginProjectError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/upload")
+async def upload_template(file: UploadFile) -> dict[str, Any]:
+    """Import an uploaded Origin graph template (browser file-picker /
+    drag-drop) into a ``GraphTemplate``-shaped dict."""
+    name = Path(file.filename or "template.otp").name or "template.otp"
+    content = await file.read()
+    try:
+        with tempfile.TemporaryDirectory() as tmp:
+            dest = Path(tmp) / name
+            dest.write_bytes(content)
+            return read_origin_template(dest)
+    except OriginProjectError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc