Hypergeometry: Concepts and Software Design

Published 2025-10-11

HyperGeometry is built in Python using numpy, as it was expected to benefit from fast matrix and array operations. The two main types of objects are Points and Polys.

A Point represents a single point or vector in a d-dimensional space as a 1D numpy array of its coordinates. A Poly is a collection of points or vectors of the same number of dimensions, stored as a 2D numpy array internally. It can be used to apply the same operation to a set of points fast, to represent a basis of vectors, or a series of points forming a polygon.

Another type is a Span, which combines a Point and a Poly (used as a basis of vectors) to represent a subspace spanning from the point in the direction(s) of the vectors. Finally, a Combination is another way of representing a subspace as the set of points that are the linear combinations of a Poly where the sum of the coefficients is 1. At the moment it seems that Spans are going to be more fruitful for our purposes, but Combinations are still available.

By design all objects are treated as immutable (with extremely limited exceptions) -- something I learnt to be extremely beneficial for the programmer's sanity while coding templating systems. This means that Points, Polys, etc. can be assigned and re-used as primitives. It also allows for Poly objects to cache certain derivatives of their data, like the transpose or inverse of the matrices of coordinates. The exceptions to the immutability rule are in generators of these objects where modifying and then returning the same object is expected to have considerable performance benefits. (Admittedly though creating newer and newer objects during calculations is already not great for performance. But at this stage HyperGeometry is designed to be primarily correct, not fast.)

Another design decision was not to provide overrides for infix operators like + for add(), etc. This is because these are difficult to chain, e.g. a simple chain of a.scale(2).add(b).norm() would need to be written as a mixture of infix and postfix operators (a.scale(2) + b).norm() which in my opinion is less readable or formattable.

Tags: hypergeometry

« Opening LUKS drives on boot broken in Debian 13 - Solution

Information Inequalities for Five Random Variables »