morphis 0.8.0

A unified mathematical framework for geometric computation

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, animation, themes
│   │   └── drawing/    # Vector mesh generation
│   ├── examples/       # Runnable demos
│   └── utils/          # Easing functions, observers, 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

Command	Description
make lint	Format and lint code with ruff
make test	Run tests with pytest
make build	Build distribution packages
make clean	Remove generated files and caches
make reset	Clean and reinstall from scratch

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.