FlagAlgebraToolbox: Automated Flag Algebra Calculations

• FlagAlgebraToolbox is a SageMath extension that automates flag algebra computations, transforming theoretical setups into provable bounds in extremal combinatorics.
• It employs a layered architecture integrating theory specification, flag enumeration, SDP construction, and rational rounding to yield exact certificates.
• The toolbox supports both numerical and symbolic manipulations via a programmable API, enabling precise and verifiable combinatorial optimizations.

FlagAlgebraToolbox is an extension of SageMath that specializes in automating flag algebra calculations and semidefinite optimizations for extremal combinatorial problems. It encapsulates the formalism of Razborov’s flag algebras, enabling the user to move rigorously from theory to provable bounds through an integrated workflow that includes theory specification, flag enumeration, semidefinite programming (SDP) formation and solution, and rounding to exact certificates. The toolbox targets a wide range of combinatorial theories, leveraging a layered architecture and supporting both numerical and symbolic manipulations with a programmable API suited to contemporary mathematical research settings (Bodnár, 10 Jan 2026).

1. Theoretical Foundations

FlagAlgebraToolbox is grounded in the theory of flag algebras, which studies asymptotic densities and inequalities within families of finite structures. A Theory $T$ is defined by a finite set of relation symbols, associated arities, symmetry or ordering conventions, and a list of forbidden induced substructures. A type $\tau$ is an isomorphism class of marked vertex structures in $T$, formally created in code as $\tau = T(k, \ldots, \text{ftype}=\text{range}(k))$, marking all $k$ vertices. A flag $F$ of order $\ell$ and type $\tau$ is an $\ell$-vertex structure with a prescribed injection of type-marks, instantiated as $F = T(\ell, \ldots, \text{ftype}=[0,2])$ in the API.

For a family of large $\tau$0-structures $\tau$1, the density of a flag $\tau$2 is

$\tau$3

The flag algebra formalism considers linear combinations $\tau$4 and aims to establish asymptotic inequalities

$\tau$5

which are encoded as semidefinite constraints using block-diagonal SDP matrices corresponding to each type. The central SDP is expressed as maximizing $\tau$6 subject to

$\tau$7

where $\tau$8 are multiplication/projection coefficients, “1” is the empty-type, and $\tau$9 is the asymptotic bound being optimized (Bodnár, 10 Jan 2026).

2. Architecture and Programming Interface

FlagAlgebraToolbox is modularized within SageMath, with a combinatorial layer (theories.py), algebraic layer (flag_algebra.py), and optimization layer (optimize.py and rounding.py). The main entity is Theory, which supports instantiation of flags, creation of patterns, exclusion or reset of forbidden substructures, and flag generation:

• T(size, **relations, ftype=[…]) constructs a flag of the given size, relation data, and marked vertices.
• T.pattern(size, …) instantiates a non‐induced template (Pattern).
• T.exclude(…) and T.reset() manage forbidden induced configurations.
• T.generate(n, ftype=None) enumerates all non-excluded flags for a size $T$0 and type.

Flag algebra elements (FlagAlgebraElement) represent formal linear combinations, support symbolic algebraic operations, projection, density evaluation, and derivatives. Optimization is triggered via optimize(…), specifying target linear combinations to maximize (or minimize), the truncation order, and settings for numerics or exact rational rounding. Bundled SDP solvers include CSDP, with optional export to SDPA format through external_optimize(…). Certificates and results can be dumped for later verification (Bodnár, 10 Jan 2026).

3. Workflow for Combinatorial Theories and Inputs

A typical workflow consists of:

1. Declaring the core theory. Example: $\tau = T(k, \ldots, \text{ftype}=\text{range}(k))$9
2. Imposing forbidden induced patterns, e.g., a triangle-free constraint: $k$0
3. Instantiating flags or types, such as empty-type flags with G(1) or marked flags like pointed_edge = G(2, edges=[[0,1]], ftype=[0]). Larger flags can be specified with appropriate edge lists and type markings.

