tnfr 4.5.2__py3-none-any.whl → 8.5.0__py3-none-any.whl

tnfr/alias.py

@@ -4,39 +4,113 @@
 alias-based attribute access. Legacy wrappers ``alias_get`` and
 ``alias_set`` have been removed; use :func:`get_attr` and
 :func:`set_attr` instead.
+
+CRITICAL: Canonical Attribute Access
+=====================================
+
+**ALWAYS use the alias system for reading/writing TNFR attributes.**
+
+The TNFR canonical attribute keys use Unicode symbols (e.g., 'νf' for structural
+frequency), but NetworkX and Python code often use ASCII equivalents (e.g., 'vf').
+This creates a critical inconsistency:
+
+**WRONG (breaks canonicity)**:
+    >>> G.add_node(0, vf=1.0)           # Uses ASCII 'vf' key
+    >>> value = G.nodes[0]['vf']         # Reads ASCII 'vf' - may not exist!
+    >>> G.nodes[0]['vf'] = 2.0           # Writes ASCII 'vf' - wrong key!
+
+**CORRECT (maintains canonicity)**:
+    >>> from tnfr.alias import set_vf, get_attr
+    >>> from tnfr.constants.aliases import ALIAS_VF
+    >>> from tnfr.constants import VF_PRIMARY
+    >>>
+    >>> # For initialization, use canonical setters:
+    >>> set_vf(G, 0, 1.0)                # Writes to 'νf' (Greek nu)
+    >>>
+    >>> # For reading, use canonical getters:
+    >>> value = get_attr(G.nodes[0], ALIAS_VF, 0.0)  # Reads from 'νf'
+    >>>
+    >>> # Or use PRIMARY constants in add_node:
+    >>> G.add_node(1, **{VF_PRIMARY: 1.0})  # Writes to 'νf' directly
+
+**Why This Matters**:
+- The alias system tries ALL aliases in order: ('νf', 'nu_f', 'nu-f', 'nu', 'freq', 'frequency')
+- If you write to 'vf', the data is stored under a key NOT in the alias list
+- Reading via get_attr() will return the default (0.0) instead of your value
+- This breaks the nodal equation: ∂EPI/∂t = νf · ΔNFR(t)
+
+**For Tests**:
+    >>> from tnfr.structural import create_nfr
+    >>> # PREFERRED: Use create_nfr which handles canonicity
+    >>> G, node = create_nfr("test", vf=1.0, epi=0.5, theta=0.0)
+    >>>
+    >>> # ALTERNATIVE: Manual initialization with canonical setters
+    >>> from tnfr.alias import set_vf, get_attr
+    >>> from tnfr.constants.aliases import ALIAS_VF
+    >>> G = nx.Graph()
+    >>> G.add_node(0, theta=0.0, EPI=1.0, Si=0.5)  # Other attrs OK
+    >>> set_vf(G, 0, 1.0)                          # Use canonical setter for vf
+    >>> value = get_attr(G.nodes[0], ALIAS_VF, 0.0)  # Use canonical getter
+
+**Applies to**: νf (vf), θ (theta), ΔNFR (dnfr), and other aliased attributes.
+See ALIAS_VF, ALIAS_THETA, ALIAS_DNFR in tnfr.constants.aliases for full lists.
 """
 
 from __future__ import annotations
+
 from collections import defaultdict
-from collections.abc import Iterable, Sized
-from dataclasses import dataclass
+from collections.abc import Iterable, Mapping, MutableMapping, Sized
+from functools import lru_cache, partial
+from threading import Lock
+from types import ModuleType
 from typing import (
+    TYPE_CHECKING,
     Any,
     Callable,
-    TypeVar,
-    Optional,
     Generic,
     Hashable,
-    TYPE_CHECKING,
+    Optional,
+    TypeVar,
     cast,
 )
 
-from functools import lru_cache, partial
-from threading import Lock
-
-from .constants import get_aliases
-from .value_utils import convert_value
-
-ALIAS_VF = get_aliases("VF")
-ALIAS_DNFR = get_aliases("DNFR")
-ALIAS_THETA = get_aliases("THETA")
+from .compat.dataclass import dataclass
+from .constants.aliases import ALIAS_DNFR, ALIAS_THETA, ALIAS_VF
+from .types import FloatArray, NodeId
+from .utils import convert_value
 
 if TYPE_CHECKING:  # pragma: no cover
-    import networkx  # type: ignore[import-untyped]
+    import networkx
 
 T = TypeVar("T")
 
 
+def _bepi_to_float(value: Any) -> float:
+    """Extract scalar from BEPIElement dict or convert value to float.
+
+    When operators transform EPI from float to BEPIElement dict, this helper
+    extracts the maximum magnitude from the 'continuous' component. This
+    preserves ΔNFR semantics (§3.3) and structural metrics accuracy (§3.9).
+
+    Parameters
+    ----------
+    value : Any
+        Value to convert. If it's a dict with a 'continuous' key, extracts
+        the maximum magnitude. Otherwise converts directly to float.
+
+    Returns
+    -------
+    float
+        Scalar representation of the value.
+    """
+    if isinstance(value, dict) and "continuous" in value:
+        cont = value["continuous"]
+        if isinstance(cont, tuple):
+            return float(max(abs(c) for c in cont)) if cont else 0.0
+        return float(abs(cont))
+    return float(value)
+
+
 @lru_cache(maxsize=128)
 def _alias_cache(alias_tuple: tuple[str, ...]) -> tuple[str, ...]:
     """Validate and cache alias tuples.
