quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/figure_ticks.py

@@ -0,0 +1,217 @@
+"""Axis tick-label FORMATTING for matplotlib export (MAIN #24) -- mirrors the
+on-screen `AxisFormat` contract (`frontend/src/lib/uplotOpts.ts`'s
+`tickFormatter` + `frontend/src/lib/ticks.ts`'s `decimalsForIncrement`) so a
+published figure's tick labels read exactly like the interactive plot's.
+Pure layer, split out of ``calc.figure`` purely to stay under the 500-line
+god-module ceiling (mirrors ``figure_scale``/``figure_break``/``figure_overrides``).
+
+``AxisFormat`` is ``{mode: "auto"|"fixed"|"sci"|"eng", digits: number}``:
+``auto`` returns ``None`` here (matplotlib's own default formatter stays,
+unlike the frontend's own Intl-based ``auto`` formatter -- the two rendering
+engines don't need byte-identical ``auto`` output, only the explicit
+fixed/sci/eng modes the owner can actually configure per axis). ``fixed``/
+``sci``/``eng`` each floor their configured ``digits`` at whatever the DRAWN
+tick increment needs (screen-side ``decimalsForIncrement``/
+``mantissaDecimalFloor``), the same "never render two different ticks with
+the same label" guarantee MAIN #20 fixed on-screen.
+
+matplotlib has no direct equivalent of uPlot's ``values(u, splits, ...,
+foundIncr)`` callback (which receives the increment its own tick generator
+just found). A tick label is instead built one at a time by a
+``Formatter.__call__(x, pos)``, with no increment argument at all.
+``_AxisTickFormatter`` below is a ``matplotlib.ticker.Formatter`` subclass
+(not a plain ``FuncFormatter`` closure) so it can read ``self.axis`` (set by
+``Axis.set_major_formatter``) and pull ``self.axis.get_majorticklocs()``
+LAZILY, INSIDE ``__call__`` -- at draw time, after the axis's locator has
+committed to its final tick positions. A ``FuncFormatter`` closure computed
+once when the formatter is attached would instead capture whatever ticks
+existed at THAT moment, which ``tight_layout``/``savefig`` can still revise
+before the real draw -- the locator-aware subclass approach is robust to
+matplotlib recomputing ticks between attachment and draw.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from typing import Any
+
+from matplotlib.ticker import Formatter
+
+__all__ = ["apply_tick_formats", "axis_tick_formatter"]
+
+_MODES = ("fixed", "sci", "eng")
+
+
+def _pow10(k: int) -> float:
+    """Exact ``10**k`` for integer ``k`` via decimal-literal parsing --
+    mirrors the frontend's ``pow10`` (``lib/ticks.ts``), which exists because
+    ``Math.pow(10, k)`` is not guaranteed correctly rounded; both Python's
+    ``float()`` and JS's ``Number()`` ARE required to correctly round a
+    parsed decimal literal, so this stays exact on every platform."""
+    return float(f"1e{k}")
+
+
+def _js_round(v: float) -> int:
+    """``Math.round`` semantics (round half AWAY FROM negative infinity, i.e.
+    half rounds up) -- Python's builtin ``round`` is round-half-to-EVEN, which
+    disagrees with JS at exact X.5 digit counts. Only the sign/tie-break at
+    ``.5`` differs; both agree everywhere else."""
+    return math.floor(v + 0.5)
+
+
+def _decimals_for_increment(incr: float, max_decimals: int = 20) -> int:
+    """Port of the frontend's ``decimalsForIncrement`` (``lib/ticks.ts``):
+    the decimal-place FLOOR a fixed-decimal tick formatter must never go
+    below, so ticks ``incr`` apart never collapse to the same label. Starts
+    from the log10 order of magnitude, then round-trips (format -> parse ->
+    compare) upward for "nice" non-power-of-10 steps whose exact decimal form
+    needs a digit or two more than ``-log10(incr)`` alone implies."""
+    if not (incr > 0) or not math.isfinite(incr):
+        return 0
+    d = max(0, min(max_decimals, math.ceil(-math.log10(incr) - 1e-9)))
+    tol = max(incr * 1e-6, 1e-15)
+    while d < max_decimals and abs(float(f"{incr:.{d}f}") - incr) > tol:
+        d += 1
+    return d
+
+
+def _mantissa_decimal_floor(incr: float, exp: int) -> int:
+    """Port of ``mantissaDecimalFloor``: ``incr`` rescaled into the
+    mantissa's own units (divided by the value's own ``10**exp``) before
+    flooring -- used by the sci/eng formatters below."""
+    return _decimals_for_increment(incr / _pow10(exp)) if incr > 0 else 0
+
+
+def _splits_increment(locs: Any) -> float:
+    """Smallest positive gap between the axis's CURRENT major tick
+    locations -- port of the frontend's ``splitsIncrement``, minus its
+    uPlot-specific ``foundIncr`` fallback (matplotlib's Locator/Formatter
+    split has no equivalent second value fed to the formatter). A
+    degenerate axis (fewer than 2 finite ticks) returns 0, which floors
+    nothing (``max(digits, 0) == digits``) -- the same degenerate-range
+    behaviour the frontend documents for ``decimalsForIncrement``."""
+    vals = sorted(v for v in locs if math.isfinite(v))
+    incr = math.inf
+    for a, b in zip(vals, vals[1:], strict=False):
+        gap = b - a
+        if 0 < gap < incr:
+            incr = gap
+    return incr if math.isfinite(incr) else 0.0
+
+
+def _strip_neg_zero(formatted: str) -> str:
+    """Port of ``stripNegZero``: a legitimately non-zero split (e.g.
+    ``-0.00003``) can still format as "-0"/"-0.00"/"-0.00e+0" once rounded to
+    the tick's display precision -- never meaningful data (MAIN #20, the
+    owner's screenshot showed a bare "-0" tick on a dense M-H moment axis)."""
+    if not formatted.startswith("-"):
+        return formatted
+    bare = formatted[1:]
+    try:
+        return bare if float(bare) == 0 else formatted
+    except ValueError:
+        return formatted
+
+
+def _to_exponential(v: float, d: int) -> str:
+    """``v.toExponential(d)`` equivalent, in the frontend's plain (no rich
+    ``x10^n`` markup) shape: ``1.20e-3`` / ``1.20e+3`` -- NOT Python's own
+    zero-padded ``%e`` shape (``1.20e-03``). Python's ``%e`` formatting is
+    itself correctly rounded (it normalizes a mantissa that rounds up to 10
+    into the next exponent automatically, the same guarantee JS's
+    ``Number.prototype.toExponential`` makes), so this only reformats its
+    exponent -- no zero-padding, explicit sign -- rather than re-deriving the
+    mantissa by hand."""
+    mantissa, exp_str = f"{v:.{d}e}".split("e")
+    exp = int(exp_str)
+    return f"{mantissa}e{'+' if exp >= 0 else '-'}{abs(exp)}"
+
+
+def _format_fixed(v: float, digits: int, incr: float) -> str:
+    d = max(digits, _decimals_for_increment(incr))
+    return _strip_neg_zero(f"{v:.{min(20, d)}f}")
+
+
+def _format_sci(v: float, digits: int, incr: float) -> str:
+    exp = 0 if v == 0 else math.floor(math.log10(abs(v)))
+    d = max(digits, _mantissa_decimal_floor(incr, exp))
+    return _strip_neg_zero(_to_exponential(v, min(20, d)))
+
+
+def _format_eng(v: float, digits: int, incr: float) -> str:
+    """Engineering notation: mantissa in [1, 1000), exponent a multiple of 3
+    (e.g. ``1.2e-3``, ``12.3e-6``) -- port of the frontend's ``formatEng``.
+    ``v == 0`` has no meaningful exponent, so it renders bare "0". A mantissa
+    that rounds up to >= 1000 bumps the exponent by 3 and re-divides."""
+    if v == 0:
+        return "0"
+    sign = "-" if v < 0 else ""
+    av = abs(v)
+    exp = math.floor(math.floor(math.log10(av)) / 3) * 3
+    d = min(20, max(digits, _mantissa_decimal_floor(incr, exp)))
+    mantissa = av / _pow10(exp)
+    m_str = f"{mantissa:.{d}f}"
+    if float(m_str) >= 1000:
+        exp += 3
+        mantissa = av / _pow10(exp)
+        m_str = f"{mantissa:.{d}f}"
+    exp_str = f"+{exp}" if exp >= 0 else str(exp)
+    return _strip_neg_zero(f"{sign}{m_str}e{exp_str}")
+
+
+class _AxisTickFormatter(Formatter):
+    """A ``matplotlib.ticker.Formatter`` for one non-``auto`` ``AxisFormat``
+    mode. See the module doc for why this is a ``Formatter`` subclass
+    (reading ``self.axis`` lazily) rather than a ``FuncFormatter`` closure."""
+
+    def __init__(self, mode: str, digits: float) -> None:
+        self.mode = mode
+        self.digits = max(0, min(20, _js_round(digits)))
+
+    def __call__(self, x: float, pos: int | None = None) -> str:
+        # `self.axis` is typed as a union of matplotlib's real `Axis` and two
+        # internal placeholder types (`_DummyAxis`/`_AxisWrapper`) that don't
+        # declare `get_majorticklocs` -- getattr-with-default sidesteps the
+        # union-attr mismatch; a placeholder axis (never seen in practice,
+        # only used by matplotlib internals for detached artists) just skips
+        # the increment floor, same as the "no axis attached yet" case.
+        get_locs = getattr(self.axis, "get_majorticklocs", None)
+        locs = get_locs() if callable(get_locs) else ()
+        incr = _splits_increment(locs)
+        if self.mode == "sci":
+            return _format_sci(x, self.digits, incr)
+        if self.mode == "eng":
+            return _format_eng(x, self.digits, incr)
+        return _format_fixed(x, self.digits, incr)
+
+
+def axis_tick_formatter(fmt: Mapping[str, Any] | None) -> Formatter | None:
+    """Build a matplotlib tick ``Formatter`` from an ``AxisFormat``-shaped
+    mapping (``{"mode": ..., "digits": ...}``). ``None``/an ``"auto"`` mode
+    returns ``None`` -- matplotlib's own default formatter stays untouched,
+    the same "no override" contract ``apply_axis_scale``'s callers rely on
+    for ``"linear"``."""
+    if not fmt:
+        return None
+    mode = fmt.get("mode", "auto")
+    if mode not in _MODES:
+        return None
+    digits = fmt.get("digits", 2)
+    return _AxisTickFormatter(str(mode), float(digits))
+
+
+def apply_tick_formats(
+    ax: Any, x_fmt: Mapping[str, Any] | None, y_fmt: Mapping[str, Any] | None
+) -> None:
+    """Apply ``x_fmt``/``y_fmt`` (``AxisFormat``-shaped mappings) to ``ax``'s
+    x/y major tick formatter, when non-``auto``. The single application
+    chokepoint shared by ``figure.draw_series_axes`` (single-figure export +
+    figure-page panels) and ``figure_break.render_breaks_impl`` (broken-axis
+    panels) -- MAIN #24."""
+    xf = axis_tick_formatter(x_fmt)
+    if xf is not None:
+        ax.xaxis.set_major_formatter(xf)
+    yf = axis_tick_formatter(y_fmt)
+    if yf is not None:
+        ax.yaxis.set_major_formatter(yf)

