quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/units.py

@@ -0,0 +1,80 @@
+"""Physical unit conversions. Port of utilities.convertUnits.
+
+Pure calc layer. Multiplicative families (magnetic field, magnetic moment, angle,
+length) convert through a shared base unit; temperature is affine (via Kelvin).
+Unit tokens are case-insensitive; ``/`` and other non-alphanumerics are mapped to
+``_`` to match MATLAB's ``makeValidName`` keying (so ``"A/m"`` -> ``a_m``).
+"""
+
+from __future__ import annotations
+
+import math
+import re
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+__all__ = ["convert_units"]
+
+_FOUR_PI = 4.0 * math.pi
+
+# value * table[from] -> base unit;  base / table[to] -> target.
+_FIELD = {"oe": 1000.0 / _FOUR_PI, "t": 1e4 / _FOUR_PI, "mt": 10.0 / _FOUR_PI, "a_m": 1.0}
+_FIELD_CANON = {"oe": "Oe", "t": "T", "mt": "mT", "a_m": "A/m"}
+_MOMENT = {"emu": 1e-3, "a_m2": 1.0, "j_t": 1.0, "memu": 1e-6}
+_MOMENT_CANON = {"emu": "emu", "a_m2": "A·m²", "j_t": "J/T", "memu": "memu"}
+_ANGLE = {"deg": math.pi / 180.0, "rad": 1.0}
+_ANGLE_CANON = {"deg": "deg", "rad": "rad"}
+_LENGTH = {"nm": 1e-9, "um": 1e-6, "mm": 1e-3, "cm": 1e-2, "m": 1.0, "ang": 1e-10}
+_LENGTH_CANON = {"nm": "nm", "um": "µm", "mm": "mm", "cm": "cm", "m": "m", "ang": "Å"}
+_TABLES = (
+    (_FIELD, _FIELD_CANON),
+    (_MOMENT, _MOMENT_CANON),
+    (_ANGLE, _ANGLE_CANON),
+    (_LENGTH, _LENGTH_CANON),
+)
+_TEMP = {"k", "c", "f"}
+_TEMP_CANON = {"k": "K", "c": "°C", "f": "°F"}
+
+
+def _key(unit: str) -> str:
+    return re.sub(r"[^a-z0-9]", "_", unit.strip().lower())
+
+
+def _to_kelvin(v: NDArray[np.float64], unit: str) -> NDArray[np.float64]:
+    if unit == "k":
+        return v
+    if unit == "c":
+        return np.asarray(v + 273.15, dtype=float)
+    return np.asarray((v - 32.0) * 5.0 / 9.0 + 273.15, dtype=float)  # f
+
+
+def _from_kelvin(k: NDArray[np.float64], unit: str) -> NDArray[np.float64]:
+    if unit == "k":
+        return k
+    if unit == "c":
+        return np.asarray(k - 273.15, dtype=float)
+    return np.asarray((k - 273.15) * 9.0 / 5.0 + 32.0, dtype=float)  # f
+
+
+def convert_units(
+    value: ArrayLike, from_unit: str, to_unit: str
+) -> tuple[NDArray[np.float64], str]:
+    """Convert ``value`` from ``from_unit`` to ``to_unit``.
+
+    Returns ``(converted_array, canonical_unit_string)``. Same-unit conversions
+    return the value unchanged with the lowercased target token (matching MATLAB).
+    Raises ``ValueError`` if the units are unknown or belong to different families.
+    """
+    val = np.asarray(value, dtype=float)
+    f = from_unit.strip().lower()
+    t = to_unit.strip().lower()
+    if f == t:
+        return val, t
+    if f in _TEMP and t in _TEMP:
+        return _from_kelvin(_to_kelvin(val, f), t), _TEMP_CANON[t]
+    fk, tk = _key(from_unit), _key(to_unit)
+    for table, canon in _TABLES:
+        if fk in table and tk in table:
+            return np.asarray(val * table[fk] / table[tk], dtype=float), canon[tk]
+    raise ValueError(f'cannot convert "{f}" -> "{t}"')

quantized/calc/vacuum.py

