quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/registry.py

@@ -0,0 +1,303 @@
+"""Headless calculator registry — the scripting/automation entry point for the
+DiraCulator calculator domains (the Python analogue of MATLAB ``api = DiraCulator()``).
+
+The ``calc/`` domain modules are already pure and headless; this module gives them
+a **single, discoverable, stable surface**: a name → pure-function catalog so any
+calculation can be listed, described, and invoked by name with a params dict —
+without the GUI, the HTTP routes, or knowing each module's import path.
+
+    >>> from quantized.calc.registry import call_calculator, list_calculators
+    >>> call_calculator("crystal.d_spacing", {"system": "cubic",
+    ...     "a": 5.4309, "b": 5.4309, "c": 5.4309, "h": 1, "k": 1, "l": 1})["d"]
+    3.135...
+
+Discovery:
+
+    >>> [op["name"] for op in list_calculators(domain="xray")]
+    ['xray.bragg_d_spacing', 'xray.bragg_two_theta', 'xray.q_from_two_theta', ...]
+    >>> describe_calculator("xray.bragg_d_spacing")["params"]   # signature params
+    [{'name': 'two_theta', 'required': True, 'default': None}, ...]
+
+Pure layer: imports only ``quantized.calc.*`` (no fastapi/pydantic). The thin
+``routes/calc.py`` adapter exposes the same catalog + call over HTTP; a CLI could
+wrap it identically. Operation names are ``<domain>.<operation>`` and are stable —
+treat them as API.
+"""
+
+from __future__ import annotations
+
+import inspect
+import math
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from quantized.calc import (
+    constants,
+    crystallography,
+    diffusion,
+    electrical,
+    electrochemistry,
+    magnetic,
+    optics,
+    semiconductor,
+    sld_formula,
+    substrates,
+    superconductor,
+    thermal,
+    thin_film,
+    unit_convert,
+    vacuum,
+    xray,
+)
+
+__all__ = [
+    "CALCULATORS",
+    "CalcOp",
+    "call_calculator",
+    "describe_calculator",
+    "list_calculators",
+]
+
+
+@dataclass(frozen=True)
+class CalcOp:
+    """One headless calculator operation: a stable name → pure function.
+
+    ``name`` is ``<domain>.<operation>``; ``fn`` is the pure ``calc`` callable it
+    dispatches to. The human summary is derived from the function's docstring, so
+    it never drifts from the implementation.
+    """
+
+    name: str
+    domain: str
+    fn: Callable[..., Any]
+
+    @property
+    def summary(self) -> str:
+        doc = (self.fn.__doc__ or "").strip()
+        return doc.splitlines()[0].strip() if doc else ""
+
+
+def _ops(domain: str, module: object, names: list[str]) -> list[CalcOp]:
+    """Register ``<domain>.<name>`` → ``module.<name>`` for each name."""
+    return [CalcOp(f"{domain}.{n}", domain, getattr(module, n)) for n in names]
+
+
+# The curated catalog. Operation names are stable public API; the second segment
+# is the calc function name (so a name maps predictably to its source), except the
+# two aliased singletons (units.convert / constants.list).
+_OPS: list[CalcOp] = [
+    CalcOp("units.convert", "units", unit_convert.unit_convert),
+    CalcOp("constants.list", "constants", constants.constants),
+    *_ops(
+        "xray",
+        xray,
+        ["bragg_d_spacing", "bragg_two_theta", "q_from_two_theta", "two_theta_from_q", "xray_calc"],
+    ),
+    *_ops(
+        "crystal",
+        crystallography,
+        ["d_spacing", "cell_volume", "theoretical_density", "plane_spacings"],
+    ),
+    *_ops("sld", sld_formula, ["sld_from_formula"]),
+    *_ops(
+        "electrical",
+        electrical,
+        [
+            "resistivity",
+            "sheet_resistance",
+            "conductivity",
+            "mobility",
+            "current_density",
+            "hall_single_point",
+            "hall_analysis",
+            "wiedemann_franz",
+        ],
+    ),
+    *_ops("thermal", thermal, ["wiedemann_franz", "debye_temperature", "thermal_diffusivity"]),
+    *_ops("diffusion", diffusion, ["arrhenius", "diffusion_length", "fick_flux"]),
+    *_ops(
+        "optics",
+        optics,
+        [
+            "fresnel_coefficients",
+            "critical_angle",
+            "brewster_angle",
+            "penetration_depth",
+            "skin_depth",
+            "dielectric_to_refractive",
+            "refractive_to_dielectric",
+        ],
+    ),
+    *_ops(
+        "vacuum",
+        vacuum,
+        [
+            "mean_free_path",
+            "monolayer_time",
+            "knudsen_number",
+            "pump_down_time",
+            "sputter_yield",
+            "gas_flow",
+        ],
+    ),
+    *_ops(
+        "electrochemistry",
+        electrochemistry,
+        [
+            "nernst_potential",
+            "butler_volmer",
+            "tafel_slope",
+            "ohmic_drop",
+            "double_layer_capacitance",
+        ],
+    ),
+    *_ops(
+        "substrates",
+        substrates,
+        ["get_substrate", "list_substrates", "lattice_mismatch", "substrate_table"],
+    ),
+    *_ops(
+        "semiconductor",
+        semiconductor,
+        [
+            "intrinsic_carrier_conc",
+            "carrier_concentration",
+            "fermi_level",
+            "built_in_potential",
+            "depletion_width",
+            "debye_length",
+            "hall_coefficient",
+            "mobility_model",
+            "thermal_velocity",
+            "sheet_carrier_density",
+            "diffusion_coeff",
+            "diffusion_length",
+            "dos_effective_mass",
+            "material_presets",
+        ],
+    ),
+    *_ops(
+        "superconductor",
+        superconductor,
+        [
+            "london_depth",
+            "coherence_length",
+            "gl_parameter",
+            "critical_fields",
+            "depairing_current",
+            "bcs_gap",
+            "material_presets",
+        ],
+    ),
+    *_ops(
+        "thinfilm",
+        thin_film,
+        [
+            "deposition_rate",
+            "sputter_rate",
+            "kiessig_thickness",
+            "stoney_stress",
+            "projected_range",
+            "multilayer_thermal_conductivity",
+            "thermal_mismatch_strain",
+            "diffusion_length_thermal",
+            "dose_from_current",
+            "dose_to_concentration",
+        ],
+    ),
+    *_ops(
+        "magnetic",
+        magnetic,
+        [
+            "moment_convert",
+            "bohr_magneton_convert",
+            "demag_factor",
+            "demag_named",
+            "curie_weiss_moment",
+            "curie_weiss_fit",
+            "langevin",
+            "magnetization",
+            "domain_wall",
+            "moment_per_atom",
+        ],
+    ),
+]
+
+CALCULATORS: dict[str, CalcOp] = {op.name: op for op in _OPS}
+
+# Stable-name invariant: no domain accidentally registers two ops under one name.
+assert len(CALCULATORS) == len(_OPS), "duplicate calculator operation name"
+
+DOMAINS: tuple[str, ...] = tuple(dict.fromkeys(op.domain for op in _OPS))
+
+
+def _jsonable(value: Any) -> Any:
+    """A signature default reduced to a JSON-safe form (or ``str`` fallback)."""
+    if value is None or isinstance(value, bool | int | str):
+        return value
+    if isinstance(value, float):
+        return None if math.isnan(value) else value
+    return str(value)
+
+
+def _param_specs(fn: Callable[..., Any]) -> list[dict[str, Any]]:
+    """Positional/keyword params of ``fn`` (name, required, default) for discovery."""
+    specs: list[dict[str, Any]] = []
+    for name, p in inspect.signature(fn).parameters.items():
+        if p.kind in (p.VAR_POSITIONAL, p.VAR_KEYWORD):
+            continue
+        required = p.default is inspect.Parameter.empty
+        specs.append(
+            {
+                "name": name,
+                "required": required,
+                "default": None if required else _jsonable(p.default),
+            }
+        )
+    return specs
+
+
+def list_calculators(domain: str | None = None) -> list[dict[str, Any]]:
+    """The catalog: ``{name, domain, summary}`` for every op (optionally one domain)."""
+    ops = _OPS if domain is None else [op for op in _OPS if op.domain == domain]
+    return [{"name": op.name, "domain": op.domain, "summary": op.summary} for op in ops]
+
+
+def describe_calculator(name: str) -> dict[str, Any]:
+    """Full description of one op: name, domain, summary, and its signature params."""
+    op = CALCULATORS.get(name)
+    if op is None:
+        raise KeyError(_unknown_message(name))
+    return {
+        "name": op.name,
+        "domain": op.domain,
+        "summary": op.summary,
+        "params": _param_specs(op.fn),
+    }
+
+
+def call_calculator(name: str, params: dict[str, Any] | None = None) -> Any:
+    """Invoke a calculator by name with a params dict (``fn(**params)``).
+
+    Raises ``KeyError`` for an unknown ``name``, and ``ValueError`` for invalid
+    parameters (a ``TypeError`` from the call — missing/extra/misnamed args) or a
+    domain-validation failure raised by the calc function itself.
+    """
+    op = CALCULATORS.get(name)
+    if op is None:
+        raise KeyError(_unknown_message(name))
+    kwargs = params or {}
+    try:
+        return op.fn(**kwargs)
+    except TypeError as exc:
+        expected = ", ".join(s["name"] for s in _param_specs(op.fn)) or "(none)"
+        raise ValueError(f"invalid parameters for {name!r} ({exc}); expected: {expected}") from exc
+
+
+def _unknown_message(name: str) -> str:
+    return (
+        f"unknown calculator {name!r}; "
+        f"see list_calculators() for the {len(CALCULATORS)} available"
+    )