This layered specification enables precise encoding of classical and modern extremal combinatorics problems, aligning input formalization with the semantics of the flag algebra method (Bodnár, 10 Jan 2026).

4. Flag Enumeration and Isomorphism Orbits

FlagAlgebraToolbox automates the enumeration of isomorphism classes of induced substructures via a brute-force generation of labeled structures filtered by exclusions and type markings. For each generated structure, the Bliss canonical labeling engine is employed for fast canonicalization. Isomorphic structures are then collated to yield unique representatives per orbit.

Similarly, Pattern.compatible_flags() enumerates all induced completions of a given pattern and filters these by isomorphism, ensuring that only structurally distinct completions are retained, which is essential for dimension reduction in SDPs and for theoretical correctness of ensuing calculations (Bodnár, 10 Jan 2026).

5. Semidefinite Programming Construction

Given a target flag algebra element $T$1, a set of types $T$2, and all corresponding $T$3-flags of fixed order, the SDP is formulated with variables $T$4 (for each type), constrained $T$5, and a scalar $T$6 for the bound. The constraints are as follows:

• Objective: Maximize $T$7.
• Linear constraints: For each small unlabeled flag $T$8, coefficients in the expansion

$T$9

are enforced to vanish, with $\tau = T(k, \ldots, \text{ftype}=\text{range}(k))$0 the explicit rational coefficient matrices determined by flag combinatorics.

• Semidefiniteness: Each matrix $\tau = T(k, \ldots, \text{ftype}=\text{range}(k))$1 must be positive semidefinite.

In compact notation: $\tau = T(k, \ldots, \text{ftype}=\text{range}(k))$2 This formalism provides both the numerical efficiency and theoretical soundness required for rigorous extremal bounds (Bodnár, 10 Jan 2026).

6. Numerical Optimization and Rational Rounding

The SDP is solved by default using CSDP, or via SDPA when exported. A floating-point solution $\tau = T(k, \ldots, \text{ftype}=\text{range}(k))$3 is produced. When the exact=True parameter is specified, a rational rounding step is performed:

• Each floating entry is approximated by a nearby rational with bounded denominators.
• A small feasibility problem is checked to confirm that all exact linear and semidefiniteness constraints are preserved.
• Parameters slack_threshold and kernel_denom serve to tune tolerances in cone rounding.

The rational value $\tau = T(k, \ldots, \text{ftype}=\text{range}(k))$4 obtained is a mathematically rigorous bound, and the rational matrices $\tau = T(k, \ldots, \text{ftype}=\text{range}(k))$5 serve as an independent certificate. These can be dumped for archival or external review; subsequent calls to T.verify("cert") will re-check the certificate fully in exact arithmetic. This pipeline ensures correctness and reproducibility for published flag algebra results (Bodnár, 10 Jan 2026).

7. Fully Verified Example: Mantel’s Theorem

As a paradigmatic demonstration, Mantel’s theorem (triangle-free graphs satisfy $\tau = T(k, \ldots, \text{ftype}=\text{range}(k))$6) is established end-to-end in the toolbox:

• The triangle-free theory is declared.
• Edge flags and pointed flags are defined.
• The sum-of-squares certificate $\tau = T(k, \ldots, \text{ftype}=\text{range}(k))$7 is checked symbolically.
• The optimization routine returns the exact rational value $\tau = T(k, \ldots, \text{ftype}=\text{range}(k))$8.
• The SDP data, floating-point and rational solutions, and rounding evidence are stored in a mantel.cert file.
• An independently verified call re-establishes the certificate and bound from scratch.

This explicit workflow demonstrates FlagAlgebraToolbox's ability to take a combinatorial extremal problem from abstract formulation through symbolic calculation, SDP construction, numerical optimization, exact rounding, and certificate-based proof verification within a single computational environment (Bodnár, 10 Jan 2026).