Sign symmetry and invariant atomic extraction

tssos_symmetry, complex_tssos_symmetry, and add_psatz_symmetry! accept signsymmetry=true in addition to their permutation group. This detects the common diagonal sign subgroup from polynomial supports over GF(2), builds the group generated by signs and permutations, and uses signed monomial actions in the Wedderburn decomposition. Alternatively, supply an n × k binary matrix, with one sign generator per column (1 flips a variable). The default remains false. The requested sign subgroup and its permutation conjugates must preserve each input polynomial. Custom action implementations cannot be combined with this keyword.

Reynolds averaging removes monomials with a nontrivial sign character. It does not identify their coefficients with positive orbit sums. This applies to Gram blocks, localizers, equality multipliers, and coefficient matching, including later term-sparsity steps. The existing two-value return shape is unchanged.

Real symmetry relaxations retain their invariant dual functional in data.moments. Invariant extraction does not assemble a dense original-variable moment matrix:

using TSSOS, DynamicPolynomials, PermutationGroups, COSMO
@polyvar x[1:2]
G = PermGroup([perm"(1,2)"])
f = sum((x.^2 .- 1).^2)
opt, data = tssos_symmetry([f, sum(x.^2)-2], x, 4, G;
    numeq=1, signsymmetry=true, TS=false, optimizer=COSMO.Optimizer, QUIET=true)
generators = [sum(x.^2), prod(x.^2)]
result = extract_invariant_atoms(data, generators, x, 4;
    degrees=[2,4], rtol=1e-5, validation_tol=1e-4)
orbits = lift_invariant_atoms(result; symmetry=:signed_permutations)

The supplied generators must be algebraically independent and generate the invariant ring. Their degrees are checked against the polynomials; algebraic independence and generation are assumptions supplied by the caller. A general finite group can have relations among its generators; that case needs a separate quotient-ring extension. Extraction currently concerns real invariant coordinates, even though the relaxation also supports complex signed actions.

Moment interface and arithmetic

The standalone interface takes a dictionary keyed by exponent tuples of the invariant generators, rather than TSSOS variable-index supports:

moments = invariant_moments([[1], [4]], [1//3, 2//3], [2], 4)
result = extract_invariant_atoms(moments, [2], 4; arithmetic=:exact)
result.atoms          # approximately [1] and [4]
result.weights        # approximately 1/3 and 2/3
result.multiplication # exact rational multiplication matrices

weighted_indices(degrees,t) enumerates the weighted truncation deterministically. invariant_moment_matrix(moments,basis) assembles its moment matrix. The generator method invariant_moments(data,generators,x,t) evaluates products using SDP dual moments. It leaves unavailable rows absent, so the extractor can reject missing required entries rather than treating them as zero.

For D = D_t, C = D_(t-maximum(degrees)), the extractor requires all D+D moments, positive semidefiniteness of M_D, and equal positive ranks of M_C and M_D. It pins the constant in a pivoted Cholesky quotient basis, forms H, shifted matrices K_j, and T_j = H \ K_j. Symmetric triangular solves produce commuting symmetric matrices. A seeded generic combination separates their joint eigenvalues; the constant's spectral coordinates give the weights. Unresolved gaps trigger reproducible retries and then :spectral_collision.

Numerical rank uses eigenvalues greater than atol + rtol * maximum(abs,eigenvalues), separately for each moment matrix. Defaults are rtol=sqrt(eps(T)), atol=0, validation_tol=100rtol, and gap_tol=10sqrt(eps(T)). Diagnostics retain the spectra, thresholds, rank gaps, commutators, eigengap, joint-eigenvector residual, weight residuals, and raw and scaled errors for every supplied moment. A near-collision may be numerically indistinguishable from a smaller measure; inspect the ranks and spectra and increase precision when appropriate. rank_resolution_warning flags positive eigenvalues above a roundoff floor but below the selected rank threshold. A successful reconstruction is relative to the declared tolerances, and does not assert that unresolved atoms are absent.

arithmetic=:exact uses rational elimination, exact PSD checks, and exact multiplication matrices as an oracle. Atom coordinates and weights still use numerical eigensolvers. Rational reconstruction is accepted only after checking every required moment exactly; when successful, diagnostics[:exact_atoms] and diagnostics[:exact_weights] contain the rational measure (otherwise nothing). BigFloat moments retain their precision through generic Cholesky solves and a symmetric Jacobi eigensolver; there is no Float64 conversion in the extraction kernel. Optional polynomial-root lifting uses Float64.

Representation and failure statuses

The result contains atoms, weights, rank, basis, H, multiplication, symmetric_multiplication, and diagnostics. Invalid dimensions, degrees, nonfinite values, missing D+D moments, or nonnormalized probability moments raise ArgumentError. Numerical or mathematical failures return a diagnostic status such as :not_psd, :not_flat, :ill_conditioned_basis, :spectral_collision, or :invalid_representation.

Three diagnostics distinguish the representation claims:

These sets need not agree. At degrees=[2], t=3, the values y₀=y₁=y₂=1, y₃=2 yield the valid sparse-flat atom 1, but do not reproduce y₃. The status is :inconsistent_full_moments; the atom is retained and the failed additional identity is reported. A :success status with incomplete coverage still has full_representation=false.

Orbits and optimization checks

lift_invariant_atoms supports :signs (squared coordinates), :permutations (elementary symmetric generators), and :signed_permutations (elementary symmetric generators in squared coordinates). It computes orbit sizes and stabilizers without enumeration by default. enumerate=true explicitly returns all original points and their individual mass weight/size. Polynomial roots are clustered at sqrt(tol)*(1+maximum(abs,roots)), and the reconstructed invariants are rechecked with tol. Orbit cardinalities near a repeated-root boundary therefore have this declared numerical resolution.

Other actions accept symmetry=:custom, callbacks lift(v) and invariants(x), and a finite group with action(g,x). This path enumerates group elements to check the fiber, deduplicate points, and verify orbit-stabilizer.

Bare extraction returns no feasibility or optimality claim. Optional inequalities, equalities, and objective callbacks are checked on every orbit point; requesting those checks can require exponential work even when enumerate=false. Passing both constraint lists explicitly, a valid lower_bound, lower_bound_certified=true, and a fully represented moment sequence permits the label :certified_global_minimizers when all original constraints and objective values pass. The validity of the supplied lower bound remains the caller's responsibility. Otherwise the label is :candidate.

Run the focused regression suite with:

julia --project=. test/invariant_extraction.jl

In an interactive session, load the package with using TSSOS; the source file is included inside the package module and should not be included directly into Main. If a previous partial source include created conflicting bindings, use TSSOS.invariant_moments(...) and TSSOS.extract_invariant_atoms(...), or restart Julia. The regression tests use their own module so existing Main bindings cannot shadow the package API.

It covers exact benchmarks A–E, family F through n=10, unequal orbit sizes, repeated coordinate eigenvalues, near-collisions in Float64 and BigFloat, the truncation counterexample, real and complex signed SDPs, dualization, equality multipliers, and certificate construction. The example example/invariant_extraction_benchmarks.jl prints reproducible timing and allocation tables without enumerating exponentially large orbits.