Introduction

Who This Guide Is For

This guide is for anyone who changes PolyMath: fixing a bug, adding a method, defining a subclass, or cutting a release. It assumes a competent Python developer who is fluent with NumPy and pytest but new to this code base. The User Guide explains how to use the package and never asks its reader to open the source. This guide is about the source, and it concentrates on the contracts that hold the package together rather than restating what the code says.

Package Overview

PolyMath, distributed as rms-polymath and imported as polymath, wraps NumPy arrays in objects that keep the shape of an array separate from the shape of its items, and that carry a mask, an optional Unit, and optional derivatives through every operation. One base class, Qube, implements all of that machinery. The nine public subclasses, Scalar, Boolean, Vector, Pair, Vector3, Quaternion, Polynomial, Matrix, and Matrix3, add constraints on the item shape and the operations that make sense for it.

Two design decisions shape everything a developer touches, and both are explained in Architecture:

  • The file for Qube holds only what defines an object. Nearly every method is written as a plain function in a module under src/polymath/extensions/ and bound onto the class when the package is imported.

  • The source carries no type annotations. Public type information lives in two stub files, __init__.pyi and typedefs.pyi, matching the only two supported import paths, and a check called stubtest keeps them honest.

Runtime requirements are Python 3.11 or later, NumPy 2.0 or later, and rms-fpzip, which compresses floating-point arrays when objects are pickled. The package runs on Linux, macOS, and Windows, and the test matrix covers all three.

Development requirements are declared as extras in pyproject.toml. The dev extra brings the linters, the test tools, the packaging check, and the type checker whose stubtest subcommand validates the stubs; it also pulls in the docs extra, which brings Sphinx 9 or later and its extensions.

Where to Look

  • polymath Module is the public API reference, generated from the docstrings.

  • Internal API Reference is a second copy of the API reference that includes the private methods and the extension modules, generated from the same docstrings.

  • Contributing is the contribution guide, covering issues, enhancement requests, and the legal terms of a code contribution.

  • CLAUDE.md and the files under .claude/rules/ in the repository root are the detailed working rules, written for AI-assisted development but binding on everyone. Coding Conventions summarizes them.