@@ -0,0 +1,290 @@
+r"""Vacuum-science calculators (DiraCulator ``buildVacuumTab`` +
+``+calc/+vacuum``).
+
+Pure calc layer — closed-form scalars in, result dicts out. No fastapi /
+pydantic imports. Ports the six MATLAB ``calc.vacuum`` functions verbatim:
+
+.. math::
+
+    \lambda = \frac{k_B T}{\sqrt{2}\,\pi d^2 P} \qquad
+    t_{\mathrm{mono}} = \frac{1}{J\,A_{\mathrm{site}}},\;
+        J = \frac{P}{\sqrt{2\pi m k_B T}} \\
+    K_n = \frac{\lambda}{L} \qquad
+    t = \frac{V}{S}\,\ln\!\frac{P_0}{P_f} \\
+    C_{\mathrm{mol}} = \frac{\pi d^3}{12 L}\sqrt{\frac{8 k_B T}{\pi m}}
+        \qquad
+    C_{\mathrm{visc}} = \frac{\pi d^4}{128\,\eta L}\,\frac{P_1+P_2}{2}
+
+SI units throughout (pressure Pa, length m, mass kg, temperature K), except
+pump-down volume/speed in L and L/s and conductances reported in L/s, matching
+the MATLAB toolbox (the behavioural reference). The sputter-yield lookup is the
+Yamamura & Tawara (1996) / Matsunami approximate table for Ar ions at 200, 500,
+1000, 5000 eV; linear interpolation in-range, NaN outside (no extrapolation).
+
+Reference values (closed-form / MATLAB docstring examples):
+  - ``mean_free_path(1e-4) -> mfp ≈ 70.36`` m (N2, 300 K)
+  - ``knudsen_number(0.05, 0.1) -> Kn = 0.5`` (transition)
+  - ``pump_down_time(50, 100, 1e5, 1e-4) -> t ≈ 10.36`` s
+  - ``sputter_yield("Cu", 500) -> Y = 3.0`` atoms/ion
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import numpy as np
+
+from quantized.calc.constants import constants
+
+__all__ = [
+    "gas_flow",
+    "knudsen_number",
+    "mean_free_path",
+    "monolayer_time",
+    "pump_down_time",
+    "sputter_yield",
+]
+
+# N2 molecular diameter (m) — default gas for mean free path / gas flow.
+_D_N2 = 3.64e-10
+# N2 molecular mass (kg, ~28 amu) — default for monolayer time / gas flow.
+_M_N2 = 4.65e-26
+# Default adsorption-site area (m^2) for the Langmuir monolayer model.
+_A_SITE = 1e-19
+# Dynamic viscosity of N2 at 300 K (Pa*s) — constant approximation in gasFlow.
+_ETA_N2 = 1.8e-5
+
+# Yamamura & Tawara (1996) / Matsunami approximate Ar-ion sputter yields.
+# Energy grid (eV) shared by every material; do-not-"fix" calibrated values.
+_SPUTTER_ENERGIES = (200.0, 500.0, 1000.0, 5000.0)
+_SPUTTER_YIELDS: dict[str, tuple[float, float, float, float]] = {
+    "si": (0.4, 0.9, 1.2, 1.4),
+    "cu": (1.5, 3.0, 4.0, 4.5),
+    "fe": (0.8, 1.6, 2.2, 2.6),
+    "au": (1.5, 3.2, 4.4, 5.0),
+    "ti": (0.3, 0.7, 1.1, 1.4),
+    "sio2": (0.3, 0.7, 1.0, 1.2),
+    "ni": (1.0, 2.2, 3.0, 3.5),
+    "al": (0.5, 1.1, 1.6, 1.8),
+    "pt": (0.8, 1.8, 2.5, 3.0),
+    "w": (0.3, 0.7, 1.0, 1.3),
+    "ta": (0.3, 0.6, 0.9, 1.2),
+    "cr": (0.7, 1.5, 2.1, 2.5),
+    "mo": (0.5, 1.1, 1.5, 1.8),
+    "ag": (1.8, 3.5, 4.8, 5.5),
+    "gaas": (0.9, 1.8, 2.5, 2.9),
+}
+
+
+def _regime(kn: float) -> str:
+    """Flow regime from the Knudsen number (MATLAB ``knudsenNumber`` thresholds).
+
+    ``Kn > 1`` molecular, ``Kn >= 0.01`` transition, else viscous.
+    """
+    if kn > 1:
+        return "molecular"
+    if kn >= 0.01:
+        return "transition"
+    return "viscous"
+
+
+def mean_free_path(
+    p: float, *, temperature: float = 300.0, d: float = _D_N2
+) -> dict[str, float]:
+    """Mean free path λ = k_B·T / (√2·π·d²·P) (m).
+
+    Args:
+        p: pressure (Pa), > 0.
+        temperature: temperature (K), > 0. Default 300.
+        d: molecular diameter (m), > 0. Default 3.64e-10 (N2).
+
+    >>> round(mean_free_path(1e-4)["mfp"], 2)
+    70.36
+    """
+    if p <= 0 or temperature <= 0 or d <= 0:
+        raise ValueError("P, T and d must be positive")
+    kb = constants()["kB"]
+    mfp = kb * temperature / (math.sqrt(2.0) * math.pi * d**2 * p)
+    return {
+        "mfp": mfp,
+        "mfpMm": mfp * 1e3,
+        "mfpUm": mfp * 1e6,
+        "P": p,
+        "T": temperature,
+        "d": d,
+    }
+
+
+def monolayer_time(
+    p: float,
+    *,
+    m: float = _M_N2,
+    temperature: float = 300.0,
+    a_site: float = _A_SITE,
+) -> dict[str, float]:
+    """Monolayer formation time (Langmuir model), t = 1/(J·A_site) (s).
+
+    Impingement flux ``J = P / sqrt(2·π·m·k_B·T)`` (molecules/m²/s).
+
+    Args:
+        p: pressure (Pa), > 0.
+        m: molecular mass (kg), > 0. Default 4.65e-26 (N2).
+        temperature: temperature (K), > 0. Default 300.
+        a_site: adsorption-site area (m²), > 0. Default 1e-19.
+
+    >>> round(monolayer_time(1.33e-4)["tMono"], 4)
+    2.6156
+    """
+    if p <= 0 or m <= 0 or temperature <= 0 or a_site <= 0:
+        raise ValueError("P, m, T and A_site must be positive")
+    kb = constants()["kB"]
+    flux = p / math.sqrt(2.0 * math.pi * m * kb * temperature)
+    t_mono = 1.0 / (flux * a_site)
+    return {"tMono": t_mono, "flux": flux, "P": p, "T": temperature}
+
+
+def knudsen_number(mfp: float, length: float) -> dict[str, Any]:
+    """Knudsen number Kn = λ/L and flow regime.
+
+    Args:
+        mfp: mean free path (m), > 0.
+        length: characteristic length (m), > 0.
+
+    >>> r = knudsen_number(0.05, 0.1)
+    >>> round(r["Kn"], 3), r["regime"]
+    (0.5, 'transition')
+    """
+    if mfp <= 0 or length <= 0:
+        raise ValueError("mfp and L must be positive")
+    kn = mfp / length
+    return {"Kn": kn, "regime": _regime(kn), "mfp": mfp, "L": length}
+
+
+def pump_down_time(v: float, s: float, p0: float, pf: float) -> dict[str, float]:
+    """Ideal exponential pump-down time t = (V/S)·ln(P0/Pf) (s).
+
+    Constant pump speed, no outgassing. Time constant τ = V/S.
+
+    Args:
+        v: chamber volume (L), > 0.
+        s: pump speed (L/s), > 0.
+        p0: initial pressure (Pa), > 0.
+        pf: final (target) pressure (Pa), > 0 and < p0.
+
+    >>> round(pump_down_time(50, 100, 1e5, 1e-4)["time"], 6)
+    10.361633
+    """
+    if v <= 0 or s <= 0 or p0 <= 0 or pf <= 0:
+        raise ValueError("V, S, P0 and Pf must be positive")
+    if pf >= p0:
+        raise ValueError("Final pressure Pf must be less than initial pressure P0.")
+    tau = v / s
+    t = tau * math.log(p0 / pf)
+    return {
+        "time": t,
+        "timeMin": t / 60.0,
+        "tau": tau,
+        "V": v,
+        "S": s,
+        "P0": p0,
+        "Pf": pf,
+    }
+
+
+def sputter_yield(material: str, energy: float, *, ion: str = "Ar") -> dict[str, Any]:
+    """Sputter yield (atoms/ion) from the Ar-ion lookup table.
+
+    Linear interpolation in energy between the tabulated [200, 500, 1000, 5000]
+    eV grid; ``Y = NaN`` outside the range or for unknown material/ion (no
+    extrapolation, matching MATLAB ``sputterYield``).
+
+    Args:
+        material: target symbol (case-insensitive), e.g. ``"Si"``, ``"Cu"``.
+        energy: ion energy (eV), > 0.
+        ion: ion species. Only ``"Ar"`` is tabulated; others return NaN.
+
+    >>> sputter_yield("Cu", 500)["Y"]
+    3.0
+    """
+    if energy <= 0:
+        raise ValueError("energy must be positive")
+
+    def _nan(mat: str, ion_in: str) -> dict[str, Any]:
+        return {"Y": float("nan"), "material": mat, "ion": ion_in, "energy": energy}
+
+    if ion.strip().lower() != "ar":
+        return _nan(material, ion)
+
+    entry = _SPUTTER_YIELDS.get(material.strip().lower())
+    if entry is None:
+        return _nan(material, ion)
+
+    grid = _SPUTTER_ENERGIES
+    if energy < grid[0] or energy > grid[-1]:
+        return _nan(material, ion)
+
+    y = float(np.interp(energy, grid, entry))
+    return {"Y": y, "material": material, "ion": ion, "energy": energy}
+
+
+def gas_flow(
+    p1: float,
+    p2: float,
+    d: float,
+    length: float,
+    *,
+    temperature: float = 300.0,
+    m: float = _M_N2,
+) -> dict[str, Any]:
+    """Molecular & viscous gas-flow conductance through a tube (L/s).
+
+    Molecular (Knudsen): ``C_mol = (π d³/12L)·sqrt(8 k_B T/(π m))``.
+    Viscous (Hagen-Poiseuille): ``C_visc = (π d⁴/128 η L)·(P1+P2)/2``.
+    The Knudsen number (mean free path at the mean pressure, length = d)
+    selects the regime; throughput ``Q = C_eff·(P1-P2)``. In the transition
+    regime the additive ``C_mol + C_visc`` is used (matching MATLAB).
+
+    Args:
+        p1: upstream pressure (Pa), > 0.
+        p2: downstream pressure (Pa), > 0.
+        d: tube inner diameter (m), > 0.
+        length: tube length (m), > 0.
+        temperature: temperature (K), > 0. Default 300.
+        m: molecular mass (kg), > 0. Default 4.65e-26 (N2).
+
+    Returns a dict with ``Cmol``/``Cvisc`` (L/s), ``throughput`` (Pa·L/s),
+    ``Kn`` and ``regime``.
+    """
+    if p1 <= 0 or p2 <= 0 or d <= 0 or length <= 0:
+        raise ValueError("P1, P2, d and L must be positive")
+    if temperature <= 0 or m <= 0:
+        raise ValueError("T and m must be positive")
+    kb = constants()["kB"]
+
+    cmol_m3s = (math.pi * d**3 / (12.0 * length)) * math.sqrt(
+        8.0 * kb * temperature / (math.pi * m)
+    )
+    p_mean = (p1 + p2) / 2.0
+    cvisc_m3s = (math.pi * d**4 / (128.0 * _ETA_N2 * length)) * p_mean
+
+    # Knudsen number at mean pressure (N2 diameter), characteristic length = d.
+    mfp = mean_free_path(p_mean, temperature=temperature, d=_D_N2)["mfp"]
+    kn_res = knudsen_number(mfp, d)
+    regime = kn_res["regime"]
+
+    if regime == "molecular":
+        c_eff = cmol_m3s
+    elif regime == "viscous":
+        c_eff = cvisc_m3s
+    else:
+        c_eff = cmol_m3s + cvisc_m3s
+    throughput = c_eff * (p1 - p2) * 1e3  # Pa*(m^3/s) -> Pa*L/s
+
+    return {
+        "Cmol": cmol_m3s * 1e3,
+        "Cvisc": cvisc_m3s * 1e3,
+        "throughput": throughput,
+        "Kn": kn_res["Kn"],
+        "regime": regime,
+    }

quantized/calc/xray.py

@@ -0,0 +1,169 @@
+r"""X-ray / neutron scattering scalar conversions (DiraCulator buildXrayNeutronTab).
+
+Pure calc layer. Standard textbook relations between the X-ray (or neutron)
+wavelength :math:`\lambda`, the Bragg angle, the detector angle :math:`2\theta`,
+the interplanar spacing :math:`d`, and the scattering-vector magnitude
+:math:`Q`. All lengths are in angstrom (Å), angles in degrees, :math:`Q` in
+1/Å.
+
+Bragg's law (order ``n``):
+
+.. math::
+
+    n\lambda = 2 d \sin\theta, \qquad \theta = \tfrac{1}{2}\,(2\theta)
+
+Scattering vector magnitude for an elastic event:
+
+.. math::
+
+    Q = \frac{4\pi}{\lambda}\sin\theta
+      = \frac{2\pi n}{d}
+
+so ``Q`` and ``d`` are reciprocal (``Q = 2*pi/d`` at first order), a handy
+cross-check. The inverse forms invert ``arcsin`` and therefore require the
+argument to lie in ``[-1, 1]`` — a reflection with ``n*lambda > 2 d`` (or
+``Q*lambda > 4 pi``) is geometrically inaccessible at that wavelength and
+raises ``ValueError``.
+
+Reference value: Cu K-alpha (``lambda = 1.5406 Å``) on Si(111)
+(``d = 3.1356 Å``) gives ``2theta ≈ 28.44°`` and ``Q ≈ 2.004 1/Å``.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Callable
+from typing import Any
+
+__all__ = [
+    "bragg_d_spacing",
+    "bragg_two_theta",
+    "q_from_two_theta",
+    "two_theta_from_q",
+    "xray_calc",
+]
+
+
+def _check_wavelength(wavelength_a: float) -> None:
+    if not (math.isfinite(wavelength_a) and wavelength_a > 0):
+        raise ValueError(f"wavelength must be positive and finite, got {wavelength_a!r}")
+
+
+def _check_order(n: int) -> None:
+    if n < 1:
+        raise ValueError(f"diffraction order n must be a positive integer, got {n!r}")
+
+
+def bragg_d_spacing(wavelength_a: float, two_theta_deg: float, n: int = 1) -> float:
+    r"""Interplanar spacing ``d`` (Å) from the detector angle ``2theta`` (deg).
+
+    :math:`d = n\lambda / (2\sin\theta)` with :math:`\theta = (2\theta)/2`.
+    Requires ``0 < two_theta_deg < 180``.
+
+    >>> round(bragg_d_spacing(1.5406, 28.44), 3)
+    3.136
+    """
+    _check_wavelength(wavelength_a)
+    _check_order(n)
+    if not (0.0 < two_theta_deg < 180.0):
+        raise ValueError(f"two_theta must be in (0, 180) deg, got {two_theta_deg!r}")
+    sin_theta = math.sin(math.radians(two_theta_deg) / 2.0)
+    return n * wavelength_a / (2.0 * sin_theta)
+
+
+def bragg_two_theta(wavelength_a: float, d_a: float, n: int = 1) -> float:
+    r"""Detector angle ``2theta`` (deg) from the spacing ``d`` (Å), via Bragg's law.
+
+    :math:`2\theta = 2\arcsin\!\big(n\lambda / (2d)\big)`. Raises if the
+    reflection is inaccessible (``n*lambda > 2 d``).
+
+    >>> round(bragg_two_theta(1.5406, 3.1356), 2)
+    28.44
+    """
+    _check_wavelength(wavelength_a)
+    _check_order(n)
+    if not (math.isfinite(d_a) and d_a > 0):
+        raise ValueError(f"d-spacing must be positive and finite, got {d_a!r}")
+    arg = n * wavelength_a / (2.0 * d_a)
+    if arg > 1.0:
+        raise ValueError(
+            f"reflection inaccessible at this wavelength: n*lambda/(2d) = {arg:.4f} > 1"
+        )
+    return math.degrees(2.0 * math.asin(arg))
+
+
+def q_from_two_theta(wavelength_a: float, two_theta_deg: float) -> float:
+    r"""Scattering-vector magnitude ``Q`` (1/Å) from ``2theta`` (deg).
+
+    :math:`Q = (4\pi/\lambda)\sin\theta`, :math:`\theta = (2\theta)/2`.
+    Requires ``0 <= two_theta_deg <= 180``.
+
+    >>> round(q_from_two_theta(1.5406, 28.44), 3)
+    2.004
+    """
+    _check_wavelength(wavelength_a)
+    if not (0.0 <= two_theta_deg <= 180.0):
+        raise ValueError(f"two_theta must be in [0, 180] deg, got {two_theta_deg!r}")
+    return (4.0 * math.pi / wavelength_a) * math.sin(math.radians(two_theta_deg) / 2.0)
+
+
+def two_theta_from_q(wavelength_a: float, q_inv_a: float) -> float:
+    r"""Detector angle ``2theta`` (deg) from the scattering vector ``Q`` (1/Å).
+
+    :math:`2\theta = 2\arcsin\!\big(Q\lambda / (4\pi)\big)`. Raises if ``Q`` is
+    too large for the wavelength (``Q*lambda > 4 pi``).
+
+    >>> round(two_theta_from_q(1.5406, 2.004), 2)
+    28.44
+    """
+    _check_wavelength(wavelength_a)
+    if not (math.isfinite(q_inv_a) and q_inv_a >= 0):
+        raise ValueError(f"Q must be non-negative and finite, got {q_inv_a!r}")
+    arg = q_inv_a * wavelength_a / (4.0 * math.pi)
+    if arg > 1.0:
+        raise ValueError(
+            f"Q inaccessible at this wavelength: Q*lambda/(4*pi) = {arg:.4f} > 1"
+        )
+    return math.degrees(2.0 * math.asin(arg))
+
+
+# Uniform (wavelength, value, n) wrappers for the order-free Q conversions so the
+# dispatch table stays a typed dict of defs (no untyped lambdas, no eval).
+def _q_from_2theta(wavelength_a: float, value: float, _n: int) -> float:
+    return q_from_two_theta(wavelength_a, value)
+
+
+def _2theta_from_q(wavelength_a: float, value: float, _n: int) -> float:
+    return two_theta_from_q(wavelength_a, value)
+
+
+# Mode dispatch (no eval): name -> (callable(wavelength, value, n), result unit).
+_MODES: dict[str, tuple[Callable[[float, float, int], float], str]] = {
+    "d_from_2theta": (bragg_d_spacing, "Å"),
+    "2theta_from_d": (bragg_two_theta, "deg"),
+    "q_from_2theta": (_q_from_2theta, "1/Å"),
+    "2theta_from_q": (_2theta_from_q, "deg"),
+}
+
+_MODE_DESC: dict[str, str] = {
+    "d_from_2theta": "interplanar spacing d from 2θ (Bragg)",
+    "2theta_from_d": "2θ from interplanar spacing d (Bragg)",
+    "q_from_2theta": "scattering vector |Q| from 2θ",
+    "2theta_from_q": "2θ from scattering vector |Q|",
+}
+
+
+def xray_calc(mode: str, wavelength_a: float, value: float, n: int = 1) -> dict[str, Any]:
+    """Dispatch one X-ray/neutron scalar conversion. Returns result + unit + label.
+
+    ``mode`` is one of ``d_from_2theta``, ``2theta_from_d``, ``q_from_2theta``,
+    ``2theta_from_q``. ``value`` is the mode's input (2θ in deg, d in Å, or Q in
+    1/Å). ``n`` is the diffraction order (Bragg modes only). Raises ``ValueError``
+    on an unknown mode or out-of-domain input.
+    """
+    entry = _MODES.get(mode)
+    if entry is None:
+        raise ValueError(f"unknown mode {mode!r}; expected one of {sorted(_MODES)}")
+    fn, unit = entry
+    result = fn(wavelength_a, value, n)
+    return {"result": result, "unit": unit, "description": _MODE_DESC[mode]}