Morphis

A unified mathematical framework for geometric computation, providing elegant tools for working with geometric algebra, manifolds, and their applications across mathematics and physics. The name derives from Greek morphe (form) — embodying the transformation and adaptation of geometric structures across different contexts while preserving their essential nature.

A 4D orthonormal frame rotating through bivector planes, projected to 3D. The view switches between e₁e₂e₃ and e₂e₃e₄ projections mid-animation.

Features

• 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 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 — Vision and scope
• Concepts — Mathematical foundations (vectors, products, duality, transforms)
• API Reference — Public interface
• Architecture — Design philosophy and decisions

Quick Start

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+.

pip install morphis

From Source

git clone https://github.com/ctl-alt-leist/morphis.git
cd morphis
make install

Project Structure

morphis/
├── src/morphis/
│   ├── elements/       # Core GA objects: Vector, MultiVector, Frame, Metric
│   │   └── tests/
│   ├── 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 and recording, ink sketches, themes
│   │   └── drawing/    # Vector mesh generation
│   ├── examples/       # Runnable demos
│   └── utils/          # Easing functions, pretty printing
├── docs/               # Design documents
├── pyproject.toml      # Project configuration
├── Makefile            # Development commands
└── ruff.toml           # Linting configuration

Development

This project uses uv for Python project management.

Setup

make install    # Create venv, install dependencies, setup pre-commit hooks

Or step by step:

make setup      # Create venv and sync dependencies
uv run pre-commit install  # Install git hooks

Common Commands

Testing

Tests are co-located with source in tests/ subdirectories:

make test                                # Run all tests
uv run pytest src/morphis/elements -v    # Run specific module tests

Code Style

• Python 3.12+ with type hints
• Ruff for formatting and linting
• Pre-commit hooks run automatically on commit

Release Workflow

Releases are triggered by git tags. When a tag matching v* is pushed, GitHub Actions automatically builds and publishes to PyPI.

To Release a New Version

1. Update version in pyproject.toml
2. Commit the change
3. Run make publish

# Example: releasing version 0.2.0
# Edit pyproject.toml: version = "0.2.0"
git add pyproject.toml
git commit -m "Bump version to 0.2.0"
make publish

The make publish command will:

• Read the version from pyproject.toml
• Create a git tag v{version}
• Push the tag to trigger the release workflow

License

MIT License - see LICENSE file for details.

Claude Code was used in the development of this project.