ManifoldGMM

ManifoldGMM: GMM Estimation on Riemannian Manifolds

ManifoldGMM is a Python package for performing Generalized Method of Moments (GMM) estimation when parameters live on smooth (Riemannian) manifolds. It extends pymanopt with Jacobian support and provides a high-level econometric interface.

Highlights

• Builds directly on the geometry of manifolds (e.g., Stiefel, PSD-FixedRank)
• Provides GMM estimation and inference that respect manifold structure
• Ships with example walkthroughs for Gaussian covariance (product manifold) and circular means on \(\mathbb{S}^1\)
• Supports automatic differentiation via JAX or Autograd
• Designed for reproducible research and extension by humans or LLM assistants

Quick Overview

• Geometry layer: defines Manifold, ManifoldPoint, and TangentSpace
• Econometrics layer: defines GMM, weighting-matrix updates, and inference
• Documentation: in Org-mode under docs/

Developer Standards

All contributors (including automated assistants) must follow the Naming & Notation Standards for mathematical symbols, API naming, and documentation conventions. Automated assistants must also adhere to the policies in AGENTS.org.

Repository Layout

src/manifoldgmm/   Core source code
docs/              Design notes, standards, and examples
tests/             Unit and integration tests

Example Walkthroughs

Gaussian location/covariance on a product manifold

docs/examples/gaussian_location_covariance.org

Circle mean inference on \(\mathbb{S}^1\)

docs/examples/circular_mean_inference.org

Getting Started

1. Install Python 3.11 (e.g., via pyenv).
2. Install Poetry (https://python-poetry.org/docs/#installation).
3. Install Emacs 28 or newer (needed for Org-mode editing/export).
4. Create the virtual environment in the project root (JAX is installed automatically):

   poetry env use 3.11
   poetry install --with dev
       

5. Run quality checks and the test suite. The quick-check target skips tests marked as slow so you can iterate quickly; run slow-tests before releasing.

   make quick-check
   make slow-tests
       

   For the full battery (including formatting against the entire repository), continue to use make check.

Working with a local DataMat checkout

• The pinned dependency is datamat==0.2.0a1, ensuring reproducible installs.
• When co-developing against a sibling clone (e.g., ../DataMat), run:

  make use-local-datamat
      

  which installs the local repository in editable mode inside the Poetry environment. Remember to reinstall the pinned release (e.g., poetry install) before committing or publishing a new ManifoldGMM release.

Citation

If you use ManifoldGMM in your research, please cite

@software{ligon25:manifoldgmm,
author = {Ligon, Ethan},
title = {{\tt ManifoldGMM}: GMM Estimation on Riemannian Manifolds},
year = {2025},
doi = {10.5281/zenodo.17508879},
url = {https://doi.org/10.5281/zenodo.17508879}
}

License

This work is licensed under the Creative Commons Attribution–NonCommercial–ShareAlike 4.0 International License (CC BY-NC-SA 4.0). To view a copy of this license, visit http://creativecommons.org/licenses/by-nc-sa/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.

References

• N. Boumal (2023), An Introduction to Optimization on Smooth Manifolds
• Pymanopt (JMLR 2016)
• Trust region methods on Riemannian manifolds (Absil et al 2006)
• Hansen (1982); Newey & McFadden (1994)