generators

graphcalc.additive_combinatorics.generators.all_subsets_of_group(group: FiniteAbelianGroup, *, max_order: int = 10) → list[AdditiveSet][source]

Return all subsets of a small finite abelian group.

Parameters:

  • group (FiniteAbelianGroup) – Ambient finite abelian group.

  • max_order (int, default=10) – Maximum ambient group order for which exhaustive subset generation is allowed.

Returns:

All subsets of the ambient group.

Return type:

list of AdditiveSet

Raises:

ValueError – If the ambient group order exceeds max_order.

graphcalc.additive_combinatorics.generators.arithmetic_progression(group: FiniteAbelianGroup, start: Sequence[int], step: Sequence[int], length: int) → AdditiveSet[source]

Return a finite arithmetic progression in an ambient finite abelian group.

Parameters:

  • group (FiniteAbelianGroup) – Ambient finite abelian group.

  • start (sequence of int) – Initial element of the progression.

  • step (sequence of int) – Common difference.

  • length (int) – Number of terms.

Returns:

The set

\[\{start + j \cdot step : 0 \le j < length\}\]

in the ambient group.

Return type:

AdditiveSet

Raises:

ValueError – If length is negative, or if start or step does not have the correct coordinate length.

Notes

In torsion groups, different progression terms may coincide, so the resulting set may have cardinality smaller than length.

graphcalc.additive_combinatorics.generators.coset(subgroup: AdditiveSet, x: Sequence[int]) → AdditiveSet[source]

Return a translate of a subgroup, viewed as a coset.

Parameters:

  • subgroup (AdditiveSet) – A subgroup of some finite abelian ambient group.

  • x (sequence of int) – Translation element.

Returns:

The translate

\[x + H = \{x + h : h \in H\}\]

in the same ambient group as subgroup.

Return type:

AdditiveSet

Raises:

ValueError – If x does not have the correct coordinate length.

Notes

This function does not itself verify that subgroup is actually a subgroup; it simply returns the translate of the given additive set.

graphcalc.additive_combinatorics.generators.empty_set(group: FiniteAbelianGroup) → AdditiveSet[source]

Return the empty subset of a finite abelian group.

Parameters:

group (FiniteAbelianGroup) – Ambient finite abelian group.

Returns:

The empty subset of group.

Return type:

AdditiveSet

graphcalc.additive_combinatorics.generators.interval(modulus: int, length: int, *, start: int = 0) → AdditiveSet[source]

Return an interval in the cyclic group \(\mathbb{Z}/n\mathbb{Z}\).

Parameters:

  • modulus (int) – Modulus n defining the cyclic group \(\mathbb{Z}/n\mathbb{Z}\).

  • length (int) – Number of consecutive residues to include.

  • start (int, default=0) – Initial residue class.

Returns:

The subset

\[\{start, start+1, \dots, start+length-1\} \pmod{n}\]

viewed as a subset of \(\mathbb{Z}/n\mathbb{Z}\).

Return type:

AdditiveSet

Raises:

ValueError – If modulus is not positive, or if length is negative.

Notes

If length exceeds modulus, the resulting subset is the whole cyclic group, since duplicate residues are removed canonically.

graphcalc.additive_combinatorics.generators.random_subset(group: FiniteAbelianGroup, *, size: int | None = None, density: float | None = None, rng=None) → AdditiveSet[source]

Return a random subset of a finite abelian group.

Parameters:

  • group (FiniteAbelianGroup) – Ambient finite abelian group.

  • size (int, optional) – Desired subset size. If provided, a subset of exactly this cardinality is sampled uniformly from all subsets of that size.

  • density (float, optional) – Bernoulli inclusion probability for each ambient group element. If provided, each element is included independently with this probability.

  • rng (numpy.random.Generator, optional) – Random number generator to use. If omitted, a new default generator is created.

Returns:

A random subset of the ambient group.

Return type:

AdditiveSet

Raises:

  • ValueError – If neither or both of size and density are provided.

  • ValueError – If size is negative or exceeds the ambient group order.

  • ValueError – If density does not lie in the interval [0, 1].

Notes

Exactly one of size and density must be specified.

graphcalc.additive_combinatorics.generators.random_symmetric_subset(group: FiniteAbelianGroup, *, density: float = 0.5, include_zero: bool = True, rng=None) → AdditiveSet[source]

Return a random symmetric subset of a finite abelian group.

Parameters:

  • group (FiniteAbelianGroup) – Ambient finite abelian group.

  • density (float, default=0.5) – Sampling density applied to inversion orbits.

  • include_zero (bool, default=True) – Whether to force inclusion of the identity element.

  • rng (numpy.random.Generator, optional) – Random number generator to use.

Returns:

A random subset A satisfying A = -A.

Return type:

AdditiveSet

Raises:

ValueError – If density is not in the interval [0, 1].

graphcalc.additive_combinatorics.generators.sample_random_subsets(group: FiniteAbelianGroup, *, num_samples: int, size: int | None = None, density: float | None = None, seed: int | None = None) → list[AdditiveSet][source]

Sample multiple random subsets of an ambient finite abelian group.

Parameters:

  • group (FiniteAbelianGroup) – Ambient finite abelian group.

  • num_samples (int) – Number of samples to draw.

  • size (int, optional) – Fixed size of each sample.

  • density (float, optional) – Bernoulli density of each sample.

  • seed (int, optional) – Seed for reproducible sampling.

Returns:

List of random samples.

Return type:

list of AdditiveSet

Raises:

ValueError – If num_samples is negative.

graphcalc.additive_combinatorics.generators.singleton(group: FiniteAbelianGroup, x: Sequence[int]) → AdditiveSet[source]

Return the singleton subset containing one ambient group element.

Parameters:

  • group (FiniteAbelianGroup) – Ambient finite abelian group.

  • x (sequence of int) – Element of the ambient group.

Returns:

The singleton set {x}, with x reduced canonically modulo the ambient group moduli.

Return type:

AdditiveSet

Raises:

ValueError – If x does not have the correct coordinate length.

graphcalc.additive_combinatorics.generators.subgroup_from_generators(group: FiniteAbelianGroup, generators: Iterable[Sequence[int]]) → AdditiveSet[source]

Return the subgroup generated by a family of elements.

Parameters:

  • group (FiniteAbelianGroup) – Ambient finite abelian group.

  • generators (iterable of sequence of int) – Generating family.

Returns:

The smallest subgroup of the ambient group containing all of the given generators.

Return type:

AdditiveSet

Notes

Since the ambient group is finite, the subgroup is computed by iterative closure under addition and negation starting from the generators and the identity element.

The empty generating family yields the trivial subgroup {0}.

graphcalc.additive_combinatorics.generators.union_of_cosets(subgroup: AdditiveSet, translates: Iterable[Sequence[int]]) → AdditiveSet[source]

Return a union of translates of a given additive set.

Parameters:

  • subgroup (AdditiveSet) – Base additive set, typically a subgroup.

  • translates (iterable of sequence of int) – Translation elements.

Returns:

The union of the translates \(t + H\) over the given translation elements \(t\).

Return type:

AdditiveSet

Notes

This function does not verify that subgroup is actually a subgroup.

graphcalc.additive_combinatorics.generators.whole_group(group: FiniteAbelianGroup) → AdditiveSet[source]

Return the whole ambient group as an additive set.

Parameters:

group (FiniteAbelianGroup) – Ambient finite abelian group.

Returns:

The full set of all elements of the ambient group.

Return type:

AdditiveSet