FigurateNum is a collection of 235 figurate number generators based on the book Figurate Numbers by Michel Deza and Elena Deza, published in 2012.

FigurateNum helps discover patterns in figurate number sequences and supports numerical computation in mathematics-related projects. It integrates with other tools for visualizing geometric structures and serves as a companion to the book.

pip install figuratenum

To enable 2D visualizations via the FigurateViz class (requires numpy and matplotlib), install the optional dependencies:

pip install figuratenum[figurate-viz]

Centered Hexagonal Pyramidal

Centered Decagonal Pyramidal

5D Hypercube

The main class, FigurateNum, provides access to all figurate number sequences across different dimensions, while dedicated classes let you work with each dimension separately:

• 79 Plane figurate numbers → PlaneFigurateNum class — Explore on GitHub
• 86 Space figurate numbers → SpaceFigurateNum class — Explore on GitHub
• 68 Multidimensional figurate numbers → MultidimensionalFigurateNum class — Explore on GitHub
• 2 Zoo figurate numbers → ZooFigurateNum class — Explore on GitHub

• Gaussian plots (2D) in polar coordinates with customizable colors, visibility options, and export capabilities.
• Seamless integration with any figurate number sequence (list[int] or tuple[int, ...]).

from figuratenum import FigurateNum, MultidimensionalFigurateNum

# 1. General use: generate any figurate sequence via FigurateNum
seq = FigurateNum()
hyperdodecahedral_gen = seq.hyperdodecahedral()
print([next(hyperdodecahedral_gen) for _ in range(4)])
# Output: [1, 600, 4983, 19468]

# 2. Specialized classes: PlaneFigurateNum, SpaceFigurateNum,
#    MultidimensionalFigurateNum, ZooFigurateNum
multi = MultidimensionalFigurateNum()
hypertetrahedron_gen = multi.k_dimensional_centered_hypertetrahedron(21)
print([next(hypertetrahedron_gen) for _ in range(12)])
# Output: [1, 23, 276, 2300, 14950, 80730, 376740,
#          1560780, 5852925, 20160075, 64512240, 193536720]

5D Hyperoctahedron

from figuratenum import FigurateNum as fgn
from figuratenum.figurate_viz.FigurateViz import FigurateViz

# Generate figurate numbers
seq_loop = fgn()
gen = seq_loop.five_dimensional_hyperoctahedron()
figuratenum_seq = [next(gen) for _ in range(704)]

# Create and draw the Gaussian plot
viz = FigurateViz(figuratenum_seq, figsize=(6, 6))
viz.gaussian_plot(
    circ_color="m", bg_color="k", num_text=False,
    num_color="g", ext_circle=True, rotate=-1
).draw()

# Export plots as .svg, .pdf, .png (matplotlib compatible),
# with options e.g., dpi, transparent, bbox_inches, pad_inches, etc.
viz.export_plot(
    "figure1.svg", circ_color="m",
    transparent=True, rotate=-1
)

from figuratenum import NumCollector as nc, FigurateNum

gen = FigurateNum().pentatope()
print(nc.take_to_tuple(gen, 10))  # first 10 values as tuple
# Output: (1, 5, 15, 35, 70, 126, 210, 330, 495, 715)

# Available methods:
# - take(n)               : first n values as iterator
# - take_to_list(stop, start=0, step=1)
# - take_to_tuple(stop, start=0, step=1)
# - take_to_array(stop, start=0, step=1)
# - pick(n)               : nth value

🚨 Version 2.0.0 includes renamed methods and changes in class usage. These changes are incompatible with previous versions. Please review the updated usage instructions below to adapt your code to the new structure.

• PDF Cheatsheet with LaTeX commands and examples.
• Errata Figurate Numbers (2012).

By default, FigurateNum uses optimized, mathematically equivalent versions that are significantly faster, especially for multidimensional figurate numbers. Incremental computation and precomputed values allow step-by-step results without recalculating everything. The original formulas from the book are available via the *_from_book() methods for reference and testing.

FigurateNum is currently under development, and we warmly invite your contributions. Just fork the project and then submit a pull request:

• Sequences from Chapters 1, 2, and 3 of the book
• New sequences not included in the book: If you have new sequences, please provide the source.
• Tests, documentation and errata (located at docs/errata/errata-figuratenum.tex).

When making commits, please use the following conventional prefixes to indicate the nature of the changes: feat, refactor, fix, docs, and test.