otter-hed 0.2.1__py3-none-any.whl

otter/__init__.py

@@ -0,0 +1,45 @@
+"""Public API for otter."""
+
+from __future__ import annotations
+
+from otter._version import __version__
+from otter.workflows import (
+    PlasmaWorkflowConfig,
+    continue_plasma_workflow_from_electronic_result,
+    parse_formula_composition,
+    resolve_plasma_composition,
+    run_formula_workflow,
+    solve_plasma_workflow,
+)
+from otter.io.state import (
+    StateExportOptions,
+    load_plasma_state,
+    save_plasma_state,
+)
+from otter.literature import (
+    CitationMixin,
+    bibliography_entries,
+    get_bibtex_ref_string,
+    get_cite_ref_string,
+    get_formatted_ref_string,
+    write_citations_markdown,
+)
+
+__all__ = [
+    "__version__",
+    "CitationMixin",
+    "PlasmaWorkflowConfig",
+    "StateExportOptions",
+    "continue_plasma_workflow_from_electronic_result",
+    "bibliography_entries",
+    "get_bibtex_ref_string",
+    "get_cite_ref_string",
+    "get_formatted_ref_string",
+    "parse_formula_composition",
+    "load_plasma_state",
+    "resolve_plasma_composition",
+    "run_formula_workflow",
+    "save_plasma_state",
+    "solve_plasma_workflow",
+    "write_citations_markdown",
+]

otter/_version.py

@@ -0,0 +1,8 @@
+"""Source version shared by the public API and runtime reports."""
+
+from __future__ import annotations
+
+__version__ = "0.2.1"
+
+
+__all__ = ["__version__"]

otter/data/__init__.py

@@ -0,0 +1,13 @@
+"""Chemical element data and density helpers."""
+from __future__ import annotations
+
+from otter.data.elements import Element, atomic_weight, element
+from otter.data.helpers import ion_density_bohr3, mu_guess_from_density
+
+__all__ = [
+    "Element",
+    "atomic_weight",
+    "element",
+    "ion_density_bohr3",
+    "mu_guess_from_density",
+]

otter/data/elements.py

