openmaterials-ai 0.1.3__py3-none-any.whl

omai/__init__.py

@@ -0,0 +1,13 @@
+"""openmaterials-ai: typed operator and representation layers for computational materials science."""
+
+# Read from the installed distribution so this can never disagree with
+# pyproject.toml (it sat at 0.0.1 through the 0.1.0 release). The literal is
+# the fallback for a source tree that was never installed, and is the one
+# place to bump alongside pyproject.
+try:  # pragma: no cover - trivial packaging branch
+    from importlib.metadata import PackageNotFoundError
+    from importlib.metadata import version as _dist_version
+
+    __version__ = _dist_version("openmaterials-ai")
+except (ImportError, PackageNotFoundError):  # pragma: no cover
+    __version__ = "0.1.3"

omai/badge.py

@@ -0,0 +1,229 @@
+"""The openmaterials version badge: a shields-style SVG naming the map version.
+
+Left segment: the mark and the word "openmaterials" on neutral dark. Right
+segment: a map version hash (12 hex characters, the canonical short form) on
+the brand indigo. A repository that uses the map embeds the badge to state
+which version its results were computed against, the same way a CI badge
+states a build:
+
+    [![openmaterials](https://openmaterials.ai/badge/<version12>.svg)](https://openmaterials.ai/)
+
+Two implementations exist and MUST stay byte-identical: this module (writes
+docs/badge.svg for the CURRENT version at map_data time) and the site
+Worker's badge.js (renders /badge/<hash>.svg for any pinned version).
+tests/test_badge.py pins the parity byte for byte, so neither can drift.
+
+The text is width-pinned with the SVG textLength attribute, so the rendered
+badge is pixel-stable regardless of the viewer's fonts; the per-character
+width table below only has to MATCH badge.js, not match Verdana exactly.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+from pathlib import Path
+
+# Approximate Verdana-11 advance widths, px. Shared verbatim with badge.js:
+# parity matters, typographic exactness does not (textLength pins rendering).
+_WIDTHS = {
+    "o": 6.9, "p": 6.9, "e": 6.6, "n": 6.9, "m": 10.6, "a": 6.6, "t": 4.6,
+    "r": 4.8, "i": 3.2, "l": 3.2, "s": 5.9,
+    "0": 6.9, "1": 6.9, "2": 6.9, "3": 6.9, "4": 6.9, "5": 6.9, "6": 6.9,
+    "7": 6.9, "8": 6.9, "9": 6.9, "b": 6.9, "c": 6.0, "d": 6.9, "f": 3.7,
+}
+_FALLBACK = 7.0
+
+LABEL = "openmaterials"
+LEFT_BG = "#555"
+RIGHT_BG = "#4f46e5"
+
+# the mark, inlined from docs/assets/favicon.svg (16-grid), scaled to 14px
+_MARK = (
+    '<g transform="translate(5,3) scale(0.875)">'
+    '<rect width="16" height="16" rx="4" fill="#4f46e5"/>'
+    '<path d="M4 4.5 L8 7.5 L4 10.5" stroke="#ffffff" stroke-width="1.6" '
+    'fill="none" stroke-linecap="round" stroke-linejoin="round"/>'
+    '<circle cx="11" cy="8" r="2.6" fill="#ffffff"/>'
+    '<circle cx="11" cy="8" r="1.1" fill="#4f46e5"/>'
+    "</g>"
+)
+
+
+def _round_half_up(x: float) -> int:
+    """JavaScript's Math.round for the positive values used here: ties go
+    UP. Python's round() is banker's rounding (ties to even), which would
+    break byte parity on any .5 width (e.g. the hash a00000000000)."""
+    return math.floor(x + 0.5)
+
+
+def _tenths(x: float) -> float:
+    return _round_half_up(x * 10) / 10
+
+
+def _num(x: float) -> str:
+    """Format a tenth-precision number the way JavaScript does: integers
+    bare (79 not 79.0), everything else with its single decimal."""
+    r = _tenths(x)
+    return str(int(r)) if float(r).is_integer() else str(r)
+
+
+def _text_width(s: str) -> float:
+    return _tenths(sum(_WIDTHS.get(c, _FALLBACK) for c in s))
+
+
+def labeled_badge_svg(label: str, message: str) -> str:
+    """A shields-style badge with an arbitrary label and message, sharing
+    the version badge's exact geometry, mark, and colors. Byte-identical
+    with badge.js statBadgeSVG for the same inputs (parity-pinned)."""
+    lw = _text_width(label)
+    rw = _text_width(message)
+    left = _round_half_up(5 + 14 + 4 + lw + 6)
+    right = _round_half_up(6 + rw + 6)
+    total = left + right
+    lx = _tenths(23 + lw / 2)
+    rx = _tenths(left + right / 2)
+    return (
+        '<svg xmlns="http://www.w3.org/2000/svg" width="' + str(total) +
+        '" height="20" role="img" aria-label="' + label + ": " + message + '">' +
+        "<title>" + label + ": " + message + "</title>" +
+        '<linearGradient id="s" x2="0" y2="100%">' +
+        '<stop offset="0" stop-color="#bbb" stop-opacity=".1"/>' +
+        '<stop offset="1" stop-opacity=".1"/></linearGradient>' +
+        '<clipPath id="r"><rect width="' + str(total) +
+        '" height="20" rx="3" fill="#fff"/></clipPath>' +
+        '<g clip-path="url(#r)">' +
+        '<rect width="' + str(left) + '" height="20" fill="' + LEFT_BG + '"/>' +
+        '<rect x="' + str(left) + '" width="' + str(right) +
+        '" height="20" fill="' + RIGHT_BG + '"/>' +
+        '<rect width="' + str(total) + '" height="20" fill="url(#s)"/></g>' +
+        _MARK +
+        '<g fill="#fff" text-anchor="middle" ' +
+        'font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">' +
+        '<text x="' + _num(lx) + '" y="15" fill="#010101" fill-opacity=".3" ' +
+        'textLength="' + _num(lw) + '">' + label + "</text>" +
+        '<text x="' + _num(lx) + '" y="14" textLength="' + _num(lw) + '">' +
+        label + "</text>" +
+        '<text x="' + _num(rx) + '" y="15" fill="#010101" fill-opacity=".3" ' +
+        'textLength="' + _num(rw) + '">' + message + "</text>" +
+        '<text x="' + _num(rx) + '" y="14" textLength="' + _num(rw) + '">' +
+        message + "</text></g></svg>"
+    )
+
+
+def map_stats() -> dict[str, int]:
+    """The live map statistics the stat badges state, computed from the
+    same published data files every page reads: never hardcoded."""
+    docs = Path(__file__).resolve().parents[1] / "docs"
+    graph = json.loads((docs / "data" / "graph.json").read_text())
+    codes = json.loads((docs / "data" / "codes.json").read_text())
+    insts = json.loads((docs / "data" / "instances.json").read_text())
+    ops = {l["op"] for l in graph.get("links", []) if isinstance(l, dict) and l.get("op")}
+    return {
+        "nodes": len(graph.get("nodes", [])),
+        "operators": len(ops),
+        "codes": len(codes),
+        "values": len(insts if isinstance(insts, list) else insts.get("instances", [])),
+    }
+
+
+def badge_svg(version: str) -> str:
+    """The badge SVG for one map version hash (shown at the canonical 12)."""
+    v = str(version)[:12]
+    lw = _text_width(LABEL)
+    rw = _text_width(v)
+    # mark at x=5 (14 wide), 4px gap, label, 6px right pad
+    left = _round_half_up(5 + 14 + 4 + lw + 6)
+    right = _round_half_up(6 + rw + 6)
+    total = left + right
+    lx = _tenths(23 + lw / 2)
+    rx = _tenths(left + right / 2)
+    return (
+        '<svg xmlns="http://www.w3.org/2000/svg" width="' + str(total) +
+        '" height="20" role="img" aria-label="' + LABEL + ": " + v + '">' +
+        "<title>" + LABEL + " map version " + v + "</title>" +
+        '<linearGradient id="s" x2="0" y2="100%">' +
+        '<stop offset="0" stop-color="#bbb" stop-opacity=".1"/>' +
+        '<stop offset="1" stop-opacity=".1"/></linearGradient>' +
+        '<clipPath id="r"><rect width="' + str(total) +
+        '" height="20" rx="3" fill="#fff"/></clipPath>' +
+        '<g clip-path="url(#r)">' +
+        '<rect width="' + str(left) + '" height="20" fill="' + LEFT_BG + '"/>' +
+        '<rect x="' + str(left) + '" width="' + str(right) +
+        '" height="20" fill="' + RIGHT_BG + '"/>' +
+        '<rect width="' + str(total) + '" height="20" fill="url(#s)"/></g>' +
+        _MARK +
+        '<g fill="#fff" text-anchor="middle" ' +
+        'font-family="Verdana,Geneva,DejaVu Sans,sans-serif" font-size="11">' +
+        '<text x="' + _num(lx) + '" y="15" fill="#010101" fill-opacity=".3" ' +
+        'textLength="' + _num(lw) + '">' + LABEL + "</text>" +
+        '<text x="' + _num(lx) + '" y="14" textLength="' + _num(lw) + '">' +
+        LABEL + "</text>" +
+        '<text x="' + _num(rx) + '" y="15" fill="#010101" fill-opacity=".3" ' +
+        'textLength="' + _num(rw) + '">' + v + "</text>" +
+        '<text x="' + _num(rx) + '" y="14" textLength="' + _num(rw) + '">' +
+        v + "</text></g></svg>"
+    )
+
+
+def write_badge(path: Path | None = None) -> Path:
+    """Write docs/badge.svg for the current map version, read from the
+    version stamp write_version() has already written (single source).
+
+    Also emits the PINNED form as a static file, docs/badge/<version12>.svg,
+    and prunes pins of other versions: before the DNS cutover the site is
+    served by GitHub Pages, which cannot run the Worker's /badge/<hash>.svg
+    route, so the pin the README carries must exist as real bytes. The
+    Worker serves the same bytes for the current version and generates any
+    other hash on demand; the static set is always exactly one file."""
+    docs = Path(__file__).resolve().parents[1] / "docs"
+    version = json.loads((docs / "data" / "version.json").read_text())["version"]
+    out = path or docs / "badge.svg"
+    out.write_text(badge_svg(version) + "\n", encoding="utf-8")
+    pin_dir = docs / "badge"
+    pin_dir.mkdir(exist_ok=True)
+    pin = pin_dir / (version[:12] + ".svg")
+    pin.write_text(badge_svg(version) + "\n", encoding="utf-8")
+    for stale in pin_dir.glob("*.svg"):
+        if stale.name != pin.name:
+            stale.unlink()
+    # the live stat badges, as static files for the Pages origin; the Worker
+    # computes the same numbers from the same data on /badge/stat/<name>.svg
+    stat_dir = pin_dir / "stat"
+    stat_dir.mkdir(exist_ok=True)
+    for name, count in map_stats().items():
+        (stat_dir / (name + ".svg")).write_text(
+            labeled_badge_svg(name, str(count)) + "\n", encoding="utf-8")
+    return out
+
+
+import re as _re
+
+_README_BADGE_RE = _re.compile(
+    r"https://openmaterials\.ai/badge/[0-9a-f]{8,64}\.svg"
+)
+
+
+def pin_readme_badge(readme: Path | None = None) -> Path:
+    """Pin the README badge to the current map version.
+
+    The repository's own README carries the PINNED badge form, not the
+    live /badge.svg: an old commit's README then shows the version that
+    commit actually had. map_data calls this after write_version, so the
+    pin updates in the same commit that moves the version, and
+    tests/test_badge.py fails whenever README and version.json disagree,
+    so a stale pin cannot land."""
+    root = Path(__file__).resolve().parents[1]
+    version = json.loads(
+        (root / "docs" / "data" / "version.json").read_text())["version"][:12]
+    path = readme or root / "README.md"
+    text = path.read_text()
+    pinned = "https://openmaterials.ai/badge/" + version + ".svg"
+    new_text, n = _README_BADGE_RE.subn(pinned, text)
+    if n == 0:
+        raise RuntimeError(
+            "README.md carries no pinned badge URL to update "
+            "(expected https://openmaterials.ai/badge/<hash>.svg)")
+    if new_text != text:
+        path.write_text(new_text)
+    return path

omai/composites/__init__.py

@@ -0,0 +1,14 @@
+"""The composites (effective-medium) domain: composite effective thermal conductivity.
+
+Domain eleven: the effective thermal conductivity of a two-phase composite (a
+dispersed filler in a continuous matrix) with interfacial (Kapitza) resistance,
+via Nan-type effective-medium theory (Nan et al., J. Appl. Phys. 81, 6692 (1997)),
+cross-checked in the spherical limit against Hasselman-Johnson (J. Compos. Mater.
+21, 508 (1987)). Seven nodes (the matrix and filler conductivities as role-labeled
+inputs, the new InterfaceConductance physics, the filler volume fraction, the
+depolarization factors, and the random / aligned effective conductivities) and
+five edges (the depolarization closed form, the Nan random and aligned mixing
+formulas, the Hasselman-Johnson second producer, and the resolve onto the neutral
+ThermalConductivity observable). One new dimension INTERFACE_CONDUCTANCE
+(W/(m^2 K)) falls out of the interface conductance.
+"""

omai/composites/domain.py

@@ -0,0 +1,37 @@
+"""The composites (effective-medium) Domain descriptor."""
+from __future__ import annotations
+
+from omai.map_data import Domain
+from omai.composites import representation as comp_rep
+from omai.composites.operator import EDGES, NODES
+
+# Canonical LaTeX symbol per variable (consistent symbolic names, not words).
+SYMBOLS: dict[str, str] = {
+    "ThermalConductivity[role=matrix]": r"\kappa_m",
+    "ThermalConductivity[role=filler]": r"\kappa_f",
+    "InterfaceConductance": r"G",
+    "FillerVolumeFraction": r"f",
+    "DepolarizationFactor": r"L",
+    "ThermalConductivity[effective_medium=nan,orientation=random]": r"\kappa_c",
+    "ThermalConductivity[effective_medium=nan,orientation=aligned]": r"\kappa_c^{\parallel}",
+}
+
+COMPOSITES = Domain(
+    name="composites",
+    nodes=NODES,
+    edges=EDGES,
+    symbols=SYMBOLS,
+    param_promotions=(),
+    tiers=(
+        (
+            "Composite",
+            "Composite effective thermal conductivity of a filled matrix with "
+            "interfacial (Kapitza) resistance: the matrix and filler "
+            "conductivities, the interface conductance, the filler volume "
+            "fraction and depolarization factors, and the Nan-type "
+            "effective-medium conductivity (random and aligned) cross-checked "
+            "against the Hasselman-Johnson spherical limit.",
+        ),
+    ),
+    representation_package=comp_rep,
+)

omai/composites/operator/__init__.py

@@ -0,0 +1,15 @@
+"""Composites (effective-medium) operator DAG: re-exports the domain's NODES and EDGES.
+
+Importing this package registers the domain's formula-symbol vocabulary and its
+symbol-dimension bindings as side effects (mirroring the thermodynamic-identities /
+electronic-transport / mechanics packages), so validate_dag and the dimensional
+gate see this domain's symbols. Here that side effect is load-bearing: four of the
+five edges are executable closed forms the dimensional gate PROVES, so the new
+field-symbol dimension bindings must be live before the gate runs.
+"""
+from omai.composites.operator import vocabulary as _vocabulary  # registers formula symbols
+from omai.composites.operator import dimensions_registry as _dimensions_registry  # registers symbol dimensions
+from omai.composites.operator.edges import EDGES
+from omai.composites.operator.nodes import NODES
+
+__all__ = ["NODES", "EDGES"]

omai/composites/operator/dimensions_registry.py

@@ -0,0 +1,52 @@
+r"""Symbol-dimension registry of the composites (effective-medium) domain.
+
+Registered into the core registry (`omai.operator.dimcheck`) when
+`omai.composites.operator` is imported, next to the vocabulary module. Four of
+this domain's five edges are executable closed forms the dimensional gate PROVES
+(the fifth, depolarization_factors, is a Piecewise the gate skips), so these
+bindings are load-bearing: they let dimension_of evaluate both sides of the Nan
+random / aligned and Hasselman-Johnson formulas.
+
+  k_m           -> THERMAL_CONDUCTIVITY   (matrix conductivity km)
+  k_f           -> THERMAL_CONDUCTIVITY   (filler tensor; its diagonal k_f[1,1]=k11, k_f[3,3]=k33)
+  G_{int}       -> INTERFACE_CONDUCTANCE  (Kapitza interface conductance G, W/(m^2 K))
+  d_1           -> LENGTH                 (equatorial inclusion dimension)
+  d_3           -> LENGTH                 (polar inclusion dimension)
+  a_{rad}       -> LENGTH                 (sphere radius, Hasselman-Johnson)
+  f_{vol}       -> DIMENSIONLESS          (filler volume fraction)
+  L_{11}, L_{33}-> DIMENSIONLESS          (depolarization factors)
+  p             -> DIMENSIONLESS          (aspect ratio d3/d1)
+  \kappa_c      -> THERMAL_CONDUCTIVITY   (composite effective conductivity)
+
+The gate then proves the Nan / HJ closed forms because the interface term
+2 (1/G) k_ii / d_i = (m^2 K/W)(W/mK)/m is dimensionless, beta_ii is a ratio of
+two THERMAL_CONDUCTIVITY quantities, and the Hasselman-Johnson alpha = (km/G)/a
+is a length over a length; so the effective kappa carries km's
+THERMAL_CONDUCTIVITY exactly. No collision: k_m, k_f, G_{int}, f_{vol},
+L_{11}, L_{33}, \kappa_c, a_{rad}, p are otherwise-unused base names (d_1 / d_3
+are this domain's; \kappa is already bound to THERMAL_CONDUCTIVITY by
+thermal_transport, a harmless matching union).
+"""
+from __future__ import annotations
+
+from omai.operator.dimcheck import register_symbol_dimensions
+from omai.operator.dimensions import (
+    DIMENSIONLESS,
+    INTERFACE_CONDUCTANCE,
+    LENGTH,
+    THERMAL_CONDUCTIVITY,
+)
+
+register_symbol_dimensions({
+    "k_m": THERMAL_CONDUCTIVITY,
+    "k_f": THERMAL_CONDUCTIVITY,
+    "G_{int}": INTERFACE_CONDUCTANCE,
+    "d_1": LENGTH,
+    "d_3": LENGTH,
+    "a_{rad}": LENGTH,
+    "f_{vol}": DIMENSIONLESS,
+    "L_{11}": DIMENSIONLESS,
+    "L_{33}": DIMENSIONLESS,
+    "p": DIMENSIONLESS,
+    r"\kappa_c": THERMAL_CONDUCTIVITY,
+})

omai/composites/operator/edges.py

@@ -0,0 +1,295 @@
+r"""Operators (edges) of the composites (effective-medium) domain.
+
+Five edges implementing the composite effective thermal conductivity of a
+filled matrix with interfacial (Kapitza) resistance:
+
+  depolarization_factors          : () -> DepolarizationFactor
+  nan_effective_kappa             : (matrix, filler, interface, fraction,
+                                     depolarization) -> effective[orientation=random]
+  nan_effective_kappa_aligned     : (matrix, filler, interface, fraction,
+                                     depolarization) -> effective[orientation=aligned]
+  hasselman_johnson               : (matrix, filler, interface, fraction)
+                                     -> effective[orientation=random]  (2nd producer)
+  resolve_effective_conductivity  : (effective[orientation=random])
+                                     -> ThermalConductivity (neutral observable)
+
+Physics (Nan et al., J. Appl. Phys. 81, 6692 (1997)) with the interface as a
+per-direction series film (Nan et al., Appl. Phys. Lett. 85, 3549 (2004) form):
+the interface-corrected filler conductivity along axis i is
+kc_ii = k_ii / (1 + 2 R k_ii / d_i) with R = 1/G the interface resistance and
+d_i the full inclusion dimension. The Bruggeman-Nan beta terms are
+beta_ii = (kc_ii - km) / (km + L_ii (kc_ii - km)); the randomly-oriented scalar
+and the perfectly-aligned tensor are the two mixing formulas. At aspect ratio 1
+(a sphere, isotropic filler) the Nan random result reduces EXACTLY to the
+Hasselman-Johnson sphere formula (J. Compos. Mater. 21, 508 (1987)); the domain
+test pins that equality to machine precision.
+
+Executability and the dimensional gate. Four of the five edges are explicit
+closed-form sympy Eqs written INLINE (kc_ii, beta_ii substituted), so the
+dimensional gate PROVES them: every sub-ratio is dimensionless (the interface
+term 2 (1/G) k_ii / d_i is dimensionless because 1/G is m^2 K / W, k_ii is
+W/(m K), d_i is m; beta_ii is a ratio of two THERMAL_CONDUCTIVITY quantities),
+so the effective kappa carries km's THERMAL_CONDUCTIVITY exactly. The
+depolarization_factors edge is a sp.Piecewise closed form in the dimensionless
+aspect ratio; the gate SKIPS it (Piecewise is not in the dimension recursion),
+which is acceptable: the dimensional gate only needs the dimensionless SHAPE,
+and the numeric branches are exercised by the domain test and served by the
+representation adapter. resolve_effective_conductivity is the identity edge that
+anchors the composite result onto the neutral ThermalConductivity observable
+(the connectivity bridge to the pre-existing map, the resolve_thermal_conductivity
+precedent).
+
+Symbols (all bound in dimensions_registry so the gate proves the four closed
+forms): k_m (THERMAL_CONDUCTIVITY, matrix), the filler tensor kappa_f[alpha,beta]
+whose diagonal gives k_{11} = kappa_f[1,1] and k_{33} = kappa_f[3,3]
+(THERMAL_CONDUCTIVITY), G_{int} (INTERFACE_CONDUCTANCE), d_1 / d_3 (LENGTH),
+f_{vol} / L_{11} / L_{33} (DIMENSIONLESS), and the outputs kappa_c
+(THERMAL_CONDUCTIVITY). The Hasselman-Johnson edge additionally uses a_{rad}
+(LENGTH, the sphere radius) and reads the filler diagonal k_{33} (= k_{11} for
+the isotropic sphere it models).
+"""
+from __future__ import annotations
+
+import sympy as sp
+
+from omai.operator.operator import Operator
+from omai.composites.operator.nodes import (
+    DEPOLARIZATION_FACTOR,
+    EFFECTIVE_CONDUCTIVITY_ALIGNED,
+    EFFECTIVE_CONDUCTIVITY_RANDOM,
+    FILLER_CONDUCTIVITY,
+    FILLER_VOLUME_FRACTION,
+    INTERFACE_CONDUCTANCE_NODE,
+    MATRIX_CONDUCTIVITY,
+)
+from omai.thermal_transport.operator.nodes import THERMAL_CONDUCTIVITY
+
+
+# ---------------------------------------------------------------------------
+# Symbols. Every base name is bound in this domain's dimensions_registry (or is
+# a pure-number constant), so the dimensional gate proves the four closed forms.
+# ---------------------------------------------------------------------------
+
+_km = sp.Symbol("k_m", positive=True)             # matrix kappa, THERMAL_CONDUCTIVITY
+_kf = sp.IndexedBase("k_f")                        # filler kappa tensor, diagonal read below
+_k11 = _kf[1, 1]                                    # transverse (in-plane) filler kappa
+_k33 = _kf[3, 3]                                    # axial (through-plane) filler kappa
+_G = sp.Symbol("G_{int}", positive=True)           # interface conductance, INTERFACE_CONDUCTANCE
+_d1 = sp.Symbol("d_1", positive=True)              # equatorial dimension, LENGTH
+_d3 = sp.Symbol("d_3", positive=True)              # polar dimension, LENGTH
+_f = sp.Symbol("f_{vol}", nonnegative=True)        # filler volume fraction, DIMENSIONLESS
+_L11 = sp.Symbol("L_{11}")                          # depolarization factor, DIMENSIONLESS
+_L33 = sp.Symbol("L_{33}")                          # depolarization factor, DIMENSIONLESS
+_kappa_c = sp.Symbol(r"\kappa_c", positive=True)   # composite effective kappa, THERMAL_CONDUCTIVITY
+_p = sp.Symbol("p", positive=True)                 # aspect ratio d3/d1, DIMENSIONLESS
+_a = sp.Symbol("a_{rad}", positive=True)           # sphere radius (HJ), LENGTH
+
+# Interface resistance R = 1/G and the per-direction interface-corrected filler
+# conductivity kc_ii = k_ii / (1 + 2 R k_ii / d_i). Written inline so the gate
+# proves the effective-kappa closed forms.
+_R = 1 / _G
+_kc11 = _k11 / (1 + 2 * _R * _k11 / _d1)
+_kc33 = _k33 / (1 + 2 * _R * _k33 / _d3)
+_beta11 = (_kc11 - _km) / (_km + _L11 * (_kc11 - _km))
+_beta33 = (_kc33 - _km) / (_km + _L33 * (_kc33 - _km))
+
+
+# ---------------------------------------------------------------------------
+# Depolarization factors (closed form; sp.Piecewise, gate-skipped by design).
+# L33(p) has an atanh branch for prolate p>1, an atan branch for oblate p<1, and
+# the sphere value 1/3 at p=1; L11 = (1 - L33)/2 (the sum rule 2 L11 + L33 = 1).
+# ---------------------------------------------------------------------------
+
+_e_prolate = sp.sqrt(1 - 1 / _p**2)
+_e_oblate = sp.sqrt(1 / _p**2 - 1)
+_L33_expr = sp.Piecewise(
+    (sp.Rational(1, 3), sp.Eq(_p, 1)),
+    (((1 - _e_prolate**2) / _e_prolate**3) * (sp.atanh(_e_prolate) - _e_prolate), _p > 1),
+    (((1 + _e_oblate**2) / _e_oblate**3) * (_e_oblate - sp.atan(_e_oblate)), True),
+)
+
+depolarization_factors = Operator(
+    name="depolarization_factors",
+    inputs=(),
+    outputs=(DEPOLARIZATION_FACTOR,),
+    formula=sp.Eq(_L33, _L33_expr),
+    auxiliary_formulas=(sp.Eq(_L11, (1 - _L33) / 2),),
+    description=(
+        "Spheroid depolarization (Eshelby) factors (L11, L33) of an "
+        "axially-symmetric inclusion (polar axis 3) from the aspect ratio "
+        "p = d3/d1: a closed form, L33(p) with an atanh branch for prolate p>1 "
+        "(fiber), an atan branch for oblate p<1 (platelet), and the sphere value "
+        "1/3 at p=1, with L11 = (1 - L33)/2 enforcing the sum rule 2 L11 + L33 = "
+        "1. Analytic limits sphere (1/3, 1/3), long fiber (1/2, 0), thin disk "
+        "(0, 1). The aspect ratio rides in the record conditions (this is a "
+        "geometry-from-conditions producer, nullary at the store level, like the "
+        "source provide_ edges). Formula is a sp.Piecewise: the dimensional gate "
+        "SKIPS it (the output is dimensionless by construction and the gate only "
+        "needs the shape), and the numeric branches are pinned by the domain test."
+    ),
+)
+
+
+# ---------------------------------------------------------------------------
+# Nan effective conductivity, randomly oriented filler (the scalar observable).
+# kappa_c = km (3 + f (2 beta11 (1-L11) + beta33 (1-L33)))
+#              / (3 - f (2 beta11 L11 + beta33 L33)),  written inline -> gate PROVES.
+# ---------------------------------------------------------------------------
+
+_nan_random_rhs = _km * (
+    3 + _f * (2 * _beta11 * (1 - _L11) + _beta33 * (1 - _L33))
+) / (
+    3 - _f * (2 * _beta11 * _L11 + _beta33 * _L33)
+)
+
+nan_effective_kappa = Operator(
+    name="nan_effective_kappa",
+    inputs=(MATRIX_CONDUCTIVITY, FILLER_CONDUCTIVITY, INTERFACE_CONDUCTANCE_NODE,
+            FILLER_VOLUME_FRACTION, DEPOLARIZATION_FACTOR),
+    outputs=(EFFECTIVE_CONDUCTIVITY_RANDOM,),
+    formula=sp.Eq(_kappa_c, _nan_random_rhs),
+    auxiliary_formulas=(
+        sp.Eq(sp.Symbol("kc_{11}"), _kc11),
+        sp.Eq(sp.Symbol("kc_{33}"), _kc33),
+        sp.Eq(sp.Symbol(r"\beta_{11}"), _beta11),
+        sp.Eq(sp.Symbol(r"\beta_{33}"), _beta33),
+    ),
+    description=(
+        "Nan-type effective-medium thermal conductivity for RANDOMLY oriented "
+        "filler with a per-direction interfacial (Kapitza) series film "
+        "(Nan et al., J. Appl. Phys. 81, 6692 (1997)): the isotropic scalar "
+        "kappa_c = km (3 + f (2 beta11 (1-L11) + beta33 (1-L33))) / (3 - f (2 "
+        "beta11 L11 + beta33 L33)), with the interface-corrected filler "
+        "conductivities kc_ii = k_ii / (1 + 2 R k_ii / d_i) (R = 1/G) and the "
+        "Bruggeman-Nan terms beta_ii = (kc_ii - km) / (km + L_ii (kc_ii - km)) "
+        "substituted INLINE. The dimensional gate PROVES it: every sub-ratio is "
+        "dimensionless (2 (1/G) k_ii / d_i = (m^2 K/W)(W/mK)/m = 1; beta_ii is a "
+        "ratio of two W/(m K) quantities), so kappa_c carries km's "
+        "THERMAL_CONDUCTIVITY (1,1,-3,-1,0,0,0). Zero loading (f=0) returns km. "
+        "Below the Kapitza radius a_K = km/G a conductive filler LOWERS kappa_c. "
+        "The reference DGEBA epoxy + 5 vol% GNP (km=0.2, k11=1200, k33=6, d1=5um, "
+        "d3=0.02um, G=25 MW/m2K, f=0.05) gives kappa_c = 1.2452 W/(m K)."
+    ),
+)
+
+
+# ---------------------------------------------------------------------------
+# Nan effective conductivity, perfectly aligned filler (anisotropic tensor).
+# Declared closed form is the AXIAL (through-plane) component al33; the transverse
+# al11 is its L11 / beta11 companion (documented, rides in conditions).
+# al33 = km (1 + f beta33 (1-L33)) / (1 - f beta33 L33),  inline -> gate PROVES.
+# ---------------------------------------------------------------------------
+
+_nan_aligned33_rhs = _km * (1 + _f * _beta33 * (1 - _L33)) / (1 - _f * _beta33 * _L33)
+
+nan_effective_kappa_aligned = Operator(
+    name="nan_effective_kappa_aligned",
+    inputs=(MATRIX_CONDUCTIVITY, FILLER_CONDUCTIVITY, INTERFACE_CONDUCTANCE_NODE,
+            FILLER_VOLUME_FRACTION, DEPOLARIZATION_FACTOR),
+    outputs=(EFFECTIVE_CONDUCTIVITY_ALIGNED,),
+    formula=sp.Eq(_kappa_c, _nan_aligned33_rhs),
+    auxiliary_formulas=(
+        sp.Eq(sp.Symbol(r"\kappa_c^{al11}"),
+              _km * (1 + _f * _beta11 * (1 - _L11)) / (1 - _f * _beta11 * _L11)),
+    ),
+    description=(
+        "Nan-type effective conductivity for PERFECTLY ALIGNED filler "
+        "(Nan et al. 1997), a different mixing formula from the random "
+        "orientation: the anisotropic composite tensor whose AXIAL "
+        "(through-plane, along the alignment axis 3) component is the declared "
+        "closed form al33 = km (1 + f beta33 (1-L33)) / (1 - f beta33 L33), and "
+        "whose TRANSVERSE (in-plane, transverse to axis 3) component is the "
+        "L11/beta11 companion al11 = km (1 + f beta11 (1-L11)) / (1 - f beta11 "
+        "L11) (the auxiliary formula; it rides in instance conditions, the "
+        "elastic-constants precedent for tensor components). Same inline kc_ii / "
+        "beta_ii substitution, so the gate PROVES al33 carries km's "
+        "THERMAL_CONDUCTIVITY. Aligned platelets are the enhancement geometry a "
+        "thermal-interface material targets."
+    ),
+)
+
+
+# ---------------------------------------------------------------------------
+# Hasselman-Johnson sphere cross-check (J. Compos. Mater. 21, 508 (1987)), a
+# SECOND PRODUCER (Pattern C) of the random effective-kappa node. For an
+# isotropic spherical filler (kp = k11 = k33, radius a) with interfacial
+# resistance, alpha = a_K / a = (km/G)/a (dimensionless), and
+# kappa_c = km [kp(1+2a) + 2km + 2f(kp(1-a)-km)] / [kp(1+2a) + 2km - f(kp(1-a)-km)].
+# At aspect 1 the Nan random result reduces to this EXACTLY; the domain test pins
+# the agreement to machine precision. Written inline -> the gate PROVES it.
+# ---------------------------------------------------------------------------
+
+_alpha_hj = (_km / _G) / _a
+_hj_diff = _k33 * (1 - _alpha_hj) - _km
+_hj_rhs = _km * (
+    _k33 * (1 + 2 * _alpha_hj) + 2 * _km + 2 * _f * _hj_diff
+) / (
+    _k33 * (1 + 2 * _alpha_hj) + 2 * _km - _f * _hj_diff
+)
+
+hasselman_johnson = Operator(
+    name="hasselman_johnson",
+    inputs=(MATRIX_CONDUCTIVITY, FILLER_CONDUCTIVITY, INTERFACE_CONDUCTANCE_NODE,
+            FILLER_VOLUME_FRACTION),
+    outputs=(EFFECTIVE_CONDUCTIVITY_RANDOM,),
+    formula=sp.Eq(_kappa_c, _hj_rhs),
+    description=(
+        "Hasselman-Johnson effective conductivity for spherical filler with "
+        "interfacial (Kapitza) resistance (J. Compos. Mater. 21, 508 (1987)), an "
+        "INDEPENDENT cross-check: for an isotropic sphere (kp = k11 = k33, radius "
+        "a) with alpha = a_K / a = (km/G)/a the Kapitza-radius-to-radius ratio "
+        "(dimensionless), kappa_c = km [kp(1+2 alpha) + 2 km + 2 f (kp(1-alpha) - "
+        "km)] / [kp(1+2 alpha) + 2 km - f (kp(1-alpha) - km)]. Reads the filler "
+        "diagonal k33 (= k11 for the isotropic sphere it models). SECOND PRODUCER "
+        "(Pattern C) of the random effective-kappa node alongside "
+        "nan_effective_kappa: at aspect ratio 1 (a sphere) the Nan random formula "
+        "reduces to THIS one EXACTLY, so the two must agree numerically (the "
+        "redundant-route pattern BulkModulus's three producers already bless); the "
+        "domain test pins the agreement to machine precision. The dimensional gate "
+        "PROVES it: alpha is dimensionless (km/G is a length, over the radius a), "
+        "so kappa_c carries km's THERMAL_CONDUCTIVITY."
+    ),
+)
+
+
+# ---------------------------------------------------------------------------
+# Resolve onto the method-neutral observable. The composite effective
+# conductivity IS a thermal conductivity: a measurement of the composite reports
+# THIS observable, and the effective-medium route is its estimator. This edge
+# anchors the random effective-kappa onto the neutral ThermalConductivity node
+# (the resolve_thermal_conductivity precedent), which also connects this domain
+# to the pre-existing map (connectivity: the neutral node is a pre-existing store
+# node). Identity Eq, marked executable like resolve_thermal_conductivity.
+# ---------------------------------------------------------------------------
+
+_kappa_obs = sp.IndexedBase(r"\kappa")
+
+resolve_effective_conductivity = Operator(
+    name="resolve_effective_conductivity",
+    inputs=(EFFECTIVE_CONDUCTIVITY_RANDOM,),
+    outputs=(THERMAL_CONDUCTIVITY,),
+    formula=sp.Eq(_kappa_obs[sp.Symbol("alpha"), sp.Symbol("beta")],
+                  _kappa_obs[sp.Symbol("alpha"), sp.Symbol("beta")]),
+    is_executable_in_sympy_override=True,
+    description=(
+        "Identity: the randomly-oriented composite effective conductivity is the "
+        "physical thermal conductivity a measurement of the composite reports "
+        "(isotropic, so its scalar sits on the diagonal of the neutral kappa "
+        "tensor). This edge anchors the composite result onto the method-neutral "
+        "ThermalConductivity observable, the home for measured and "
+        "method-unspecified kappa: the Nan effective-medium route (and the "
+        "Hasselman-Johnson second producer) are ESTIMATORS of this observable, "
+        "related by the shared thermal_conductivity tag, exactly the "
+        "resolve_thermal_conductivity precedent that anchors the lattice LBTE "
+        "kappa. It also bridges this domain to the pre-existing map (the neutral "
+        "node already exists in the store)."
+    ),
+)
+
+EDGES: tuple[Operator, ...] = (
+    depolarization_factors,
+    nan_effective_kappa,
+    nan_effective_kappa_aligned,
+    hasselman_johnson,
+    resolve_effective_conductivity,
+)