quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/fit_bumps.py

@@ -0,0 +1,258 @@
+"""Optional bumps fit engine adapter (GOTO #10).
+
+Pure calc layer. `bumps <https://github.com/bumps/bumps>`_ (BSD-3) is an
+OPTIONAL dependency, imported inside functions and guarded — the MATLAB-parity
+fitter (``calc.fitting.curve_fit``, golden-locked) stays the default engine
+everywhere; bumps adds ``amoeba`` / ``lm`` / ``de`` (synchronous, Hessian
+uncertainties) and ``dream`` (posterior sampling — long-running, driven
+through the poll-model job runner ``quantized.jobs`` by the route layer).
+
+There is deliberately NO golden parity here: bumps has no ``quantized_matlab``
+counterpart, so its tests are reference-value / invariant tests, never
+``@pytest.mark.golden`` (see ``tests/test_calc_fit_bumps.py``).
+
+A registry model name (``calc.fit_models.FIT_MODELS`` — which also holds
+equation-builder custom models once registered) or a raw ``f(x, p)`` callable
+is wrapped into a ``bumps.curve.Curve`` via a synthesized keyword signature
+(bumps introspects parameter names; internal names are ``p1..pn`` to avoid
+collisions with ``Curve`` attributes, and results map back positionally).
+"""
+
+from __future__ import annotations
+
+import inspect
+import math
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from .fit_models import FIT_MODELS, evaluate
+
+__all__ = ["BUMPS_ENGINES", "bumps_available", "fit_bumps"]
+
+ModelFn = Callable[[NDArray[np.float64], NDArray[np.float64]], NDArray[np.float64]]
+ProgressFn = Callable[[float], None]
+AbortFn = Callable[[], bool]
+
+#: Supported bumps engine ids (bumps.fitters FITTERS ids).
+BUMPS_ENGINES = ("amoeba", "lm", "de", "dream")
+
+_INSTALL_HINT = (
+    "bumps is not installed - the optional fit engine needs "
+    "'pip install quantized[bumps]' (or: uv sync --extra bumps)"
+)
+
+
+def bumps_available() -> bool:
+    """True when the optional bumps dependency is importable."""
+    try:
+        import bumps  # noqa: F401
+    except ImportError:
+        return False
+    return True
+
+
+def _import_bumps() -> tuple[Any, Any, Any, Any]:
+    """Guarded import -> (Curve, FitProblem, FITTERS, FitDriver)."""
+    try:
+        from bumps.curve import Curve
+        from bumps.fitproblem import FitProblem
+        from bumps.fitters import FITTERS, FitDriver
+    except ImportError as exc:
+        raise ValueError(_INSTALL_HINT) from exc
+    return Curve, FitProblem, FITTERS, FitDriver
+
+
+def _wrap_model(model_fcn: ModelFn, n_params: int) -> tuple[Callable[..., Any], list[str]]:
+    """Wrap ``f(x, p_array)`` for bumps' signature introspection.
+
+    bumps ``Curve`` reads parameter names from the function signature and
+    calls ``fn(x, **params)``; the wrapper carries a synthesized signature
+    with safe internal names ``p1..pn`` (guaranteed not to collide with
+    ``Curve`` attributes such as ``x``/``y``/``name``/``state``).
+    """
+    names = [f"p{i + 1}" for i in range(n_params)]
+
+    def fn(x: Any, **kw: float) -> Any:
+        p = np.array([kw[nm] for nm in names], dtype=float)
+        return model_fcn(np.asarray(x, dtype=float), p)
+
+    pos = inspect.Parameter.POSITIONAL_OR_KEYWORD
+    sig = inspect.Signature(
+        [inspect.Parameter("x", pos)] + [inspect.Parameter(nm, pos) for nm in names]
+    )
+    setattr(fn, "__signature__", sig)  # noqa: B010 — plain attr assign confuses mypy
+    return fn, names
+
+
+class _ProgressMonitor:
+    """bumps Monitor -> plain ``progress_callback(fraction)`` bridge.
+
+    ``total_steps`` is the predicted generation count (burn + draw
+    generations); the reported fraction is clamped below 1.0 — the caller
+    (job runner) owns the terminal 100%.
+    """
+
+    def __init__(self, total_steps: int, callback: ProgressFn) -> None:
+        self._total = max(1, total_steps)
+        self._callback = callback
+
+    def config_history(self, history: Any) -> None:
+        history.requires(step=1)
+
+    def __call__(self, history: Any) -> None:
+        step = int(history.step[0])
+        self._callback(min(0.99, step / self._total))
+
+
+def _resolve_model(
+    model: str | ModelFn, param_names: list[str] | None, n_params: int
+) -> tuple[ModelFn, list[str]]:
+    """Registry name or callable -> (f(x, p) callable, display param names)."""
+    if callable(model):
+        names = list(param_names) if param_names else [f"p{i + 1}" for i in range(n_params)]
+        return model, names
+
+    if model not in FIT_MODELS:
+        raise ValueError(f"unknown fit model: {model}")
+    spec = FIT_MODELS[model]
+    if n_params != int(spec["nParams"]):
+        raise ValueError(
+            f"model '{model}' takes {spec['nParams']} parameters, got {n_params} initial values"
+        )
+
+    def fcn(x: NDArray[np.float64], p: NDArray[np.float64]) -> NDArray[np.float64]:
+        return evaluate(model, x, p)
+
+    names = list(param_names) if param_names else list(spec["paramNames"])
+    return fcn, names
+
+
+def fit_bumps(
+    x: ArrayLike,
+    y: ArrayLike,
+    dy: ArrayLike | None = None,
+    *,
+    model: str | ModelFn,
+    p0: list[float],
+    lower: list[float] | None = None,
+    upper: list[float] | None = None,
+    param_names: list[str] | None = None,
+    engine: str = "amoeba",
+    samples: int = 10_000,
+    burn: int = 100,
+    pop: int = 10,
+    return_samples: bool = False,
+    progress_callback: ProgressFn | None = None,
+    abort_check: AbortFn | None = None,
+) -> dict[str, Any]:
+    """Fit (x, y[, dy]) with a bumps engine; returns a plain result dict.
+
+    ``model`` is a ``calc.fit_models`` registry name (covers built-in AND
+    saved equation-builder models) or a raw ``f(x, p)`` callable. ``engine``
+    is one of ``BUMPS_ENGINES``: amoeba / lm / de report Hessian-derived
+    uncertainties (``uncertainty_kind='hessian'``); dream samples the
+    posterior (``uncertainty_kind='posterior'``) and additionally returns
+    per-parameter medians and central 68% intervals (plus the raw draw
+    matrix when ``return_samples`` — corner-plot food).
+
+    ``samples`` / ``burn`` / ``pop`` tune dream only. ``progress_callback``
+    (fraction in [0, 1)) and ``abort_check`` (True -> stop sampling early)
+    let the job runner drive progress and cancellation; an exception raised
+    by ``progress_callback`` (e.g. ``jobs.JobCancelled``) propagates out.
+
+    Raises ``ValueError`` for a missing bumps install, unknown model/engine,
+    or malformed inputs — the route layer maps that to HTTP 422.
+    """
+    Curve, FitProblem, FITTERS, FitDriver = _import_bumps()
+
+    if engine not in BUMPS_ENGINES:
+        raise ValueError(f"unknown bumps engine: {engine} (choose from {', '.join(BUMPS_ENGINES)})")
+    xv = np.asarray(x, dtype=float).ravel()
+    yv = np.asarray(y, dtype=float).ravel()
+    if xv.size != yv.size:
+        raise ValueError(f"x and y must have equal length (got {xv.size} and {yv.size})")
+    n_params = len(p0)
+    if n_params == 0:
+        raise ValueError("p0 must contain at least one initial parameter value")
+    if xv.size <= n_params:
+        raise ValueError(f"need more points ({xv.size}) than parameters ({n_params})")
+    if not all(math.isfinite(v) for v in p0):
+        raise ValueError("p0 values must be finite")
+    dyv: NDArray[np.float64] | None = None
+    if dy is not None:
+        dyv = np.asarray(dy, dtype=float).ravel()
+        if dyv.size != yv.size:
+            raise ValueError(f"dy must match y length (got {dyv.size} and {yv.size})")
+        if not np.all(dyv > 0):
+            raise ValueError("dy values must all be positive")
+    lb = list(lower) if lower is not None else [-math.inf] * n_params
+    ub = list(upper) if upper is not None else [math.inf] * n_params
+    if len(lb) != n_params or len(ub) != n_params:
+        raise ValueError("lower/upper bounds must match the number of parameters")
+
+    model_fcn, display_names = _resolve_model(model, param_names, n_params)
+    fn, internal = _wrap_model(model_fcn, n_params)
+
+    init = dict(zip(internal, [float(v) for v in p0], strict=True))
+    curve = Curve(fn, xv, yv, dyv, name="", **init)
+    for nm, lo, hi in zip(internal, lb, ub, strict=True):
+        curve.pars[nm].range(float(lo), float(hi))
+    problem = FitProblem(curve)
+
+    fitclass = next(f for f in FITTERS if f.id == engine)
+    options: dict[str, Any] = {}
+    monitors: list[Any] = []
+    if engine == "dream":
+        options = {"samples": int(samples), "burn": int(burn), "pop": int(pop)}
+        if progress_callback is not None:
+            pop_size = int(math.ceil(pop * n_params))
+            total = int(burn) + -(-int(samples) // max(1, pop_size))
+            monitors.append(_ProgressMonitor(total, progress_callback))
+    driver = FitDriver(
+        fitclass=fitclass, problem=problem, monitors=monitors, abort_test=abort_check, **options
+    )
+    driver.clip()  # start inside the bounds
+    x_best, _fx = driver.fit()
+    if x_best is None:  # aborted before the first iteration completed
+        x_best = problem.getp()
+    problem.setp(x_best)
+
+    # Map fitted values back to input parameter order via problem labels.
+    labels = [str(s) for s in problem.labels()]
+    order = [labels.index(nm) for nm in internal]
+    xb = np.asarray(x_best, dtype=float)
+    popt = [float(xb[i]) for i in order]
+    try:
+        dx = np.asarray(driver.stderr(), dtype=float)
+        uncertainties = [float(dx[i]) for i in order]
+    except Exception:  # noqa: BLE001 — e.g. aborted dream with a near-empty state
+        uncertainties = [float("nan")] * n_params
+
+    y_fit = np.asarray(model_fcn(xv, np.asarray(popt, dtype=float)), dtype=float)
+    result: dict[str, Any] = {
+        "engine": engine,
+        "popt": popt,
+        "uncertainties": uncertainties,
+        "chisq": float(problem.chisq()),
+        "uncertainty_kind": "posterior" if engine == "dream" else "hessian",
+        "paramNames": display_names,
+        "yFit": y_fit,
+    }
+
+    if engine == "dream":
+        draw = driver.fitter.state.draw()
+        pts = np.asarray(draw.points, dtype=float)[:, order]
+        lo68, med, hi68 = (
+            np.asarray(np.percentile(pts, q, axis=0), dtype=float) for q in (16.0, 50.0, 84.0)
+        )
+        result["posterior"] = {
+            "medians": [float(v) for v in med],
+            "interval68": [[float(a), float(b)] for a, b in zip(lo68, hi68, strict=True)],
+            "n_draws": int(pts.shape[0]),
+        }
+        if return_samples:
+            result["samples"] = pts
+    return result

quantized/calc/fit_constraints.py

@@ -0,0 +1,114 @@
+"""Constraint expansion for linked/constrained curve-fit parameters.
+
+Port of ``fitting.applyConstraints``. Pure: free-parameter values + per-parameter
+constraint expressions → the full parameter vector. Constraint expressions are
+evaluated with the safe equation parser (``calc.fit_equation.parse_equation``, no
+``eval``). A parameter is *free* when its constraint string is empty, else it is
+*computed* from the free parameters.
+
+Within an expression, free parameters may be referenced as ``p1..pK`` (the 1-based
+position among ALL parameters, rewritten to free-local indices here) or by name.
+
+Faithful-to-MATLAB note: ``parse_equation`` indexes parameters by order of
+appearance, and ``applyConstraints`` rewrites references with two sequential regex
+passes (named, then positional). Both behaviours are replicated exactly, so the
+result matches MATLAB even in the corner cases its rewrite does not fully
+normalise (mixed/reindexed references).
+"""
+
+from __future__ import annotations
+
+import re
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from .fit_equation import parse_equation
+
+__all__ = ["apply_constraints"]
+
+
+def _rewrite_constraint_expr(expr: str, all_names: list[str], free_idx: list[int]) -> str:
+    """Rewrite param references to free-local ``p1..pK`` indices (port of
+    rewriteConstraintExpr): named refs first (longest first), then positional
+    ``p<global>``. Sequential, like MATLAB — do not reorder."""
+    m = len(all_names)
+    g2l = {gi: li + 1 for li, gi in enumerate(free_idx)}  # global → local (1-based)
+
+    # 1) named references, longest names first (stable for ties, as MATLAB sort)
+    for gi in sorted(range(m), key=lambda i: len(all_names[i]), reverse=True):
+        if gi not in g2l or not all_names[gi]:
+            continue
+        pat = r"(?<![A-Za-z0-9_])" + re.escape(all_names[gi]) + r"(?![A-Za-z0-9_])"
+        expr = re.sub(pat, f"p{g2l[gi]}", expr)
+
+    # 2) positional p<global 1-based> → p<local> (after names, ascending global)
+    for gi in range(m):
+        if gi not in g2l:
+            continue
+        pat = r"(?<![A-Za-z0-9_])p" + str(gi + 1) + r"(?![0-9])"
+        expr = re.sub(pat, f"p{g2l[gi]}", expr)
+
+    return expr
+
+
+def apply_constraints(
+    p_free: ArrayLike,
+    constraints: list[str],
+    all_param_names: list[str],
+) -> tuple[NDArray[np.float64], list[int]]:
+    """Expand free parameters to the full vector using constraint expressions.
+
+    Port of ``fitting.applyConstraints``. ``constraints[i]`` is ``""`` for a free
+    parameter or an expression for a computed one. Returns ``(p_full, free_idx)``
+    where ``free_idx`` are the 0-based positions of the free parameters (MATLAB
+    returns 1-based). Raises ``ValueError`` on size mismatch, when a constraint
+    references another constrained parameter, or on parse/eval failure.
+    """
+    pf = np.asarray(p_free, dtype=float).ravel()
+    m = len(constraints)
+    if len(all_param_names) != m:
+        raise ValueError("constraints and all_param_names must have the same length")
+
+    is_constrained = [bool(c.strip()) for c in constraints]
+    free_idx = [i for i in range(m) if not is_constrained[i]]
+    k = len(free_idx)
+    if k == 0 and pf.size:
+        raise ValueError(
+            f"all {m} parameters are constrained — p_free must be empty when nothing is free"
+        )
+    if pf.size != k:
+        raise ValueError(f"p_free has {pf.size} elements but {k} free parameters found")
+
+    p_full = np.full(m, np.nan)
+    for li, gi in enumerate(free_idx):
+        p_full[gi] = pf[li]
+
+    constrained_names = [all_param_names[i] for i in range(m) if is_constrained[i]]
+    for kk in range(m):
+        expr = constraints[kk].strip()
+        if not expr:
+            continue
+        rewritten = _rewrite_constraint_expr(expr, all_param_names, free_idx)
+
+        # A residual constrained-name reference means a constraint depends on a
+        # non-free parameter — unsupported (would be circular).
+        for nm in constrained_names:
+            if not nm:
+                continue
+            if re.search(r"(?<![A-Za-z0-9_])" + re.escape(nm) + r"(?![A-Za-z0-9_])", rewritten):
+                raise ValueError(
+                    f'constraint for "{all_param_names[kk]}" references "{nm}" which is '
+                    f"itself constrained; only free parameters may appear in constraints"
+                )
+
+        try:
+            fcn, _ = parse_equation(rewritten)
+            val = fcn(0.0, pf)
+        except Exception as exc:
+            raise ValueError(
+                f'failed to evaluate constraint for "{all_param_names[kk]}" ("{expr}"): {exc}'
+            ) from exc
+        p_full[kk] = float(np.asarray(val, dtype=float).ravel()[0])
+
+    return p_full, free_idx

quantized/calc/fit_equation.py

@@ -0,0 +1,264 @@
+"""Safe equation-string parser for custom fit models. Port of fitting.parseEquation.
+
+Pure calc layer. Tokenizes an expression (e.g. ``a*exp(-x/b)+c``), converts to RPN
+via the shunting-yard algorithm, and evaluates by **interpreting the RPN stack** —
+NO eval/exec/str2func (per the no-eval rule; this is safer than the MATLAB source
+which compiled via str2func). Parameters are the free identifiers (not x / known
+functions / constants), returned in order of first appearance.
+
+``equation_model`` / ``default_guesses`` bridge a parsed equation into the
+standard bounded-NLLS fit path (``calc.fitting.curve_fit``) for the custom
+fit-model builder (GOTO #1).
+"""
+
+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 scipy.special import erf, erfc
+
+__all__ = ["default_guesses", "equation_model", "parse_equation"]
+
+
+def _coth(a: NDArray[np.float64]) -> NDArray[np.float64]:
+    return np.asarray(1.0 / np.tanh(a), dtype=float)
+
+
+def _matlab_round(a: NDArray[np.float64]) -> NDArray[np.float64]:
+    return np.asarray(np.sign(a) * np.floor(np.abs(a) + 0.5), dtype=float)
+
+
+_FUNCS: dict[str, Callable[[Any], Any]] = {
+    "exp": np.exp, "log": np.log, "log10": np.log10, "sqrt": np.sqrt, "abs": np.abs,
+    "sin": np.sin, "cos": np.cos, "tan": np.tan, "asin": np.arcsin, "acos": np.arccos,
+    "atan": np.arctan, "sinh": np.sinh, "cosh": np.cosh, "tanh": np.tanh, "coth": _coth,
+    "erf": erf, "erfc": erfc, "sign": np.sign, "floor": np.floor, "ceil": np.ceil,
+    "round": _matlab_round,
+}
+_CONSTS = {"pi": float(np.pi), "e": float(np.e)}
+_PREC = {"+": 1, "-": 1, "*": 2, "/": 2, "^": 3}
+
+
+def _tokenize(s: str) -> tuple[list[dict[str, Any]], list[str]]:
+    tokens: list[dict[str, Any]] = []
+    params: list[str] = []
+    pos, n = 0, len(s)
+    prev = "start"
+    while pos < n:
+        ch = s[pos]
+        if ch in " \t":
+            pos += 1
+            continue
+        if ch.isdigit() or (ch == "." and pos + 1 < n and s[pos + 1].isdigit()):
+            start = pos
+            while pos < n and (s[pos].isdigit() or s[pos] == "."):
+                pos += 1
+            if pos < n and s[pos] in "eE":
+                pos += 1
+                if pos < n and s[pos] in "+-":
+                    pos += 1
+                while pos < n and s[pos].isdigit():
+                    pos += 1
+            tokens.append({"type": "number", "value": float(s[start:pos])})
+            prev = "value"
+            continue
+        if ch.isalpha() or ch == "_":
+            start = pos
+            while pos < n and (s[pos].isalnum() or s[pos] == "_"):
+                pos += 1
+            name = s[start:pos]
+            if name in _FUNCS:
+                tokens.append({"type": "function", "value": name})
+                prev = "function"
+                continue
+            # A non-function identifier directly followed by "(" is a call of
+            # an unknown symbol (there is no implicit multiplication in this
+            # grammar) -- reject it with a clear message instead of letting it
+            # fail the arity check with a generic one.
+            look = pos
+            while look < n and s[look] in " \t":
+                look += 1
+            if look < n and s[look] == "(":
+                if name in _CONSTS or name == "x":
+                    raise ValueError(f'"{name}" cannot be called as a function')
+                raise ValueError(
+                    f'Unknown function "{name}". Known functions: '
+                    + ", ".join(sorted(_FUNCS))
+                )
+            if name in _CONSTS:
+                tokens.append({"type": "number", "value": _CONSTS[name]})
+                prev = "value"
+            elif name == "x":
+                tokens.append({"type": "x", "value": "x"})
+                prev = "value"
+            else:
+                if name not in params:
+                    params.append(name)
+                tokens.append({"type": "param", "value": params.index(name)})
+                prev = "value"
+            continue
+        if ch in "+-*/^()":
+            if ch == "(":
+                tokens.append({"type": "lparen", "value": "("})
+                prev = "lparen"
+            elif ch == ")":
+                tokens.append({"type": "rparen", "value": ")"})
+                prev = "value"
+            elif ch == "-" and prev in ("start", "lparen", "operator"):
+                tokens.append({"type": "number", "value": 0.0})
+                tokens.append({"type": "operator", "value": "-"})
+                prev = "operator"
+            elif ch == "+" and prev in ("start", "lparen", "operator"):
+                prev = "operator"
+            else:
+                tokens.append({"type": "operator", "value": ch})
+                prev = "operator"
+            pos += 1
+            continue
+        raise ValueError(f'Unexpected character "{ch}" at position {pos}')
+    return tokens, params
+
+
+def _should_pop(stack_op: str, new_op: str) -> bool:
+    if stack_op not in _PREC:
+        return False
+    sp, np_ = _PREC[stack_op], _PREC[new_op]
+    return sp > np_ if new_op == "^" else sp >= np_
+
+
+def _to_rpn(tokens: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    rpn: list[dict[str, Any]] = []
+    op_stack: list[dict[str, Any]] = []
+    for tok in tokens:
+        ttype = tok["type"]
+        if ttype in ("number", "x", "param"):
+            rpn.append(tok)
+        elif ttype == "function":
+            op_stack.append(tok)
+        elif ttype == "operator":
+            while (op_stack and op_stack[-1]["type"] == "operator"
+                   and _should_pop(op_stack[-1]["value"], tok["value"])):
+                rpn.append(op_stack.pop())
+            op_stack.append(tok)
+        elif ttype == "lparen":
+            op_stack.append(tok)
+        elif ttype == "rparen":
+            while op_stack and op_stack[-1]["type"] != "lparen":
+                rpn.append(op_stack.pop())
+            if not op_stack:
+                raise ValueError("Mismatched parentheses.")
+            op_stack.pop()  # discard '('
+            if op_stack and op_stack[-1]["type"] == "function":
+                rpn.append(op_stack.pop())
+    while op_stack:
+        if op_stack[-1]["type"] == "lparen":
+            raise ValueError("Mismatched parentheses.")
+        rpn.append(op_stack.pop())
+    return rpn
+
+
+def _check_arity(rpn: list[dict[str, Any]]) -> None:
+    """Reject RPN that would under/overflow the eval stack (e.g. ``a +`` or
+    ``a b``). MATLAB's parseEquation compiled via str2func, so malformed input
+    errored there at compile time; erroring at parse time matches that intent
+    (the interpreter would otherwise crash or silently drop operands)."""
+    depth = 0
+    for tok in rpn:
+        ttype = tok["type"]
+        if ttype in ("number", "x", "param"):
+            depth += 1
+        elif ttype == "operator":
+            if depth < 2:
+                raise ValueError(
+                    f'operator "{tok["value"]}" is missing an operand'
+                )
+            depth -= 1
+        elif ttype == "function":
+            if depth < 1:
+                raise ValueError(f'function "{tok["value"]}" is missing its argument')
+    if depth != 1:
+        raise ValueError("malformed expression (check operators and parentheses)")
+
+
+def _eval_rpn(rpn: list[dict[str, Any]], x: NDArray[np.float64], p: NDArray[np.float64]) -> Any:
+    stack: list[Any] = []
+    for tok in rpn:
+        ttype = tok["type"]
+        if ttype == "number":
+            stack.append(tok["value"])
+        elif ttype == "x":
+            stack.append(x)
+        elif ttype == "param":
+            stack.append(p[tok["value"]])
+        elif ttype == "operator":
+            b = stack.pop()
+            a = stack.pop()
+            op = tok["value"]
+            if op == "+":
+                stack.append(a + b)
+            elif op == "-":
+                stack.append(a - b)
+            elif op == "*":
+                stack.append(a * b)
+            elif op == "/":
+                stack.append(a / b)
+            else:  # ^
+                stack.append(a**b)
+        elif ttype == "function":
+            stack.append(_FUNCS[tok["value"]](stack.pop()))
+    return stack[0]
+
+
+def parse_equation(
+    eqn_str: str,
+) -> tuple[Callable[[ArrayLike, ArrayLike], NDArray[np.float64]], list[str]]:
+    """Parse ``eqn_str`` into ``(fcn, param_names)``. Port of fitting.parseEquation.
+
+    ``fcn(x, p)`` evaluates the expression (``p`` indexed in ``param_names`` order).
+    Strips a leading ``y =`` / ``f(x) =``. Safe: RPN is interpreted, never eval'd.
+    """
+    import re
+
+    expr = re.sub(r"^\s*(y|f\(x\))\s*=\s*", "", eqn_str.strip())
+    if not expr:
+        raise ValueError("Equation string is empty.")
+    tokens, param_names = _tokenize(expr)
+    rpn = _to_rpn(tokens)
+    _check_arity(rpn)
+
+    def fcn(x: ArrayLike, p: ArrayLike) -> NDArray[np.float64]:
+        xv = np.asarray(x, dtype=float).ravel()
+        pv = np.asarray(p, dtype=float).ravel()
+        y = _eval_rpn(rpn, xv, pv)
+        out = np.broadcast_to(np.asarray(y, dtype=float), xv.shape)
+        return np.asarray(out, dtype=float).copy()
+
+    return fcn, param_names
+
+
+def equation_model(
+    eqn_str: str,
+) -> tuple[Callable[[ArrayLike, ArrayLike], NDArray[np.float64]], list[str]]:
+    """Parse ``eqn_str`` and vet it as a *fit model*: ``(model_fcn, param_names)``.
+
+    On top of ``parse_equation`` this rejects parameter names that start with
+    an underscore (MATLAB identifiers cannot, and it shuts the door on dunder
+    junk like ``__import__`` ever naming a parameter). The returned callable
+    plugs straight into ``calc.fitting.curve_fit`` as ``model_fcn``.
+    """
+    fcn, param_names = parse_equation(eqn_str)
+    for name in param_names:
+        if name.startswith("_"):
+            raise ValueError(
+                f'invalid parameter name "{name}": parameters must start with a letter'
+            )
+    return fcn, param_names
+
+
+def default_guesses(param_names: Sequence[str]) -> list[float]:
+    """Default starting guesses for an equation model: 1.0 per parameter
+    (the conventional neutral start when nothing is known about scale)."""
+    return [1.0] * len(param_names)