quantized/calc/fit_autoguess.py

@@ -0,0 +1,156 @@
+"""Initial-parameter estimation for curve fitting. Port of fitting.autoGuess.
+
+Pure calc layer. Each model name maps to a deterministic heuristic that derives
+starting parameters from the (x, y) data, beginning from the model's default p0
+and overriding specific entries. Replicated verbatim (including MATLAB quirks).
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+from numpy.typing import ArrayLike
+
+from .fit_models import FIT_MODELS
+
+__all__ = ["auto_guess"]
+
+_EPS = float(np.finfo(float).eps)
+
+
+def _first(mask: np.ndarray) -> int:
+    """First True index, or -1 if none (MATLAB find(...,1))."""
+    idx = np.flatnonzero(mask)
+    return int(idx[0]) if idx.size else -1
+
+
+def auto_guess(model_name: str, x: ArrayLike, y: ArrayLike) -> list[float]:
+    """Estimate starting parameters for ``model_name`` from data. Port of autoGuess."""
+    if model_name not in FIT_MODELS:
+        raise ValueError(f'Model "{model_name}" not found.')
+    p0 = [float(v) for v in FIT_MODELS[model_name]["p0"]]
+    xv = np.asarray(x, dtype=float).ravel()
+    yv = np.asarray(y, dtype=float).ravel()
+    x_range = float(np.ptp(xv))
+    y_range = float(np.ptp(yv))
+    y_mean = float(np.mean(yv))
+    x_mean = float(np.mean(xv))
+    n = xv.size
+    y_min = float(np.min(yv))
+    y_max = float(np.max(yv))
+
+    if model_name == "Linear":
+        p0[0] = (yv[-1] - yv[0]) / max(x_range, _EPS)
+        p0[1] = yv[0] - p0[0] * xv[0]
+    elif model_name in ("Quadratic", "Cubic", "Poly 4"):
+        p0[-2] = (yv[-1] - yv[0]) / max(x_range, _EPS)
+        p0[-1] = y_mean
+    elif model_name == "Exponential Decay":
+        p0[0], p0[1], p0[2] = y_range, x_range / 3, y_min
+        y_norm = (yv - y_min) / max(y_range, _EPS)
+        e_idx = _first(y_norm <= math.exp(-1))
+        if e_idx >= 0:
+            p0[1] = abs(xv[e_idx] - xv[0])
+    elif model_name == "Stretched Exponential":
+        p0[0], p0[1], p0[2], p0[3] = y_range, x_range / 3, 0.7, y_min
+    elif model_name == "Bi-exponential Decay":
+        p0[0], p0[1], p0[2], p0[3], p0[4] = (
+            y_range * 0.6, x_range / 5, y_range * 0.4, x_range / 1.5, y_min,
+        )
+    elif model_name == "Exponential Growth":
+        p0[0], p0[1], p0[2] = yv[0], x_range / 3, y_min
+    elif model_name == "Saturation Growth":
+        p0[0], p0[1], p0[2] = y_range, x_range / 3, y_min
+    elif model_name in ("Gaussian", "Lorentzian", "Pseudo-Voigt"):
+        pk = int(np.argmax(yv))
+        p0[0], p0[1] = yv[pk], xv[pk]
+        hm_idx = np.flatnonzero(yv >= yv[pk] / 2)
+        fwhm = (xv[hm_idx[-1]] - xv[hm_idx[0]]) if hm_idx.size >= 2 else x_range / 10
+        p0[2] = fwhm / 2.355 if model_name == "Gaussian" else fwhm / 2
+        if model_name == "Pseudo-Voigt":
+            p0[3] = 0.5
+    elif model_name in ("Power Law", "Allometric"):
+        pos = (xv > 0) & (yv > 0)
+        if int(pos.sum()) > 2:
+            log_x = np.log(xv[pos])
+            log_y = np.log(yv[pos])
+            slope = (n * np.sum(log_x * log_y) - np.sum(log_x) * np.sum(log_y)) / max(
+                n * np.sum(log_x**2) - np.sum(log_x) ** 2, _EPS
+            )
+            p0[0] = float(np.exp(np.mean(log_y) - slope * np.mean(log_x)))
+            p0[1] = float(slope)
+        if model_name == "Power Law":
+            p0[2] = 0.0
+    elif model_name in ("Logistic", "Tanh"):
+        p0[0] = y_range
+        cross = _first(np.diff(np.sign(yv - y_mean)) != 0)
+        p0[2] = xv[cross] if cross >= 0 else x_mean
+        if n > 2:
+            dy = np.diff(yv) / np.diff(xv)
+            steep = int(np.argmax(np.abs(dy)))
+            p0[1] = abs(dy[steep]) * 4 / max(y_range, _EPS)
+        else:
+            p0[1] = 4 / max(x_range, _EPS)
+        p0[3] = y_min
+    elif model_name == "Langevin":
+        p0[0] = float(np.max(np.abs(yv)))
+        if n > 2:
+            slope0 = abs(yv[1] - yv[0]) / max(abs(xv[1] - xv[0]), _EPS)
+            p0[1] = p0[0] / max(3 * slope0, _EPS)
+    elif model_name == "Curie-Weiss":
+        if np.all(yv > 0):
+            inv_y = 1.0 / yv
+            slope = (inv_y[-1] - inv_y[0]) / max(x_range, _EPS)
+            p0[1] = xv[0] - inv_y[0] / max(slope, _EPS)
+            p0[0] = float(np.mean(yv * (xv - p0[1])))
+    elif model_name == "Bloch T^3/2":
+        p0[0] = y_max
+        p0[1] = (1 - y_min / y_max) / max(xv[-1], _EPS) ** 1.5
+    elif model_name == "Arrhenius":
+        p0[0] = y_max
+        pos = (yv > 0) & (xv > 0)
+        if int(pos.sum()) > 2:
+            inv_x = 1.0 / xv[pos]
+            ln_y = np.log(yv[pos])
+            slope = (ln_y[-1] - ln_y[0]) / (inv_x[-1] - inv_x[0])
+            p0[1] = abs(float(slope))
+    elif model_name == "Langmuir":
+        p0[0] = y_max
+        k_idx = _first(yv >= y_max / 2)
+        if k_idx >= 0:
+            p0[1] = abs(xv[k_idx])
+    elif model_name == "Logarithmic":
+        pos = xv > 0
+        if int(pos.sum()) > 1:
+            log_x = np.log(xv[pos])
+            p0[0] = y_range / max(float(np.ptp(log_x)), _EPS)
+            p0[1] = y_mean - p0[0] * float(np.mean(log_x))
+    elif model_name == "Square Root":
+        pos = xv >= 0
+        if int(pos.sum()) > 1:
+            sqrt_x = np.sqrt(xv[pos])
+            p0[0] = y_range / max(float(np.ptp(sqrt_x)), _EPS)
+            p0[1] = y_mean - p0[0] * float(np.mean(sqrt_x))
+    elif model_name == "Brillouin":
+        p0[0], p0[1], p0[2], p0[3] = float(np.max(np.abs(yv))), 0.5, 2, 300
+    elif model_name == "Stoner-Wohlfarth":
+        p0[0] = float(np.max(np.abs(yv)))
+        sign_change = _first(np.diff(np.sign(yv)) != 0)
+        p0[1] = abs(xv[sign_change]) if sign_change >= 0 else x_range / 4
+        p0[2] = x_range / 2
+    elif model_name == "VFT":
+        p0[0] = float(np.min(yv[yv > 0]))
+        p0[1], p0[2] = 0.05, 0
+    elif model_name == "Debye":
+        low = xv < xv[-1] * 0.1
+        p0[0] = float(np.mean(yv[low] / np.maximum(xv[low], _EPS))) if int(low.sum()) > 1 else 0.0
+        p0[1], p0[2] = float(np.max(xv)) * 2, 1
+    elif model_name == "Einstein":
+        p0[0], p0[1], p0[2] = 0.0, float(np.max(xv)) * 0.5, 1
+    elif model_name == "Debye+Einstein":
+        low = xv < xv[-1] * 0.1
+        p0[0] = float(np.mean(yv[low] / np.maximum(xv[low], _EPS))) if int(low.sum()) > 1 else 0.0
+        p0[1], p0[2], p0[3], p0[4] = float(np.max(xv)) * 2, float(np.max(xv)) * 0.5, 0.5, 1
+
+    return p0

quantized/calc/fit_bootstrap.py

@@ -0,0 +1,163 @@
+"""Bootstrap confidence intervals + MCMC posteriors for curve fits.
+
+ORIGIN_GAP_PLAN #29 — honest uncertainty beyond the asymptotic covariance
+Origin reports. ``bootstrap_fit`` resamples (residuals or data pairs) and
+refits; ``fit_posterior`` bridges a fit into :func:`calc.mcmc.mcmc_sample`
+(Gaussian likelihood at the fit's RMSE noise scale, flat priors within the
+bounds). Both are deterministic for a given ``seed``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from quantized.calc.fitting import curve_fit
+from quantized.calc.mcmc import mcmc_sample
+
+__all__ = ["bootstrap_fit", "fit_posterior"]
+
+ModelFn = Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]]
+
+
+def bootstrap_fit(
+    x: ArrayLike,
+    y: ArrayLike,
+    model_fcn: ModelFn,
+    p0: Sequence[float],
+    *,
+    n_boot: int = 500,
+    method: str = "residual",
+    seed: int = 0,
+    alpha: float = 0.05,
+    lower: Sequence[float] | None = None,
+    upper: Sequence[float] | None = None,
+    return_samples: bool = False,
+) -> dict[str, Any]:
+    """Bootstrap parameter uncertainty for a :func:`calc.fitting.curve_fit`.
+
+    ``method='residual'`` resamples the base fit's residuals onto its fitted
+    curve (fixed design — right when x is set by the instrument);
+    ``'pairs'`` resamples (x, y) rows (robust to heteroscedasticity).
+    Each replicate refits starting from the base parameters; failed refits
+    are dropped and counted. Returns the base fit plus per-parameter
+    bootstrap SEs and percentile (1-alpha) CIs.
+
+    ``return_samples=True`` additionally returns the full bootstrap replicate
+    matrix as ``boot_samples`` (``[n_kept x P]``) -- opt-in because it can be
+    large (``n_boot`` rows) and the summary stats above are usually enough on
+    their own; :func:`calc.figure_corner.render_corner_figure` is the main
+    consumer, mirroring how :func:`fit_posterior` already returns its chain.
+    """
+    if method not in ("residual", "pairs"):
+        raise ValueError(f'method must be "residual" or "pairs", got "{method}"')
+    if n_boot < 20:
+        raise ValueError("n_boot must be >= 20 for meaningful percentiles")
+    if not 0 < alpha < 1:
+        raise ValueError("alpha must be in (0, 1)")
+
+    xv = np.asarray(x, dtype=float).ravel()
+    yv = np.asarray(y, dtype=float).ravel()
+    base = curve_fit(xv, yv, model_fcn, p0, lower=lower, upper=upper)
+    params = np.asarray(base["params"], dtype=float)
+    y_fit = np.asarray(base["yFit"], dtype=float)
+    resid = yv - y_fit
+    n = xv.size
+
+    rng = np.random.default_rng(seed)
+    boots: list[NDArray[np.float64]] = []
+    n_failed = 0
+    for _ in range(n_boot):
+        if method == "residual":
+            xb = xv
+            yb = y_fit + rng.choice(resid, size=n, replace=True)
+        else:
+            idx = rng.integers(0, n, size=n)
+            xb, yb = xv[idx], yv[idx]
+        try:
+            fit = curve_fit(
+                xb, yb, model_fcn, params.tolist(),
+                lower=lower, upper=upper, calc_errors=False,
+            )
+            boots.append(np.asarray(fit["params"], dtype=float))
+        except (ValueError, FloatingPointError):
+            n_failed += 1
+    if len(boots) < n_boot // 2:
+        raise ValueError(f"bootstrap unstable: {n_failed}/{n_boot} refits failed")
+
+    bmat = np.vstack(boots)
+    lo_q, hi_q = 100.0 * alpha / 2.0, 100.0 * (1.0 - alpha / 2.0)
+    out: dict[str, Any] = {
+        "params": params,
+        "boot_mean": np.asarray(bmat.mean(axis=0), dtype=float),
+        "boot_se": np.asarray(bmat.std(axis=0, ddof=1), dtype=float),
+        "ciLow": np.asarray(np.percentile(bmat, lo_q, axis=0), dtype=float),
+        "ciHigh": np.asarray(np.percentile(bmat, hi_q, axis=0), dtype=float),
+        "asymptotic_se": np.asarray(base.get("errors", np.full(params.size, np.nan)),
+                                    dtype=float),
+        "R2": base["R2"],
+        "n_boot": len(boots),
+        "n_failed": n_failed,
+        "method": method,
+        "alpha": alpha,
+        "seed": seed,
+    }
+    if return_samples:
+        out["boot_samples"] = bmat
+    return out
+
+
+def fit_posterior(
+    x: ArrayLike,
+    y: ArrayLike,
+    model_fcn: ModelFn,
+    p0: Sequence[float],
+    *,
+    num_steps: int = 10000,
+    burn_in: int = 1000,
+    step_scale: float = 0.02,
+    seed: int = 0,
+    lower: Sequence[float] | None = None,
+    upper: Sequence[float] | None = None,
+) -> dict[str, Any]:
+    """MCMC posterior for a curve fit's parameters (Gaussian likelihood).
+
+    Fits first (the chain starts at the optimum), takes the fit RMSE as the
+    fixed noise scale, applies flat priors inside [lower, upper], and samples
+    with :func:`calc.mcmc.mcmc_sample` (random-walk Metropolis; step size =
+    ``step_scale`` x |param| floor 1e-6). Returns the mcmc_sample result plus
+    the base fit params and per-parameter posterior medians / 68% intervals.
+    """
+    xv = np.asarray(x, dtype=float).ravel()
+    yv = np.asarray(y, dtype=float).ravel()
+    base = curve_fit(xv, yv, model_fcn, p0, lower=lower, upper=upper)
+    params = np.asarray(base["params"], dtype=float)
+    sigma = max(float(base["RMSE"]), 1e-300)
+    m = params.size
+    lb = np.asarray(lower if lower is not None else [-np.inf] * m, dtype=float)
+    ub = np.asarray(upper if upper is not None else [np.inf] * m, dtype=float)
+
+    def log_posterior(p: NDArray[np.float64]) -> float:
+        pv = np.asarray(p, dtype=float).ravel()
+        if np.any(pv < lb) or np.any(pv > ub):
+            return -np.inf
+        r = yv - model_fcn(xv, pv)
+        return float(-0.5 * np.sum((r / sigma) ** 2))
+
+    step = np.maximum(step_scale * np.abs(params), 1e-6)
+    out = mcmc_sample(
+        log_posterior, params.tolist(),
+        num_steps=num_steps, burn_in=burn_in, step_size=float(np.mean(step)), seed=seed,
+    )
+    samples = np.asarray(out["samples"], dtype=float).reshape(-1, m)
+    return {
+        **out,
+        "params": params,
+        "noise_sigma": sigma,
+        "posterior_median": np.asarray(np.median(samples, axis=0), dtype=float),
+        "ci68Low": np.asarray(np.percentile(samples, 16.0, axis=0), dtype=float),
+        "ci68High": np.asarray(np.percentile(samples, 84.0, axis=0), dtype=float),
+    }