@@ -132,6 +206,8 @@ class AliasAccessor(Generic[T]):
         log_level: int | None = None,
         conv: Callable[[Any], T] | None = None,
     ) -> Optional[T]:
+        """Return ``value`` for the first alias present in ``d``."""
+
         aliases, conv, default = self._prepare(aliases, conv, default)
         cache_key, key = self._resolve_cache_key(d, aliases)
         if key is not None:
@@ -168,6 +244,8 @@ class AliasAccessor(Generic[T]):
         value: Any,
         conv: Callable[[Any], T] | None = None,
     ) -> T:
+        """Write ``value`` under the first matching alias and cache the choice."""
+
         aliases, conv, _ = self._prepare(aliases, conv)
         cache_key, key = self._resolve_cache_key(d, aliases)
         if key is not None:
@@ -184,6 +262,25 @@ class AliasAccessor(Generic[T]):
 _generic_accessor: AliasAccessor[Any] = AliasAccessor()
 
 
+def get_theta_attr(
+    d: Mapping[str, Any],
+    default: T | None = None,
+    *,
+    strict: bool = False,
+    log_level: int | None = None,
+    conv: Callable[[Any], T] = float,
+) -> T | None:
+    """Return ``theta``/``phase`` using the English alias set."""
+    return _generic_accessor.get(
+        cast(dict[str, Any], d),
+        ALIAS_THETA,
+        default,
+        strict=strict,
+        log_level=log_level,
+        conv=conv,
+    )
+
+
 def get_attr(
     d: dict[str, Any],
     aliases: Iterable[str],
@@ -191,9 +288,17 @@ def get_attr(
     *,
     strict: bool = False,
     log_level: int | None = None,
-    conv: Callable[[Any], T] = float,
+    conv: Callable[[Any], T] = _bepi_to_float,
 ) -> T | None:
-    """Return the value for the first key in ``aliases`` found in ``d``."""
+    """Return the value for the first key in ``aliases`` found in ``d``.
+
+    WARNING: This function searches for keys in alias order. If you manually
+    wrote to a non-canonical key (e.g., 'vf' instead of 'νf'), this function
+    will NOT find it and will return the default value instead.
+
+    For structural frequency: ALWAYS use set_vf() to write, not d['vf'] = value.
+    See module docstring for detailed guidance on canonical attribute access.
+    """
 
     return _generic_accessor.get(
         d,
@@ -207,12 +312,12 @@ def get_attr(
 
 def collect_attr(
     G: "networkx.Graph",
-    nodes: Iterable[Any],
+    nodes: Iterable[NodeId],
     aliases: Iterable[str],
     default: float = 0.0,
     *,
-    np=None,
-):
+    np: ModuleType | None = None,
+) -> FloatArray | list[float]:
     """Collect attribute values for ``nodes`` from ``G`` using ``aliases``.
 
     Parameters
@@ -235,7 +340,7 @@ def collect_attr(
         Collected attribute values in the same order as ``nodes``.
     """
 
-    def _nodes_iter_and_size(nodes: Iterable[Any]) -> tuple[Iterable[Any], int]:
+    def _nodes_iter_and_size(nodes: Iterable[NodeId]) -> tuple[Iterable[NodeId], int]:
         if nodes is G.nodes:
             return G.nodes, G.number_of_nodes()
         if isinstance(nodes, Sized):
@@ -245,13 +350,46 @@ def collect_attr(
 
     nodes_iter, size = _nodes_iter_and_size(nodes)
 
+    def _value(node: NodeId) -> float:
+        return float(get_attr(G.nodes[node], aliases, default))
+
     if np is not None:
-        return np.fromiter(
-            (get_attr(G.nodes[n], aliases, default) for n in nodes_iter),
-            float,
-            count=size,
+        values: FloatArray = np.fromiter(
+            (_value(n) for n in nodes_iter), float, count=size
         )
-    return [get_attr(G.nodes[n], aliases, default) for n in nodes_iter]
+        return values
+    return [_value(n) for n in nodes_iter]
+
+
+def collect_theta_attr(
+    G: "networkx.Graph",
+    nodes: Iterable[NodeId],
+    default: float = 0.0,
+    *,
+    np: ModuleType | None = None,
+) -> FloatArray | list[float]:
+    """Collect ``theta`` values honouring the English-only attribute contract."""
+
+    def _nodes_iter_and_size(nodes: Iterable[NodeId]) -> tuple[Iterable[NodeId], int]:
+        if nodes is G.nodes:
+            return G.nodes, G.number_of_nodes()
+        if isinstance(nodes, Sized):
+            return nodes, len(nodes)  # type: ignore[arg-type]
+        nodes_list = list(nodes)
+        return nodes_list, len(nodes_list)
+
+    nodes_iter, size = _nodes_iter_and_size(nodes)
+
+    def _value(node: NodeId) -> float:
+        return float(get_theta_attr(G.nodes[node], default))
+
+    if np is not None:
+        values: FloatArray = np.fromiter(
+            (_value(n) for n in nodes_iter), float, count=size
+        )
+        return values
+
+    return [_value(n) for n in nodes_iter]
 
 
 def set_attr_generic(
@@ -261,20 +399,37 @@ def set_attr_generic(
     *,
     conv: Callable[[Any], T],
 ) -> T:
-    """Assign ``value`` to the first alias key found in ``d``."""
+    """Assign ``value`` to the FIRST (canonical) alias key in ``aliases``.
+
+    CRITICAL: This function writes to the FIRST key in the alias tuple.
+    For ALIAS_VF = ('νf', 'nu_f', ...), this writes to 'νf' (Greek nu), NOT 'vf'.
+
+    If you later try to read with G.nodes[n]['vf'], you will NOT find the value.
+    ALWAYS use get_attr() to read what set_attr() wrote.
+
+    For high-level usage, prefer set_vf(), set_theta(), etc. which handle this correctly.
+    See module docstring for detailed guidance on canonical attribute access.
+    """
 
     return _generic_accessor.set(d, aliases, value, conv=conv)
 
 
 set_attr = partial(set_attr_generic, conv=float)
 
-
 get_attr_str = partial(get_attr, conv=str)
 set_attr_str = partial(set_attr_generic, conv=str)
 
 
+def set_theta_attr(d: MutableMapping[str, Any], value: Any) -> float:
+    """Assign ``theta``/``phase`` using the English attribute names."""
+    result = float(value)
+    d["theta"] = result
+    d["phase"] = result
+    return result
+
+
 # -------------------------
-# Máximos globales con caché
+# Cached global maxima
 # -------------------------
 
 
@@ -292,7 +447,7 @@ def _coerce_abs_value(value: Any) -> float:
     if value is None:
         return 0.0
     try:
-        return float(value)
+        return _bepi_to_float(value)
     except (TypeError, ValueError):
         return 0.0
 
@@ -388,9 +543,7 @@ def _update_cached_abs_max(
     cur_node = cast(Hashable | None, G.graph.get(node_key))
 
     if val >= cur:
-        return _compute_abs_max_result(
-            G, aliases, key=key, candidate=(n, val)
-        )
+        return _compute_abs_max_result(G, aliases, key=key, candidate=(n, val))
     if cur_node == n:
         return _compute_abs_max_result(G, aliases, key=key)
     return AbsMaxResult(max_value=cur, node=cur_node)
@@ -461,9 +614,7 @@ def set_scalar(
     return set_attr_and_cache(G, n, alias, value, cache=cache, extra=extra)
 
 
-def _increment_trig_version(
-    G: "networkx.Graph", _: Hashable, __: float
-) -> None:
+def _increment_trig_version(G: "networkx.Graph", _: Hashable, __: float) -> None:
     """Increment cached trig version to invalidate trig caches."""
     g = G.graph
     g["_trig_version"] = int(g.get("_trig_version", 0)) + 1
@@ -484,7 +635,7 @@ SCALAR_SETTERS: dict[str, dict[str, Any]] = {
     "theta": {
         "alias": ALIAS_THETA,
         "extra": _increment_trig_version,
-        "doc": "Set ``θ`` for node ``n`` and invalidate trig caches.",
+        "doc": "Set ``theta`` for node ``n`` and invalidate trig caches.",
     },
 }
 
@@ -528,15 +679,41 @@ for _name, _spec in SCALAR_SETTERS.items():
 
 del _name, _spec, _make_scalar_setter
 
+_set_theta_impl = cast(
+    Callable[["networkx.Graph", Hashable, float], AbsMaxResult | None],
+    globals()["set_theta"],
+)
+
+
+def _set_theta_with_compat(
+    G: "networkx.Graph", n: Hashable, value: float
+) -> AbsMaxResult | None:
+    nd = cast(MutableMapping[str, Any], G.nodes[n])
+    result = _set_theta_impl(G, n, value)
+    theta_val = get_theta_attr(nd, value)
+    if theta_val is not None:
+        float_theta = float(theta_val)
+        nd["theta"] = float_theta
+        nd["phase"] = float_theta
+    return result
+
+
+_set_theta_with_compat.__name__ = "set_theta"
+_set_theta_with_compat.__qualname__ = "set_theta"
+_set_theta_with_compat.__doc__ = _set_theta_impl.__doc__
+globals()["set_theta"] = _set_theta_with_compat
 
 __all__ = [
     "AbsMaxResult",
     "set_attr_generic",
     "get_attr",
+    "get_theta_attr",
     "collect_attr",
+    "collect_theta_attr",
     "set_attr",
     "get_attr_str",
     "set_attr_str",
+    "set_theta_attr",
     "set_attr_and_cache",
     "set_attr_with_max",
     "set_scalar",

tnfr/alias.pyi

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable, Mapping, MutableMapping
+from types import ModuleType
+from typing import TYPE_CHECKING, Any, Hashable, TypeVar
+
+from .types import FloatArray, NodeId
+
+if TYPE_CHECKING:
+    import networkx as nx
+
+T = TypeVar("T")
+
+__all__: list[str]
+
+def __getattr__(name: str) -> Any: ...
+
+class AbsMaxResult:
+    max_value: float
+    node: Hashable | None
+
+SCALAR_SETTERS: dict[str, dict[str, Any]]
+
+def get_attr(
+    d: dict[str, Any],
+    aliases: Iterable[str],
+    default: T | None = ...,
+    *,
+    strict: bool = ...,
+    log_level: int | None = ...,
+    conv: Callable[[Any], T] = ...,
+) -> T | None: ...
+def get_theta_attr(
+    d: Mapping[str, Any],
+    default: T | None = ...,
+    *,
+    strict: bool = ...,
+    log_level: int | None = ...,
+    conv: Callable[[Any], T] = ...,
+) -> T | None: ...
+def collect_attr(
+    G: "nx.Graph",
+    nodes: Iterable[NodeId],
+    aliases: Iterable[str],
+    default: float = ...,
+    *,
+    np: ModuleType | None = ...,
+) -> FloatArray | list[float]: ...
+def collect_theta_attr(
+    G: "nx.Graph",
+    nodes: Iterable[NodeId],
+    default: float = ...,
+    *,
+    np: ModuleType | None = ...,
+) -> FloatArray | list[float]: ...
+def set_attr_generic(
+    d: dict[str, Any],
+    aliases: Iterable[str],
+    value: Any,
+    *,
+    conv: Callable[[Any], T],
+) -> T: ...
+def set_attr(
+    d: dict[str, Any],
+    aliases: Iterable[str],
+    value: Any,
+    conv: Callable[[Any], T] = ...,
+) -> T: ...
+def get_attr_str(
+    d: dict[str, Any],
+    aliases: Iterable[str],
+    default: str | None = ...,
+    *,
+    strict: bool = ...,
+    log_level: int | None = ...,
+    conv: Callable[[Any], str] = ...,
+) -> str | None: ...
+def set_attr_str(d: dict[str, Any], aliases: Iterable[str], value: Any) -> str: ...
+def set_theta_attr(d: MutableMapping[str, Any], value: Any) -> float: ...
+def multi_recompute_abs_max(
+    G: "nx.Graph", alias_map: Mapping[str, tuple[str, ...]]
+) -> dict[str, float]: ...
+def set_attr_and_cache(
+    G: "nx.Graph",
+    n: Hashable,
+    aliases: tuple[str, ...],
+    value: float,
+    *,
+    cache: str | None = ...,
+    extra: Callable[["nx.Graph", Hashable, float], None] | None = ...,
+) -> AbsMaxResult | None: ...
+def set_attr_with_max(
+    G: "nx.Graph", n: Hashable, aliases: tuple[str, ...], value: float, *, cache: str
+) -> AbsMaxResult: ...
+def set_scalar(
+    G: "nx.Graph",
+    n: Hashable,
+    alias: tuple[str, ...],
+    value: float,
+    *,
+    cache: str | None = ...,
+    extra: Callable[["nx.Graph", Hashable, float], None] | None = ...,
+) -> AbsMaxResult | None: ...
+def set_vf(
+    G: "nx.Graph", n: Hashable, value: float, *, update_max: bool = ...
+) -> AbsMaxResult | None: ...
+def set_dnfr(G: "nx.Graph", n: Hashable, value: float) -> AbsMaxResult | None: ...
+def set_theta(G: "nx.Graph", n: Hashable, value: float) -> AbsMaxResult | None: ...