figurate-numbers

Pure-Python library for polygonal and figurate numbers. Zero runtime dependencies.

Provides forward generation, membership testing, and inverse lookup for the full k-gonal family, plus pyramidal numbers, generalized centered polygonal numbers, star, pronic, and Catalan numbers.

Install

pip install figurate-numbers

Quick start

from figurate_numbers import (
    triangular, pentagonal, hexagonal, polygonal,
    is_triangular, is_polygonal,
    inverse_triangular, inverse_polygonal,
    tetrahedral, square_pyramidal,
    is_tetrahedral, inverse_tetrahedral,
    centered_polygonal, is_centered_polygonal,
)

triangular(10)          # 55
pentagonal(7)           # 70
hexagonal(5)            # 45
polygonal(10, 3)        # 55  (same as triangular)

is_triangular(28)       # True
is_triangular(50)       # False
is_polygonal(70, 5)     # True  (pentagonal)

inverse_triangular(55)  # 10
inverse_polygonal(45, 6)  # 5

# Pyramidal numbers (3D figurate)
tetrahedral(5)          # 35
square_pyramidal(5)     # 55
is_tetrahedral(20)      # True
inverse_tetrahedral(20) # 4

# Generalized centered polygonal
centered_polygonal(3, 4)  # 19  (centered triangular)
centered_polygonal(6, 3)  # 19  (centered hexagonal, same as centered_hexagonal(3))
is_centered_polygonal(4, 25)  # True  (centered square)

API

Generators

All generators require n >= 1. polygonal additionally requires k >= 3. centered_polygonal additionally requires sides >= 3.

Membership

is_triangular, is_square, is_pentagonal, is_hexagonal, is_heptagonal, is_octagonal - test whether an integer belongs to the sequence.

is_polygonal(m, k) - general k-gonal membership test. Requires k >= 3.

is_tetrahedral(m), is_square_pyramidal(m) - pyramidal membership tests (integer cube-root + exact verification).

is_centered_polygonal(sides, m) - centered s-gonal membership test. Requires sides >= 3.

All membership functions use integer arithmetic only (no floats in results).

Inverse lookup

inverse_triangular(m) - returns n such that triangular(n) == m, or None.

inverse_polygonal(m, k) - returns n such that polygonal(n, k) == m, or None. Requires k >= 3.

inverse_tetrahedral(m) - returns n such that tetrahedral(n) == m, or None.

inverse_square_pyramidal(m) - returns n such that square_pyramidal(n) == m, or None.

Development

uv venv .venv
uv pip install -e ".[dev]"
pytest
ruff check .
mypy src

License

MIT