morphis 0.6.0__tar.gz → 0.9.0__tar.gz

{morphis-0.6.0 → morphis-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: morphis
-Version: 0.6.0
+Version: 0.9.0
 Summary: A unified mathematical framework for geometric computation
 Keywords: geometric-algebra,mathematics,visualization,multivector,pga
 Author: ctl-alt-leist
@@ -53,12 +53,45 @@ essential nature.
 
 ## Features
 
-- **Geometric Algebra Core**: Blades, multivectors, and operations (wedge, geometric product, duality)
+- **Geometric Algebra Core**: Vectors (k-vectors), multivectors, and operations (wedge, geometric product, duality)
 - **Metric-Aware**: Objects carry their metric context (Euclidean, projective, etc.)
-- **Linear Operators**: Structured linear maps between blade spaces with SVD, pseudoinverse, least squares
-- **Visualization**: 3D rendering of blades with PyVista, timeline-based animation, 4D projection
+- **Linear Operators**: Structured linear maps between vector spaces with SVD, pseudoinverse, least squares
+- **Visualization**: 3D rendering of vectors with PyVista, timeline-based animation, 4D projection
 - **Motor Transforms**: Rotors and translations via sandwich product
 
+## Documentation
+
+- [Project Overview](docs/0_project-overview.md) — Vision and scope
+- [Concepts](docs/1_concepts/) — Mathematical foundations (vectors, products, duality, transforms)
+- [API Reference](docs/3_api/api.md) — Public interface
+- [Architecture](docs/5_dev/1_architecture.md) — Design philosophy and decisions
+
+## Quick Start
+
+```python
+from morphis.elements import Frame, basis_vectors, euclidean_metric
+from morphis.operations import normalize
+from morphis.transforms import rotor
+from numpy import pi
+
+# Create a 3D Euclidean metric and basis vectors
+g = euclidean_metric(3)
+e1, e2, e3 = basis_vectors(g)
+
+# Bivector: oriented plane of rotation
+b = (e1 ^ e2).normalize()
+
+# Frame: ordered collection of vectors
+F = Frame(e1, e2, e3)
+
+# Rotor: multivector that performs rotation
+R = rotor(b, pi / 4)
+
+# Transform vector and frame via sandwich product
+e1_rotated = e1.transform(R)
+F_rotated = F.transform(R)
+```
+
 ## Installation
 
 Requires Python 3.12+.
@@ -80,16 +113,16 @@ make install
 ```
 morphis/
 ├── src/morphis/
-│   ├── elements/       # Core GA objects: Blade, MultiVector, Frame, Operator, Metric
+│   ├── elements/       # Core GA objects: Vector, MultiVector, Frame, Metric
 │   │   └── tests/
-│   ├── algebra/        # Linear algebra: BladeSpec, einsum patterns, solvers
+│   ├── algebra/        # Linear algebra: VectorSpec, einsum patterns, solvers
 │   │   └── tests/
 │   ├── operations/     # GA operations: wedge, geometric product, duality, norms
 │   │   └── tests/
 │   ├── transforms/     # Rotors, translators, PGA, motor constructors
 │   │   └── tests/
 │   ├── visuals/        # PyVista rendering, animation, themes
-│   │   └── drawing/    # Blade mesh generation
+│   │   └── drawing/    # Vector mesh generation
 │   ├── examples/       # Runnable demos
 │   └── utils/          # Easing functions, observers, pretty printing
 ├── docs/               # Design documents

{morphis-0.6.0 → morphis-0.9.0}/README.md

@@ -16,12 +16,45 @@ essential nature.
 
 ## Features
 
-- **Geometric Algebra Core**: Blades, multivectors, and operations (wedge, geometric product, duality)
+- **Geometric Algebra Core**: Vectors (k-vectors), multivectors, and operations (wedge, geometric product, duality)
 - **Metric-Aware**: Objects carry their metric context (Euclidean, projective, etc.)
-- **Linear Operators**: Structured linear maps between blade spaces with SVD, pseudoinverse, least squares
-- **Visualization**: 3D rendering of blades with PyVista, timeline-based animation, 4D projection
+- **Linear Operators**: Structured linear maps between vector spaces with SVD, pseudoinverse, least squares
+- **Visualization**: 3D rendering of vectors with PyVista, timeline-based animation, 4D projection
 - **Motor Transforms**: Rotors and translations via sandwich product
 
+## Documentation
+
+- [Project Overview](docs/0_project-overview.md) — Vision and scope
+- [Concepts](docs/1_concepts/) — Mathematical foundations (vectors, products, duality, transforms)
+- [API Reference](docs/3_api/api.md) — Public interface
+- [Architecture](docs/5_dev/1_architecture.md) — Design philosophy and decisions
+
+## Quick Start
+
+```python
+from morphis.elements import Frame, basis_vectors, euclidean_metric
+from morphis.operations import normalize
+from morphis.transforms import rotor
+from numpy import pi
+
+# Create a 3D Euclidean metric and basis vectors
+g = euclidean_metric(3)
+e1, e2, e3 = basis_vectors(g)
+
+# Bivector: oriented plane of rotation
+b = (e1 ^ e2).normalize()
+
+# Frame: ordered collection of vectors
+F = Frame(e1, e2, e3)
+
+# Rotor: multivector that performs rotation
+R = rotor(b, pi / 4)
+
+# Transform vector and frame via sandwich product
+e1_rotated = e1.transform(R)
+F_rotated = F.transform(R)
+```
+
 ## Installation
 
 Requires Python 3.12+.
@@ -43,16 +76,16 @@ make install
 ```
 morphis/
 ├── src/morphis/
-│   ├── elements/       # Core GA objects: Blade, MultiVector, Frame, Operator, Metric
+│   ├── elements/       # Core GA objects: Vector, MultiVector, Frame, Metric
 │   │   └── tests/
-│   ├── algebra/        # Linear algebra: BladeSpec, einsum patterns, solvers
+│   ├── algebra/        # Linear algebra: VectorSpec, einsum patterns, solvers
 │   │   └── tests/
 │   ├── operations/     # GA operations: wedge, geometric product, duality, norms
 │   │   └── tests/
 │   ├── transforms/     # Rotors, translators, PGA, motor constructors
 │   │   └── tests/
 │   ├── visuals/        # PyVista rendering, animation, themes
-│   │   └── drawing/    # Blade mesh generation
+│   │   └── drawing/    # Vector mesh generation
 │   ├── examples/       # Runnable demos
 │   └── utils/          # Easing functions, observers, pretty printing
 ├── docs/               # Design documents

{morphis-0.6.0 → morphis-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "morphis"
-version = "0.6.0"
+version = "0.9.0"
 description = "A unified mathematical framework for geometric computation"
 readme = "README.md"
 license = "MIT"

morphis-0.9.0/src/morphis/__init__.py

@@ -0,0 +1,56 @@
+"""
+Morphis - Geometric Algebra Library
+
+A unified mathematical framework for geometric computation.
+"""
+
+import runpy
+import sys
+
+
+EXAMPLES = [
+    "clifford",
+    "duality",
+    "exterior",
+    "operators",
+    "phasors",
+    "rotations_3d",
+    "rotations_4d",
+    "transforms_pga",
+]
+
+
+def main() -> None:
+    """CLI entry point: morphis example [name]"""
+    args = sys.argv[1:]
+
+    # morphis (no args) or morphis example (no name)
+    if not args or args == ["example"]:
+        print("Usage: morphis example <name>")
+        print()
+        print("Available examples:")
+        for name in EXAMPLES:
+            print(f"  {name}")
+        return
+
+    # morphis example <name> [args...]
+    if args[0] == "example":
+        name = args[1] if len(args) > 1 else None
+        remaining = args[2:]
+
+        if name not in EXAMPLES:
+            print(f"Unknown example: {name}")
+            print(f"Available: {', '.join(EXAMPLES)}")
+            sys.exit(1)
+
+        module = f"morphis.examples.{name}"
+        sys.argv = [module] + remaining
+        runpy.run_module(module, run_name="__main__", alter_sys=True)
+    else:
+        print(f"Unknown command: {args[0]}")
+        print("Usage: morphis example <name>")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

{morphis-0.6.0 → morphis-0.9.0}/src/morphis/_legacy/rotations.py

@@ -192,7 +192,7 @@ def solve_rotation_angle(u: NDArray, v: NDArray, axis: NDArray) -> float:
 
 
 # =============================================================================
-# Blade Visual Transform Operations
+# Vector Visual Transform Operations
 # =============================================================================
 
 
@@ -204,7 +204,7 @@ def rotate_blade(blade, axis: NDArray, angle: float) -> None:
     (composed with existing rotation).
 
     Args:
-        blade: Blade to rotate (its visual_transform is modified)
+        blade: Vector to rotate (its visual_transform is modified)
         axis: Rotation axis (will be normalized)
         angle: Rotation angle in radians
     """
@@ -220,7 +220,7 @@ def translate_blade(blade, delta: NDArray) -> None:
     This modifies blade.visual_transform in place. The translation is accumulated.
 
     Args:
-        blade: Blade to translate (its visual_transform is modified)
+        blade: Vector to translate (its visual_transform is modified)
         delta: Translation vector
     """
     blade.visual_transform.translation = blade.visual_transform.translation + array(delta)
@@ -231,7 +231,7 @@ def set_blade_position(blade, position: NDArray) -> None:
     Set a blade's visual position (absolute, not relative).
 
     Args:
-        blade: Blade to position (its visual_transform is modified)
+        blade: Vector to position (its visual_transform is modified)
         position: New position vector
     """
     blade.visual_transform.translation = array(position)
@@ -242,6 +242,6 @@ def reset_blade_transform(blade) -> None:
     Reset a blade's visual transform to identity.
 
     Args:
-        blade: Blade to reset (its visual_transform is modified)
+        blade: Vector to reset (its visual_transform is modified)
     """
     blade.visual_transform.reset()

morphis-0.9.0/src/morphis/algebra/__init__.py

@@ -0,0 +1,27 @@
+"""
+Linear Algebra Module
+
+Provides structured linear algebra utilities for geometric algebra operators.
+Includes vector specifications, einsum pattern generation, solvers, and contraction.
+"""
+
+from morphis.algebra.contraction import (
+    IndexedTensor as IndexedTensor,
+    contract as contract,
+)
+from morphis.algebra.patterns import (
+    INPUT_COLLECTION as INPUT_COLLECTION,
+    INPUT_GEOMETRIC as INPUT_GEOMETRIC,
+    OUTPUT_COLLECTION as OUTPUT_COLLECTION,
+    OUTPUT_GEOMETRIC as OUTPUT_GEOMETRIC,
+    adjoint_signature as adjoint_signature,
+    forward_signature as forward_signature,
+    operator_shape as operator_shape,
+)
+from morphis.algebra.solvers import (
+    structured_lstsq as structured_lstsq,
+    structured_pinv as structured_pinv,
+    structured_pinv_solve as structured_pinv_solve,
+    structured_svd as structured_svd,
+)
+from morphis.algebra.specs import VectorSpec as VectorSpec, vector_spec as vector_spec

morphis-0.9.0/src/morphis/algebra/contraction.py

@@ -0,0 +1,263 @@
+"""
+Linear Algebra - Tensor Contraction
+
+Provides two contraction APIs for Morphis tensors:
+1. Index notation: G["mnab"] * q["n"] - bracket syntax with IndexedTensor
+2. Einsum-style: contract("mnab, n -> mab", G, q) - explicit signature
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from numpy import einsum
+
+
+if TYPE_CHECKING:
+    from morphis.elements.vector import Vector
+    from morphis.operations.operator import Operator
+
+
+# =============================================================================
+# IndexedTensor - Bracket Syntax API
+# =============================================================================
+
+
+class IndexedTensor:
+    """
+    Lightweight wrapper that pairs a tensor with index labels for contraction.
+
+    This class enables einsum-style syntax:
+        G["mnab"] * q["n"]  # contracts on index 'n'
+
+    The wrapper holds a reference (not a copy) to the underlying tensor,
+    making indexing O(1). Computation only happens when two IndexedTensors
+    are multiplied.
+
+    Attributes:
+        tensor: The underlying Vector or Operator (reference, not copy)
+        indices: String of index labels (e.g., "mnab")
+
+    Examples:
+        >>> G = Operator(...)  # lot=(M, N), grade=2 output
+        >>> q = Vector(...)  # lot=(N,), grade=0
+        >>> b = G["mnab"] * q["n"]  # contracts on 'n', result has indices "mab"
+    """
+
+    __slots__ = ("tensor", "indices")
+
+    def __init__(self, tensor: "Vector | Operator", 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
+        """
+        self.tensor = tensor
+        self.indices = indices
+
+        # Validate index count matches tensor dimensions
+        expected_ndim = tensor.data.ndim
+        if len(indices) != expected_ndim:
+            raise ValueError(
+                f"Index string '{indices}' has {len(indices)} indices, but tensor has {expected_ndim} dimensions"
+            )
+
+    def __mul__(self, other: "IndexedTensor") -> "Vector":
+        """
+        Contract two indexed tensors on matching indices.
+
+        Args:
+            other: Another IndexedTensor to contract with
+
+        Returns:
+            Vector with the contracted result
+        """
+        if not isinstance(other, IndexedTensor):
+            return NotImplemented
+
+        return _contract_indexed(self, other)
+
+    def __rmul__(self, other: "IndexedTensor") -> "Vector":
+        """Right multiplication for contraction."""
+        if not isinstance(other, IndexedTensor):
+            return NotImplemented
+
+        return _contract_indexed(other, self)
+
+    def __repr__(self) -> str:
+        tensor_type = type(self.tensor).__name__
+        return f"IndexedTensor({tensor_type}, indices='{self.indices}')"
+
+
+def _contract_indexed(*indexed_tensors: IndexedTensor) -> "Vector":
+    """
+    Contract multiple IndexedTensor objects.
+
+    Internal function that performs the actual contraction for bracket syntax.
+    """
+    from morphis.elements.vector import Vector
+
+    if len(indexed_tensors) < 2:
+        raise ValueError("Contraction requires at least 2 indexed tensors")
+
+    # Collect all index information
+    all_indices = [it.indices for it in indexed_tensors]
+    all_data = [it.tensor.data for it in indexed_tensors]
+
+    # Count index occurrences to determine output indices
+    index_counts: dict[str, int] = {}
+    for indices in all_indices:
+        for idx in indices:
+            index_counts[idx] = index_counts.get(idx, 0) + 1
+
+    # Output indices are those that appear exactly once (not contracted)
+    # Preserve order of first appearance
+    seen = set()
+    output_indices = ""
+    for indices in all_indices:
+        for idx in indices:
+            if idx not in seen:
+                seen.add(idx)
+                if index_counts[idx] == 1:
+                    output_indices += idx
+
+    # Build einsum signature
+    input_sig = ",".join(all_indices)
+    einsum_sig = f"{input_sig}->{output_indices}"
+
+    # Perform contraction
+    result_data = einsum(einsum_sig, *all_data)
+
+    # Get metric from first tensor that has one
+    metric = None
+    for it in indexed_tensors:
+        if hasattr(it.tensor, "metric") and it.tensor.metric is not None:
+            metric = it.tensor.metric
+            break
+
+    # Infer grade from output
+    result_grade = _infer_grade_from_indexed(indexed_tensors, output_indices)
+
+    return Vector(data=result_data, grade=result_grade, metric=metric)
+
+
+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()
+
+    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)
+
+    # Count geometric indices in output
+    result_grade = sum(1 for idx in output_indices if idx in geo_indices)
+    return result_grade
+
+
+# =============================================================================
+# contract() - Einsum-Style API
+# =============================================================================
+
+
+def contract(signature: str, *tensors: "Vector | Operator") -> "Vector":
+    """
+    Einsum-style contraction for Morphis tensors.
+
+    Works exactly like numpy.einsum, but accepts Vector and Operator objects.
+    Extracts the underlying data, performs the einsum, and wraps the result
+    back into a Vector.
+
+    Args:
+        signature: Einsum signature string (e.g., "mn, n -> m")
+        *tensors: Morphis objects (Vector or Operator) to contract
+
+    Returns:
+        Vector containing the contracted result
+
+    Examples:
+        >>> g = euclidean_metric(3)
+        >>> u = Vector([1, 2, 3], grade=1, metric=g)
+        >>> v = Vector([4, 5, 6], grade=1, metric=g)
+
+        >>> # Dot product
+        >>> s = contract("a, a ->", u, v)
+        >>> s.data  # 1*4 + 2*5 + 3*6 = 32
+
+        >>> # Matrix-vector product
+        >>> M = Vector(data, grade=2, metric=g)  # shape (3, 3)
+        >>> w = contract("ab, b -> a", M, v)
+
+        >>> # Outer product
+        >>> outer = contract("a, b -> ab", u, v)
+
+        >>> # Batch contraction
+        >>> G = Vector(data, grade=2, lot=(M, N), metric=g)  # shape (M, N, 3, 3)
+        >>> q = Vector(data, grade=0, lot=(N,), metric=g)  # shape (N,)
+        >>> b = contract("mnab, n -> mab", G, q)
+    """
+    from morphis.elements.vector import Vector
+
+    if len(tensors) < 1:
+        raise ValueError("contract() requires at least 1 tensor")
+
+    # Extract data arrays from tensors
+    data_arrays = [t.data for t in tensors]
+
+    # Normalize signature: allow spaces around comma and arrow
+    sig = signature.replace(" ", "")
+
+    # Perform einsum
+    result_data = einsum(sig, *data_arrays)
+
+    # Get metric from first tensor that has one
+    metric = None
+    for t in tensors:
+        if hasattr(t, "metric") and t.metric is not None:
+            metric = t.metric
+            break
+
+    # Infer grade from output shape
+    result_grade = _infer_grade_from_signature(sig, tensors, result_data)
+
+    return Vector(data=result_data, grade=result_grade, metric=metric)
+
+
+def _infer_grade_from_signature(signature: str, tensors: tuple, result_data) -> int:
+    """Infer grade for einsum-style contraction result."""
+    from morphis.elements.vector import Vector
+
+    # Parse signature to get output indices
+    if "->" in signature:
+        input_part, output_indices = signature.split("->")
+    else:
+        # No explicit output - numpy determines it
+        return 0 if result_data.ndim == 0 else result_data.ndim
+
+    input_parts = input_part.split(",")
+
+    # Track which indices are geometric (vs lot)
+    geo_indices = set()
+
+    for k, t in enumerate(tensors):
+        if k < len(input_parts) and isinstance(t, Vector):
+            indices = input_parts[k]
+            n_lot = len(t.lot)
+            n_geo = t.grade
+            # Geometric indices are the last 'grade' indices
+            if len(indices) >= n_lot + n_geo:
+                geo_part = indices[n_lot : n_lot + n_geo]
+                geo_indices.update(geo_part)
+
+    # Count geometric indices in output
+    result_grade = sum(1 for idx in output_indices if idx in geo_indices)
+
+    return result_grade