Metadata-Version: 2.4
Name: morphis
Version: 0.5.0
Summary: A unified mathematical framework for geometric computation
Keywords: geometric-algebra,mathematics,visualization,multivector,pga
Author: ctl-alt-leist
Author-email: ctl-alt-leist <ctl-alt-leist@users.noreply.github.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Visualization
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: pyvista>=0.46.4
Requires-Dist: scipy>=1.16.3
Requires-Dist: tomli>=2.3.0
Requires-Dist: build ; extra == 'dev'
Requires-Dist: flake8 ; extra == 'dev'
Requires-Dist: ipython ; extra == 'dev'
Requires-Dist: pip-tools ; extra == 'dev'
Requires-Dist: pre-commit ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: python-lsp-server ; extra == 'dev'
Requires-Dist: ruff ; extra == 'dev'
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
Description-Content-Type: text/markdown

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

<p align="center">
  <img src="figures/rotations-4d.gif" alt="4D rotations animation" width="400">
</p>

<p align="center" width="500">
  <em>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.</em>
</p>

## Features

- **Geometric Algebra Core**: Blades, 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
- **Motor Transforms**: Rotors and translations via sandwich product

## Installation

Requires Python 3.12+.

```bash
pip install morphis
```

### From Source

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

## Project Structure

```
morphis/
├── src/morphis/
│   ├── elements/       # Core GA objects: Blade, MultiVector, Frame, Operator, Metric
│   │   └── tests/
│   ├── algebra/        # Linear algebra: BladeSpec, 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
│   ├── 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](https://docs.astral.sh/uv/) for Python project management.

### Setup

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

Or step by step:

```bash
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:

```bash
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`

```bash
# 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.*
