dataset_generators

graphcalc.additive_combinatorics.dataset_generators.additive_dataset_column_definitions() → dict[str, dict]

Return the schema for additive-combinatorics conjecturing datasets.

Returns:

Dictionary keyed by column name. Each value is a metadata record describing the column type and intended meaning.

Return type:

dict of str to dict

Notes

The schema is designed for conjecturing workflows in which each row describes one finite additive set together with ambient-group descriptors, numerical invariants, Boolean predicates, and optional provenance information.

The returned dictionary is intended to be stable enough for downstream export helpers and dataframe construction.

graphcalc.additive_combinatorics.dataset_generators.additive_set_to_record(A: AdditiveSet, *, construction: str | None = None, construction_parameters: dict | None = None) → dict

Convert an additive set into a conjecturing-oriented record.

Parameters:

• A (AdditiveSet) – Input additive set.

• construction (str, optional) – Optional label describing how the set was generated.

• construction_parameters (dict, optional) – Optional parameter dictionary recording the construction choices.

Returns:

Dictionary containing ambient descriptors, numerical invariants, Boolean predicates, and optional provenance metadata.

Return type:

dict

Notes

Quantities that are undefined on the empty set, such as \(|A+A|/|A|\), are stored as None instead of raising an exception. This makes the resulting records easier to place into a pandas dataframe.

graphcalc.additive_combinatorics.dataset_generators.generate_additive_set_dataset(instances: Iterable[AdditiveSet | tuple[AdditiveSet, str] | tuple[AdditiveSet, str, dict]]) → list[dict]

Convert a collection of additive sets into dataset rows.

Parameters:

instances (iterable) –

Iterable whose entries are one of:

• an AdditiveSet,

• a pair (A, construction), or

• a triple (A, construction, construction_parameters).

Returns:

Dataset rows obtained by applying additive_set_to_record().

Return type:

list of dict

Raises:

TypeError – If an entry is not in one of the accepted formats.

graphcalc.additive_combinatorics.dataset_generators.large_additive_snapshot(*, cyclic_moduli: Sequence[int] = (4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20), product_moduli: Sequence[tuple[int, ...]] = ((2, 2), (2, 3), (3, 3), (2, 2, 2)), random_samples_per_group: int = 25) → list[dict]

Return a larger deterministic additive-combinatorics dataset snapshot.

Parameters:

• cyclic_moduli (sequence of int, default=range(4, 21)) – Cyclic moduli to include as ambient groups \(\mathbb{Z}/n\mathbb{Z}\).

• product_moduli (sequence of tuple of int, optional) – Product-group ambient moduli to include.

• random_samples_per_group (int, default=25) – Number of fixed-size and density-based random samples to generate per ambient group.

Returns:

Deterministic dataset rows with many examples and descriptors.

Return type:

list of dict

Raises:

ValueError – If random_samples_per_group is negative.

Notes

This snapshot is designed for conjecturing workflows that benefit from many examples. All randomness is seeded deterministically from the ambient-group parameters.

graphcalc.additive_combinatorics.dataset_generators.medium_additive_snapshot() → list[dict]

Return a medium deterministic additive-combinatorics dataset snapshot.

Returns:

Reproducible dataset rows spanning cyclic and product groups together with structured and seeded random families.

Return type:

list of dict

Notes

This snapshot is intended for richer conjecturing experiments while remaining small enough for routine unit testing and documentation use.

graphcalc.additive_combinatorics.dataset_generators.small_additive_snapshot() → list[dict]

Return a small deterministic additive-combinatorics dataset snapshot.

Returns:

Reproducible dataset rows spanning several structured and random families in small cyclic groups.

Return type:

list of dict

Notes

This snapshot is intended for quick experimentation, smoke tests, and documentation examples.