quantized/calc/relaxation.py

@@ -0,0 +1,119 @@
+"""Magnetic relaxation model comparison. Port of utilities.compareRelaxation.
+
+Pure calc layer. Fits Arrhenius (lnτ = lnτ₀ + Ea/(kB·T), linear/closed-form) and
+Vogel-Fulcher-Tammann (lnτ = lnτ₀ + Ea/(kB·(T-T₀)), nonlinear Nelder-Mead) to
+relaxation-time vs temperature data, then ranks them by AIC/BIC.
+
+Parity note: the Arrhenius fit and its metrics are exact; the VFT fit uses
+Nelder-Mead, so scipy and MATLAB ``fminsearch`` may land at marginally different
+points — the VFT parameters are matched only to a loose tolerance.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+from scipy.optimize import minimize
+
+__all__ = ["compare_relaxation"]
+
+_KB = 8.617333e-5  # Boltzmann constant, eV/K
+_EPS = float(np.finfo(float).eps)
+
+
+def _compute_metrics(
+    y: NDArray[np.float64], residuals: NDArray[np.float64], n_params: int
+) -> tuple[float, float, float]:
+    """Return (AIC, BIC, R²) for a fit. Port of the local computeMetrics helper."""
+    n = y.size
+    rss = float(np.sum(residuals**2))
+    tss = float(np.sum((y - np.mean(y)) ** 2))
+    r2 = 1.0 - rss / max(tss, _EPS)
+    if rss < _EPS:
+        return float("-inf"), float("-inf"), r2
+    log_l = n * math.log(rss / n)
+    return log_l + 2 * n_params, log_l + n_params * math.log(n), r2
+
+
+def _vft_rss(
+    p: NDArray[np.float64], t: NDArray[np.float64], lntau_obs: NDArray[np.float64], tmin: float
+) -> float:
+    """VFT sum-of-squared residuals with the MATLAB penalty walls."""
+    lntau0, ea, t0 = float(p[0]), float(p[1]), float(p[2])
+    if t0 >= tmin - 0.5:
+        return 1e12 * (1.0 + abs(t0 - tmin + 0.5))
+    denom = _KB * (t - t0)
+    if np.any(denom <= 0):
+        return 1e12
+    pred = lntau0 + ea / denom
+    return float(np.sum((lntau_obs - pred) ** 2))
+
+
+def compare_relaxation(
+    temperature: ArrayLike, relaxation_time: ArrayLike
+) -> dict[str, Any]:
+    """Compare Arrhenius vs VFT relaxation fits. Port of utilities.compareRelaxation.
+
+    Returns ``{"arrhenius", "vft", "preferred", "deltaAIC", "deltaBIC"}``. Each
+    model sub-dict carries tau0, Ea_eV, R², AIC, BIC (VFT also T0). ``preferred``
+    is "VFT" when ΔBIC > 0 (VFT lower BIC), else "Arrhenius".
+    """
+    t = np.asarray(temperature, dtype=float).ravel()
+    tau = np.asarray(relaxation_time, dtype=float).ravel()
+    n = t.size
+    if n != tau.size:
+        raise ValueError("temperature and relaxation_time must have the same length")
+    if n < 5:
+        raise ValueError("at least 5 data points are required")
+    if np.any(tau <= 0):
+        raise ValueError("all relaxation times must be positive")
+    if np.any(t <= 0):
+        raise ValueError("all temperatures must be positive (K)")
+
+    lntau = np.log(tau)
+    xmat = np.column_stack([np.ones(n), 1.0 / t])
+    b = np.linalg.lstsq(xmat, lntau, rcond=None)[0]
+    aic_a, bic_a, r2_a = _compute_metrics(lntau, lntau - xmat @ b, 2)
+    arrhenius = {
+        "tau0": math.exp(b[0]),
+        "Ea_eV": float(b[1] * _KB),
+        "R2": r2_a,
+        "AIC": aic_a,
+        "BIC": bic_a,
+    }
+
+    tmin = float(t.min())
+    p0 = np.array([b[0], b[1] * _KB, max(0.0, tmin * 0.5)])
+    res = minimize(
+        _vft_rss,
+        p0,
+        args=(t, lntau, tmin),
+        method="Nelder-Mead",
+        options={"maxiter": 20000, "maxfev": 50000, "xatol": 1e-10, "fatol": 1e-12},
+    )
+    p_vft = np.asarray(res.x, dtype=float)
+    t0_vft = min(float(p_vft[2]), tmin - 1.0)
+    ea_vft = float(p_vft[1])
+    lntau_vft_fit = p_vft[0] + ea_vft / (_KB * np.maximum(t - t0_vft, _EPS))
+    aic_v, bic_v, r2_v = _compute_metrics(lntau, lntau - lntau_vft_fit, 3)
+    vft = {
+        "tau0": math.exp(p_vft[0]),
+        "Ea_eV": ea_vft,
+        "T0": t0_vft,
+        "R2": r2_v,
+        "AIC": aic_v,
+        "BIC": bic_v,
+    }
+
+    delta_aic = aic_a - aic_v
+    delta_bic = bic_a - bic_v
+    return {
+        "arrhenius": arrhenius,
+        "vft": vft,
+        "preferred": "VFT" if delta_bic > 0 else "Arrhenius",
+        "deltaAIC": delta_aic,
+        "deltaBIC": delta_bic,
+    }

quantized/calc/report.py

@@ -0,0 +1,253 @@
+"""Structured report sheets: the serializable substrate for exports & batch.
+
+ORIGIN_GAP_PLAN #36 (W7 contract item). A :class:`ReportSheet` is plain,
+diffable, JSON-round-trippable data (like ``DataStruct``) — never markup. Curve
+fits, peak fits, W5 stats, the peak wizard, and batch runs all emit one (see
+:mod:`quantized.calc.report_emit`); the #37/#38 exporters (docx / pptx / LaTeX /
+HTML) and the future frontend viewer render the SAME schema with no
+per-renderer special cases.
+
+Structure — a report is a title + optional source references + an ordered list
+of sections; each section is a title + an ordered list of typed blocks. Blocks
+are a small closed set discriminated by ``"type"``::
+
+    text    {"type": "text",   "text": str}
+    table   {"type": "table",  "columns": [str], "rows": [[cell]], "caption"?}
+    params  {"type": "params", "params": [{name, value, error?, unit?}], "caption"?}
+    figure  {"type": "figure", "name": str, "image"?: {mime, data}, "caption"?}
+
+A table cell is ``str | float | int | None``. Builders validate and normalize
+on the way in (numpy scalars -> python scalars); :func:`validate_report`
+re-checks a decoded dict so a round-tripped or hand-authored report is safe to
+hand to any renderer.
+
+Pure layer — no fastapi/pydantic imports (enforced by test_repo_integrity).
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = [
+    "BLOCK_TYPES",
+    "ReportSheet",
+    "figure_block",
+    "params_block",
+    "section",
+    "source_ref",
+    "table_block",
+    "text_block",
+    "validate_report",
+]
+
+BLOCK_TYPES = ("text", "table", "params", "figure")
+
+
+def _cell(value: Any) -> str | float | int | None:
+    """Coerce a table cell to a JSON scalar (numpy scalars -> python)."""
+    if value is None:
+        return None
+    if isinstance(value, bool):  # keep bool out of the int branch
+        return str(value)
+    if isinstance(value, (int, float)):
+        v = float(value)
+        return None if not math.isfinite(v) else value
+    # numpy scalar or anything else -> try float, else str
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return str(value)
+
+
+# ── Block builders ────────────────────────────────────────────────────────
+def text_block(text: str) -> dict[str, Any]:
+    """A free-text note block."""
+    return {"type": "text", "text": str(text)}
+
+
+def table_block(
+    columns: Sequence[str],
+    rows: Iterable[Sequence[Any]],
+    *,
+    caption: str | None = None,
+) -> dict[str, Any]:
+    """A generic table: column headers + a grid of scalar cells.
+
+    Covers ANOVA / post-hoc / descriptive-stats / peak tables — anything
+    rectangular. Every row must match the column count.
+    """
+    cols = [str(c) for c in columns]
+    out_rows: list[list[str | float | int | None]] = []
+    for r in rows:
+        r = list(r)
+        if len(r) != len(cols):
+            raise ValueError(f"row has {len(r)} cells, expected {len(cols)}")
+        out_rows.append([_cell(v) for v in r])
+    block: dict[str, Any] = {"type": "table", "columns": cols, "rows": out_rows}
+    if caption:
+        block["caption"] = str(caption)
+    return block
+
+
+def params_block(
+    params: Iterable[Mapping[str, Any]],
+    *,
+    caption: str | None = None,
+) -> dict[str, Any]:
+    """A fitted-parameter block: ordered ``{name, value, error?, unit?}`` rows.
+
+    Kept distinct from a plain table so renderers can format value ± error to
+    the precision implied by the uncertainty (the LaTeX/booktabs path, #38).
+    """
+    out: list[dict[str, Any]] = []
+    for p in params:
+        # non-finite value/error -> None/omitted, so to_json() stays valid wire
+        # JSON (consistent with _cell / DataStruct's null-at-the-boundary rule).
+        val = float(p["value"])
+        entry: dict[str, Any] = {
+            "name": str(p["name"]),
+            "value": val if math.isfinite(val) else None,
+        }
+        err = p.get("error")
+        if err is not None and math.isfinite(float(err)):
+            entry["error"] = float(err)
+        unit = p.get("unit")
+        if unit:
+            entry["unit"] = str(unit)
+        out.append(entry)
+    block: dict[str, Any] = {"type": "params", "params": out}
+    if caption:
+        block["caption"] = str(caption)
+    return block
+
+
+def figure_block(
+    name: str,
+    *,
+    image: Mapping[str, str] | None = None,
+    caption: str | None = None,
+) -> dict[str, Any]:
+    """A figure reference, optionally carrying an embedded image.
+
+    ``image`` is ``{"mime": "image/png"|"image/svg+xml"|..., "data": <base64>}``
+    so an exporter can embed the figure without re-rendering; without it the
+    block is a pure reference (``name`` points at a FigureDoc, #12).
+    """
+    block: dict[str, Any] = {"type": "figure", "name": str(name)}
+    if image is not None:
+        if "mime" not in image or "data" not in image:
+            raise ValueError("figure image needs 'mime' and 'data' keys")
+        block["image"] = {"mime": str(image["mime"]), "data": str(image["data"])}
+    if caption:
+        block["caption"] = str(caption)
+    return block
+
+
+def section(title: str, blocks: Iterable[Mapping[str, Any]]) -> dict[str, Any]:
+    """A titled, ordered group of blocks."""
+    return {"title": str(title), "blocks": [dict(b) for b in blocks]}
+
+
+def source_ref(kind: str, ref_id: str, name: str | None = None) -> dict[str, Any]:
+    """A pointer back to a source object (dataset / fit / figure id)."""
+    ref: dict[str, Any] = {"kind": str(kind), "id": str(ref_id)}
+    if name:
+        ref["name"] = str(name)
+    return ref
+
+
+# ── Validation ──────────────────────────────────────────────────────────────
+def _validate_block(block: Mapping[str, Any], where: str) -> None:
+    if not isinstance(block, Mapping):
+        raise ValueError(f"{where}: block must be an object")
+    btype = block.get("type")
+    if btype not in BLOCK_TYPES:
+        raise ValueError(f"{where}: unknown block type {btype!r}")
+    if btype == "text":
+        if not isinstance(block.get("text"), str):
+            raise ValueError(f"{where}: text block needs a string 'text'")
+    elif btype == "table":
+        cols = block.get("columns")
+        rows = block.get("rows")
+        if not isinstance(cols, list) or not isinstance(rows, list):
+            raise ValueError(f"{where}: table needs list 'columns' and 'rows'")
+        for r in rows:
+            if not isinstance(r, list) or len(r) != len(cols):
+                raise ValueError(f"{where}: every table row must match the column count")
+    elif btype == "params":
+        ps = block.get("params")
+        if not isinstance(ps, list):
+            raise ValueError(f"{where}: params block needs a list 'params'")
+        for p in ps:
+            if not isinstance(p, Mapping) or "name" not in p or "value" not in p:
+                raise ValueError(f"{where}: each param needs 'name' and 'value'")
+    elif btype == "figure":  # noqa: SIM102
+        if not isinstance(block.get("name"), str):
+            raise ValueError(f"{where}: figure block needs a string 'name'")
+
+
+def validate_report(payload: Mapping[str, Any]) -> None:
+    """Raise ``ValueError`` if ``payload`` is not a well-formed report dict."""
+    if not isinstance(payload.get("title"), str):
+        raise ValueError("report needs a string 'title'")
+    sections = payload.get("sections", [])
+    if not isinstance(sections, list):
+        raise ValueError("report 'sections' must be a list")
+    for si, sec in enumerate(sections):
+        if not isinstance(sec, Mapping):
+            raise ValueError(f"section {si} must be an object")
+        if not isinstance(sec.get("title"), str):
+            raise ValueError(f"section {si} needs a string 'title'")
+        blocks = sec.get("blocks", [])
+        if not isinstance(blocks, list):
+            raise ValueError(f"section {si} 'blocks' must be a list")
+        for bi, block in enumerate(blocks):
+            _validate_block(block, f"section {si} block {bi}")
+
+
+# ── The report sheet ──────────────────────────────────────────────────────
+@dataclass(frozen=True, slots=True)
+class ReportSheet:
+    """An immutable, serializable report: title + source refs + sections."""
+
+    title: str
+    sections: tuple[dict[str, Any], ...] = ()
+    source_refs: tuple[dict[str, Any], ...] = ()
+    created: str | None = None  # ISO string, set by the caller (keeps calc pure/deterministic)
+    meta: Mapping[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "title": self.title,
+            "sections": [dict(s) for s in self.sections],
+            "source_refs": [dict(r) for r in self.source_refs],
+            "created": self.created,
+            "meta": dict(self.meta),
+        }
+
+    @classmethod
+    def from_dict(cls, payload: Mapping[str, Any]) -> ReportSheet:
+        validate_report(payload)
+        return cls(
+            title=str(payload["title"]),
+            sections=tuple(dict(s) for s in payload.get("sections", [])),
+            source_refs=tuple(dict(r) for r in payload.get("source_refs", [])),
+            created=payload.get("created"),
+            meta=dict(payload.get("meta", {})),
+        )
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, text: str) -> ReportSheet:
+        return cls.from_dict(json.loads(text))
+
+    def iter_blocks(self) -> Iterable[dict[str, Any]]:
+        """Yield every block across all sections (renderer convenience)."""
+        for sec in self.sections:
+            yield from sec.get("blocks", [])