@@ -0,0 +1,233 @@
+"""
+otter/data/elements.py
+
+Periodic-table lookup utilities used by tests and example scripts.
+
+Design goals
+------------
+- Keep one canonical mapping: atomic number (Z), symbol, atomic mass.
+- Allow case-insensitive symbol lookup.
+- Provide simple helpers for converting between Z/symbol/mass.
+
+Notes
+-----
+Atomic masses are standard atomic weights for stable elements and conventional
+representative values for short-lived/transuranic elements.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, Iterable, Tuple
+
+
+@dataclass(frozen=True)
+class Element:
+    """Periodic-table entry."""
+
+    z: int
+    symbol: str
+    atomic_mass: float
+
+
+_ELEMENT_ROWS: Tuple[Tuple[int, str, float], ...] = (
+    (1, "H", 1.008),
+    (2, "He", 4.002602),
+    (3, "Li", 6.94),
+    (4, "Be", 9.0121831),
+    (5, "B", 10.81),
+    (6, "C", 12.011),
+    (7, "N", 14.007),
+    (8, "O", 15.999),
+    (9, "F", 18.998403163),
+    (10, "Ne", 20.1797),
+    (11, "Na", 22.98976928),
+    (12, "Mg", 24.305),
+    (13, "Al", 26.9815385),
+    (14, "Si", 28.085),
+    (15, "P", 30.973761998),
+    (16, "S", 32.06),
+    (17, "Cl", 35.45),
+    (18, "Ar", 39.948),
+    (19, "K", 39.0983),
+    (20, "Ca", 40.078),
+    (21, "Sc", 44.955908),
+    (22, "Ti", 47.867),
+    (23, "V", 50.9415),
+    (24, "Cr", 51.9961),
+    (25, "Mn", 54.938044),
+    (26, "Fe", 55.845),
+    (27, "Co", 58.933194),
+    (28, "Ni", 58.6934),
+    (29, "Cu", 63.546),
+    (30, "Zn", 65.38),
+    (31, "Ga", 69.723),
+    (32, "Ge", 72.63),
+    (33, "As", 74.921595),
+    (34, "Se", 78.971),
+    (35, "Br", 79.904),
+    (36, "Kr", 83.798),
+    (37, "Rb", 85.4678),
+    (38, "Sr", 87.62),
+    (39, "Y", 88.90584),
+    (40, "Zr", 91.224),
+    (41, "Nb", 92.90637),
+    (42, "Mo", 95.95),
+    (43, "Tc", 98.0),
+    (44, "Ru", 101.07),
+    (45, "Rh", 102.90550),
+    (46, "Pd", 106.42),
+    (47, "Ag", 107.8682),
+    (48, "Cd", 112.414),
+    (49, "In", 114.818),
+    (50, "Sn", 118.710),
+    (51, "Sb", 121.760),
+    (52, "Te", 127.60),
+    (53, "I", 126.90447),
+    (54, "Xe", 131.293),
+    (55, "Cs", 132.90545196),
+    (56, "Ba", 137.327),
+    (57, "La", 138.90547),
+    (58, "Ce", 140.116),
+    (59, "Pr", 140.90766),
+    (60, "Nd", 144.242),
+    (61, "Pm", 145.0),
+    (62, "Sm", 150.36),
+    (63, "Eu", 151.964),
+    (64, "Gd", 157.25),
+    (65, "Tb", 158.92535),
+    (66, "Dy", 162.500),
+    (67, "Ho", 164.93033),
+    (68, "Er", 167.259),
+    (69, "Tm", 168.93422),
+    (70, "Yb", 173.045),
+    (71, "Lu", 174.9668),
+    (72, "Hf", 178.49),
+    (73, "Ta", 180.94788),
+    (74, "W", 183.84),
+    (75, "Re", 186.207),
+    (76, "Os", 190.23),
+    (77, "Ir", 192.217),
+    (78, "Pt", 195.084),
+    (79, "Au", 196.966569),
+    (80, "Hg", 200.592),
+    (81, "Tl", 204.38),
+    (82, "Pb", 207.2),
+    (83, "Bi", 208.98040),
+    (84, "Po", 209.0),
+    (85, "At", 210.0),
+    (86, "Rn", 222.0),
+    (87, "Fr", 223.0),
+    (88, "Ra", 226.0),
+    (89, "Ac", 227.0),
+    (90, "Th", 232.0377),
+    (91, "Pa", 231.03588),
+    (92, "U", 238.02891),
+    (93, "Np", 237.0),
+    (94, "Pu", 244.0),
+    (95, "Am", 243.0),
+    (96, "Cm", 247.0),
+    (97, "Bk", 247.0),
+    (98, "Cf", 251.0),
+    (99, "Es", 252.0),
+    (100, "Fm", 257.0),
+    (101, "Md", 258.0),
+    (102, "No", 259.0),
+    (103, "Lr", 266.0),
+    (104, "Rf", 267.0),
+    (105, "Db", 268.0),
+    (106, "Sg", 269.0),
+    (107, "Bh", 270.0),
+    (108, "Hs", 277.0),
+    (109, "Mt", 278.0),
+    (110, "Ds", 281.0),
+    (111, "Rg", 282.0),
+    (112, "Cn", 285.0),
+    (113, "Nh", 286.0),
+    (114, "Fl", 289.0),
+    (115, "Mc", 290.0),
+    (116, "Lv", 293.0),
+    (117, "Ts", 294.0),
+    (118, "Og", 294.0),
+)
+
+_BY_Z: Dict[int, Element] = {z: Element(z=z, symbol=symbol, atomic_mass=mass) for z, symbol, mass in _ELEMENT_ROWS}
+_BY_SYMBOL: Dict[str, Element] = {item.symbol.upper(): item for item in _BY_Z.values()}
+
+
+def _normalize_symbol(symbol: str) -> str:
+    """Return canonical case-insensitive symbol key."""
+    s = str(symbol).strip()
+    if not s:
+        raise ValueError("Element symbol cannot be empty.")
+    return s.upper()
+
+
+def all_elements() -> Tuple[Element, ...]:
+    """Return all element entries ordered by atomic number."""
+    return tuple(_BY_Z[z] for z in sorted(_BY_Z))
+
+
+def element_from_z(z: int) -> Element:
+    """Return Element for atomic number z."""
+    z_int = int(z)
+    if z_int not in _BY_Z:
+        raise KeyError(f"Unknown atomic number: {z_int}")
+    return _BY_Z[z_int]
+
+
+def element_from_symbol(symbol: str) -> Element:
+    """Return Element for chemical symbol (case-insensitive)."""
+    key = _normalize_symbol(symbol)
+    if key not in _BY_SYMBOL:
+        raise KeyError(f"Unknown element symbol: {symbol}")
+    return _BY_SYMBOL[key]
+
+
+def element(key: int | str) -> Element:
+    """Return Element from atomic number or symbol string."""
+    if isinstance(key, int):
+        return element_from_z(key)
+    if isinstance(key, str):
+        s = key.strip()
+        if s.isdigit():
+            return element_from_z(int(s))
+        return element_from_symbol(s)
+    raise TypeError("Element key must be int (Z) or str (symbol).")
+
+
+def atomic_number(symbol: str) -> int:
+    """Return atomic number for symbol."""
+    return element_from_symbol(symbol).z
+
+
+def atomic_symbol(z: int) -> str:
+    """Return symbol for atomic number."""
+    return element_from_z(z).symbol
+
+
+def atomic_weight(key: int | str) -> float:
+    """Return atomic mass (atomic weight) for atomic number or symbol."""
+    return element(key).atomic_mass
+
+
+def has_element(key: int | str) -> bool:
+    """Return True if key is a known element symbol or atomic number."""
+    try:
+        element(key)
+        return True
+    except (TypeError, ValueError, KeyError):
+        return False
+
+
+__all__ = [
+    "Element",
+    "all_elements",
+    "element",
+    "element_from_z",
+    "element_from_symbol",
+    "atomic_number",
+    "atomic_symbol",
+    "atomic_weight",
+    "has_element",
+]
+

otter/data/helpers.py

@@ -0,0 +1,131 @@
+"""
+otter/data/helpers.py
+
+Shared helpers for tests and example scripts.
+"""
+from __future__ import annotations
+
+import math
+import numpy as np
+
+from otter.numerics.constants import CM_TO_BOHR
+from otter.data.elements import atomic_weight as element_atomic_weight
+
+
+def ion_density_bohr3(rho_g_cc: float, atomic_weight: float) -> float:
+    """Return ion number density (Bohr^-3) from mass density and atomic weight."""
+    if atomic_weight <= 0.0:
+        raise ValueError("atomic_weight must be positive.")
+    avogadro = 6.02214076e23
+    n_i_cm3 = rho_g_cc / atomic_weight * avogadro
+    return n_i_cm3 / (CM_TO_BOHR ** 3)
+
+
+def resolve_atomic_weight(spec: float | int | str) -> float:
+    """
+    Resolve atomic weight from a direct mass, atomic number, or symbol.
+
+    Rules
+    -----
+    - float -> treated as explicit atomic weight.
+    - int   -> treated as atomic number Z.
+    - str   -> symbol (e.g. \"Al\") or integer string (e.g. \"13\").
+    """
+    if isinstance(spec, bool):
+        raise TypeError("Atomic weight spec must not be bool.")
+    if isinstance(spec, float):
+        if spec <= 0.0:
+            raise ValueError("Atomic weight must be positive.")
+        return float(spec)
+    if isinstance(spec, int):
+        return float(element_atomic_weight(spec))
+    if isinstance(spec, str):
+        s = spec.strip()
+        if not s:
+            raise ValueError("Atomic weight spec string cannot be empty.")
+        if s.replace(".", "", 1).isdigit() and "." in s:
+            val = float(s)
+            if val <= 0.0:
+                raise ValueError("Atomic weight must be positive.")
+            return val
+        return float(element_atomic_weight(s))
+    raise TypeError("Atomic weight spec must be float, int(Z), or str(symbol/Z).")
+
+
+def mu_guess_from_density(n_i: float, zbar: float = 3.0) -> float:
+    """Return a free-electron mu guess from ion density and target Zbar."""
+    n0 = zbar * n_i
+    return 0.5 * (3.0 * np.pi**2 * n0) ** (2.0 / 3.0)
+
+
+def grid_step_from_r(r: np.ndarray, grid_kind: str) -> float:
+    """Return the grid step for the specified grid kind."""
+    if r.size < 2:
+        raise ValueError("Grid must have at least two points.")
+    grid_kind = str(grid_kind).lower()
+    if grid_kind == "log":
+        return float(np.log(r[1] / r[0]))
+    if grid_kind == "sqrt":
+        return float(np.sqrt(r[1]) - np.sqrt(r[0]))
+    if grid_kind == "linear":
+        return float(r[1] - r[0])
+    raise ValueError(f"Unsupported grid_kind: {grid_kind}")
+
+
+def trapz_integral(y: np.ndarray, x: np.ndarray) -> float:
+    """Return a version-independent one-dimensional trapezoidal integral."""
+    y_arr = np.asarray(y, dtype=float)
+    x_arr = np.asarray(x, dtype=float)
+    if y_arr.ndim != 1 or x_arr.ndim != 1 or y_arr.size != x_arr.size:
+        raise ValueError("trapz_integral requires equal one-dimensional arrays.")
+    if y_arr.size < 2:
+        return 0.0
+    return float(
+        np.sum(0.5 * (y_arr[1:] + y_arr[:-1]) * np.diff(x_arr))
+    )
+
+
+def ion_level_weight(energy: float, gamma: float) -> float:
+    """Return the M(e) weight from :cite:`StarrettSaumon2013`, Eq. (81)."""
+    if gamma <= 0.0:
+        return 1.0
+    arg = -2.0 * math.sqrt(math.log(2.0)) * energy / gamma
+    m_val = math.erf(arg)
+    return float(min(max(m_val, 0.0), 1.0))
+
+
+def electron_count(r: np.ndarray,
+                   n: np.ndarray,
+                   r_ws: float | None = None,
+                   r_min: float | None = None) -> float:
+    """Integrate electron density on r (optionally between r_min and r_ws)."""
+    r = np.asarray(r, dtype=float)
+    n = np.asarray(n, dtype=float)
+    mask = np.ones_like(r, dtype=bool)
+    if r_min is not None:
+        mask &= r >= float(r_min)
+    if r_ws is not None:
+        mask &= r <= float(r_ws)
+    if not np.any(mask):
+        return 0.0
+    integrand = n[mask] * r[mask] ** 2
+    if hasattr(np, "trapezoid"):
+        integral = np.trapezoid(integrand, r[mask])
+    else:
+        integral = np.trapz(integrand, r[mask])
+    return float(4.0 * np.pi * integral)
+
+
+def tail_stats(r: np.ndarray, n_full: np.ndarray, n_ext: np.ndarray) -> dict:
+    """Return tail means for full/ext/pa/scr densities."""
+    tail_mask = r >= 0.7 * r[-1]
+    if not np.any(tail_mask):
+        tail_mask = slice(None)
+    n_pa = n_full - n_ext
+    n_scr = n_pa
+    return {
+        "n_full": float(np.mean(n_full[tail_mask])),
+        "n_ext": float(np.mean(n_ext[tail_mask])),
+        "n_pa": float(np.mean(n_pa[tail_mask])),
+        "n_scr": float(np.mean(n_scr[tail_mask])),
+    }

otter/electronic/__init__.py

@@ -0,0 +1,31 @@
+"""Electronic-structure solvers and average-atom workflow drivers."""
+from __future__ import annotations
+
+from otter.electronic.full_external import FullExternalConfig, solve_full_only, solve_full_then_external
+from otter.electronic.ks_dft import KSDTFConfig, solve_ks_dft_is
+from otter.electronic.mixture import MixtureConfig, solve_mixture_full_then_ext, solve_mixture_full_only
+from otter.electronic.thomas_fermi import (
+    FermiHalfEvaluator,
+    ThomasFermiConfig,
+    incomplete_fermi_half_lower,
+    incomplete_fermi_half_upper,
+    solve_thomas_fermi_full_then_external,
+)
+from otter.electronic.xc import xc_provenance
+
+__all__ = [
+    "FermiHalfEvaluator",
+    "FullExternalConfig",
+    "KSDTFConfig",
+    "MixtureConfig",
+    "ThomasFermiConfig",
+    "incomplete_fermi_half_lower",
+    "incomplete_fermi_half_upper",
+    "solve_full_only",
+    "solve_full_then_external",
+    "solve_ks_dft_is",
+    "solve_mixture_full_only",
+    "solve_mixture_full_then_ext",
+    "solve_thomas_fermi_full_then_external",
+    "xc_provenance",
+]

otter/electronic/continuum/__init__.py

@@ -0,0 +1,32 @@
+"""Continuum-electron models."""
+from __future__ import annotations
+
+from otter.electronic.continuum.hybrid import QuantumContinuumHybrid
+from otter.electronic.continuum.ideal import IdealContinuum, ideal_unbound_density
+from otter.electronic.continuum.scattering import (
+    QuantumContinuumFree,
+    QuantumContinuumScattering,
+    continuum_density_free,
+    continuum_density_scattering,
+    continuum_density_scattering_adaptive,
+    continuum_density_scattering_basis,
+    fermi_dirac,
+    gamma_from_phase_shift_cache,
+)
+from otter.electronic.continuum.tail import apply_tail_match, tail_parameters
+
+__all__ = [
+    "IdealContinuum",
+    "QuantumContinuumFree",
+    "QuantumContinuumHybrid",
+    "QuantumContinuumScattering",
+    "apply_tail_match",
+    "continuum_density_free",
+    "continuum_density_scattering",
+    "continuum_density_scattering_adaptive",
+    "continuum_density_scattering_basis",
+    "fermi_dirac",
+    "gamma_from_phase_shift_cache",
+    "ideal_unbound_density",
+    "tail_parameters",
+]

otter/electronic/continuum/hybrid.py

@@ -0,0 +1,124 @@
+"""
+otter/electronic/continuum/hybrid.py
+
+Purpose
+-------
+Provide a hybrid continuum model: quantum scattering at low energies
+plus an ideal-gas high-energy tail.
+
+Methods
+-------
+- Compute low-energy continuum with Numerov scattering (A3).
+- Add a uniform high-energy tail using the ideal free-electron DOS.
+- Default n0_mode uses an integral-based density for consistency.
+
+Equations
+---------
+Ideal DOS contribution (atomic units):
+  n = (sqrt(2)/pi^2) * integral_{e0}^{e1} e^(1/2) f(e; mu, T) de
+
+Hybrid density:
+  n_c(r) = n_low(r; e in [e_min, e_cut]) + n_high (uniform)
+
+References
+----------
+- :cite:`StarrettSaumon2014`, Appendix A/B. The high-energy ideal-gas tail
+  and its splice controls are Otter numerical implementation choices.
+"""
+from __future__ import annotations
+
+from typing import Dict
+import numpy as np
+
+from .interface import ContinuumModel
+from .scattering import fermi_dirac, QuantumContinuumScattering
+from .ideal import ideal_unbound_density
+
+
+def _trapz(y: np.ndarray, x: np.ndarray) -> np.ndarray:
+    if hasattr(np, "trapezoid"):
+        return np.trapezoid(y, x)
+    return np.trapz(y, x)
+
+
+def ideal_density_range(mu: float,
+                         temperature: float,
+                         e_min: float,
+                         e_max: float,
+                         n_samples: int = 800) -> float:
+    """
+    Integrate the ideal free-electron density over a finite energy range.
+
+    Parameters
+    ----------
+    mu : float
+        Chemical potential (Ha).
+    temperature : float
+        Temperature (Ha).
+    e_min : float
+        Lower energy bound (Ha).
+    e_max : float
+        Upper energy bound (Ha).
+    n_samples : int
+        Number of energy samples.
+
+    Returns
+    -------
+    float
+        Density contribution over [e_min, e_max] (Bohr^-3).
+    """
+    if e_max <= e_min:
+        return 0.0
+    e_min = max(float(e_min), 0.0)
+    e_max = float(e_max)
+    n_samples = max(int(n_samples), 16)
+
+    e_grid = np.linspace(e_min, e_max, n_samples)
+    occ = fermi_dirac(e_grid, mu, temperature)
+    integrand = np.sqrt(np.maximum(e_grid, 0.0)) * occ
+    pref = np.sqrt(2.0) / (np.pi ** 2)
+    return float(pref * _trapz(integrand, e_grid))
+
+
+class QuantumContinuumHybrid(ContinuumModel):
+    """
+    Hybrid continuum: scattering at low energy + ideal high-energy tail.
+    """
+
+    def density(self,
+                r: np.ndarray,
+                mu: float,
+                temperature: float,
+                params: Dict[str, float] | None = None) -> np.ndarray:
+        params = params or {}
+
+        v_eff = params.get("v_eff", None)
+        if v_eff is None:
+            raise ValueError("params['v_eff'] is required for hybrid continuum.")
+
+        e_min = float(params.get("e_min", 1e-6))
+        e_cut = float(params.get("e_cut", max(mu + 4.0 * temperature, 1.0)))
+        e_high_max = float(params.get("e_high_max", max(e_cut + 20.0 * temperature, mu + 30.0 * temperature)))
+        n_e_low = int(params.get("n_e_low", 120))
+        n_e_high = int(params.get("n_e_high", 400))
+
+        n0_mode = str(params.get("n0_mode", "integral")).lower()
+        if n0_mode not in ("ideal", "integral"):
+            raise ValueError("n0_mode must be 'ideal' or 'integral'.")
+
+        scatter = QuantumContinuumScattering()
+        low_params = dict(params)
+        low_params["e_max"] = e_cut
+        low_params["n_e"] = n_e_low
+        n_low = scatter.density(r, mu, temperature, params=low_params)
+
+        if n0_mode == "ideal":
+            n0_total = ideal_unbound_density(mu, temperature)
+            n0_low = ideal_density_range(mu, temperature, e_min, e_cut, n_samples=n_e_high)
+            n_high = max(n0_total - n0_low, 0.0)
+        else:
+            n0_total = ideal_density_range(mu, temperature, 0.0, e_high_max, n_samples=n_e_high)
+            n_high = ideal_density_range(mu, temperature, e_cut, e_high_max, n_samples=n_e_high)
+
+        n_hybrid = n_low + n_high
+        return n_hybrid