morphis 0.10.0__tar.gz → 0.12.0__tar.gz

{morphis-0.10.0 → morphis-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: morphis
-Version: 0.10.0
+Version: 0.12.0
 Summary: A unified mathematical framework for geometric computation
 Keywords: geometric-algebra,mathematics,visualization,multivector,pga
 Author: ctl-alt-leist
@@ -12,14 +12,17 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Mathematics
 Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Dist: dracopy>=1.4.0
 Requires-Dist: imageio>=2.37.2
 Requires-Dist: imageio-ffmpeg>=0.6.0
 Requires-Dist: matplotlib>=3.10.8
 Requires-Dist: numpy>=2.3.5
 Requires-Dist: pydantic>=2.12.5
+Requires-Dist: pygltflib>=1.16.5
 Requires-Dist: pyvista>=0.46.4
 Requires-Dist: scipy>=1.16.3
 Requires-Dist: tomli>=2.3.0
+Requires-Dist: trimesh>=4.11.1
 Requires-Dist: build ; extra == 'dev'
 Requires-Dist: flake8 ; extra == 'dev'
 Requires-Dist: ipython ; extra == 'dev'
@@ -28,11 +31,18 @@ Requires-Dist: pre-commit ; extra == 'dev'
 Requires-Dist: pytest ; extra == 'dev'
 Requires-Dist: python-lsp-server ; extra == 'dev'
 Requires-Dist: ruff ; extra == 'dev'
+Requires-Dist: pyvista>=0.46.4 ; extra == 'visuals'
+Requires-Dist: imageio>=2.37.2 ; extra == 'visuals'
+Requires-Dist: imageio-ffmpeg>=0.6.0 ; extra == 'visuals'
+Requires-Dist: trimesh>=4.11.1 ; extra == 'visuals'
+Requires-Dist: pygltflib>=1.16.5 ; extra == 'visuals'
+Requires-Dist: dracopy>=1.4.0 ; extra == 'visuals'
 Requires-Python: >=3.12
 Project-URL: Homepage, https://github.com/ctl-alt-leist/morphis
 Project-URL: Repository, https://github.com/ctl-alt-leist/morphis
 Project-URL: Issues, https://github.com/ctl-alt-leist/morphis/issues
 Provides-Extra: dev
+Provides-Extra: visuals
 Description-Content-Type: text/markdown
 
 # Morphis

{morphis-0.10.0 → morphis-0.12.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "morphis"
-version = "0.10.0"
+version = "0.12.0"
 description = "A unified mathematical framework for geometric computation"
 readme = "README.md"
 license = "MIT"
@@ -18,17 +18,31 @@ classifiers = [
     "Topic :: Scientific/Engineering :: Visualization",
 ]
 dependencies = [
+    "DracoPy>=1.4.0",
     "imageio>=2.37.2",
     "imageio-ffmpeg>=0.6.0",
     "matplotlib>=3.10.8",
     "numpy>=2.3.5",
     "pydantic>=2.12.5",
+    "pygltflib>=1.16.5",
     "pyvista>=0.46.4",
     "scipy>=1.16.3",
     "tomli>=2.3.0",
+    "trimesh>=4.11.1",
 ]
 
 [project.optional-dependencies]
+visuals = [
+  # These are currently in main dependencies but documented here
+  # for explicit dependency declaration. In a future major version,
+  # these may be moved out of main dependencies.
+  "pyvista>=0.46.4",
+  "imageio>=2.37.2",
+  "imageio-ffmpeg>=0.6.0",
+  "trimesh>=4.11.1",
+  "pygltflib>=1.16.5",
+  "DracoPy>=1.4.0",
+]
 dev = [
   "build",
   "flake8",

{morphis-0.10.0 → morphis-0.12.0}/src/morphis/algebra/contraction.py

@@ -37,6 +37,8 @@ class IndexedTensor:
     Attributes:
         tensor: The underlying Vector or Operator (reference, not copy)
         indices: String of index labels (e.g., "mnab")
+        output_geo_indices: Indices that represent output geometric dimensions.
+            These determine the result grade when present in contraction output.
 
     Examples:
         >>> G = Operator(...)  # lot=(M, N), grade=2 output
@@ -44,18 +46,21 @@ class IndexedTensor:
         >>> b = G["mnab"] * q["n"]  # contracts on 'n', result has indices "mab"
     """
 
-    __slots__ = ("tensor", "indices")
+    __slots__ = ("tensor", "indices", "output_geo_indices")
 
-    def __init__(self, tensor: "Vector | Operator", indices: str):
+    def __init__(self, tensor: "Vector | Operator", indices: str, output_geo_indices: str = ""):
         """
         Create an indexed tensor wrapper.
 
         Args:
             tensor: The underlying Vector or Operator
             indices: String of index labels, one per axis of tensor.data
+            output_geo_indices: Subset of indices representing output geometric
+                dimensions. If empty, will be inferred during contraction (legacy).
         """
         self.tensor = tensor
         self.indices = indices
+        self.output_geo_indices = output_geo_indices
 
         # Validate index count matches tensor dimensions
         expected_ndim = tensor.data.ndim
@@ -78,9 +83,14 @@ class IndexedTensor:
 
         if isinstance(other, LotIndexed):
             # Convert LotIndexed to IndexedTensor by adding geo indices
+            # All of a Vector's geometric indices are "output geometric"
             n_geo = other.vector.grade
             geo_labels = "".join(chr(ord("A") + i) for i in range(n_geo))
-            other = IndexedTensor(other.vector, other.indices + geo_labels)
+            other = IndexedTensor(
+                other.vector,
+                other.indices + geo_labels,
+                output_geo_indices=geo_labels,
+            )
 
         if not isinstance(other, IndexedTensor):
             return NotImplemented
@@ -152,23 +162,20 @@ def _contract_indexed(*indexed_tensors: IndexedTensor) -> "Vector":
 
 
 def _infer_grade_from_indexed(indexed_tensors: tuple[IndexedTensor, ...], output_indices: str) -> int:
-    """Infer grade for IndexedTensor contraction result."""
-    from morphis.elements.vector import Vector
-
-    # Track which indices are geometric (vs lot)
-    geo_indices = set()
+    """
+    Infer grade for IndexedTensor contraction result.
 
+    The result grade equals the number of output geometric indices that appear
+    in the result. Each IndexedTensor carries its output_geo_indices, which
+    identify which indices represent geometric (grade-contributing) dimensions.
+    """
+    # Collect output geometric indices from all tensors
+    all_output_geo = set()
     for it in indexed_tensors:
-        if isinstance(it.tensor, Vector):
-            n_lot = len(it.tensor.lot)
-            n_geo = it.tensor.grade
-            # Geometric indices are the last 'grade' indices
-            geo_part = it.indices[n_lot : n_lot + n_geo]
-            geo_indices.update(geo_part)
+        all_output_geo.update(it.output_geo_indices)
 
-    # Count geometric indices in output
-    result_grade = sum(1 for idx in output_indices if idx in geo_indices)
-    return result_grade
+    # Result grade = count of output geometric indices in the result
+    return sum(1 for idx in output_indices if idx in all_output_geo)
 
 
 # =============================================================================

{morphis-0.10.0 → morphis-0.12.0}/src/morphis/algebra/solvers.py

@@ -8,9 +8,8 @@ structured Operators for the results.
 
 from typing import TYPE_CHECKING
 
-import numpy as np
-from numpy import prod
-from numpy.linalg import lstsq, svd
+from numpy import diag_indices_from, prod
+from numpy.linalg import lstsq, pinv, solve, svd
 from numpy.typing import NDArray
 
 from morphis.algebra.specs import VectorSpec
@@ -143,9 +142,9 @@ def structured_lstsq(
     if alpha > 0:
         # Regularized: (G^H G + alpha*I) x = G^H y
         GhG = G_matrix.conj().T @ G_matrix
-        GhG[np.diag_indices_from(GhG)] += alpha
+        GhG[diag_indices_from(GhG)] += alpha
         Ghy = G_matrix.conj().T @ y_vector
-        x_vector = np.linalg.solve(GhG, Ghy)
+        x_vector = solve(GhG, Ghy)
     else:
         # Standard least squares
         x_vector, _, _, _ = lstsq(G_matrix, y_vector, rcond=None)
@@ -211,9 +210,9 @@ def structured_pinv(
 
     # Compute pseudoinverse
     if r_cond is None:
-        G_pinv = np.linalg.pinv(G_matrix)
+        G_pinv = pinv(G_matrix)
     else:
-        G_pinv = np.linalg.pinv(G_matrix, rcond=r_cond)
+        G_pinv = pinv(G_matrix, rcond=r_cond)
 
     # Reconstruct as Operator with swapped specs
     return _from_matrix(

{morphis-0.10.0 → morphis-0.12.0}/src/morphis/algebra/tests/test_contraction.py

@@ -1,11 +1,14 @@
 """Tests for tensor contraction with both bracket and einsum-style APIs."""
 
+import numpy as np
 import pytest
 from numpy import array, ones
 from numpy.testing import assert_allclose, assert_array_equal
 
 from morphis.algebra.contraction import IndexedTensor, contract
+from morphis.algebra.specs import VectorSpec
 from morphis.elements import Vector, euclidean_metric
+from morphis.operations.operator import Operator
 
 
 # =============================================================================
@@ -222,3 +225,84 @@ class TestSlicingStillWorks:
 
         assert isinstance(result, Vector)
         assert result.shape == (5, 3)
+
+
+# =============================================================================
+# Operator Indexed Contraction
+# =============================================================================
+
+
+class TestOperatorIndexedContraction:
+    """Tests for indexed contraction between Operators and Vectors."""
+
+    def test_operator_vector_contraction_preserves_output_grade(self):
+        """
+        Operator contraction should preserve output_spec.grade in result.
+
+        This is the key regression test: when an Operator with output_spec.grade=2
+        contracts with a Vector, the result must have grade=2, not grade=0.
+        """
+        g = euclidean_metric(3)
+
+        # Operator: maps grade-0 lot (N,) to grade-2 lot (M,)
+        M, N = 2, 3
+        O = Operator(
+            data=np.random.randn(M, N, 3, 3),  # shape (M, N, 3, 3)
+            input_spec=VectorSpec(grade=0, lot=(N,), dim=3),
+            output_spec=VectorSpec(grade=2, lot=(M,), dim=3),
+            metric=g,
+        )
+
+        # Input: grade-0 with lot (N,)
+        v = Vector(np.random.randn(N), grade=0, metric=g)
+
+        # Contract on "n" (the input lot index)
+        result = O["mnab"] * v["n"]
+
+        # Result should have: grade=2, lot=(M,)
+        assert result.grade == 2, f"Expected grade=2, got grade={result.grade}"
+        assert result.lot == (M,), f"Expected lot=(2,), got lot={result.lot}"
+        assert result.shape == (M, 3, 3)
+
+    def test_operator_lot_indexed_vector_contraction(self):
+        """Operator contraction via LotIndexed syntax also preserves grade."""
+        g = euclidean_metric(3)
+
+        M, N = 4, 5
+        O = Operator(
+            data=np.ones((M, N, 3, 3)),
+            input_spec=VectorSpec(grade=0, lot=(N,), dim=3),
+            output_spec=VectorSpec(grade=2, lot=(M,), dim=3),
+            metric=g,
+        )
+
+        # Input as grade-0 vector with lot
+        v = Vector(np.ones(N), grade=0, metric=g)
+
+        result = O["mnab"] * v["n"]
+
+        assert result.grade == 2
+        assert result.lot == (M,)
+        # Each element should be sum over N: N * 1 = 5
+        assert_allclose(result.data, np.ones((M, 3, 3)) * N)
+
+    def test_operator_vector_to_vector_contraction(self):
+        """Operator mapping grade-1 to grade-1 preserves grade in contraction."""
+        g = euclidean_metric(3)
+
+        M, N = 2, 3
+        # grade-1 -> grade-1 operator (outermorphism)
+        O = Operator(
+            data=np.eye(3).reshape(1, 1, 3, 3) * np.ones((M, N, 1, 1)),
+            input_spec=VectorSpec(grade=1, lot=(N,), dim=3),
+            output_spec=VectorSpec(grade=1, lot=(M,), dim=3),
+            metric=g,
+        )
+
+        v = Vector(np.ones((N, 3)), grade=1, metric=g)
+
+        result = O["mnab"] * v["nb"]
+
+        assert result.grade == 1
+        assert result.lot == (M,)
+        assert result.shape == (M, 3)

{morphis-0.10.0 → morphis-0.12.0}/src/morphis/elements/__init__.py

@@ -1,7 +1,7 @@
 """
 Geometric Algebra - Elements
 
-Core geometric algebra objects: Vectors, MultiVectors, Frames, and Metrics.
+Core geometric algebra objects: Vectors, MultiVectors, Frames, Surfaces, and Metrics.
 """
 
 from morphis.elements.base import (
@@ -9,6 +9,7 @@ from morphis.elements.base import (
     Element as Element,
     GradedElement as GradedElement,
 )
+from morphis.elements.field import Field
 from morphis.elements.frame import Frame
 from morphis.elements.lot_indexed import LotIndexed as LotIndexed
 from morphis.elements.metric import (
@@ -32,6 +33,7 @@ from morphis.elements.protocols import (
     Spanning as Spanning,
     Transformable as Transformable,
 )
+from morphis.elements.surface import Surface
 from morphis.elements.tensor import Tensor
 from morphis.elements.vector import (
     Vector,
@@ -48,3 +50,5 @@ Vector.model_rebuild()
 MultiVector.model_rebuild()
 Frame.model_rebuild()
 Tensor.model_rebuild()
+Surface.model_rebuild()
+Field.model_rebuild()

{morphis-0.10.0 → morphis-0.12.0}/src/morphis/elements/base.py

@@ -30,6 +30,7 @@ from morphis.elements.metric import Metric
 
 if TYPE_CHECKING:
     from morphis.algebra.contraction import IndexedTensor
+    from morphis.elements.multivector import MultiVector
     from morphis.elements.vector import Vector
 
 
@@ -124,6 +125,33 @@ class Element(BaseModel):
         """Dimension of the underlying vector space."""
         return self.metric.dim
 
+    def apply_similarity(
+        self,
+        S: "MultiVector",
+        t: "Vector | None" = None,
+    ) -> Self:
+        """
+        Apply a similarity transformation to this element.
+
+        Computes: transform(self, S) + t
+
+        The similarity versor S (from align_vectors or a rotor) is applied via
+        sandwich product. The optional translation t is added after.
+
+        Args:
+            S: Similarity versor or rotor (MultiVector with grades {0, 2})
+            t: Optional translation vector (grade-1). Added after sandwich product.
+
+        Returns:
+            New element with the transformation applied.
+
+        Example:
+            S = align_vectors(u, v)  # Similarity versor
+            t = Vector([1, 0, 0], grade=1, metric=g)  # Translation
+            v_transformed = v.apply_similarity(S, t)
+        """
+        raise NotImplementedError("Subclasses must implement apply_similarity()")
+
 
 class GradedElement(Element):
     """

morphis-0.12.0/src/morphis/elements/field.py

@@ -0,0 +1,102 @@
+"""
+Field Element - Positions with Values (Skeleton)
+
+Field represents a collection of positions in space, each with an associated
+value (scalar, vector, frame, or multivector). This is a skeleton for future
+implementation.
+
+Typical uses:
+- Scalar fields: temperature, pressure, density
+- Vector fields: velocity, electric field, force
+- Frame fields: stress tensors, rotation fields
+- Multivector fields: electromagnetic field (F = E + IcB)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Self
+
+from pydantic import ConfigDict, model_validator
+
+from morphis.elements.base import Element
+from morphis.elements.vector import Vector
+
+
+if TYPE_CHECKING:
+    from morphis.elements.frame import Frame
+    from morphis.elements.metric import Metric
+    from morphis.elements.multivector import MultiVector
+
+
+class Field(Element):
+    """
+    A field of values at positions in space.
+
+    SKELETON: This class structure is defined for future implementation.
+    Full implementation is deferred.
+
+    Attributes:
+        positions: Grade-1 Vector with lot=(N,) representing N sample positions
+        values: The field values at each position (Vector, Frame, or MultiVector)
+
+    The values must have lot matching positions.lot, so each position has
+    exactly one associated value.
+
+    Examples:
+        # Velocity field (3D vectors at 3D positions)
+        positions = Vector(sample_points, grade=1, metric=g)  # lot=(100,)
+        velocities = Vector(velocity_data, grade=1, metric=g)  # lot=(100,)
+        field = Field(positions=positions, values=velocities)
+
+        # Scalar field (scalars at positions)
+        temperatures = Vector(temp_data, grade=0, metric=g)  # lot=(100,)
+        field = Field(positions=positions, values=temperatures)
+    """
+
+    model_config = ConfigDict(
+        arbitrary_types_allowed=True,
+        frozen=False,
+    )
+
+    positions: Vector
+    values: "Vector | Frame | MultiVector"
+
+    @model_validator(mode="after")
+    def _validate_field(self):
+        """Validate positions and values are compatible."""
+        # Positions must be grade-1 vectors
+        if self.positions.grade != 1:
+            raise ValueError(f"Positions must be grade-1 Vectors, got grade={self.positions.grade}")
+
+        # Lots must match
+        if self.positions.lot != self.values.lot:
+            raise ValueError(f"Positions lot {self.positions.lot} != values lot {self.values.lot}")
+
+        # Sync metric and lot from positions
+        object.__setattr__(self, "metric", self.positions.metric)
+        object.__setattr__(self, "lot", self.positions.lot)
+
+        return self
+
+    @property
+    def n_samples(self) -> int:
+        """Number of sample positions in the field."""
+        return self.positions.lot[0] if self.positions.lot else 1
+
+    def copy(self) -> Self:
+        """Create a deep copy of this field."""
+        return Field(
+            positions=self.positions.copy(),
+            values=self.values.copy(),
+        )
+
+    def with_metric(self, metric: "Metric") -> Self:
+        """Return a new Field with the specified metric context."""
+        return Field(
+            positions=self.positions.with_metric(metric),
+            values=self.values.with_metric(metric),
+        )
+
+    def __repr__(self) -> str:
+        value_type = type(self.values).__name__
+        return f"Field(n_samples={self.n_samples}, value_type={value_type})"

{morphis-0.10.0 → morphis-0.12.0}/src/morphis/elements/multivector.py

@@ -526,6 +526,51 @@ class MultiVector(CompositeElement):
 
         return unit(self)
 
+    def apply_similarity(
+        self,
+        S: MultiVector,
+        t: "Vector | None" = None,
+    ) -> MultiVector:
+        """
+        Apply a similarity transformation to this MultiVector.
+
+        Computes: S * self * ~S + t (translation on grade-1 component only)
+
+        The similarity versor S (from align_vectors or a rotor) is applied via
+        sandwich product. The optional translation t is added to the grade-1
+        component only (translations affect positions, not orientations).
+
+        Args:
+            S: Similarity versor or rotor (MultiVector with grades {0, 2})
+            t: Optional translation vector (grade-1). Added to grade-1 component.
+
+        Returns:
+            New MultiVector with the transformation applied.
+
+        Example:
+            S = align_vectors(u, v)
+            t = Vector([1, 0, 0], grade=1, metric=g)
+            M_transformed = M.apply_similarity(S, t)
+        """
+        from morphis.operations.products import geometric, reverse
+
+        # Sandwich product: S * self * ~S
+        S_rev = reverse(S)
+        temp = geometric(S, self)
+        result = geometric(temp, S_rev)
+
+        if t is not None:
+            # Translation applies to grade-1 component only
+            grade1 = result.grade_select(1)
+            if grade1 is not None:
+                new_grade1 = grade1 + t
+                result = MultiVector(
+                    data={**result.data, 1: new_grade1},
+                    metric=result.metric,
+                    lot=result.lot,
+                )
+        return result
+
     # =========================================================================
     # Utility Methods
     # =========================================================================