Utilities for iterating over group elements from a finite generating set.

In Sage, many algebraic objects (finite abelian groups, finite multiplicative groups, etc.) provide a list of generators via a .gens() method. These generators are used to build (finite) combinations by taking suitable products or sums of generator powers.

This module provides pure-Python iterator implementations that enumerate all elements in the finite subgroup generated by M.gens():

  • multiplicative_iterator(M) yields all products of generator powers, using each generator’s finite multiplicative order.

  • abelian_iterator(M) yields all sums of generator multiples, using each generator’s finite additive order.

The iteration is implemented as a mixed-radix “odometer”: an exponent/count vector is incremented and carried across generators, and the current element is updated incrementally.

sage.structure.gens_py.abelian_iterator(M)[source]

Iterate over elements of M using additive generator combinations.

The object M is expected to provide:

  • M.gens(): a list/sequence of generators for the finite abelian group.

  • M(0): a callable constructor returning the additive identity element.

  • Each generator g must implement g.additive_order().

The iterator yields each group element produced by taking sums of generator multiples where the coefficient of generator g runs from 0 up to g.additive_order() - 1.

INPUT:

  • M – a finite additive group-like object

OUTPUT:

  • elements of M in a deterministic order

If not all generators have finite additive order, an ArithmeticError is raised.

sage.structure.gens_py.multiplicative_iterator(M)[source]

Iterate over elements of M using multiplicative generator combinations.

The object M is expected to provide:

  • M.gens(): a list/sequence of generators for the finite group.

  • M(1): a callable constructor returning the identity element.

  • Each generator g must implement g.multiplicative_order().

The iterator yields each group element produced by multiplying generator powers where the exponent of generator g runs from 0 up to g.multiplicative_order() - 1.

INPUT:

  • M – a finite multiplicative group-like object

OUTPUT:

  • elements of M in a deterministic order

If not all generators have finite multiplicative order, an ArithmeticError is raised.