vcti-derived 1.0.0__py3-none-any.whl

vcti/derived/__init__.py

@@ -0,0 +1,34 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""vcti.derived — An extensible, catalog-driven library for computing
+derived fields from multi-component engineering data arrays.
+"""
+
+from importlib.metadata import version
+
+from . import dof6, ranges, scalar, symtensor, vector
+from .catalog import CATALOG, Catalog, Context, DerivedField, OutputKind, Parameter
+from .families import CANONICAL_COMPONENTS, DataFamily
+from .order import ComponentOrder, OrderLike, SolverOrder
+
+__version__ = version("vcti-derived")
+
+__all__ = [
+    "CANONICAL_COMPONENTS",
+    "CATALOG",
+    "Catalog",
+    "ComponentOrder",
+    "Context",
+    "DataFamily",
+    "DerivedField",
+    "OrderLike",
+    "OutputKind",
+    "Parameter",
+    "SolverOrder",
+    "__version__",
+    "dof6",
+    "ranges",
+    "scalar",
+    "symtensor",
+    "vector",
+]

vcti/derived/catalog.py

@@ -0,0 +1,649 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""The catalog: which derived fields exist, per data family.
+
+Each :class:`DerivedField` entry carries a stable id (append-only once
+shipped — downstream registries build dispatch values from them), display
+metadata, an output kind, a declared parameter spec, and the bound kernel.
+The module-level :data:`CATALOG` is the populated registry; consumers
+enumerate it (``by_family``, ``default``) and compute through entries
+(:meth:`DerivedField.compute`).
+
+Entries never contain math: every kernel lives in a family module, and
+conceptual compositions are fused into kernel parameters there (see
+``docs/design.md``, "Parameterized kernels").
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from dataclasses import dataclass
+from enum import StrEnum
+from functools import partial
+from typing import Any, Final
+
+from numpy.typing import NDArray
+
+from . import dof6, scalar, symtensor, vector
+from .families import CANONICAL_COMPONENTS, DataFamily
+from .order import OrderLike
+
+type Array = NDArray[Any]
+type Kernel = Callable[..., Array]
+
+
+class OutputKind(StrEnum):
+    """The shape of a derived field's output."""
+
+    SCALAR = "scalar"  # (N,)
+    VECTOR = "vector"  # (N, 2) or (N, 3)
+    MATRIX = "matrix"  # (N, k, k)
+
+
+class Context(StrEnum):
+    """The physical vocabulary an entry belongs to, for consumer filtering."""
+
+    GENERAL = "general"
+    STRESS = "stress"
+    STRAIN = "strain"
+    ENGINEERING_STRAIN = "engineering_strain"
+
+
+@dataclass(frozen=True)
+class Parameter:
+    """A declared kernel parameter: name, kind, and default.
+
+    ``default=None`` marks the parameter as required (e.g. the plane
+    normal of a traction entry).
+    """
+
+    name: str
+    kind: str  # "float" | "vector"
+    default: float | tuple[float, ...] | None = None
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class DerivedField:
+    """One derived field: a named computation on one data family."""
+
+    id: str
+    family: DataFamily
+    name: str
+    display_name: str
+    description: str
+    output_kind: OutputKind
+    kernel: Kernel
+    parameters: tuple[Parameter, ...] = ()
+    contexts: tuple[Context, ...] = (Context.GENERAL,)
+
+    def compute(self, a: Array, *, order: OrderLike = None, **params: object) -> Array:
+        """Run the kernel on ``a`` with validated parameters.
+
+        ``order`` maps the caller's component layout onto canonical order
+        (scalar-family entries reject it — scalars have no components).
+        """
+        declared = {p.name: p for p in self.parameters}
+        unknown = set(params) - set(declared)
+        if unknown:
+            raise TypeError(
+                f"{self.id} got unknown parameter(s) {sorted(unknown)}; "
+                f"declared: {sorted(declared)}"
+            )
+        merged: dict[str, object] = {}
+        for name, spec in declared.items():
+            if name in params:
+                merged[name] = params[name]
+            elif spec.default is not None:
+                merged[name] = spec.default
+            else:
+                raise TypeError(f"{self.id} requires parameter {name!r}")
+        if self.family is DataFamily.SCALAR:
+            if order is not None:
+                raise TypeError("scalar fields have no component order")
+            return self.kernel(a, **merged)
+        return self.kernel(a, order=order, **merged)
+
+
+class Catalog:
+    """The registry of derived fields, queryable by family and context."""
+
+    def __init__(self) -> None:
+        self._entries: dict[str, DerivedField] = {}
+        self._defaults: dict[DataFamily, str] = {}
+
+    def register(self, entry: DerivedField, *, default: bool = False) -> None:
+        """Add an entry; ids are unique and, once shipped, append-only."""
+        if entry.id in self._entries:
+            raise ValueError(f"duplicate derived-field id {entry.id!r}")
+        self._entries[entry.id] = entry
+        if default:
+            self._defaults[entry.family] = entry.id
+
+    def get(self, field_id: str) -> DerivedField:
+        """The entry with this id."""
+        try:
+            return self._entries[field_id]
+        except KeyError:
+            raise KeyError(f"unknown derived field {field_id!r}") from None
+
+    def ids(self) -> tuple[str, ...]:
+        """All entry ids, in registration order."""
+        return tuple(self._entries)
+
+    def by_family(
+        self, family: DataFamily, *, context: Context | None = None
+    ) -> tuple[DerivedField, ...]:
+        """The family's entries, optionally filtered to one physical context.
+
+        With a ``context``, entries tagged :attr:`Context.GENERAL` are
+        always included alongside the context-specific ones.
+        """
+        entries = (e for e in self._entries.values() if e.family is family)
+        if context is None:
+            return tuple(entries)
+        return tuple(e for e in entries if context in e.contexts or Context.GENERAL in e.contexts)
+
+    def default(self, family: DataFamily) -> DerivedField:
+        """The family's default entry (e.g. von Mises for symtensor3d)."""
+        try:
+            return self._entries[self._defaults[family]]
+        except KeyError:
+            raise KeyError(f"no default derived field for {family.value}") from None
+
+    def __contains__(self, field_id: str) -> bool:
+        return field_id in self._entries
+
+    def __iter__(self) -> Iterator[DerivedField]:
+        return iter(self._entries.values())
+
+    def __len__(self) -> int:
+        return len(self._entries)
+
+
+_NU: Final = Parameter("nu", "float", 0.5, "Effective Poisson's ratio (0.5 = fully plastic).")
+_NORMAL3: Final = Parameter("normal", "vector", None, "Unit plane normal, (3,) or (N, 3).")
+
+_COMPONENT_DISPLAY: Final[dict[str, str]] = {
+    "tx": "Translational X",
+    "ty": "Translational Y",
+    "tz": "Translational Z",
+    "rx": "Rotational X",
+    "ry": "Rotational Y",
+    "rz": "Rotational Z",
+}
+
+
+def _principal(
+    a: Array,
+    *,
+    index: int,
+    shear_factor: float = 1.0,
+    order: OrderLike = None,
+) -> Array:
+    return symtensor.principals(a, shear_factor=shear_factor, order=order)[:, index]
+
+
+def _principal_direction(a: Array, *, index: int, order: OrderLike = None) -> Array:
+    return symtensor.principal_directions(a, order=order)[:, :, index]
+
+
+def _deviatoric_principal(a: Array, *, index: int, order: OrderLike = None) -> Array:
+    return symtensor.deviatoric_principals(a, order=order)[:, index]
+
+
+def _register_components(
+    catalog: Catalog,
+    family: DataFamily,
+    kernel: Kernel,
+    *,
+    contexts: tuple[Context, ...] = (Context.GENERAL,),
+) -> None:
+    for label in CANONICAL_COMPONENTS[family]:
+        catalog.register(
+            DerivedField(
+                id=f"{family.value}.{label}",
+                family=family,
+                name=label,
+                display_name=_COMPONENT_DISPLAY.get(label, label.upper()),
+                description=f"The {label.upper()} component.",
+                output_kind=OutputKind.SCALAR,
+                kernel=partial(kernel, comp=label),
+                contexts=contexts,
+            )
+        )
+
+
+def _register_scalar(catalog: Catalog) -> None:
+    family = DataFamily.SCALAR
+
+    def entry(
+        name: str,
+        display: str,
+        description: str,
+        kernel: Kernel,
+        parameters: tuple[Parameter, ...] = (),
+    ) -> DerivedField:
+        return DerivedField(
+            id=f"{family.value}.{name}",
+            family=family,
+            name=name,
+            display_name=display,
+            description=description,
+            output_kind=OutputKind.SCALAR,
+            kernel=kernel,
+            parameters=parameters,
+        )
+
+    catalog.register(
+        entry("identity", "Value", "The values unchanged.", scalar.identity),
+        default=True,
+    )
+    catalog.register(
+        entry("absolute", "Absolute Value", "Element-wise absolute value.", scalar.absolute)
+    )
+    catalog.register(
+        entry(
+            "affine",
+            "Affine Conversion",
+            "scale · x + offset — the unit-conversion primitive.",
+            scalar.affine,
+            (
+                Parameter("scale", "float", 1.0, "Multiplier."),
+                Parameter("offset", "float", 0.0, "Additive offset."),
+            ),
+        )
+    )
+    for name in scalar.TEMPERATURE_CONVERSIONS:
+        source, _, target = name.partition("_to_")
+        catalog.register(
+            entry(
+                name,
+                f"{source.capitalize()} → {target.capitalize()}",
+                f"Temperature conversion, {source} to {target}.",
+                partial(scalar.convert, conversion=name),
+            )
+        )
+
+
+def _register_vectors(catalog: Catalog) -> None:
+    for family in (DataFamily.VECTOR2, DataFamily.VECTOR3):
+        _register_components(catalog, family, vector.component)
+        catalog.register(
+            DerivedField(
+                id=f"{family.value}.magnitude",
+                family=family,
+                name="magnitude",
+                display_name="Resultant",
+                description="Euclidean magnitude of the vector.",
+                output_kind=OutputKind.SCALAR,
+                kernel=vector.magnitude,
+            ),
+            default=True,
+        )
+
+
+def _register_dof6(catalog: Catalog) -> None:
+    for family in (DataFamily.DOF6_2D, DataFamily.DOF6_3D):
+        _register_components(catalog, family, dof6.component)
+        k = len(CANONICAL_COMPONENTS[family]) // 2
+
+        def entry(
+            name: str,
+            display: str,
+            description: str,
+            kind: OutputKind,
+            kernel: Kernel,
+            *,
+            fam: DataFamily = family,
+        ) -> DerivedField:
+            return DerivedField(
+                id=f"{fam.value}.{name}",
+                family=fam,
+                name=name,
+                display_name=display,
+                description=description,
+                output_kind=kind,
+                kernel=kernel,
+            )
+
+        catalog.register(
+            entry(
+                "translation",
+                "Translation Vector",
+                f"The translational part, (N, {k}).",
+                OutputKind.VECTOR,
+                dof6.translation,
+            )
+        )
+        catalog.register(
+            entry(
+                "rotation",
+                "Rotation Vector",
+                f"The rotational part, (N, {k}).",
+                OutputKind.VECTOR,
+                dof6.rotation,
+            )
+        )
+        catalog.register(
+            entry(
+                "translation_magnitude",
+                "Translational Magnitude",
+                "Magnitude of the translational part.",
+                OutputKind.SCALAR,
+                dof6.translation_magnitude,
+            ),
+            default=True,
+        )
+        catalog.register(
+            entry(
+                "rotation_magnitude",
+                "Rotational Magnitude",
+                "Magnitude of the rotational part.",
+                OutputKind.SCALAR,
+                dof6.rotation_magnitude,
+            )
+        )
+
+
+def _tensor_entry(
+    family: DataFamily,
+    name: str,
+    display: str,
+    description: str,
+    kernel: Kernel,
+    *,
+    kind: OutputKind = OutputKind.SCALAR,
+    parameters: tuple[Parameter, ...] = (),
+    contexts: tuple[Context, ...] = (Context.GENERAL,),
+) -> DerivedField:
+    return DerivedField(
+        id=f"{family.value}.{name}",
+        family=family,
+        name=name,
+        display_name=display,
+        description=description,
+        output_kind=kind,
+        kernel=kernel,
+        parameters=parameters,
+        contexts=contexts,
+    )
+
+
+def _register_symtensor2d(catalog: Catalog) -> None:
+    family = DataFamily.SYMTENSOR2D
+    _register_components(catalog, family, symtensor.component)
+    entries = [
+        _tensor_entry(family, "mean", "Mean", "In-plane mean: (xx + yy) / 2.", symtensor.mean),
+        _tensor_entry(
+            family,
+            "von_mises",
+            "Von Mises",
+            "Plane-stress von Mises value.",
+            symtensor.von_mises,
+            contexts=(Context.STRESS,),
+        ),
+        _tensor_entry(
+            family,
+            "principals",
+            "Principal Values",
+            "Both in-plane principal values, ascending, (N, 2).",
+            symtensor.principals,
+            kind=OutputKind.VECTOR,
+        ),
+        _tensor_entry(
+            family,
+            "min_principal",
+            "Minimum Principal Value",
+            "The smaller principal value.",
+            partial(_principal, index=0),
+        ),
+        _tensor_entry(
+            family,
+            "max_principal",
+            "Maximum Principal Value",
+            "The larger principal value.",
+            partial(_principal, index=-1),
+        ),
+        _tensor_entry(
+            family,
+            "abs_max_principal",
+            "Absolute Maximum Principal Value",
+            "Signed in-plane principal value of largest magnitude.",
+            symtensor.abs_max_principal,
+        ),
+        _tensor_entry(
+            family,
+            "principal_directions",
+            "Principal Directions",
+            "Unit eigenvectors, (N, 2, 2); [:, :, i] pairs with principal i.",
+            symtensor.principal_directions,
+            kind=OutputKind.MATRIX,
+        ),
+        _tensor_entry(
+            family,
+            "max_shear",
+            "Maximum Shear",
+            "In-plane maximum shear: (tmax − tmin) / 2 (no out-of-plane term).",
+            symtensor.max_shear,
+            contexts=(Context.STRESS,),
+        ),
+        _tensor_entry(
+            family,
+            "max_shear_angle",
+            "Maximum Shear Angle",
+            "Angle of the max-shear direction with the x-axis, degrees.",
+            symtensor.max_shear_angle,
+        ),
+    ]
+    for e in entries:
+        catalog.register(e, default=(e.name == "von_mises"))
+
+
+def _register_symtensor3d(catalog: Catalog) -> None:
+    family = DataFamily.SYMTENSOR3D
+    _register_components(catalog, family, symtensor.component)
+    principal_names = ("min", "mid", "max")
+    entries = [
+        _tensor_entry(
+            family,
+            "mean",
+            "Mean (Hydrostatic)",
+            "Hydrostatic value: (xx + yy + zz) / 3.",
+            symtensor.mean,
+        ),
+        _tensor_entry(
+            family,
+            "von_mises",
+            "Von Mises Stress",
+            "The von Mises equivalent value.",
+            symtensor.von_mises,
+            contexts=(Context.STRESS,),
+        ),
+        _tensor_entry(
+            family,
+            "equivalent_strain",
+            "Von Mises Strain",
+            "1/(1+ν) of the von Mises value; tensorial shear storage.",
+            symtensor.equivalent_strain,
+            parameters=(_NU,),
+            contexts=(Context.STRAIN,),
+        ),
+        _tensor_entry(
+            family,
+            "equivalent_strain_engineering",
+            "Von Mises Strain (Engineering)",
+            "1/(1+ν) of the von Mises value; engineering-shear storage.",
+            partial(symtensor.equivalent_strain, shear_factor=0.5),
+            parameters=(_NU,),
+            contexts=(Context.ENGINEERING_STRAIN,),
+        ),
+        _tensor_entry(
+            family,
+            "octahedral",
+            "Octahedral Shear Stress",
+            "τ_oct = (√2⁄3) · σ_vm.",
+            symtensor.octahedral,
+            contexts=(Context.STRESS,),
+        ),
+        _tensor_entry(
+            family,
+            "principals",
+            "Principal Values",
+            "All three principal values, ascending, (N, 3).",
+            symtensor.principals,
+            kind=OutputKind.VECTOR,
+        ),
+        _tensor_entry(
+            family,
+            "principal_directions",
+            "Principal Directions",
+            "Unit eigenvectors, (N, 3, 3); [:, :, i] pairs with principal i.",
+            symtensor.principal_directions,
+            kind=OutputKind.MATRIX,
+        ),
+        _tensor_entry(
+            family,
+            "max_shear",
+            "Maximum Shear",
+            "(tmax − tmin) / 2.",
+            symtensor.max_shear,
+            contexts=(Context.STRESS,),
+        ),
+        _tensor_entry(
+            family,
+            "equal_direct",
+            "Equal Direct at Maximum Shear",
+            "(tmax + tmin) / 2.",
+            symtensor.equal_direct,
+            contexts=(Context.STRESS,),
+        ),
+        _tensor_entry(
+            family,
+            "intensity",
+            "Intensity",
+            "tmax − tmin (twice the maximum shear).",
+            symtensor.intensity,
+        ),
+        _tensor_entry(
+            family,
+            "abs_max_principal",
+            "Absolute Maximum Principal Value",
+            "Signed principal value of largest magnitude.",
+            symtensor.abs_max_principal,
+        ),
+        _tensor_entry(
+            family,
+            "abs_max_principal_engineering",
+            "Absolute Maximum Principal Strain (Engineering)",
+            "Signed principal of largest magnitude, engineering-shear storage.",
+            partial(symtensor.abs_max_principal, shear_factor=0.5),
+            contexts=(Context.ENGINEERING_STRAIN,),
+        ),
+        _tensor_entry(
+            family,
+            "determinant",
+            "Determinant",
+            "The third invariant.",
+            symtensor.determinant,
+        ),
+        _tensor_entry(
+            family,
+            "traction",
+            "Traction Vector",
+            "t = σ·n on the plane with normal n, (N, 3).",
+            symtensor.traction,
+            kind=OutputKind.VECTOR,
+            parameters=(_NORMAL3,),
+            contexts=(Context.STRESS,),
+        ),
+        _tensor_entry(
+            family,
+            "traction_normal",
+            "Normal Stress Vector",
+            "Normal component of the traction: (t·n)·n, (N, 3).",
+            symtensor.traction_normal,
+            kind=OutputKind.VECTOR,
+            parameters=(_NORMAL3,),
+            contexts=(Context.STRESS,),
+        ),
+        _tensor_entry(
+            family,
+            "traction_shear",
+            "Shear Stress Vector",
+            "Shear component of the traction: t − (t·n)·n, (N, 3).",
+            symtensor.traction_shear,
+            kind=OutputKind.VECTOR,
+            parameters=(_NORMAL3,),
+            contexts=(Context.STRESS,),
+        ),
+    ]
+    for i, which in enumerate(principal_names):
+        entries.append(
+            _tensor_entry(
+                family,
+                f"{which}_principal",
+                f"{which.capitalize()}imum Principal Value"
+                if which != "mid"
+                else "Middle Principal Value",
+                f"The {which} principal value.",
+                partial(_principal, index=i),
+            )
+        )
+        entries.append(
+            _tensor_entry(
+                family,
+                f"{which}_principal_engineering",
+                (
+                    f"{which.capitalize()}imum Principal Strain (Engineering)"
+                    if which != "mid"
+                    else "Middle Principal Strain (Engineering)"
+                ),
+                f"The {which} principal value with engineering-shear storage.",
+                partial(_principal, index=i, shear_factor=0.5),
+                contexts=(Context.ENGINEERING_STRAIN,),
+            )
+        )
+        entries.append(
+            _tensor_entry(
+                family,
+                f"{which}_principal_direction",
+                (
+                    f"{which.capitalize()}imum Principal Direction"
+                    if which != "mid"
+                    else "Middle Principal Direction"
+                ),
+                f"Unit direction of the {which} principal value, (N, 3).",
+                partial(_principal_direction, index=i),
+                kind=OutputKind.VECTOR,
+            )
+        )
+        entries.append(
+            _tensor_entry(
+                family,
+                f"deviatoric_{which}_principal",
+                (
+                    f"Deviatoric {which.capitalize()}imum Principal Value"
+                    if which != "mid"
+                    else "Deviatoric Middle Principal Value"
+                ),
+                f"The {which} principal value of the deviator.",
+                partial(_deviatoric_principal, index=i),
+            )
+        )
+    for e in entries:
+        catalog.register(e, default=(e.name == "von_mises"))
+
+
+def _build_catalog() -> Catalog:
+    catalog = Catalog()
+    _register_scalar(catalog)
+    _register_vectors(catalog)
+    _register_dof6(catalog)
+    _register_symtensor2d(catalog)
+    _register_symtensor3d(catalog)
+    return catalog
+
+
+CATALOG: Final[Catalog] = _build_catalog()
+"""The populated derived-field registry."""